Docs · Interfaces

REST API

The daemon's own HTTP API: create and start profiles, assign proxies, follow events — the surface every other interface sits on.

Base URL and authentication

Everything lives under /v1 on the native API, which binds127.0.0.1:8787 by default. Every /v1 route requires a bearer token; it is compared in constant time, and a missing, malformed or wrong one is a401 carrying error code 4010.

Authorization: Bearer <token>

GET /health is the one exception. It sits outside the auth layer and answers {"status":"ok","service":"scalebrowser-api"} without a token, which is what makes it usable as a monitor probe. The token itself comes from your config file, from SCALEBROWSER_BEARER_TOKEN, or fromscalebrowser-daemon --generate-token — seeInstall & run.

Request and response shape

Bodies are JSON in both directions, and a success is the resource itself — a profile, a list of profiles — never an envelope. Errors are always these two fields:

{ "code": 4005, "message": "preflight failed: …" }

code is a stable number for the failures you are expected to handle, andnull for the generic ones — bad input, a conflict, an internal error. The full list is at the end of this page.

Updates are PATCH: partial, with absent fields left unchanged.PUT is routed to the identical handler on every updatable resource, so an older client that sends it keeps working; new code should send PATCH.

Profiles

/v1/profiles/ids is registered ahead of /v1/profiles/:id, so the literal ids is never read as a profile id. /v1/proxies/checkis handled the same way.

A listed or fetched profile carries a protection object alongside its own fields. That verdict is produced by the same functions the launch runs, soblocked means “this profile will refuse to start” rather than a second opinion. Coherence & proxies explains what is checked.

The two calls everyone makes first

Create a profile. Only name is required — everything else is drawn from a seed, and an omitted host_mode takes the daemon's default for its own operating system.

$ curl -X POST http://127.0.0.1:8787/v1/profiles \ -H "Authorization: Bearer $SCALEBROWSER_BEARER_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "shop-01", "geo_mode": "follow_exit", "proxy_id": "px_7f3a"}'

The reply is the created profile. It is long — the identity alone is dozens of fields — so these are the parts you act on:

{"id": "pr_9c21e4", "name": "shop-01", "runtime_state": "stopped", "enabled": true, "host_mode": "linux_engine_spoof", "geo_mode": "follow_exit", "proxy_id": "px_7f3a", "engine_version": "…", "seed": "…", "created_at": 1754300000, "persona": { /* the whole identity — see /coherence */ }}

The other accepted create fields are seed (reproduce a known identity),engine_version, host_mode, expected_country andgroup_id. Then start it:

$ curl -X POST http://127.0.0.1:8787/v1/profiles/pr_9c21e4/start \ -H "Authorization: Bearer $SCALEBROWSER_BEARER_TOKEN" \ -H "Content-Type: application/json" \ -d '{"headless": false}'

{"profile_id": "pr_9c21e4", "cdp_ws": "ws://127.0.0.1:41337/devtools/browser/2f1c…", "debug_port": 41337, "headless": false, "pid": 48221, "started_at": 1754300112}

cdp_ws points at the browser's own DevTools socket on loopback, on a port the engine picks per launch — not at the daemon. That endpoint is how you drive the page yourself, and Direct CDP covers it. The request body is optional: an omitted headless means headless, and false asks for a visible window.

A start is where the pre-launch checks run, so this is the call that returns4002, 4003, 4004, 4005 or4006.

Bulk operations

Every bulk call answers with a per-id list of { id, ok, error? }, so one bad id does not fail the batch. bulk/start adds three fields:started (how many browsers came up), remaining (ids never attempted) and stopped_reason when it ended early. headless is one decision for the whole batch.

Groups and presets

A group is a flat label a profile belongs to. A preset is a stored operating configuration that POST /v1/bulk/profiles stamps out. Both are plain CRUD:

Proxies

Credentials are write-only. No endpoint returns them, and the type that carries them cannot be serialised at all — so a proxy password cannot leave through a response by accident. An unreachable proxy is reported as healthy: false, not as an error.

A proxy whose stored credentials cannot be decrypted — a database restored without its key — is flagged credentials_unreadable. It stays listable and deletable, and every path that would use it fails closed: an authenticated proxy is never run without its credentials, because that would send the session out over the host's real address.

Extensions

Two levels: a daemon-wide library of packages, and which of them a profile loads.

ext_ref is a library id, never a path. Note that the unassign call carries it in the request body: an HTTP client that silently drops bodies onDELETE will unassign nothing and report success.

Session bundles

An export that could only capture cookies is flagged as degraded in its own response rather than passed off as complete.

Live detector audit

Drive a running profile through the external detector pages and keep the verdict against the launch it was measured on. A run takes minutes of real network traffic, so it is two calls rather than one:

Metrics

GET /v1/metrics answers with the resource picture behind the dashboard: the live running count, the configured capacity and budgets, host memory, CPU and GPU figures, and a per-profile breakdown. It is served from a background sampler, so the request path probes nothing and the numbers are at most one sampling interval old.

Each measured value is paired with a probe state of measured,unsupported or unavailable, so “zero” and “we could not read this” never look alike. A separate Prometheus endpoint exists for a deployed daemon; it is off by default and configured under [observability].

Event streams

Two transports, the same events, both behind the bearer token:GET /v1/events is Server-Sent Events with a 15-second keep-alive, andGET /v1/ws is a WebSocket. Both are server-to-client only. Each connection subscribes before its response is produced, so nothing published between your request and the first frame is lost, and a slow client skips events rather than being disconnected.

Each message is one JSON object with a type field:

at is a Unix timestamp in seconds. /v1/ws is this event stream and nothing else — it is not a CDP connection, which comes back fromstart.

The MCP endpoint

/v1/mcp is mounted inside the same bearer-auth layer, but it is a nested service rather than a plain route: it speaks Streamable HTTP, which usesPOST, GET and DELETE on that one path.MCP server is the page for it.

Error codes

These numbers are part of the contract and do not change. 4007 is retired and reserved — it belonged to a tier that no longer exists, and nothing returns it.

Next

• Direct CDP — what to do with the cdp_ws a start hands back.
• MCP server — the same daemon, driven by an AI agent.
• AdsPower adapter — the compatibility surface for existing scripts.
• Coherence & proxies — what the checks behind 4002 and 4005 actually verify.