API reference

VeilBrowser exposes two surfaces:

1. Cloud API (https://api.veilbrowser.net) — provision profiles and inspect session activity.
2. Local API (on each worker) — launch and stop browsers.

They use different credentials. Do not mix them.

Authentication

Profile management is done from the signed-in dashboard (or any client that carries that session). Organization API keys are for self-hosted workers talking to the control plane — not for general profile CRUD from scripts.

Profiles

Sessions (cloud — read-only)

The cloud GET /v1/sessions endpoint is a read-only activity list. Workers populate it by calling POST / DELETE /v1/profiles/:id/sessions with an organization API key. There is no cloud endpoint that launches or stops a browser.

Launch and stop (Local API)

Browsers run on your workers. Launch and stop go to the Local API (or the cluster load balancer), not to api.veilbrowser.net.

curl -X POST http://localhost:3000/sessions/profile \
  -H "X-API-Key: $WORKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profileId": "<profile-uuid>" }'

The response includes a webSocketDebuggerUrl (CDP) you can connect to with Puppeteer, Playwright, or any CDP client.

curl -X DELETE http://localhost:3000/sessions/<session-id> \
  -H "X-API-Key: $WORKER_API_KEY"

For a one-step, load-balanced launch over a single socket, see Cluster mode.

Worker integration (organization API key)

Self-hosted workers use the organization key (VEIL_KEY / X-API-Key) against the cloud for licensing and session tracking:

• POST /v1/license/authorize — concurrency check before launch (fail-closed)
• GET /v1/profiles/:id/config — fetch launch config
• POST /v1/profiles/:id/sessions — session start
• DELETE /v1/profiles/:id/sessions — session end

See Licensing & concurrency.

Next steps

• Automation — attach a framework to webSocketDebuggerUrl.
• Self-hosting — run the API and workers yourself.