Docs / API reference
API Reference
Drive a real, hosted browser — open pages, read them, click/type, extract data. All routes below are served from https://app.getagentbrowser.com. This page is rendered directly from the live, machine-readable contract at /.well-known/openapi.yaml (OpenAPI 3.0.1) — also published as /.well-known/ai-plugin.json for GPT-plugin discovery.
Authentication
Every REST request carries an Authorization: Bearer header with a workspace API key. AgentBrowser's separate MCP server surface (clients & integrations) uses its own short-lived, self-issued OAuth2 client-credentials tokens instead — see the raw spec's components.securitySchemes.mcpOAuth for that flow.
POST /api/sessions
Open a hosted browser session on a live render node.
Operation ID: createSession
Request body (optional)
| Field | Type | Description |
|---|---|---|
url | string | Optional public HTTP(S) URL to open immediately (default about:blank). Exact about:blank is allowed; credentials, loopback, private, link-local, metadata, mixed public/private DNS answers, and every other scheme are rejected. |
profile | string | mobile emulates an iPhone-class device (viewport, UA, touch).
|
record | boolean | Capture video + console/network/DOM events, downloadable as a tar.gz. Not supported when cdp is true. |
dom | boolean | Also record an rrweb-style DOM track. Not supported when cdp is true. |
no_video | boolean | Skip the mp4 (events only). Not supported when cdp is true. |
cdp | boolean | Raw-CDP session: allocate a dedicated, isolated browser you drive over the Chrome DevTools Protocol (Playwright/Puppeteer connectOverCDP). Node-enforced public-only egress remains active. The response includes cdp_url; the act verb surface does not apply, and record/dom/no_video are rejected. |
region | string | Preferred render region (best-effort). The plane routes to a node in this region when one has capacity, else the least-loaded node anywhere. |
Responses
200
Session created.
| Field | Type | Description |
|---|---|---|
session_id | string | |
cdp_url | string | Present when cdp:true — the preferred complete wss:// URL carrying a short-lived, session-scoped ticket; hand it to connectOverCDP unchanged. Alternatively connect to /api/sessions/{id}/cdp and send the workspace gbk_ API key in an Authorization: Bearer header. Never put a reusable API key in a query string. |
400
Invalid options, including caller proxy/bypass settings or hosted recorder options combined with cdp:true.
503
No render node available.
POST /api/sessions/{id}/act
Drive the session with a verb.
Operation ID: act
Path parameters
| Param | In | Type | |
|---|---|---|---|
id | path | string | required |
Request body (required)
| Field | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
verb required | string | The full canonical verb set, kept in sync with cmd/gb-noded's action switch by this repo's internal/conformance conformance check (P2-210) — a go test failure blocks any release that lets this list drift from what the node/MCP/SDK surfaces actually support.
| ||||||||||||
url | string | for navigate, new_tab | ||||||||||||
ref | string | an [e#] ref from snapshot (click/type) | ||||||||||||
selector | string | CSS selector (click/type/extract) | ||||||||||||
fields | object (map of string → string) | Object mapping result names to CSS selectors for extract_all; response values use the same names and are null when no element matches. | ||||||||||||
text | string | text to type | ||||||||||||
expression | string | JS to evaluate | ||||||||||||
predicate | string | JS predicate for wait_for | ||||||||||||
secret | string | vault secret name (login) | ||||||||||||
cookies | array of objects | Chrome DevTools Protocol CookieParam objects passed to Network.setCookies for set_cookies. | ||||||||||||
x | number | viewport x px (click_at/move_to/drag) | ||||||||||||
y | number | viewport y px (click_at/move_to/drag) | ||||||||||||
to_x | number | drag end x px | ||||||||||||
to_y | number | drag end y px | ||||||||||||
value | string | option to choose (select) | ||||||||||||
checked | boolean | desired state (check) | ||||||||||||
key | string | key to press, e.g. Enter (press) | ||||||||||||
dx | integer | horizontal scroll px (scroll) | ||||||||||||
dy | integer | vertical scroll px (scroll) | ||||||||||||
file_data_base64 | string | base64 file bytes for set_file_input (selector/ref pick the input) | ||||||||||||
download_guid | string | for wait_for_download/get_download/cancel_download; empty waits for the next download | ||||||||||||
timeout_ms | integer | for wait_for_download/wait_for_dialog/wait_for_popup/wait_for_response/cancel_download | ||||||||||||
accept | boolean | accept (true) or dismiss (false) the pending dialog (handle_dialog) | ||||||||||||
prompt_text | string | text to answer a JS prompt() with (handle_dialog) | ||||||||||||
tab_id | string | for switch_tab/close_tab | ||||||||||||
tab_index | integer | 0-based tab index, alternative to tab_id (switch_tab) | ||||||||||||
url_pattern | string | URL substring match (wait_for_response) | ||||||||||||
method | string | HTTP method filter, e.g. POST (wait_for_response) | ||||||||||||
request_id | string | network request id from wait_for_response (get_response_body) | ||||||||||||
patterns | array of string | URL substrings to block (block_requests) — matches either patterns or resource_types. | ||||||||||||
resource_types | array of string | CDP Network.ResourceType values to block, e.g. image, stylesheet, font (block_requests). | ||||||||||||
overrides | array of objects | Replaces the session's full request-header-override rule list (set_header_overrides). Reliable for ordinary headers; Chrome recomputes a few browser-managed ones (notably Referer) after request interception regardless of what this call sends, so a remove rule on those is not guaranteed to reach the real outgoing request — a verified Chrome/CDP limitation, not a bug in this API.
| ||||||||||||
reason | string | why human takeover is needed (request_human_takeover) | ||||||||||||
storage_state | object (free-form) | cookies + per-origin localStorage previously returned by export_storage_state (import_storage_state). |
Responses
200
Result of the verb (shape depends on the verb).
| Field | Type | Description |
|---|---|---|
ok | boolean | |
outline | string | for snapshot |
text | string | for read_page/extract |
value | any | for evaluate |
png_base64 | string | for screenshot |
pdf_base64 | string | for pdf |
404
Unknown session (or not yours).
DELETE /api/sessions/{id}
Close the session (billed for wall-time held).
Operation ID: closeSession
Path parameters
| Param | In | Type | |
|---|---|---|---|
id | path | string | required |
Responses
200
Closed.
| Field | Type | Description |
|---|---|---|
ok | boolean | |
billed_seconds | number |