Local only
The API is bound to 127.0.0.1 on port 36542 (configurable in the app). Base URL:
http://127.0.0.1:36542/api/v1
There is no hosted API. The only server is the one the desktop app starts on your machine, so the app must be running, and there is nothing to call at api.justbrowser.app. The request itself never leaves 127.0.0.1, but the operation can, exactly as the same action in the app does: creating a profile while signed in asks justbrowser.app to generate the fingerprint (a local draw is used when signed out or offline), sync uploads the profile to cloud storage, teams, shares, licence refresh and the proxy catalogue call justbrowser.app, and a proxy test connects through the proxy. Nothing extra is sent because you used the API.
Authentication
Every request under /api/v1 carries Authorization: Bearer <token> (the scheme in any case). The token is shown on the AI page in the app, which also writes a plain-text briefing of this API for pasting into an agent. A missing or wrong token returns 401.
One route needs no token: GET /health at the server root (http://127.0.0.1:36542/health, outside /api/v1; HEAD and a query string work too) answers {"status": "ok", "version": …, "timestamp": …} while the app runs with its API on, for a monitor.
A website cannot read the API's answers: only a page served from this computer (an origin on 127.0.0.1, localhost or [::1]) gets the browser's permission (CORS). Call the API from a script, an agent or a server process.
The API is available on an active subscription and during the trial. Team seats can run shared profiles but have no API access of their own.
Profiles start headless by default
POST /profiles/{id}/start with no body launches a headless browser. Send {"headless": false} as JSON when you want a window. The response carries cdp_url, a ws://127.0.0.1:PORT/devtools/browser/… endpoint. Headless or not, a start takes the profile's cloud lock, and its session uploads when it stops.
Responses and errors
Every endpoint under /api/v1 wraps its result in {"data": …}, except GET /docs, which returns the OpenAPI document itself. Errors come back with a non-2xx status and {"error": {"code", "message"}}. Branch on code, not the message, which varies by layer. details is an array of issues for VALIDATION_ERROR and SETTING_NOT_WRITABLE, and an object for other errors that carry one (heldBy, sameDevice, limitBytes…). Bodies are JSON; send Content-Type: application/json. JSON types are not converted: a number sent for a text field is refused. A body may be up to 3 MiB; a larger one answers 413: send it in smaller parts, for example fewer cookies in each import.
Each operation below lists its own answers. Any route can also answer 401 (the token), 403 SUBSCRIPTION_REQUIRED (the account no longer includes the API), 503 PLAN_CHECK_PENDING (the plan is not confirmed yet; retry after Retry-After), 404 ROUTE_NOT_FOUND, 400 INVALID_JSON, 415 (not JSON), 500 (an unexpected failure) and 504 SHELL_RPC_TIMEOUT (the app did not answer in time: the change may still have gone through, so check before trying again). Under each operation, “Also, as any route” lists the ones that apply to it: 401, 403, 500 and 503 everywhere, and 400, 413 and 415 where a body is sent (POST, PUT, PATCH).
This reference is generated from the app's route definitions and committed with the code; a test in the repository fails whenever the routes and this file disagree, so it stays in step with the source. Your installed app serves its own copy at GET http://127.0.0.1:36542/api/v1/docs, the authoritative document for the version you are running (this page was generated from 2.2.0). The AI page in the app offers a plain-text briefing for agents, built from the same endpoint catalogue with your port and token filled in. Questions or a gap you hit: support@justbrowser.app.