API Overview

View as Markdown

The BCTRL REST API launches cloud browser runtimes, runs hosted agents inside them, and records everything that happens. It is a plain HTTP API: one base URL, Bearer auth, JSON in and out. The SDKs and CLI are thin clients over these same endpoints.

Base URL and authentication

All endpoints live under one base URL and take your API key as a Bearer token.

$https://api.bctrl.ai/v1
$curl "https://api.bctrl.ai/v1/spaces" \
>  -H "Authorization: Bearer ${BCTRL_API_KEY}"
1const res = await fetch("https://api.bctrl.ai/v1/spaces", {
2  method: "POST",
3  headers: {
4    Authorization: `Bearer ${process.env.BCTRL_API_KEY}`,
5    "Content-Type": "application/json",
6  },
7  body: JSON.stringify({ name: "invoice-agent" }),
8});

Create a key in the dashboard. Confirm who a key belongs to with GET /v1/auth/whoami.

The flow

Five calls take you from nothing to a recorded run.

  1. POST /v1/runtimes - create a browser runtime (optionally scoped to a space).
  2. POST /v1/runtimes/{id}/start - start it. The response returns connectUrl (a CDP endpoint) and runId.
  3. Drive it: connect your own tooling to connectUrl, or POST /v1/runtimes/{id}/invocations to run a hosted agent.
  4. GET /v1/runs/{runId}/events - read what happened.
  5. POST /v1/runtimes/{id}/stop - stop the runtime.

A runtime takes one controller at a time. A CDP connection and a hosted invocation cannot drive the same runtime at once - the second request is rejected until the first releases.

Resources

Four resource groups cover the whole core workflow - most integrations never need anything else:

CoreWhat it does
RuntimesCreate, configure, start, stop, update, and delete browser runtimes. Includes runtime files, invocations, and targets (tabs).
RunsThe durable record of a runtime’s lifecycle: events, activity, files, invocations, plus live and recording viewer leases.
SpacesBoundaries that scope storage, vault, and AI access. Includes the space environment (mounts).
FilesDurable storage for uploads and run outputs.

The rest of the API is platform depth - reach for these when the workflow calls for them:

PlatformWhat it does
Tools / Toolsets / Tool callsDefine callable tools, bundle them, and inspect every call.
AI ProvidersSaved model credentials that agents and tools use by reference.
VaultEncrypted secrets and TOTP, mounted into spaces.
ProxiesCustom and managed proxies, plus managed pools.
Browser ExtensionsUpload or import extensions to load into runtimes.
AccountAPI keys, subaccounts, and usage.
AuthIdentify the current API key.
HelpMachine-readable API, SDK, and CLI guidance.

Pagination

List endpoints return a page of data and a nextCursor. Pass it back as the cursor query parameter to fetch the next page. When nextCursor is null, you have reached the end.

$curl "https://api.bctrl.ai/v1/runtimes?cursor=${NEXT_CURSOR}" \
>  -H "Authorization: Bearer ${BCTRL_API_KEY}"

The SDKs walk this for you with iter() - see Pagination.

Errors

Errors return a non-2xx status and a JSON body with a stable shape:

1{
2  "error": "Runtime not found",
3  "code": "runtime.not_found",
4  "requestId": "req_123",
5  "details": { "runtimeId": "rt_123" }
6}

Branch on code (stable and machine-readable), not on the human error string. Always log requestId - it is what support needs to trace a request.

Next