REST API reference

The sessions API is small on purpose: create a browser, list what is running, stop what you no longer need. Everything else happens over the session's CDP websocket.

Base URL and authentication

All endpoints live under https://api.browsergen.com/v8. Authenticate every request with an API key from the dashboard in the Authorization header:

header

Authorization: Bearer brl-k-v7-YOUR-KEY

Keys have the prefix brl-k-v7- and carry the full access of your workspace. Treat them like passwords: server-side only, never in client-side code.

POST/web/sessions

Creates a browser session and returns once it is running (typically a few seconds). All body fields are optional.

Field	Type	Description
`timeout`	integer	Session lifetime in seconds, 60 to 21600 (6 hours). Defaults to 3600. Values above your plan cap are clamped.
`country`	string	Exit-country code for the session ("us", "de", "us-dal" for a specific city, ...). Mutually exclusive with proxy.
`proxy`	string	Custom proxy URL (http, https, or socks5 with optional credentials) the browser egresses through. Mutually exclusive with country.
`url`	string	A page the browser opens immediately after start.

request body

{
  "timeout": 3600,
  "country": "de",
  "url": "https://example.com"
}

Response:

response

{
  "status": "ok",
  "id": "9f2c1e0a",
  "connectUrl": "wss://api.browsergen.com/web/9f2c1e0a/cdp?token=wct_...",
  "liveViewUrl": "https://browsergen.com/dash/sessions/9f2c1e0a",
  "createdAt": "2026-07-09T09:30:00.000Z",
  "timeout": 3600,
  "quota": { "concurrency_total": 5, "used": 2, "available": 3 }
}

Field	Type	Description
`id`	string	Session id, used in every per-session endpoint and in the dashboard.
`connectUrl`	string	CDP websocket endpoint including its one-time token. Works directly with Playwright connectOverCDP and Puppeteer browserWSEndpoint; the HTTP /json/version discovery form works too.
`liveViewUrl`	string	Dashboard page streaming the session live, with manual control.
`createdAt`	string	ISO 8601 creation timestamp.
`timeout`	integer	The effective timeout after clamping.
`quota`	object	Concurrency snapshot at creation: concurrency_total (plan), used, and available.

GET/web/sessions

Lists active sessions. Add ?status=all to include ended sessions from the last 30 days, and &limit= to cap the result count.

response

{
  "status": "ok",
  "sessions": [
    {
      "id": "9f2c1e0a",
      "state": "running",
      "createdAt": "2026-07-09T09:30:00.000Z",
      "timeout": 3600,
      "country": "de"
    }
  ]
}

GET/web/sessions/:id

Returns one session, including its state (running or an ended state with ended_reason: stopped, timeout, disconnect, or error).

DELETE/web/sessions/:id

Stops a running session immediately and frees its concurrency slot. POST /web/sessions/:id/stop is an equivalent alias for clients that cannot send DELETE.

GET/web/usage

Current concurrency usage plus a 30-day session count.

response

{
  "status": "ok",
  "concurrency": { "total": 5, "used": 2, "available": 3 },
  "history": { "sessions": 412, "since": "2026-06-09T00:00:00.000Z" }
}

Errors

Every response carries a status field. Success is "ok"; a rejected request is "denied" (bad input, quota, permissions) and a platform fault is "error". Failures include a human-readable message:

error

{
  "status": "denied",
  "message": "Your plan allows 5 concurrent browsers and all of them are in use."
}

Retry guidance: treat denied as non-retriable until you change the request (or a slot frees up), and error as retriable with backoff.

Playwright guideconnectOverCDP, contexts, and clean shutdown.Limits and retentionTimeout bounds, concurrency, geo list, history.

REST API reference

Base URL and authentication

Errors

Related