Cloudbrowse Docs

Authentication

Send your API key as a bearer token on every API request.

Authorization: Bearer <api-key>

API keys

Use the dashboard to sign in, generate a client key, copy it once, and revoke it when needed.

GET /v1/api-keys
POST /v1/api-keys
DELETE /v1/api-keys/:id

Create a crawl

Create a crawl job with a target URL, mode, outputs, proxy policy, and retry strategy.

POST /v1/crawl
Content-Type: application/json

{
  "url": "https://example.com",
  "mode": "browser-cdp",
  "referer": "https://example.com/",
  "outputs": ["metadata", "html", "text", "screenshot"],
  "proxy": { "pool": "direct" },
  "strategy": {
    "maxAttempts": 2,
    "retryOnBlock": true,
    "retryOnTimeout": true,
    "proxyRotation": "rotate_on_retry",
    "adaptiveProfile": true
  }
}

Proxy controls

No proxy

{ "proxy": { "pool": "direct" } }

Residential proxy

{ "proxy": { "pool": "residential", "country": "AUTO", "sessionId": "user-42" } }

Use AUTO when any residential country is acceptable. Use an ISO country code when country-tagged inventory is available.

The same sessionId pins the same residential exit IP for the provider's sticky window, so repeated requests in a session keep one IP.

Sessions

A persistent session routes later jobs to the same warm headful Chromium profile and keeps its fingerprint, cookies, localStorage, cache, and residential exit IP together. Cookies and storage are checkpointed to R2 for container restarts.

{
  "url": "https://example.com/account",
  "proxy": { "pool": "residential", "sessionId": "customer-1" },
  "session": { "id": "customer-1", "persist": true },
  "strategy": { "proxyRotation": "sticky" }
}

session.persist: reuse the live browser profile and checkpoint cookies + storage after every completed attempt, including block pages.
The jar is keyed by session.id (falling back to proxy.sessionId); a residential crawl with a session.id pins its IP to that id automatically.
Persisted sessions default to proxyRotation: "sticky" when strategy is omitted and keep one stable browser fingerprint.
Containers wind down automatically after five idle minutes; R2 restores cookies and local storage when a fresh container starts.

Import a verified state

PUT /v1/sessions/customer-1
Content-Type: application/json

{
  "ttlSeconds": 86400,
  "storageState": { "cookies": [], "origins": [] }
}

GET /v1/sessions/customer-1
DELETE /v1/sessions/customer-1

Outputs

metadata: final URL, status code, title, timings, block signal.
html: rendered document HTML.
text: visible page text.
screenshot: PNG screenshot.
pdf: PDF rendering where supported.
network: request and response metadata.

Job polling

GET /v1/jobs/:id
GET /v1/jobs/:id/result
GET /v1/jobs/:id/artifacts/html

Errors

Errors use a consistent shape with a machine-readable code and a developer-readable message.

{
  "error": {
    "code": "invalid_request",
    "message": "url must be a valid http or https URL"
  }
}

Cloudbrowse API