Node.js SDK reference

import { Rayobrowse } from 'rayobrowse';

const client = new Rayobrowse({ apiKey: 'rb_live_YOUR_KEY' });

Constructor

Property	Type	Description
endpoint	string	Optional. Gateway base URL. Left out, the client uses DEFAULT_ENDPOINT
apiKey	string	Your rb_live_ key

DEFAULT_ENDPOINT is exported from the package and is https://browser.rayobyte.com.

connectUrl(options): Promise<string>

Creates a browser and resolves to its CDP WebSocket URL.

Option	Type	Description
proxy	string	Required by the gateway, though the type marks it optional. scheme://user:pass@host:port
os	string	windows, android, linux, macos. Defaults to windows
headless	boolean	Run without a window
vnc	boolean	Request a live-view URL
maxLifetime	number	Seconds. Omitted means 7200, clamped into 120 to 86400
browserLanguage	string	Accept-Language value
uiLanguage	string	UI locale
browserVersionMin	number	Lowest Chromium major version the profile may claim. Defaults to the running version
browserVersionMax	number	Highest Chromium major version the profile may claim. Defaults to the running version
screenWidthMin	number	Lowest screen width
screenHeightMin	number	Lowest screen height
forceVisibility	boolean	Keep a background tab reporting itself visible and focused
metadata	object	Stored on the session, JSON-stringified on the way out

reconnectUrl(sessionId): Promise<string>

The CDP URL of a running session. Creates nothing. Pass the sessionId value, not the br_ id inside a CDP URL, which returns 404.

close(sessionId?): Promise<void>

Closes a session, defaulting to the most recent one. Either id works: the sessionId value or the br_ id at the end of the CDP URL. Throws RayobrowseError when there is no id to use.

listBrowsers(): Promise<BrowserSession[]>

Your running sessions. Each carries browserId, cdpUrl, status, createdAt and expiresAt.

getHealth(): Promise<HealthStatus>

The gateway’s health response.

getSessionCount(): Promise<SessionCount>

await client.getSessionCount(); // { limit: 5, remaining: 4, active: 1 }

Your concurrent browser limit, the browsers running now, and the slots free. remaining is limit - active and never goes below 0. The numbers come from GET /user/api/limits, which does not count against the per-minute launch limit, so polling it is free.

Properties

Property	Type	Description
sessionId	string | null	br_ id from the last connectUrl()
vncUrl	string | null	Live-view URL, set only when vnc: true was passed and the browser came up with one

Types

interface ConnectOptions {
  proxy?: string;
  os?: string;
  headless?: boolean;
  vnc?: boolean;
  maxLifetime?: number;
  browserLanguage?: string;
  uiLanguage?: string;
  browserVersionMin?: number;
  browserVersionMax?: number;
  screenWidthMin?: number;
  screenHeightMin?: number;
  forceVisibility?: boolean;
  metadata?: Record<string, unknown>;
}

interface SessionCount {
  limit: number;
  remaining: number;
  active: number;
}

interface HealthStatus {
  status: string;
  uptime: number;
}

Error classes

Error	Status	Properties
RayobrowseError	any	statusCode, body
AuthError	401	statusCode. No body; the gateway’s message is on message
ConcurrencyLimitError	429	limit, active, retryAfter. No body
RateLimitError	429	retryAfter. No body
BrowserCreateError	any other	statusCode, body

Each 429 class names the limit that was hit: ConcurrencyLimitError when your browsers are all running, RateLimitError when more than 60 launches went out in the last minute. retryAfter comes from the retry-after header, is a whole number of seconds and is never negative. It is 5 for a full account and 60 for the rate limit. See Limits.

The Python SDK has no AuthError. It raises BrowserCreateError with status_code 401 for a rejected key, so code ported between the two has to change here.

A missing or malformed proxy throws BrowserCreateError with statusCode 400, and a proxy the browser cannot get through throws it with statusCode 422. body is the plain-text message from /connect, a string, so there is no body.code to read. Match on the status. Neither is worth retrying.