API reference
Every endpoint, parameter and header in one place.
Basics
| Base URL | https://api.staging.boxline.dev |
|---|---|
| Authentication | x-api-key: <key> or Authorization: Bearer <key> on every request |
| Request bodies | JSON with content-type: application/json, except file writes, which send the raw bytes |
| Errors | Matching HTTP status and {"error": {"code": "not_found", "message": "…"}} |
curl https://api.staging.boxline.dev/v1/usage \
-H "x-api-key: $BOXLINE_API_KEY"Error codes you will meet often: concurrency_limit (429, too many running sessions for your plan), plan_limit (403, e.g. a timeout above your plan’s maximum), session_not_running (409) and not_found (404).
With a proxy you may also see plan_limit (402, your plan does not include the platform’s proxies), spend_limit (402, this month’s proxy data is used up) and proxy_unavailable (503). See Proxies.
captcha_timeout: a plain-English step waited 4 minutes for someone to solve a CAPTCHA. It comes in the action result (ok: false, code: "captcha_timeout"), and the SDKs raise it with status 409. The SDKs’ waitForHuman / wait_for_human raise the same code (408) when their own timeout runs out. See CAPTCHAs.
WebSockets and live view
| Session field | What it is |
|---|---|
connectUrl | Chrome DevTools Protocol WebSocket (/v1/connect?sessionId=…&token=…) for Playwright or Puppeteer. |
liveUrl | Live view HTML page (/live/:id?token=…). Open it to watch the browser or take control, for example to solve a CAPTCHA. Anyone with it can control the browser: treat it like a password. Only Boxline’s own apps can frame it; embedding it on your site needs per-project embed origins, not available yet. |
terminalUrl | Terminal WebSocket (/v1/sessions/:id/terminal?token=…). Send JSON text frames {"type":"input","data":"…"} or {"type":"resize","cols":N,"rows":N}; receive raw terminal output as binary frames. |
All endpoints
| Endpoint | Description |
|---|---|
POST/v1/sessions | Create a session. |
GET/v1/sessions | List sessions. |
GET/v1/sessions/:id | Get a session. Besides its settings, it has attention: { type: "captcha", kind, url, tabId, since } while a CAPTCHA waits for a person, otherwise null. |
GET/v1/sessions/:id/events | The session's log, oldest first: console, network, navigation, error, lifecycle, action, exec and captcha events. GET /v1/sessions/:id/events/stream sends them live. |
PATCH/v1/sessions/:id | Change a running or paused session. |
POST/v1/sessions/:id/proxy/rotate | Give the session's proxy a new IP; a sticky session keeps one IP until you call this. 400 without a proxy. |
POST/v1/sessions/:id/release | End a session (also DELETE /v1/sessions/:id). Billing stops. |
POST/v1/sessions/:id/pause | Save browser state and files, free the machine and stop billing. |
POST/v1/sessions/:id/resume | Resume a paused session. Connecting or calling actions, exec or files also resumes it. |
POST/v1/sessions/:id/move | Move a running session to a fresh machine. Clients reconnect to the same connectUrl. |
GET/v1/sessions/:id/live | Get fresh signed live view and terminal URLs. |
POST/v1/sessions/:id/actions | Run one action or a list of actions next to the browser. |
POST/v1/sessions/:id/browser/cookies/export | Write the browser's cookies as a Netscape cookie file (for curl -b / wget) in the workspace. |
POST/v1/sessions/:id/exec | Run a command in the session's persistent shell. |
POST/v1/sessions/:id/shell/restart | Restart a persistent shell. |
GET/v1/sessions/:id/files | Read a file, or list a directory with list=1. |
PUT/v1/sessions/:id/files | Write a file. The request body is the raw bytes. |
DELETE/v1/sessions/:id/files | Delete a file. |
GET/v1/sessions/:id/files/wait | Wait for a finished file matching a glob. 408 if none appears in time. |
POST/v1/contexts | Create a context for saved browser state (cookies and localStorage). |
GET/v1/contexts/:id | Get a context, including inUseBy (the running session using it, or null). |
DELETE/v1/contexts/:id | Delete a context. 409 while a running session uses it. |
POST/v1/fetch | Open a URL in a real browser and return its content. captcha is the kind of CAPTCHA waiting for a person on the page (e.g. "recaptcha"), or null. |
POST/v1/screenshot | Screenshot of a URL in a fresh browser context. Headers x-final-url, x-page-status, x-page-title (URI-encoded), x-page-captcha (the kind of CAPTCHA waiting for a person, or empty) and x-render-ms describe the page. |
POST/v1/pdf | PDF of a URL, printed like Chrome's Save as PDF. Same headers as screenshot. |
POST/v1/extract | Structured data from pages: they load in a real browser, then a model follows prompt and/or fills schema. |
POST/v1/crawl | Start a crawl from a URL in the background (breadth-first, robots.txt respected). Poll GET /v1/crawl/:id for the pages (each has captcha: a CAPTCHA kind, or null); POST /v1/crawl/:id/cancel stops it. |
POST/v1/agent/runs | Start a Claude-powered agent run. |
GET/v1/agent/runs/:id | Get a run. status is "running", "paused", "completed", "failed" or "canceled". While paused, handover is { by: "user" | "agent" | "captcha", reason }; "captcha" runs continue by themselves once a person has solved it, and fail after 5 minutes. |
GET/v1/agent/runs/:id/events | Server-sent events, one per step. |
GET/v1/usage | Your account's usage. |
GET/v1/pricing | The public price table, including proxies: { residentialPerGb, datacenterPerGb, customPerGb }. |
Sessions
POST/v1/sessions
Create a session. Returns 201 Session. Guide: Sessions.
| Name | Type | Description |
|---|---|---|
browser | boolean | Start Chrome. Default true. |
shell | boolean | Add a bash shell (Python, Node, ffmpeg and sudo included). Default false. |
timeout | number | Lifetime in seconds. Default 300, minimum 60, maximum set by your plan. |
keepAlive | boolean | Keep a browser-only session running after its last CDP client disconnects. Default false. |
viewport | object | { width, height }, 200×200 to 3840×2160. |
userMetadata | object | Any JSON; returned on the session. |
context | object | { id, persist? }: load a context; with persist, save back on end. |
proxy | true | object | array | Send the session's traffic through a proxy: true (a residential proxy in the US), { type: "residential" | "datacenter", country?, state?, city?, ip?, scope? }, { type: "custom", server, username?, password?, ip?, scope? }, or a list of up to 10 rules by site (each a proxy or { type: "none" }, with an optional domainPattern; the first match wins). ip defaults to "sticky", scope to "browser". |
captcha | string | What agent runs and plain-English steps do when a CAPTCHA waits for a person: "ask" (default) waits until someone solves it in the live view (agent runs up to 5 minutes, steps up to 4); "ignore" carries on. The platform never solves CAPTCHAs. |
GET/v1/sessions
List sessions. Returns { data: [Session] }. Guide: Sessions.
| Name | Type | Description |
|---|---|---|
status | string | RUNNING, PAUSED, COMPLETED or ERROR. |
limit | number | Maximum number of sessions to return. |
GET/v1/sessions/:id
Get a session. Besides its settings, it has attention: { type: "captcha", kind, url, tabId, since } while a CAPTCHA waits for a person, otherwise null. Returns Session. Guide: Sessions.
GET/v1/sessions/:id/events
The session's log, oldest first: console, network, navigation, error, lifecycle, action, exec and captcha events. GET /v1/sessions/:id/events/stream sends them live. Returns { data: [Event], nextAfter }. Guide: Logs & replay.
| Name | Type | Description |
|---|---|---|
types | string | Comma-separated event types, e.g. captcha or console,error. |
after | number | Only events after this seq; pass back nextAfter to page forward. |
limit | number | Maximum number of events. Default 500, at most 2000. |
PATCH/v1/sessions/:id
Change a running or paused session. Returns Session. Guide: Session control.
| Name | Type | Description |
|---|---|---|
keepAlive | boolean | Keep a browser-only session running after its last CDP client disconnects. |
userMetadata | object | Replaces the session's metadata. |
proxy | true | object | array | null | A new proxy or list of rules (same shape as on create), or null to remove it. New connections use it at once. Left out: unchanged. |
captcha | string | "ask" or "ignore" (see create). Left out: unchanged. |
POST/v1/sessions/:id/proxy/rotate
Give the session's proxy a new IP; a sticky session keeps one IP until you call this. 400 without a proxy. Returns Session. Guide: Proxies.
POST/v1/sessions/:id/release
End a session (also DELETE /v1/sessions/:id). Billing stops. Returns Session (COMPLETED). Guide: Sessions.
POST/v1/sessions/:id/pause
Save browser state and files, free the machine and stop billing. Returns Session (PAUSED). Guide: Move, pause & resume.
POST/v1/sessions/:id/resume
Resume a paused session. Connecting or calling actions, exec or files also resumes it. Returns Session (RUNNING). Guide: Move, pause & resume.
POST/v1/sessions/:id/move
Move a running session to a fresh machine. Clients reconnect to the same connectUrl. Returns { session, timings: { captureMs, acquireMs, restoreMs, totalMs } }. Guide: Move, pause & resume.
GET/v1/sessions/:id/live
Get fresh signed live view and terminal URLs. Returns { liveUrl, terminalUrl }. Guide: Browser.
Browser
POST/v1/sessions/:id/actions
Run one action or a list of actions next to the browser. Returns { results: [{ ok, action, value?, error?, code?, ms }] }. Guide: Browser.
| Name | Type | Description |
|---|---|---|
actions | array | goto, click, fill, type, press, scroll, wait, screenshot, content, evaluate, upload, tabs, newTab, switchTab, closeTab, back, forward, reload, step (plain English; waits up to 4 minutes while a CAPTCHA waits for a person, with the session's captcha option "ask"). Or send a single action object as the body. |
POST/v1/sessions/:id/browser/cookies/export
Write the browser's cookies as a Netscape cookie file (for curl -b / wget) in the workspace. Returns { path, count }. Guide: Shell.
| Name | Type | Description |
|---|---|---|
path | string | Where to write it. Default cookies.txt. |
Shell
POST/v1/sessions/:id/exec
Run a command in the session's persistent shell. Returns { stdout, stderr, exitCode, timedOut, truncated, durationMs }, or an NDJSON stream. Guide: Shell.
| Name | Type | Description |
|---|---|---|
command | string | The bash command to run. |
timeoutMs | number | Default 120,000, maximum 3,600,000. |
cwd | string | Working directory inside the workspace. |
env | object | Extra environment variables. |
shell | string | false | "default", another name for a separate persistent shell, or false for a fresh process. |
stream | boolean | Stream {type:"stdout"|"stderr", data} lines, then {type:"exit", …}. |
POST/v1/sessions/:id/shell/restart
Restart a persistent shell. Returns 204. Guide: Shell.
| Name | Type | Description |
|---|---|---|
shell | string | Which shell. Default "default". |
Files
GET/v1/sessions/:id/files
Read a file, or list a directory with list=1. Returns File bytes, or { path, entries: [{ name, type, size, mtime }] }. Guide: Files.
| Name | Type | Description |
|---|---|---|
path | string | Relative to /workspace, or absolute inside it. |
list | 1 | List the directory instead of reading a file. |
PUT/v1/sessions/:id/files
Write a file. The request body is the raw bytes. Returns { path, size }. Guide: Files.
| Name | Type | Description |
|---|---|---|
path | string | Where to write the file. |
DELETE/v1/sessions/:id/files
Delete a file. Returns 204. Guide: Files.
| Name | Type | Description |
|---|---|---|
path | string | The file to delete. |
GET/v1/sessions/:id/files/wait
Wait for a finished file matching a glob. 408 if none appears in time. Returns { path, size }. Guide: Files.
| Name | Type | Description |
|---|---|---|
pattern | string | Glob in the last segment, e.g. downloads/*.csv. |
timeoutMs | number | How long to wait. |
Contexts
POST/v1/contexts
Create a context for saved browser state (cookies and localStorage). Returns { id, sizeBytes, createdAt, updatedAt }. Guide: Contexts.
GET/v1/contexts/:id
Get a context, including inUseBy (the running session using it, or null). Returns { id, sizeBytes, createdAt, updatedAt, inUseBy }. Guide: Contexts.
DELETE/v1/contexts/:id
Delete a context. 409 while a running session uses it. Returns 204. Guide: Contexts.
Fetch, screenshot, PDF, extract and crawl
POST/v1/fetch
Open a URL in a real browser and return its content. captcha is the kind of CAPTCHA waiting for a person on the page (e.g. "recaptcha"), or null. Returns { url, finalUrl, status, title, content, captcha, ms }. Guide: Fetch API.
| Name | Type | Description |
|---|---|---|
url | string | The page to fetch. |
format | string | "markdown", "html" or "text". |
timeoutMs | number | How long to wait for the page. |
waitUntil | string | "load", "domcontentloaded" or "networkidle". |
proxy | true | object | array | Load the page through a proxy (same shape as on sessions). ip defaults to "rotating". |
POST/v1/screenshot
Screenshot of a URL in a fresh browser context. Headers x-final-url, x-page-status, x-page-title (URI-encoded), x-page-captcha (the kind of CAPTCHA waiting for a person, or empty) and x-render-ms describe the page. Returns PNG or JPEG bytes. Guide: Proxies.
| Name | Type | Description |
|---|---|---|
url | string | The page. Required. |
fullPage | boolean | The whole page instead of the viewport. |
format | string | "png" or "jpeg". |
quality | number | JPEG quality, 1 to 100. |
selector | string | Capture only the first element that matches. |
viewport | object | { width, height }. |
waitUntil | string | When the page counts as loaded: "load", "domcontentloaded" or "networkidle". |
delayMs | number | Extra wait after the page loads, up to 10,000. |
timeoutMs | number | How long to wait for the page. |
proxy | true | object | array | Load the page through a proxy (same shape as on sessions). ip defaults to "rotating". |
POST/v1/pdf
PDF of a URL, printed like Chrome's Save as PDF. Same headers as screenshot. Returns PDF bytes. Guide: Proxies.
| Name | Type | Description |
|---|---|---|
url | string | The page. Required. |
paper | string | "A4", "A3", "A5", "Letter", "Legal" or "Tabloid". |
landscape | boolean | Landscape instead of portrait. |
printBackground | boolean | Print background colours and images. Default true. |
scale | number | Zoom of the printed page. |
waitUntil | string | When the page counts as loaded: "load", "domcontentloaded" or "networkidle". |
delayMs | number | Extra wait after the page loads, up to 10,000. |
timeoutMs | number | How long to wait for the page. |
proxy | true | object | array | Load the page through a proxy (same shape as on sessions). ip defaults to "rotating". |
POST/v1/extract
Structured data from pages: they load in a real browser, then a model follows prompt and/or fills schema. Returns { data, pages: [{ url, finalUrl, status, title }], provider, model, usage, ms }. Guide: Proxies.
| Name | Type | Description |
|---|---|---|
url or urls | string or string[] | One page, or up to 10. |
prompt | string | What to extract. prompt or schema is required. |
schema | object | JSON Schema the result must match. |
provider, model | string | Which model to use; a fast, low-cost one by default. |
waitUntil | string | When the page counts as loaded: "load", "domcontentloaded" or "networkidle". |
delayMs | number | Extra wait after the page loads, up to 10,000. |
timeoutMs | number | How long to wait for the page. |
proxy | true | object | array | Load the pages through a proxy (same shape as on sessions). ip defaults to "rotating". |
POST/v1/crawl
Start a crawl from a URL in the background (breadth-first, robots.txt respected). Poll GET /v1/crawl/:id for the pages (each has captcha: a CAPTCHA kind, or null); POST /v1/crawl/:id/cancel stops it. Returns 201 crawl job. Guide: Proxies.
| Name | Type | Description |
|---|---|---|
url | string | Where to start. Required. |
maxPages | number | Default 20, maximum 200. |
maxDepth | number | Default 3, maximum 10. |
sameHost | boolean | Stay on the start URL's host. Default true. |
include, exclude | string[] | Regular expressions for URLs to follow or skip. |
format | string | "markdown", "text" or "html". |
waitUntil | string | When the page counts as loaded: "load", "domcontentloaded" or "networkidle". |
delayMs | number | Extra wait after the page loads, up to 10,000. |
timeoutMs | number | How long to wait for the page. |
proxy | true | object | array | Crawl through a proxy (same shape as on sessions). ip defaults to "sticky": one IP for the whole crawl. |
Agent
POST/v1/agent/runs
Start a Claude-powered agent run. Returns 201 { id, status, sessionId }. Guide: Agent API.
| Name | Type | Description |
|---|---|---|
task | string | What the agent should do. Required. |
sessionId | string | Use an existing session. |
browser | boolean | New session gets a browser. Default true. |
shell | boolean | New session gets a shell. Default false. |
maxSteps | number | Default 30, maximum 100. |
effort | string | "low", "medium", "high", "xhigh" or "max". |
keepSession | boolean | Keep the session the run created. Default false. |
proxy | true | object | array | A proxy for the session the run creates (same shape as on sessions). Ignored with sessionId: that session's proxy applies. |
GET/v1/agent/runs/:id
Get a run. status is "running", "paused", "completed", "failed" or "canceled". While paused, handover is { by: "user" | "agent" | "captcha", reason }; "captcha" runs continue by themselves once a person has solved it, and fail after 5 minutes. Returns { id, status, task, sessionId, provider, model, steps, result, error, usage, handover }. Guide: Agent API.
GET/v1/agent/runs/:id/events
Server-sent events, one per step. Returns text/event-stream. Guide: Agent API.
Usage
GET/v1/usage
Your account's usage. Returns { sessions, browserSeconds, sandboxVcpuSeconds, sandboxGibSeconds, proxy: { residentialGb, datacenterGb, customGb, costUsd }, costUsd, byDay: [{ date, seconds, costUsd }] }. costUsd includes proxy data. Guide: Pricing.
GET/v1/pricing
The public price table, including proxies: { residentialPerGb, datacenterPerGb, customPerGb }. Returns Price table. Guide: Pricing.
These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.