SPHYNX
esc
  • Loading
Open console

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-deflate is 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.createBrowserContext with proxyServer or proxyBypassList, Target.exposeDevToolsProtocol and Target.setRemoteLocations. Each is answered with a CDP error, code -32601, that names the method with .notAllowed added, or .proxyNotAllowed for Target.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();
Puppeteer
import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: session.cdp_url,
  defaultViewport: null,
});
const [page] = await browser.pages();
A refused command
{
  "id": 7,
  "error": {
    "code": -32601,
    "message":
      "'Target.setRemoteLocations.notAllowed' wasn't found"
  }
}

Create a connect token

POST/v1/sessions/{id}/tokens

Returns 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
curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/tokens" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"
200
{
  "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.

Embed
<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.

HTTPCodeWhen
401unauthorizedMissing or invalid API key on the token call
403invalid_tokenBad or expired token on cdp_url or live_view_url
404session_not_foundNo such session for this key
410session_closedThe session has ended
429connection_limitToo many open connections to the session: 10 on cdp_url, 5 on the live view. details.limit is the cap. Retry-After is set
500internalOn the token call: our fault. Send us the request_id