API reference

POST/run

Run a goal synchronously on an authorized target (~10 credits).

A SIGN-IN run (credentials/account/login-worded goal) that hits a 2FA/approval wall it can't auto-resolve PARKS by default: the 200 body is { status:"paused", sessionId, reason, challenge } instead of a completed run — resume it via POST /runs/{id}/resume (or hand a texted/typed code via the streaming /live/resume). Set hitl:false to opt out and get a plain needs-human miss instead. A free-text goal in the { target, goal } shape is a 400 (goal is a named/compiled skill; use { url, prompt, success } for free text).

POST/live

Run a goal and stream the LIVE browser view back as Server-Sent Events (~10 credits).

Same body as /run, but the response is a live SSE screencast of the browser: an `event: meta` frame with { runId }, then `event: frame` JPEG frames, then a terminal `event: result`. The run is recorded, so a durable video is replayable afterwards via GET /runs/{id}/video. Metered like /run (higher-of the ~10-credit floor vs LLM COGS); settles once on the terminal frame or disconnect (failed/no-result → full refund).

POST/live/resume

Hand a 2FA code (or cancel) to a live run holding on an await-user step.

When a live /live run hits a login second factor it cannot auto-resolve, its SSE emits an `event: step` with `type:"await-user"` carrying a `token`, a `challenge` (sms-code | totp | email-code | app-approval) and a human `reason`. POST that `token` here with the user-supplied `code` (or `cancel:true`) to unblock the run — it continues on the SAME open SSE, no new connection. Not billed here (the parent run owns metering).

GET/runs

List this tenant's runs (newest first, paginated).

GET/runs/{id}

Read a single run: status, success, masked action path, credits, video, timestamps.

POST/runs/{id}/resume

Continue a paused (HITL) sync run after an out-of-band approval.

When a sync /run pauses for human action it returns `{ status:"paused", sessionId }`. Once the step is completed out of band (e.g. a phone approval), POST the `sessionId` here to finish the run on the same parked browser session. Charges the flat run floor on completion; still-paused → refunded and returns paused again. This is the continuation channel — a texted/typed CODE goes to POST /live/resume on the streaming path instead.

POST/runs/{id}/input

Drive a paused run's browser by hand (click / type / key / scroll / goto).

The companion to /runs/{id}/resume. Resume hands back a verification CODE; this hands back an INTERACTION, so a person (or an agent reading a screenshot) can finish a step the agent could not — typically a sign-in on a site that blocks automated login, or one you hold no credential for. Coordinates are FRACTIONS of the viewport (0..1 from the top-left), not pixels: they are hit-tested server-side against the observed element map, so a click lands correctly whatever the viewer's size. Typed text is redacted from the stream and never stored. There is no "done" call — the run re-checks the page after every interaction and continues by itself once the block clears.

GET/runs/{id}/stream

Watch a paused run's browser live (SSE screencast) so you can drive it.

Server-sent events: `meta`, then `frame` (base64 JPEG) until you disconnect. Drives no agent and costs no credits — it mirrors a browser that is already open and waiting. Pair with POST /runs/{id}/input.

GET/runs/{id}/video

Stream a run's recorded video (only if the run was created with record:true).

Returns the recorded browser video bytes for a run that opted into recording. Served from durable storage (lazily persisted from the engine on first view). 404 when the run is not this tenant's, was not recorded, or the recording is no longer available.

POST/agentdeprecated

DEPRECATED alias for POST /run with {"stealth":true} — prefer that. Forces the full anti-detection stack.

DEPRECATED — a thin alias for POST /run with {"stealth":true,"humanize":true,"platformProxy":true}. Prefer calling /run directly with "stealth": true. In ONE call it forces stealth-fleet routing, human-mimicry timing, and sticky residential egress. Requires the same REQUIRED "authorized": true attestation and Pro/Enterprise plan as any stealth /run — now enforced by /run itself (the single source of truth), so /run {stealth:true} and /agent gate identically. Billed like a stealth /run: higher-of(~10-credit floor, LLM COGS) plus a per-SUCCESS stealth surcharge.

POST/dispatch

Semantic cache: match to a compiled skill (hit) or compile + cache (miss).

GET/skills

List this tenant's compiled skills.

POST/skills

Compile a skill — discover + minimize (~50 credits).

POST/skills/{name}/run

Deterministically replay a compiled skill — no LLM (~1 credit).

GET/library

Search the cross-tenant shared skill corpus — metadata only (free).

GET/cache/stats

Semantic-cache analytics for this tenant — hit rate + credits saved (free, no charge).

Reduces this tenant's runs over a rolling window into per-mode counts (skill = cache HIT, adapt = cross-tenant ADAPT, compile = MISS, run/job = uncached), a cache hit_rate = (skill+adapt)/(skill+adapt+compile), total credits_charged, and estimated_credits_saved (credits the cache HITs/ADAPTs saved versus cold compiles). Read-only metadata lookup — does not reserve or charge credits.

GET/templates

List the extraction-template catalog used by /extract and /etl (public, no key).

Per-host + generic-metadata templates that extract structured data deterministically (zero LLM). Optional ?url= reports which template matches that URL.

GET/jobs

List this tenant's recent async jobs.

POST/jobs

Submit a goal as an async job (~10 credits). Returns 202 { jobId }.

Optionally pass callbackUrl/callbackSecret to receive an HMAC-signed result webhook on completion. Like /run, a SIGN-IN job that hits a 2FA/approval wall PARKS by default — GET /jobs/{id} then reports status:"paused" with a sessionId (resume via POST /runs/{id}/resume); set hitl:false to opt out.

GET/jobs/{id}

Poll an async job; settles credits on first terminal status.

GET/jobs/{id}/stream

Stream an async job's status as Server-Sent Events (an alternative to polling).

Emits `event: status` frames ({ jobId, status, success, steps, error }) as the engine transitions the job, then a final authoritative frame, then closes. Billing settles once on close (complete → charge, failed/cancelled → refund); a client that disconnects early settles on its next poll.

POST/jobs/{id}/cancel

Cancel a running async job — full refund of the reserved credits.

Best-effort aborts the in-flight engine work, then flips the run to cancelled and refunds the reservation in full. Idempotent: cancelling an already-terminal job is a no-op that returns its current state with cancelled:false.

POST/search

Web search across blended sources (Brave web/discussions/news/faq + Hacker News, deduped, each result tagged with source). Shallow (default): sync ranked results (~3 cr) + optional fetch (+1 cr/page). Deep (depth:"deep"): async job, scrapes top N (3 cr + 5 cr/page), returns 202 { jobId }.

POST/extract

Extract structured JSON from a page with an LLM (metered, ~5-credit floor).

POST/screenshot

Capture a single page as a PNG (flat ~1 credit, no LLM cost).

POST/map

Discover all URLs of a site fast — sitemap + robots + shallow link scan (flat ~2 credits, no LLM).

POST/crawl

Crawl an entire site as an async job — billed per page (~3 credits/page). Returns 202 { jobId }.

Poll GET /jobs/{id} for the result (an array of pages). Optionally pass callbackUrl/callbackSecret for a completion webhook.

POST/etl

General ETL: extract → transform (clean + optional schema) → chunk → embed → load into the queryable content store.

Domain-agnostic ingest of any source (url | html | text), one or many per call. Embedding is ON by default (set embedding:false for store-only; store:false to return content without persisting). Billed per source: higher-of(~5-credit floor, metered LLM COGS) — only schema/fields extraction incurs LLM cost.

POST/etl/query

Semantic search over content ingested via /etl — top-k similar chunks with source url/title (flat 1 credit, no LLM).

GET/monitors

List this tenant's monitors (secrets excluded).

POST/monitors

Create a monitor that watches a page on a schedule and pushes a signed webhook on change.

GET/monitors/{id}

Read a single monitor (secrets excluded).

PATCH/monitors/{id}

Update / pause / resume a monitor (active, interval, callback, selector, watch spec).

DELETE/monitors/{id}

Delete a monitor and its check history.

GET/monitors/{id}/history

A monitor's recent check history (changed/unchanged/error + value excerpts).

GET/connect/sessions

List connect links and whether each sign-in was completed.

Use this to check whether the user finished the sign-in before re-running the task. Never returns the token.

POST/connect/sessions

Mint a link that lets a HUMAN sign into a site, so later runs are already logged in.

The answer to `code: "credential_missing"`, and to sites that hard-challenge automated logins from datacenter IPs and cannot be signed into by an agent at all. Returns a single-use `url`. Send your end-user there; they complete the sign-in (password, 2FA, CAPTCHA) in a Twin-Browser-hosted browser, and the resulting session is captured. Re-run the original task afterwards and it restores that session (`sessionRestored: true`) — no credentials, no 2FA. OAuth-shaped, for sites that offer no OAuth. The link expires in ~30 minutes and is scoped to that one host, and the end-user's PASSWORD is never stored — only the session.

POST/sessions/import

Import a browser session captured on the user’s OWN machine (the capture extension).

The counterpart to the hosted connect flow, for popup-OAuth sign-ins ("Continue with Google") that only complete in a real local browser: the user signs in on their own machine and the companion extension ships the resulting cookies here. They are assembled into an encrypted session exactly as a hosted sign-in would be, so every later run on that host is `sessionRestored: true`. Cookies are the captured SESSION, never a password. Stored under both apex and www forms of the host.

GET/accounts

Which logins this tenant already has — metadata only, never a credential.

The discovery half of the credential system: every run-shaped endpoint accepts an `account` label to pick one of several logins for a host, and this endpoint tells you which labels exist. Read-only metadata — host, label, and a MASKED email preview. The ciphertext is never loaded; a credential leaves the system exactly once, at fill-time inside the browser.

GET/secrets

List this tenant's stored secret NAMES (write-only vault — values are never returned). Free.

POST/secrets

Store (encrypt) a named secret for this tenant, referenceable in prompts as {{secret:NAME}}. Free.

DELETE/secrets/{name}

Delete a stored secret by name for this tenant. Free.

GET/email-inbox

List the connected IMAP inboxes used to auto-resolve emailed 2FA codes (host/user only).

POST/email-inbox

Connect an IMAP inbox so sign-in runs auto-fill the emailed 2FA code (no HITL pause).

Stores an IMAP inbox (encrypted) that the engine's email-first path reads to fetch and fill an emailed verification code itself, so a login run resolves the 2FA wall without parking for a human. The inbox is VALIDATED against a real IMAP connection before it is stored (a wrong host/app-password is rejected 400). Use a provider app-password (e.g. Gmail: host imap.gmail.com, port 993). The app-password is write-only — never returned. Re-posting the same user updates it. This is the API-key equivalent of the dashboard's Connect-inbox action.

DELETE/email-inbox

Disconnect a stored IMAP inbox by name.

POST/observe

Serialize a page into indexed DOM state without acting (~1 credit).

POST/solve-captcha

Solve a captcha blocking an in-flight session (~5 credits, charged only on success).

Asks the engine to solve a captcha in an already-open session (via 2captcha). No target URL — the session already holds the page context. Charges 5 credits ONLY when a captcha was actually solved; an unsolved attempt is fully refunded (credits_charged:0).

GET/tenants

Reseller: list your subtenants with balances and what they cost you.

POST/tenants

Reseller: create a subtenant under your account and mint its API key.

Requires the `tenants:provision` scope. `billing` decides who pays: "self" (the subtenant pays from its own balance; fund it with `credits`) or "parent" (your credit pool pays, each charge attributed to the subtenant). The API key is returned ONCE.

GET/pricing

Public credit rate card (no API key required).