REST API

The daemon's own HTTP API. It creates and starts profiles, assigns proxies and streams events, and it is the surface every other interface on this site sits on.

Base URL and authentication

Everything lives under /v1 on the native API, which binds 127.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 a 401 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 from scalebrowser-daemon --generate-token; see Install & run.

Request and response shape

Bodies are JSON in both directions, and a success is the resource itself, a profile or 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, and null 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 and /v1/profiles/count are registered ahead of /v1/profiles/:id, so neither literal is read as a profile id. /v1/proxies/check is handled the same way.

count takes no state parameter on purpose. Its caller is usually a screen that sits in one state and has to put a number on all of them, so a count narrowed by the active state would report zero for every other one. total counts rows rather than adding the four fields up, which keeps a profile in a state an older build does not know visible in the total instead of silently counted as stopped.

A listed or fetched profile carries a protection object alongside its own fields. That verdict is produced by the same functions the launch runs, so blocked 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.

$ 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, because 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,
  "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, expected_country, persona_country (the region the identity is drawn for, see Profiles & personas) and group_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 returns 4002, 4003, 4004, 4005 or 4006.

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, for instance 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 on DELETE 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, and GET /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, an at in Unix seconds and a seq. There are 23 types, and Events is the page for them, along with the resync frame that tells you when you fell behind.

/v1/ws is this event stream and nothing else. It is not a CDP connection, which comes back from start.

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 uses POST, GET and DELETE on that one path. MCP server is the page for it.

Error codes

Every failing request answers { code, message }, where code is a stable number for the failures you are expected to handle by kind and null for the generic ones. The numbers are append-only: none is ever reused, and a retired one stays reserved.

The full table, with the HTTP status and the remedy for each, is on Errors. The three that surprise people most: 4003 means this machine is full and waiting helps, 4008 means your subscription is full and waiting does not, and 4012 means that one profile is open on another machine of yours.

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.