Browza API

Send a task in plain language; Browza opens a real browser, does the work, and returns a structured result. The API is a conventional JSON-over-HTTPS interface: create a run, poll or stream its progress, collect the result. Everything the dashboard can see, the API can see.

https://api.browza.xyz

curl -X POST https://api.browza.xyz/v1/runs \
  -H "Authorization: Bearer bz_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "task": "List the top 5 trending GitHub repositories with name and stars",
    "config": { "outputSchema": {
      "type": "object",
      "properties": { "repos": { "type": "array", "items": {
        "type": "object",
        "properties": { "name": {"type":"string"}, "stars": {"type":"number"} }
      }}}
    }}
  }'

# → 202 { "id": "8b5e2f6a-1c9d-4e37-9f1b-2f60c9f4d21e", "status": "queued" }

Run ids are plain UUIDs. The run executes on a worker, not inside your request — poll GET /v1/runs/:id until status is terminal, or follow the event stream.

Authentication

Authenticate with an API key in the Authorization header. Keys are minted in the dashboard under API keys (admin role required) and shown once at creation. Two modes exist — bz_live_… and bz_test_… — both scoped to one workspace.

Authorization: Bearer bz_live_...

An API key acts for the workspace as a whole. Endpoints marked Dashboard below manage the account itself (keys, models, members, billing, agent configuration) and require a signed-in dashboard session — an API key calling them receives 403 user_auth_required.

Conventions

Error envelope

Every error is JSON with a stable machine-readable code beside a human-readable message:

{ "error": { "code": "tier_limit", "message": "timeoutMs 7200000 exceeds the starter plan limit of 900000" } }

Pagination

List endpoints take limit (1–100, default 25) and offset, and return { …rows, total, limit, offset }. Run events use a forward cursor instead — see Run events.

Idempotency

The three run-creating endpoints honor an Idempotency-Key header (up to 200 characters). Repeating a request with the same key returns the original run with HTTP 200 instead of 202 — safe to retry on timeouts.

Rate limits

Most endpoints are unthrottled beyond your plan's own concurrency and allowance gates. The invite and device-pairing endpoints carry abuse limits; a throttled request returns 429 rate_limited with retry-after and x-ratelimit-* headers. Timestamps are ISO-8601 UTC throughout. Request bodies are capped at 1 MB.

The run object

A run is one browser task from prompt to result. Its status moves through queued → claimed → running to one of the terminal states succeeded | failed | cancelled | timed_out. awaiting_human is non-terminal: the browser is alive and waiting for a person (a login or challenge) — see takeover.

{
  "id": "8b5e2f6a-1c9d-4e37-9f1b-2f60c9f4d21e",
  "status": "succeeded",
  "task": "List the top 5 trending GitHub repositories with name and stars",
  "config": { "timeoutMs": 600000, "maxSteps": 150, "screenshots": "every_step", ... },
  "result": { "answer": "linux leads this month's trending list…", "data": { "repos": [ ... ] } },
  "errorCode": null,
  "errorMessage": null,
  "attempt": 1,
  "usage": {
    "planner": { "inputTokens": 4210, "outputTokens": 380 },
    "observe": { "inputTokens": 0, "outputTokens": 0 },
    "act":     { "inputTokens": 0, "outputTokens": 0 },
    "extract": { "inputTokens": 9120, "outputTokens": 640 },
    "total":   { "inputTokens": 13330, "outputTokens": 1020, "cachedInputTokens": 3900 }
  },
  "inputs": {},
  "procedureId": null,
  "agentId": null,
  "modelUsed": { "provider": "openai", "modelName": "gpt-5" },
  "pageUrl": "https://github.com/trending",
  "rating": null,
  "createdAt": "2026-08-30T13:04:11.512Z",
  "startedAt": "2026-08-30T13:04:14.906Z",
  "finishedAt": "2026-08-30T13:05:02.331Z"
}

usage.total.cachedInputTokens is the subset of input tokens served from the provider's prompt cache — an annotation, never additive. result matches your outputSchema when one was supplied.

Create a run

{ "id": "8b5e2f6a-1c9d-4e37-9f1b-2f60c9f4d21e", "status": "queued" }

List runs

{ "runs": [ { ...run } ], "total": 132, "limit": 25, "offset": 0 }

Get a run

Returns the full run object above, or 404 not_found.

Cancel a run

A queued run cancels immediately; a running one is signalled and stops at its next step boundary. Returns 202 { id, outcome }; a terminal run answers 409 not_cancellable.

Rate a run

Terminal runs only (409 not_ratable otherwise); the latest rating wins. Returns the updated run object.

Run events

The run's life as an append-only feed: run.claimed, turn.started, step.finished, verification, egress, run.resumed, run.finished, and more.

curl "https://api.browza.xyz/v1/runs/:id/events?after=0&limit=200" \
  -H "Authorization: Bearer bz_live_..."

# → { "events": [ { "id": "18734", "seq": 12, "type": "step.finished",
#                   "actor": "worker:…", "payload": { ... }, "ts": "…" } ],
#     "nextAfter": "18734" }

Run steps

What the agent actually did, one row per step: { attempt, seq, kind, status, reason, instruction, input, output, pageUrl, screenshotArtifactId, inputTokens, outputTokens, durationMs, startedAt }. kind is one of goto · observe · act · fill · scroll · extract · verify · decide · use_skill.

Per-kind latency rollup for one run: { kinds: [{ kind, steps, totalMs, totalTokens }] }.

Artifacts

Streams an artifact's raw bytes (screenshots today) with its content type. Artifact ids arrive on step rows as screenshotArtifactId and in artifact.created events — there is no separate list endpoint.

Live view & takeover

Every run can be watched live — the browser's real frames — and a person can take the mouse mid-run and hand it back. Three endpoints cooperate:

Returns { ticket, expiresInMs: 45000 } — a short-lived credential that gates the socket connection only.

A WebSocket of JPEG frames, tab state, and verification events. Connect within 45 seconds of minting the ticket; the run may outlive many tickets.

The agent object

An agent is a persistent browser worker: a goal, an optional signed-in browser profile, durable instructions, attached skills, a file drawer, an optional schedule, and a history of runs. Its status is derived, never stored: ready · running · needs_login · needs_attention · paused.

{
  "id": "0f2f9f6e-…",
  "name": "Morning briefing",
  "goal": "Collect the top stories from our five sources and file a summary",
  "browserProfileId": null,
  "domainPolicy": "allowlist",
  "allowedDomains": ["news.ycombinator.com", "lobste.rs"],
  "deniedDomains": [],
  "approvalPolicy": "autonomous",
  "pausedAt": null,
  "createdAt": "…", "updatedAt": "…"
}

approvalPolicy is browse_only (refuses page actions), confirm_actions (pauses for a person before acting), or autonomous. Only policies that never pause can be scheduled. The domain policy keeps an agent on task; a stored host matches itself and its subdomains, never upward.

Read agents

{ agents: [...] } — each with status, skillCount, instructionCount, and profileName.

The agent plus its instructions and skills (sanitized manifests: names and input names, never selectors or stored values).

Run an agent

Fire the agent now — from your code, a cron job, or the dashboard's Run button; a schedule produces exactly the same kind of run. The task is the agent's goal plus its instructions; an optional { config } body merges under the agent's own profile. Honors Idempotency-Key.

curl -X POST https://api.browza.xyz/v1/agents/:id/run   -H "Authorization: Bearer bz_live_..."   -H "Idempotency-Key: briefing-2026-08-30"

# → 202 { "id": "…", "status": "queued" }

Manage agents

Creating and configuring agents is done from the dashboard today (these endpoints require a signed-in session — an API key receives 403 user_auth_required):

Schedules

Scheduling requires an approval policy that never pauses — confirm_actions agents are refused with 409 approval_blocks_schedule (nobody answers a confirmation at 8am).

Files

Every file an agent downloads or generates lands in its drawer; you can also add files for it to use.

All files across agents: { files: [{ id, agentId, agentName, runId, origin, filename, contentType, sizeBytes, sourceUrl, createdAt }], total, limit, offset } — origin ∈ downloaded · generated · uploaded.

Streams the bytes with Content-Disposition: attachment.

Upload: { filename, contentType?, contentBase64 } (base64, whole request ≤1 MB) → 201.

Skills & automations

A procedure is a learned, replayable flow — compiled from a successful run or taught with the recorder. Replays are deterministic: saved actions, zero model calls, verified per step.

{
  "id": "…", "domainPattern": "github.com", "intent": "list trending repositories",
  "hasActions": false, "source": "agent", "autoMatch": false,
  "parameters": [{ "name": "query", "label": "Search term", "required": true }],
  "constants": [{ "paramName": "region", "value": "US" }],
  "successCount": 14, "failureCount": 1, "version": 3
}

Run an automation

curl -X POST https://api.browza.xyz/v1/procedures/:id/run   -H "Authorization: Bearer bz_live_..."   -H "Content-Type: application/json"   -d '{ "inputs": { "query": "Q3 invoices" } }'

# → 202 { "id": "…", "status": "queued" }

autoMatch: false (the default for taught automations) means it runs only when invoked by name — similarity matching never picks it up until a human opts in.

Teaching (recorder)

The Browza Local extension records a demonstration in your own browser; the server compiles it into a parameterized automation. The extension drives these endpoints — documented for completeness, not for hand-rolled clients:

Browser profiles

A profile is a durable browser identity — cookies and logins that persist between runs, on any worker. Sign in once (via takeover) and every later run with that profile arrives signed in.

{ "id": "…", "name": "quickbooks", "hasIdentity": true, "sizeBytes": 18234,
  "clearedAt": "…", "lastUsedAt": "…", "inUse": false, "lastShutdownGraceful": true }

204, or 409 profile_in_use while a run holds it.

Browser sessions

The workspace's browser session history: { sessions: [{ id, runId, provider, status, startedAt, endedAt }], total, limit, offset }.

API keys

Keys are managed from the dashboard — you cannot mint a key with a key.

Models

Runs use Browza's hosted model by default; bring your own key for OpenAI, Anthropic, Google, or any OpenAI-compatible endpoint. Provider credentials are stored as secret references and live-tested before saving.

Workspace & billing

Workspace membership (invites, roles), notifications, and billing (plan, credits, auto-reload, invoices) are dashboard-session surfaces — see the Billing page. The API equivalents exist under /v1/tenant/*, /v1/tenants, and /v1/billing/* and require a signed-in session. One shape worth knowing: GET /v1/billing returns your plan, credit balance, per-axis usage against allowance, and this month's add-on costs.

Usage

{ "totals": { "runs": 132, "inputTokens": 1204331, "outputTokens": 88213, "cachedInputTokens": 402118 },
  "byStatus": { "succeeded": 117, "failed": 9, "cancelled": 4, "timed_out": 2 },
  "recentErrors": [ { "code": "source_blocked", "message": "…", "runId": "…", "at": "…" } ] }

Knowledge

What Browza has learned about the sites you use — proven pages, verified flows, and the model calls that learning avoided: { savings, totals, hosts, page, pageSize }.

Egress

Network identity health: exit nodes, residential bandwidth budget, and per-domain effectiveness — { nodes, bandwidth, effectiveness }.

{ ok: true, service: "browza-control-plane" } — also at /v1/health.

Errors

The codes an integration should branch on, beyond the auth set above:

Run-level failures (a blocked site, a wall needing a person, a drifted automation) are not HTTP errors — the run finishes with status: "failed" and a named errorCode such as source_blocked, verification_required, procedure_drift, no_progress, or max_steps_exceeded.