# Browseit API (https://api.browseit.live)
Rent on-demand cloud browsers driven by AI. Auth: Authorization: Bearer byd_<key>.
Errors: JSON { error, code }. Rate limit: 240/min per key (30/min on /v1/intent), 429 + Retry-After.
OpenAPI: https://api.browseit.live/openapi.json. Health: GET https://api.browseit.live/ (no auth; /healthz is reserved by the platform).
Credit: GET /v1/me -> credit { period: monthly|lifetime, quotaUsd, spentUsd, remainingUsd, resetsAt } + usage (lifetime + thisMonth).

v2 engine (send engine:"v2"):
- POST /v1/tasks { engine:"v2", steps:[...<=25], browser?:"light"|"full", credentialId?, proxyId?, model?, continueOnError? } -> { ok, sessionId, results:[{type, ok, data|error, ms, model?, fallbackFrom?}], finalUrl, usage:{browserMs, proxyBytes, llm...}, timing:{readyMs,totalMs} }. Sync, up to 15 min, one fresh browser.
  steps: navigate{url} back forward reload wait{ms} act{instruction} observe{instruction} extract{instruction,schema?} agent{instruction,maxSteps?} screenshot{format?,fullPage?}->base64 content->{text,html} pdf->base64 save{kind?:png|pdf|dom}->Files ip evaluate{expression}->JSON viewport{width,height} tabs tab_new{url?} tab_switch{tabId} tab_close{tabId} save_login{domain,name?,rememberEverything?}
- POST /v1/sessions { engine:"v2", url?, browser?, credentialId?, proxyId?, cdp? } -> 201 { session:{id,...}, connectUrl:"wss://.../s?t=<single-use, 60s>" }. Raw CDP (account grant): use .../cdp?t=... with Playwright chromium.connectOverCDP; one shared context (use browser.contexts()[0]; newContext is refused).
- POST /v1/sessions/:id/connect -> fresh connectUrl; resumes from the last save point. One connection lasts at most ~55 min (close 4005 = reconnect). Idle 5 min ends it.
- Close codes: 1000 ended, 4001 idle, 4002 out of credit, 4003 stopped, 4005 max time (reconnect), 4006 control plane unreachable.
- Scheduled / saved v2 runs: POST /v1/jobs { name, engine:"v2", steps:[...] | script (+files, entry, env), schedule:{cron,tz}?, delivery:{ webhooks?, email?:"failure"|"always"|"never", discordWebhookUrl?, report? } } -> runs inside Browseit on the cron (or POST /v1/jobs/:id/run). Each run: GET /v1/jobs/:id/runs/:runId -> { status, stepResults, fileIds, reportUrl }. Delivery: your webhooks (run.finished/run.failed with checks, fileIds, reportUrl), email, a Discord post with screenshots, a stable report link.
- POST /v1/scripts { script | files+entry, env?, timeoutSec?<=780, browser?, credentialId?, proxyId? } (account grant) -> { ok, runId, exit:{code,signal,timedOut}, result (your /results/result.json), files:[{name,size,base64}], log, usage, timing }. An unchanged Playwright script: chromium.launch() gives it a fresh Browseit browser; it writes /results. Sandboxed: no network except that browser, no child processes, files only in its own folder, 1 GB memory. GET /v1/scripts/:id = the run record.
- Errors: { error, code } with code no_credit (402), quota (429, concurrent browsers), forbidden (403), bad_url (400), ended (409).

Classic:
- POST /v1/tasks  one-shot; body: one of act | instructions(+schema) | observe, optional url/sessionId/model. Sync (~95s). -> { ok, data, usage, taskId }. GET /v1/tasks/:id to fetch later.
- POST /v1/agent  autonomous multi-step in a session; body: { sessionId, instruction, url?, credentialId?, maxSteps? }. Sync (~95s).
- Sessions: POST /v1/sessions { url?, contextId?, credentialId?, proxyId?, cookies? } -> { session:{ id, liveUrl } } (embed liveUrl in an iframe). GET/DELETE /v1/sessions/:id. :id/navigate|heartbeat|stats|ip|content|screenshot|pdf|agent-progress|save-login. Idempotency-Key supported on create. Ping heartbeat ~60s or the session is reaped.
- Jobs (background, up to 5h): POST /v1/jobs { name, steps:[{instruction,url?}], schedule:{cron,tz}?, contextId?, credentialId?, proxyId?, continueOnError? }. POST /v1/jobs/:id/run -> { runId } (poll GET /v1/jobs/:id/runs/:runId). :id/runs, runs/:runId/cancel. Scheduled runs fire on the cron automatically. A run that can no longer finish is closed as failed with a reason.
- Contexts (login-once profiles), Credentials (saved logins, write-only; auto-refreshed), Proxies (BYO egress), Files (exported artifacts), Webhooks (run.finished/run.failed/session.ended, HMAC-signed), Account (/v1/me usage + credit, /v1/keys, /v1/models). Models ending in :free (listed in /v1/models "free") are free: rate-limited, prompts may be logged by the provider; avoid for private/signed-in data; on failure a step falls back to the paid "fallback" model.
Longer than ~95s or unattended? Use a Job, or a v2 task (up to 15 min).