Browser API

Manage browser sessions and execute actions.

Endpoints

Method	Endpoint	Description
GET	/api/agents/{id}/browser	List sessions
POST	/api/agents/{id}/browser	Create session
DELETE	/api/agents/{id}/browser	Delete session
POST	/api/agents/{id}/browser/{sessionId}/execute	Execute action
GET	/api/agents/{id}/browser/{sessionId}/live-view	Get live view
POST	/api/agents/{id}/browser/{sessionId}/takeover	Request takeover

List Sessions

GET /api/agents/{id}/browser

Response

{
  "sessions": [
    {
      "id": "session-123",
      "status": "active",
      "headless": true,
      "viewport": {
        "width": 1280,
        "height": 720
      },
      "created_at": "2024-12-15T10:00:00Z",
      "last_activity": "2024-12-15T10:05:00Z"
    }
  ]
}

Create Session

POST /api/agents/{id}/browser
Content-Type: application/json

Request Body

{
  "headless": true,
  "viewport": {
    "width": 1920,
    "height": 1080
  },
  "user_agent": "Mozilla/5.0..."
}

Response

{
  "id": "session-123",
  "status": "active",
  "live_view_url": "https://browserbase.com/live/...",
  "created_at": "2024-12-15T10:00:00Z"
}

Delete Session

DELETE /api/agents/{id}/browser?id={sessionId}

Response

{
  "success": true
}

Execute Action

POST /api/agents/{id}/browser/{sessionId}/execute
Content-Type: application/json

Navigate

{
  "action": "navigate",
  "url": "https://example.com"
}

Click

{
  "action": "click",
  "selector": "#submit-button"
}

Type

{
  "action": "type",
  "selector": "#email",
  "text": "user@example.com"
}

Press

{
  "action": "press",
  "key": "Enter"
}

Screenshot

{
  "action": "screenshot",
  "full_page": false
}

Response:

{
  "success": true,
  "result": {
    "image": "data:image/png;base64,..."
  }
}

Extract

{
  "action": "extract",
  "selector": ".product-price",
  "attribute": "text"
}

Response:

{
  "success": true,
  "result": {
    "value": "$99.99"
  }
}

Scroll

{
  "action": "scroll",
  "direction": "down",
  "amount": 500
}

Wait

{
  "action": "wait",
  "selector": "#content",
  "state": "visible",
  "timeout": 5000
}

Multiple Actions

{
  "actions": [
    { "action": "navigate", "url": "https://example.com" },
    { "action": "wait", "selector": "#login" },
    { "action": "click", "selector": "#login" },
    { "action": "type", "selector": "#email", "text": "user@example.com" },
    { "action": "press", "key": "Enter" }
  ]
}

Response

{
  "success": true,
  "results": [
    { "action": "navigate", "success": true, "duration_ms": 1500 },
    { "action": "wait", "success": true, "duration_ms": 200 },
    { "action": "click", "success": true, "duration_ms": 50 },
    { "action": "type", "success": true, "duration_ms": 300 },
    { "action": "press", "success": true, "duration_ms": 10 }
  ],
  "total_duration_ms": 2060
}

Live View

GET /api/agents/{id}/browser/{sessionId}/live-view

Response

{
  "url": "https://browserbase.com/live/session-123",
  "expires_at": "2024-12-15T11:00:00Z"
}

Human Takeover

POST /api/agents/{id}/browser/{sessionId}/takeover
Content-Type: application/json

Request Body

{
  "reason": "CAPTCHA detected",
  "timeout": 300
}

Response

{
  "takeover_id": "takeover-123",
  "status": "pending",
  "takeover_url": "https://browserbase.com/takeover/...",
  "expires_at": "2024-12-15T10:05:00Z"
}

Session Status

Status	Description
active	Session is running
paused	Temporarily paused
takeover	Human control active
closed	Session ended
error	Session failed

Action Types

Action	Description
navigate	Go to URL
click	Click element
type	Enter text
press	Press key
screenshot	Capture image
extract	Get content
scroll	Scroll page
wait	Wait for condition
hover	Hover element
select	Select option
upload	Upload file
evaluate	Run JavaScript

Errors

Code	Description
400	Invalid action
404	Session not found
408	Action timeout
500	Browser error

Examples

Complete Flow

# Create session
SESSION=$(curl -X POST .../browser -d '{"headless": true}' | jq -r '.id')

# Navigate
curl -X POST ".../browser/$SESSION/execute" \
  -d '{"action": "navigate", "url": "https://example.com"}'

# Fill form
curl -X POST ".../browser/$SESSION/execute" \
  -d '{
    "actions": [
      {"action": "type", "selector": "#email", "text": "user@example.com"},
      {"action": "type", "selector": "#password", "text": "password"},
      {"action": "click", "selector": "#submit"}
    ]
  }'

# Screenshot
curl -X POST ".../browser/$SESSION/execute" \
  -d '{"action": "screenshot"}' | jq -r '.result.image' > screenshot.png

# Close session
curl -X DELETE ".../browser?id=$SESSION"