Authentication

Every render authenticates with your account key — a long random string prefixed sbk_, handed to you when you place an order. It is the only identity we hold. Send it as a bearer token:

Authorization: Bearer sbk_your_key_here

There is no login, no password, and no account signup. Lose the key and (unless you set a recovery email) it cannot be recovered — that is the cost of holding no identity for you. Treat it like a password: anyone with it can spend your budget.

Buy task-units

You don't buy renders one at a time — you buy a budget of browser-task-units, and each render draws its endpoint's weight (screenshot ×1, PDF ×2, scrape ×1). Create an order for a budget; a paid order returns a single-use USDC address, and your units are credited automatically once the payment confirms.

POST /api/order
{ "units": 1000, "email": "you@example.com" }

→ 201
{
  "orderId": "ord_…",
  "apikey": "sbk_…",           // your account key — SAVE IT
  "address": "0x…",            // single-use USDC address (the order reference)
  "amountUsdc": "…",           // exact amount to send
  "chainId": 8453,
  "usdc": "0x…",
  "statusUrl": "/api/order/ord_…/status"
}

The email is optional and used only for magic-link recovery. A budget within the free floor is credited directly with no payment. Poll GET /api/order/:id/status for waiting → detected → confirmed. Want the live price for a budget first? POST /api/quote { "units": 1000 } returns the exact USDC amount without creating an order.

Regions

Pass a region on any render to choose the continent it runs from. A multi-region render draws the endpoint weight once per region.

americas    — Montréal, Canada
europe-de   — Frankfurt, Germany
asia        — Singapore

Render a full-page PNG of the target after its JavaScript runs.

curl -X POST https://api.swarmbrowser.net/v1/screenshot \
  -H "Authorization: Bearer sbk_…" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "region": "americas" }'

Returns the PNG plus a signed receipt id. Every URL, redirect and sub-resource is re-validated at connect time; private or internal addresses are refused (SSRF-safe).

Render a print-quality, paginated PDF of the target.

curl -X POST https://api.swarmbrowser.net/v1/pdf \
  -H "Authorization: Bearer sbk_…" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "region": "europe-de" }'

Extract structured content from the rendered DOM — text plus any selectors you pass.

curl -X POST https://api.swarmbrowser.net/v1/scrape \
  -H "Authorization: Bearer sbk_…" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "selectors": { "title": "h1" } }'

Budget

Check how many task-units remain on your account at any time.

GET /api/budget
Authorization: Bearer sbk_…

→ { "unitsTotal": 1000, "unitsUsed": 12, "unitsRemaining": 988 }

Receipts & verification

Every render returns an Ed25519-signed receipt — the endpoint, the hashed target, the region and the units it cost, with no raw URL and no PII. Fetch a stored receipt, then verify it against our published public key, so you never have to trust our word for what ran.

GET  /api/receipt/:id            (Authorization: Bearer sbk_…)
GET  /.well-known/swarmbrowser-receipt-pubkey
POST /api/verify  { "receipt": { … } }   →  { "valid": true }

Account recovery

If you set a recovery email, you can get a one-time magic link back to your account — no password. It is oracle-neutral: the response is identical whether or not the address is known.

POST /api/recover          { "email": "you@example.com" }
POST /api/recover/redeem   { "token": "…" }   →  { "session": "sbs_…" }
GET  /api/recover/session  (Authorization: Bearer sbs_…)

The link lands on your dashboard, which redeems the token for a session and shows your budget and history. On erasure the email, the mapping and the key itself are all deleted — afterward you leave zero trace.