API Overview

Browsr exposes a single authenticated API for four main workflows:

• Remote browser sessions and command execution
• High-level scrape, crawl, and search APIs
• Relay-backed Chrome debugging for local browsers
• Remote shell sessions for code and terminal workflows

Base URL:

https://api.browsr.dev

OpenAPI:

https://api.browsr.dev/openapi.json

Direct links:

• Download/Open OpenAPI spec
• Command reference
• Sessions reference
• Shell reference

Authentication

Most API calls use an API key in the x-api-key header:

export BROWSR_API_KEY="bak_..."

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

Relay websocket and embedded frame flows may use bearer tokens instead, but API-key auth is the normal developer path.

What the API can do

1. Browser sessions

Use /sessions, /commands, /observe, and /browser_step when you want a persistent browser context with cookies, local storage, and navigation state.

Typical flow:

1. POST /sessions
2. POST /commands
3. POST /observe or POST /browser_step
4. DELETE /sessions/{session_id}

2. High-level extraction

Use these when you do not want to manage browser sessions yourself:

• POST /v1/scrape
• POST /v1/crawl
• POST /search

Browsr provisions the browser work internally and returns structured output.

3. Relay debugging

Use relay APIs when a local browser is already connected through Browsr Relay and you want CDP-level inspection:

• GET /relay/sessions
• POST /cdp
• GET /relay/sessions/{id}/events
• DELETE /relay/sessions/{id}/events

This is the right layer for console events, network inspection, and raw CDP actions.

4. Shell execution

Use shell sessions when you need terminal commands or code execution in an isolated environment:

• POST /shell/sessions
• GET /shell/sessions
• POST /shell/exec
• DELETE /shell/sessions/{id}

Core endpoints

Browser automation

Endpoint	Purpose
POST /sessions	Create a browser session
GET /sessions	List sessions
DELETE /sessions/{session_id}	Stop a session
POST /commands	Execute tagged browser commands
POST /observe	Capture current session state
POST /browser_step	Execute commands with richer step context

Extraction

Endpoint	Purpose
POST /v1/scrape	Extract one page
POST /v1/crawl	Crawl multiple pages
POST /search	Search the web

Relay

Endpoint	Purpose
GET /relay/sessions	List relay-backed sessions
POST /cdp	Execute raw CDP on a session
GET /relay/sessions/{id}/events	Inspect buffered relay events
DELETE /relay/sessions/{id}/events	Clear relay events

Shell

Endpoint	Purpose
POST /shell/sessions	Create a shell session
GET /shell/sessions	List shell sessions
POST /shell/exec	Run a shell command
DELETE /shell/sessions/{id}	Stop a shell session

Examples

Scrape without managing a session

curl -X POST https://api.browsr.dev/v1/scrape \
  -H "x-api-key: $BROWSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown", "html"]
  }'

Create a session and run commands

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

curl -X POST https://api.browsr.dev/commands \
  -H "x-api-key: $BROWSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "SESSION_ID",
    "commands": [
      {"command":"navigate_to","data":{"url":"https://example.com"}},
      {"command":"get_title"}
    ]
  }'

Inspect a relay session

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

curl -X POST https://api.browsr.dev/cdp \
  -H "x-api-key: $BROWSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "RELAY_SESSION_ID",
    "method": "Runtime.evaluate",
    "params": {"expression":"1+1","returnByValue":true}
  }'

Execute in a shell session

curl -X POST https://api.browsr.dev/shell/sessions \
  -H "x-api-key: $BROWSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language":"python","timeoutSecs":300}'

curl -X POST https://api.browsr.dev/shell/exec \
  -H "x-api-key: $BROWSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id":"SHELL_SESSION_ID",
    "command":"python3 -c \"print(1+1)\""
  }'

Choosing the right surface

Use:

• scrape, crawl, or search for one-shot data retrieval
• sessions plus commands for multi-step browser workflows
• relay plus cdp when debugging a local browser
• shell when you need terminal or code execution