API reference

Base URL: https://browser.rayobyte.com

Every endpoint takes the x-api-key header. GET /connect also accepts the key as a token query parameter.

Endpoints

Method	Path	Returns
GET	/connect	A CDP WebSocket URL as plain text
POST	/api/browser/create	The session as JSON
POST	/api/browser/close	{ browserId, status }
GET	/api/browser/:id/status	One session
GET	/api/browsers	Your running sessions
GET	/user/api/limits	{ limit, active, remaining, unlimited } for concurrent browsers
GET	/user/api/me	Your profile, limits and lifetime usage
GET	/user/api/sessions	Your sessions, paginated
GET	/user/api/usage	Totals and up to 30 daily buckets
POST	/user/api/regenerate-key	A new API key
GET	/health	Gateway health, no key needed

/connect and /api/browser/create do the same job in different shapes. /connect is one GET that answers with a bare URL; create takes a JSON body and answers with the whole session object, including expiresAt and the vncUrl.

Response shapes

Success on /connect is text/plain and the body is the URL. Everything else is JSON.

Errors are flat JSON, not nested:

{
  "error": "You've used your 48 free browser hours. Contact [email protected] to keep going.",
  "code": "USAGE_CAP_REACHED",
  "remainingSeconds": 0
}

/connect is the exception. Errors from the route itself (400, 404, 410, 422 and 5xx) come back as text/plain with the message in the body, and a 400, 422 or 503 carries its code in the X-Error-Code header. Errors answered before the route runs stay JSON on /connect too: 401, 402, both 429s and the authentication 503.

Status codes

Status	Meaning
200	Created, closed or read. A create is 200, not 201
400	PROXY_REQUIRED, PROXY_INVALID, a malformed parameter, or a missing browserId
401	Missing or invalid API key
402	USAGE_CAP_REACHED, the 48 browser hours are spent
404	No session with that id for you, including one that belongs to another account. On a reconnect, also the br_ id from a CDP URL
410	Reconnect to a session that has ended
422	PROXY_UNREACHABLE, the browser could not connect through the proxy
429	CONCURRENCY_LIMIT or RATE_LIMIT, in the body’s code
500	A create failed on the backend
502	The backend refused a close, or failed a create without answering
503	CAPACITY, or the key lookup failed

Full detail on Limits.