API reference

Run steps in a fresh browser. Synchronous, up to 15 minutes.

Returns { ok, sessionId, results: [{ type, ok, data | error, ms }], finalUrl, usage, timing }

curl https://api.browseit.live/v1/tasks \
  -H "Authorization: Bearer $BROWSEIT_KEY" -H "Content-Type: application/json" \
  -d '{ "engine": "v2", "continueOnError": true, "steps": [
        { "type": "navigate", "url": "https://news.ycombinator.com" },
        { "type": "extract", "instruction": "the top 3 story titles",
          "schema": { "type": "object", "properties": { "titles": { "type": "array", "items": { "type": "string" } } }, "required": ["titles"] } },
        { "type": "screenshot", "format": "png" },
        { "type": "evaluate", "expression": "document.title" } ] }'
# -> { "ok": true, "results": [ { "type": "navigate", "ok": true, ... }, ... ], "usage": {...}, "timing": {...} }

Open a live browser. Returns a single-use connectUrl (valid 60 s) for the live view. With cdp: true (raw-browser grant needed), connect Playwright to the /cdp form of that link.

Returns 201 { session: { id, status }, connectUrl, expiresInSec: 60 }

// Playwright, connected to a Browseit browser (needs the raw-browser grant on your account)
const r = await fetch('https://api.browseit.live/v1/sessions', { method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.BROWSEIT_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ engine: 'v2', cdp: true }) }).then((x) => x.json());
const browser = await chromium.connectOverCDP(r.connectUrl.replace('/s?t=', '/cdp?t='));
const page = await browser.contexts()[0].newPage(); // one shared context: newContext() is refused
await page.goto('https://example.com');

A fresh connectUrl for the same browser. One connection lasts up to about 55 minutes; reconnect and the browser resumes from its last save point (cookies and open tabs, saved every minute). An idle browser ends after 5 minutes.

Returns { session, connectUrl, expiresInSec: 60 }

Your plan, usage (all time and this month) and credit: { period: "monthly" | "lifetime", quotaUsd, spentUsd, remainingUsd, resetsAt }.

Run a single task. Provide exactly one of act, instructions+schema, or observe.

Returns { ok, data, usage, taskId }: synchronous; runs on the live-command budget (~95s). For longer work, use a Job.

curl https://api.browseit.live/v1/tasks \
  -H "Authorization: Bearer $BROWSEIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.ycombinator.com",
    "instructions": "the top 3 story titles and their points",
    "schema": {
      "type": "object",
      "properties": { "stories": { "type": "array", "items": {
        "type": "object",
        "properties": { "title": {"type":"string"}, "points": {"type":"number"} }
      } } }
    }
  }'

Act example: perform an action and return what happened.

curl https://api.browseit.live/v1/tasks \
  -H "Authorization: Bearer $BROWSEIT_KEY" -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/pricing", "act": "add the cheapest plan to the cart" }'

Fetch a past task/agent run by id (the taskId a run returns).

Run an autonomous agent against a live session.

Returns { ok, result: { success, summary, data, steps, stoppedReason, finalUrl, file? }, usage }: synchronous, ~95s budget.

curl https://api.browseit.live/v1/agent \
  -H "Authorization: Bearer $BROWSEIT_KEY" -H "Content-Type: application/json" \
  -d '{
    "sessionId": "sess_…",
    "instruction": "find the cheapest direct flight NYC->LON next Friday and return the price + airline"
  }'

Open a live browser. Returns a session id + token-gated liveUrl.

Returns { session: { id, liveUrl, startedAt, … }, cookieReport? }

curl https://api.browseit.live/v1/sessions \
  -H "Authorization: Bearer $BROWSEIT_KEY" -H "Content-Type: application/json" \
  -d '{ "contextId": "ctx_…", "proxyId": "px_…" }'
# -> { "session": { "id": "sess_…", "liveUrl": "https://…?token=…" } }

List your sessions (live + ended) with duration and cost.

Fetch one session.

Navigate the browser to a URL.

Keep the session alive: ping about every 60s (idle sessions are reaped).

Live bandwidth + performance + proxy status.

The egress IP the session is using (verify your proxy).

Current page HTML + visible text + title + URL.

PNG of the current page (?full=1 for full height).

PDF render of the current page.

Release the session.

Create a job.

# 1) create a saved job
curl https://api.browseit.live/v1/jobs \
  -H "Authorization: Bearer $BROWSEIT_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Daily HN digest",
        "steps": [ { "instruction": "list the top 5 story titles", "url": "https://news.ycombinator.com" } ] }'
# 2) run it (returns a runId; poll /v1/jobs/:id/runs)
curl -X POST https://api.browseit.live/v1/jobs/JOB_ID/run -H "Authorization: Bearer $BROWSEIT_KEY"

List your jobs.

Fetch one job.

Update name / steps / attachments / enabled.

Delete a job.

Set a schedule (cron) to run automatically.

Run now: returns a runId (202). Poll the run for status + results.

Returns { runId, status }

Run history: status, per-step results, timing.

Fetch one run directly (poll this after Run-now).

Returns { run: { status, stepResults[], browserMs, … } }

List your saved contexts.

Create a context.

Fetch one context.

Rename a context.

Delete a context + its saved profile.

List saved logins (never returns secrets).

Save a login.

Replace fields (secrets are replace-only, never shown).

Delete a saved login.

List your proxies (never returns the password).

Add a proxy.

Update a proxy (password replace-only).

Delete a proxy.

List exported files.

File metadata.

A signed download URL.

Delete a file.

List your webhook subscriptions.

Subscribe a URL to events. Returns the signing secret ONCE.

Returns { webhook, secret } : signature header: X-Browseit-Signature: t=<ts>,v1=HMAC_SHA256(secret, "<ts>.<body>")

Remove a webhook.

Plan, quotas, and usage-to-date (sessions, browser-minutes, tasks, LLM spend).

Recent tasks + sessions.

The models you may choose from + the default.

List your API keys.

Rotate your API key (the old one stops working).

Save a login once, then attach it to a session or job so it starts signed in.

# 1) open a session with a saved login attached
curl https://api.browseit.live/v1/sessions -H "Authorization: Bearer $BROWSEIT_KEY" \
  -H "Content-Type: application/json" -d '{ "credentialId": "cred_…", "url": "https://app.example.com/reports" }'
# 2) extract with the agent (already authenticated)
curl https://api.browseit.live/v1/agent -H "Authorization: Bearer $BROWSEIT_KEY" \
  -H "Content-Type: application/json" -d '{ "sessionId": "sess_…", "instruction": "export this month's revenue as JSON" }'

Save the steps as a Job, schedule it, and get a webhook when it finishes.

# create a scheduled job (8am daily): the run output is saved to Files each day
curl https://api.browseit.live/v1/jobs -H "Authorization: Bearer $BROWSEIT_KEY" \
  -H "Content-Type: application/json" -d '{
    "name": "Daily price check",
    "steps": [ { "instruction": "extract the price as JSON", "url": "https://shop.example.com/item/42" } ],
    "schedule": { "cron": "0 8 * * *", "tz": "America/Toronto" }, "enabled": true }'
# subscribe to completion events
curl https://api.browseit.live/v1/webhooks -H "Authorization: Bearer $BROWSEIT_KEY" \
  -H "Content-Type: application/json" -d '{ "url": "https://your-app.com/hooks", "events": ["run.finished"] }'

Open a session and drop its liveUrl (already token-gated) into an iframe. It stays live until you DELETE the session or it hits its time cap.

const { session } = await createSession();   // POST /v1/sessions
<iframe src={session.liveUrl} allow="clipboard-read; clipboard-write" />

curl https://api.browseit.live/v1/sessions -H "Authorization: Bearer $BROWSEIT_KEY" \
  -H "Content-Type: application/json" -d '{ "proxyId": "px_…" }'
curl https://api.browseit.live/v1/sessions/SESS_ID/ip -H "Authorization: Bearer $BROWSEIT_KEY"   # -> your proxy's IP