Browser

Oya Browser docs

REST and WebSocket API reference

Every Oya Browser REST route under /api, the command API with examples, and the WebSocket protocol browsers connect over.

REST API

Every route lives under /api and needs an Authorization: Bearer YOUR_API_KEY header; only /api/health and agent self-signup answer without one. The table leaves the prefix off: GET /browsers means GET https://oyabrowser.com/api/browsers. The machine-readable description is at /openapi.json. For the full route list, including auth, pool, cookies and admin config, read the REST API section of oyabrowser.com/llms.txt.

MethodEndpointDescription
GET/healthServer status + browser count
GET/browsersList your connected browsers
POST/browsers/startStart one ({ "persona": "auto" }), provider comes from your key; an endpoint another browser holds answers 409 endpoint_in_use
GET/browsers/:idOne browser with counters, health and its recent activity
POST/browsers/:id/stopStop it, destroys a cloud sandbox, releases a CDP session
POST/browsers/stopBulk: { "ids": [...] } or { "all": true }
GET/fleetTotals by health, provider and persona; usage and limits
POST/browsers/:id/commandSend command ({ "action": "...", "params": {} })
POST/browsers/:id/chatChat ({ "messages": [...] })
GET/live/:id?ticket=...SSE live view frame stream (single-use ticket)
GET/POST/mcp/:idMCP Streamable HTTP endpoint
GET/POST/personasList or create personas
DELETE/personas/:idDelete a persona (409 while in use)
PUT/personas/:idRename, set the cap or the proxy hint, never the device
POST/personas/:id/cloneA new persona of the same kind of device
POST/personas/previewThe fingerprint a set of choices would produce
GET/personas/optionsPlatforms and their coherent timezones and locales
PUT/personas/:id/mfaStore a second factor
POST/browsers/:id/captchaDetect and clear a CAPTCHA
POST/browsers/:id/mfaAnswer an MFA prompt
GET/usageThis key's usage, bucketed by hour
GET/auditThis key's audit history
GET/configThis key's settings, credentials masked
POST/configUpdate this key's settings

Command API Reference

Send commands via POST /api/browsers/:id/command. Each action uses only specific params, the rest are ignored.

Navigation Actions

ActionParamsDescription
navigateurl (required)Navigate to a URL
open_taburl (optional)Open a new tab
switch_tabtab_id (required)Activate a tab by ID
close_tabtab_id (optional, defaults to active)Close a tab
list_tabsnoneList all open tabs

Page Analysis Actions

ActionParamsDescription
analyzeformat?Full page + numbered elements, as toon (default), markdown or jsonl
read_pageselector (optional), limit (default 50)Lightweight element listing
screenshotnoneCapture page as PNG

Interaction Actions

ActionParamsDescription
clickselector (e.g. [data-ac-id="3"])Click an element
typeselector + textType into an input
press_keykey (e.g. Enter, Tab, Escape)Press a keyboard key
scrolldirection (up/down), amount (px, default 500)Scroll the page
waitselector, timeout (ms, default 10000)Wait for element to appear

Examples

Example
// Navigate to a page
{ "action": "navigate", "params": { "url": "https://google.com" } }

// Analyze current page (no params needed)
{ "action": "analyze" }

// Click element #3 from analyze results
{ "action": "click", "params": { "selector": "[data-ac-id=\"3\"]" } }

// Type into element #9
{ "action": "type", "params": { "selector": "[data-ac-id=\"9\"]", "text": "hello world" } }

// Press Enter
{ "action": "press_key", "params": { "key": "Enter" } }

// Scroll down
{ "action": "scroll", "params": { "direction": "down", "amount": 500 } }

// Screenshot (no params needed)
{ "action": "screenshot" }

// List all tabs
{ "action": "list_tabs" }

// Open new tab
{ "action": "open_tab", "params": { "url": "https://gmail.com" } }

// Switch to tab
{ "action": "switch_tab", "params": { "tab_id": 2 } }

// Close tab (omit tab_id to close active tab)
{ "action": "close_tab", "params": { "tab_id": 3 } }

// Wait for element
{ "action": "wait", "params": { "selector": ".results", "timeout": 10000 } }

// Read page elements (lightweight)
{ "action": "read_page", "params": { "limit": 20 } }

Typical Workflow

Example
1. navigate → go to the page
2. analyze  → understand the page, get element IDs
3. click / type / press_key / scroll → interact
4. analyze  → re-analyze after page changes (old IDs are invalid)
5. repeat until task is done

WebSocket Protocol

Browsers connect via WebSocket at wss://oyabrowser.com/ws.

Auth

First message from browser:

Example
{ "type": "auth", "api_key": "...", "browser_id": "...", "browser_name": "..." }

Server responds:

Example
{ "type": "auth_ok", "browser_id": "..." }

Commands

Server → Browser:

Example
{ "type": "cmd", "id": "uuid", "action": "analyze", "params": {} }

Browser → Server:

Example
{ "type": "cmd_result", "id": "uuid", "ok": true, "data": { ... } }

Ping/Pong

Both sides send { "type": "ping" } and respond with { "type": "pong" } every 15-20 seconds.

Live Stream

Server → Browser: { "type": "stream_start", "fps": 2 }

Browser → Server: { "type": "frame", "data": "data:image/jpeg;base64,..." }

Server → Browser: { "type": "stream_stop" }