Cloud Browser API Reference#

The Cloud Browser API provisions account-owned Chromium instances and returns CDP proxy URLs that do not require custom caller headers.

Base URL#

https://apothic.ai

All endpoints below are under /api/v1/chromium.

Authentication#

Requests must be authenticated as an Apothic user with full account access.

Browser requests made from the dashboard use the active website session. Programmatic callers should send an Apothic API key as a bearer token or in x-api-key.

Create a browser#

POST /api/v1/chromium/sessions
Content-Type: application/json
Accept: application/json

Request body#

interface CreateCloudBrowserRequest {
  region?: string;
  autoDestroy?: boolean;
}

| Field | Default | Description | | --- | --- | --- | | region | account default, currently iad | Optional Fly region code such as iad, ord, dfw, lax, sjc, ewr, yyz, ams, fra, lhr, or nrt. | | autoDestroy | true for API calls | When true, the browser receives an expiration timestamp and its CDP endpoint expires. When false, the returned endpoint is persistent until deletion. |

Compatibility aliases are accepted for older clients: expires and expireCredentials. Prefer autoDestroy in new integrations.

Example#

curl -X POST https://apothic.ai/api/v1/chromium/sessions \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $APOTHIC_API_KEY" \
  -d '{
    "region": "iad",
    "autoDestroy": false
  }'

Response#

{
  "id": "056d80d8-44b0-49d2-9bf5-2d7d94e8f386",
  "status": "starting",
  "expiresAt": null,
  "createdAt": "2026-04-27T17:00:00.000Z",
  "updatedAt": "2026-04-27T17:00:01.000Z",
  "readyAt": null,
  "suspendedAt": null,
  "errorMessage": null,
  "fly": {
    "appName": "kernel-browser",
    "machineId": "287e005f570448",
    "machineName": "chromium-session",
    "region": "iad",
    "image": "registry.fly.io/kernel-browser:chromium-sessions-20260427-165236"
  },
  "cdp": {
    "endpointUrl": "https://cdp.apothic.ai/sessions/<session-id>/cdp/<token>",
    "versionUrl": "https://cdp.apothic.ai/sessions/<session-id>/cdp/<token>/json/version",
    "webSocketUrl": "wss://cdp.apothic.ai/sessions/<session-id>/cdp/<token>/devtools/browser",
    "credentialsAvailableOnlyOnCreate": true,
    "proxyManagedHeaders": [
      "Authorization",
      "fly-force-instance-id"
    ]
  },
  "statusUrl": "/api/v1/chromium/sessions/056d80d8-44b0-49d2-9bf5-2d7d94e8f386",
  "note": "Machine is warming and will suspend itself after the runtime readiness callback completes."
}

The cdp object is returned only when the browser is created. Store the returned URLs if your client needs them later.

List browsers#

GET /api/v1/chromium/sessions
Accept: application/json

Response#

{
  "sessions": [
    {
      "id": "056d80d8-44b0-49d2-9bf5-2d7d94e8f386",
      "status": "suspended",
      "expiresAt": null,
      "createdAt": "2026-04-27T17:00:00.000Z",
      "updatedAt": "2026-04-27T17:04:00.000Z",
      "readyAt": "2026-04-27T17:03:30.000Z",
      "suspendedAt": "2026-04-27T17:04:00.000Z",
      "errorMessage": null,
      "fly": {
        "appName": "kernel-browser",
        "machineId": "287e005f570448",
        "machineName": "chromium-session",
        "region": "iad",
        "image": "registry.fly.io/kernel-browser:chromium-sessions-20260427-165236"
      },
      "cdp": null
    }
  ]
}

Listing reconciles transitional session state with Fly Machine state. Expired auto-destroy sessions are cleaned up during lifecycle reconciliation and omitted from the list.

Inspect a browser#

GET /api/v1/chromium/sessions/:id
Accept: application/json

Returns the same public session shape used by the list endpoint. This endpoint does not re-issue CDP credentials.

Delete a browser#

DELETE /api/v1/chromium/sessions/:id
Accept: application/json

Deletes the Fly Machine, marks the session deleted, and removes it from future list responses.

Response#

{
  "session": {
    "id": "056d80d8-44b0-49d2-9bf5-2d7d94e8f386",
    "status": "deleted",
    "expiresAt": null,
    "createdAt": "2026-04-27T17:00:00.000Z",
    "updatedAt": "2026-04-27T17:10:00.000Z",
    "readyAt": "2026-04-27T17:03:30.000Z",
    "suspendedAt": "2026-04-27T17:04:00.000Z",
    "errorMessage": null,
    "fly": {
      "appName": "kernel-browser",
      "machineId": "287e005f570448",
      "machineName": "chromium-session",
      "region": "iad",
      "image": "registry.fly.io/kernel-browser:chromium-sessions-20260427-165236"
    }
  }
}

Status values#

| Status | Meaning | | --- | --- | | creating | Database record exists, Fly Machine creation has not completed. | | starting | Fly Machine exists and Chromium is warming. | | ready | Runtime callback completed. | | suspending | Apothic is snapshotting/suspending the Machine. | | suspended | Machine is in standby and ready to resume through the CDP proxy. | | error | Provisioning, readiness, or deletion failed. | | deleted | User deleted the browser. | | expired | Auto-destroy lifetime elapsed and lifecycle cleanup ran. |

Error format#

Errors return JSON with an error.message field:

{
  "error": {
    "message": "Authentication required"
  }
}

Common statuses:

| HTTP status | Meaning | | --- | --- | | 400 | Invalid JSON body or missing session id. | | 401 | Authentication required. | | 404 | Browser session not found. | | 502 | Fly Machine provisioning or deletion failed. | | 503 | Cloud Browser infrastructure is not configured. |

CDP proxy behavior#

The returned CDP URLs point at cdp.apothic.ai. The proxy injects upstream headers internally:

Authorization: Bearer <session CDP token>
fly-force-instance-id: <Fly Machine id>

Callers should not send those headers themselves.

For persistent MCP and CDP clients, create the browser with autoDestroy: false.