API reference
Connect
Attach a CDP client to a session, watch it live, and renew the URLs that do both.
Creating a session returns two URLs: cdp_url for a client to drive the browser and live_view_url for a person to watch it. Each carries its own token, valid for token_expires_in_seconds and usable any number of times until then. The token of one URL is refused on the other.
Connect over CDP
cdp_url is a browser-level Chrome DevTools Protocol endpoint. Pass it to Playwright, Puppeteer or any other CDP client exactly as returned. The token is in the URL because WebSocket clients cannot reliably send headers.
Three rules keep the session's fingerprint intact:
- Use the existing context,
contexts()[0]. A new context loses the session's identity and storage. - Do not set a viewport, user agent, locale or timezone from the client. The session already has consistent values.
- With Puppeteer pass
defaultViewport: null.
Disconnecting a client does not end the session. It keeps running until you delete it or it times out, and every CDP frame resets its idle clock. Playwright's browser.close() only disconnects. With Puppeteer call browser.disconnect(): its browser.close() tells the browser to exit, which ends the session with close_reason browser_closed.
Do not close the session's last page from a client; open the new page first. A session with no page has no tabs, and drive calls answer tab_not_found until Open a tab opens one.
A bad or expired token fails the WebSocket handshake with 403 invalid_token. Get a new URL from Create a connect token.
Limits
- At most 10 connections to one session at a time. One more fails the handshake with 429
connection_limit. - Text frames only, without WebSocket compression:
permessage-deflateis not negotiated. A binary frame or a message over 16 MiB ends the connection. - Three commands are refused, because they would let traffic leave the session around its proxy:
Target.createBrowserContextwithproxyServerorproxyBypassList,Target.exposeDevToolsProtocolandTarget.setRemoteLocations. Each is answered with a CDP error, code-32601, that names the method with.notAllowedadded, or.proxyNotAllowedforTarget.createBrowserContext.
import { chromium } from "playwright-core";
const browser = await chromium.connectOverCDP(
session.cdp_url,
);
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://example.com");
// Disconnects only. The session keeps running.
await browser.close();from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.connect_over_cdp(session["cdp_url"])
page = browser.contexts[0].pages[0]
page.goto("https://example.com")import puppeteer from "puppeteer-core";
const browser = await puppeteer.connect({
browserWSEndpoint: session.cdp_url,
defaultViewport: null,
});
const [page] = await browser.pages();{
"id": 7,
"error": {
"code": -32601,
"message":
"'Target.setRemoteLocations.notAllowed' wasn't found"
}
}Create a connect token
POST/v1/sessions/{id}/tokensReturns a new cdp_url and live_view_url for a running session. Call it when the URLs from create have expired, or when you only have the session ID. It takes no body.
Path
- idstringrequired
The session ID.
Response
- cdp_urlstring
The WebSocket address a CDP client connects to.
- live_view_urlstring
A page that shows the session live.
- token_expires_in_secondsint
How long the token in both URLs stays valid. The token is reusable until it expires.
curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/tokens" \
-H "Authorization: Bearer $SPHYNX_API_KEY"{
"cdp_url": "wss://api.example/.../cdp?token=...",
"live_view_url": "https://api.example/.../view?token=...",
"token_expires_in_seconds": 1800
}Live view
Open live_view_url in a browser to watch the session, or embed it in a page of your own. It is view only. Watching does not keep the session alive: it does not reset the idle clock.
At most 5 viewers can watch one session at a time. One more is refused with 429 connection_limit.
The guide is Live view.
<iframe
src="LIVE_VIEW_URL"
style="width: 100%; aspect-ratio: 16 / 10; border: 0"
></iframe>Errors
The shape is the same as everywhere else: see Errors.
| HTTP | Code | When |
|---|---|---|
| 401 | unauthorized | Missing or invalid API key on the token call |
| 403 | invalid_token | Bad or expired token on cdp_url or live_view_url |
| 404 | session_not_found | No such session for this key |
| 410 | session_closed | The session has ended |
| 429 | connection_limit | Too many open connections to the session: 10 on cdp_url, 5 on the live view. details.limit is the cap. Retry-After is set |
| 500 | internal | On the token call: our fault. Send us the request_id |