Sessions

Sessions keep a browser context alive — cookies, viewport, and navigation history persist across calls.

Create a session

curl -X POST https://api.browsr.dev/sessions \
  -H "x-api-key: $BROWSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "headless": true,
    "start_url": "https://example.com",
    "use_random_user_agent": true
  }'

Parameter	Type	Default	Description
headless	boolean	false	Run Chrome without UI
requested_name	string	—	Human-readable session name
start_url	string	—	Navigate on creation
cdp_url	string	—	Connect to existing Chrome DevTools Protocol endpoint
use_random_user_agent	boolean	false	Randomize user agent
disable_automation_detection	boolean	false	Apply stealth tweaks
user_agent	string	—	Custom user agent
profile_id	string	—	UUID of a saved profile to load

{
  "status": "ready",
  "session_id": "session-abc123",
  "frame_token": "eyJhbG...",
  "sse_url": "https://api.browsr.dev/stream/sse?session_id=session-abc123"
}

Async provisioning

When workers need to scale, the response returns status: "provisioning" with a provision_id. Poll until ready:

curl -X POST https://api.browsr.dev/sessions/provision/PROVISION_ID \
  -H "x-api-key: $BROWSR_API_KEY"

Stages: provisioning → scaling → worker_found → creating → ready

List sessions

curl https://api.browsr.dev/sessions \
  -H "x-api-key: $BROWSR_API_KEY"

Delete a session

curl -X DELETE https://api.browsr.dev/sessions/session-abc123 \
  -H "x-api-key: $BROWSR_API_KEY"

Returns 204 No Content.

tip

If you omit session_id from a /commands request, a session is created automatically and returned in the response.