GET /connect

curl -i -G "https://browser.rayobyte.com/connect" \
  --data-urlencode "os=windows" \
  --data-urlencode "vnc=true" \
  --data-urlencode "proxy=http://USERNAME:[email protected]:8000" \
  -H "x-api-key: rb_live_YOUR_KEY"

HTTP/2 200
x-session-id: br_3f8a1c9d2e4b5a60
x-vnc-url: https://sb-02.browser.rayobyte.com/vnc/vnc.html?path=ws%3Ftoken%3Dbr_5d4d8610784e2a91&autoconnect=true&resize=scale
x-ratelimit-limit: 5
x-ratelimit-remaining: 4
content-type: text/plain; charset=utf-8

wss://sb-02.browser.rayobyte.com/cdp/br_5d4d8610784e2a91

Auth: x-api-key header, or the token query parameter.

After this response the gateway is out of the data path. Your CDP traffic goes straight to the backend.

Query parameters

Parameter	Default	Example	Description
proxy (required)	—	proxy=http://user:[email protected]:8000	Route the browser's traffic through this proxy. Mandatory on every launch. Accepted schemes are http, https, socks5 and socks5h, and the port must be written out.
os	windows	os=windows	Fingerprint OS: windows, android, linux, macos.
headless	false	headless=true	Run without a window. The literal string true enables it; any other value is false. Sites can detect it: see Headless and headful.
vnc	false	vnc=true	Return an x-vnc-url header for the live view.
maxLifetime	7200	maxLifetime=3600	Session lifetime in seconds, clamped into 120 to 86400. 0 counts as omitted.
sessionId	none	sessionId=br_3f8a1c9d2e4b5a60	Reconnect to a running session, using the x-session-id value. Every other parameter is ignored and no browser is created.
token	none	token=rb_live_...	Your API key as a query parameter, in place of the x-api-key header.
browser_version_min	current	browser_version_min=N	Lowest Chromium major version the profile may claim. Defaults to the version the browser runs. See Version matching.
browser_version_max	current	browser_version_max=N	Highest Chromium major version the profile may claim. Defaults to the version the browser runs.
browser_language	auto	browser_language=en-US	Accept-Language value.
ui_language	auto	ui_language=en-US	Browser UI locale.
screen_width_min	auto	screen_width_min=1280	Lowest screen width the profile may have.
screen_height_min	auto	screen_height_min=720	Lowest screen height the profile may have.
force_visibility	false	force_visibility=true	Keep a background or unfocused tab reporting itself as visible and focused. The literal string true only.
metadata	none	metadata=%7B%22job%22%3A%22crawl-42%22%7D	URL-encoded JSON object stored on the session. A value that does not parse is dropped without an error.

Response

Body: the CDP WebSocket URL as text/plain. No JSON wrapper, no guaranteed trailing newline.

Header	Sent when
x-session-id	Always. The session id, the one reconnect takes
x-vnc-url	vnc=true and the browser came up with a viewer
x-ratelimit-limit	Your concurrent browser limit, not the per-minute rate
x-ratelimit-remaining	On a create, concurrent browsers still free after this one. On a reconnect, free right now
X-Error-Code	On a 400 or 422 proxy error, or a 503 capacity error

The br_ id at the end of the CDP URL is a second id for the same session. Close and status accept it. Reconnect does not, and answers 404 Session not found.

Reconnect

curl "https://browser.rayobyte.com/connect?sessionId=br_3f8a1c9d2e4b5a60" \
  -H "x-api-key: rb_live_YOUR_KEY"

No browser is created and no concurrency slot is used. A reconnect is not subject to the concurrency or rate limits. Every parameter other than sessionId is ignored, silently. x-vnc-url comes back if the session was created with vnc=true.

Errors

Status	Body	Meaning
400	A proxy is required for this account. ... (no proxy supplied)	No proxy. X-Error-Code: PROXY_REQUIRED
400	That proxy is not valid. ... (missing port)	Proxy present, malformed. X-Error-Code: PROXY_INVALID, and the rule it broke in parentheses
400	Malformed browser params: ...	A parameter value was rejected
401	{"error": "Missing API key"}	Neither header nor token
401	{"error": "Invalid API key"}	The key is not a live key
402	{"error": "...", "code": "USAGE_CAP_REACHED", "remainingSeconds": 0}	48 browser hours used. Creates only; reconnects still work
404	Session not found	Reconnect with an unknown id, another account’s id, or the id from a CDP URL
410	Session is CLOSED	Reconnect, the session already ended. Also DEAD or EXPIRED
422	The browser could not connect through that proxy. ...	Wrong proxy credentials, or a proxy that is down. X-Error-Code: PROXY_UNREACHABLE
429	{"error": "Concurrent browser limit reached", "code": "CONCURRENCY_LIMIT", "limit": 5, "active": 5}	5 already running. retry-after: 5
429	{"error": "Rate limit exceeded", "code": "RATE_LIMIT", "limit": 60, "window": "60s"}	More than 60 creates this minute. retry-after: 60
500 or 502	Browser creation failed	The browser did not start
500	Reconnect failed: ...	The reconnect lookup failed. Retry
503	All browsers are busy right now, try again in a moment.	No free seat anywhere. X-Error-Code: CAPACITY, retry-after: 2
503	{"error": "Authentication service temporarily unavailable"}	The key lookup failed. Retry

The rows whose body is a JSON object are JSON; everything else is text/plain. Parsing every error as JSON throws on most of them. Branch on the status, then on X-Error-Code or the JSON code where there is one.