API overview

Base URL

https://api.datum.org/api/v4

Requests and answers are JSON (an extension upload is multipart). Fields are camelCase, times are ISO 8601 in UTC, and money is a decimal string in US dollars ("0.0042"), as Browser Use Cloud writes them.

Authentication

Send an organization’s secret key (sk_…, from Connect) in either header:

X-Browser-Use-API-Key: sk_...
Authorization: Bearer sk_...

A publishable key is refused (403 secret_key_required): a browser spends the organization’s balance, so keep the key on your server.

Pagination

Lists take pageSize (1–100, 10 by default) and pageNumber (from 1), and answer:

{ "items": [], "totalItems": 0, "pageNumber": 1, "pageSize": 10 }

Errors

Errors have FastAPI’s shape, as Browser Use answers them:

{ "detail": { "message": "This organization's balance is spent: …", "code": "balance_exhausted" } }

A body that does not validate answers 422 with a list of the fields at fault:

{ "detail": [{ "loc": ["body", "timeout"], "msg": "Too big: expected number to be <=240", "type": "too_big" }] }

Status	Code	When
401	unauthorized	No key, or not a key of an organization
403	secret_key_required	A publishable key
402	balance_exhausted	The balance is spent. Add credits, or turn on auto recharge, on Billing
404		No such browser, profile, policy or extension in your organization
409	profile_in_use	The profile’s live browser has another proxy or screen than the create asks for
422		A body or value that is not accepted; the message says why
429	too_many_sessions	Your tier’s live browsers are all running. Comes with Retry-After
429	no_capacity	No machine free right now; retry in a minute
502	proxy_failed	No residential address could be had for the country
503	start_failed	The browser did not start; retry

Resources

Resource	Routes
Browsers	POST /browsers, GET /browsers, GET /browsers/{id}, PATCH /browsers/{id}
Proxies	GET /browsers/{id}/proxy, PATCH /browsers/{id}/proxy
Profiles	GET/POST /profiles, GET/PATCH/DELETE /profiles/{id}, POST /profiles/{id}/import
Network policies	GET/POST /network-policies, GET/PATCH/DELETE /network-policies/{id}
Extensions	GET/POST /extensions, GET/DELETE /extensions/{id}
Files and recordings	GET /browsers/{id}/downloads, recordingUrl on a browser