SPHYNX
esc
  • Loading
Open console

Get started

Authentication

Send your API key as a bearer token. Session URLs carry their own short-lived token.

There are two credentials. Your API key goes in the Authorization header of every request. The URLs you connect a browser client or a viewer to carry a token of their own, so they work where a header cannot be set.

API key

Send Authorization: Bearer <key> on every /v1 route and on /mcp. Keys start with sx_live_.

GET/v1/usage is a cheap call to check a key with: it starts nothing and returns this month's totals.

curl -s "$SPHYNX_URL/v1/usage" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"
200
{
  "period_start": "2026-11-01T00:00:00Z",
  "period_end": "2026-12-01T00:00:00Z",
  "sessions": 412,
  "browser_seconds": 98211,
  "proxy_bytes": { "residential": 5120334411, "external": 88213 },
  "concurrent_sessions": 3,
  "concurrency_limit": 5
}

Read the key from the environment or a secrets store. Do not commit it and do not send it to a browser: anyone who has it can start sessions on your account.

What a key can see

A key sees only the sessions it created. Another key's session answers 404 session_not_found, the same as a session that does not exist.

Usage and the concurrency limit are per key. concurrency_limit in the usage response is how many sessions the key may run at once. One more than that fails with 429 concurrency_limit, and the Retry-After header says when to try again.

A key can also hold at most twice its concurrency limit in open MCP connections. One more answers 429 mcp_connection_limit.

Session tokens

A session has two URLs that are opened by something other than your HTTP client: cdp_url for Playwright or Puppeteer, and live_view_url for a person watching. Both carry a token in the query string, because WebSocket clients cannot reliably send headers.

  • The token is bound to one session.
  • Each URL carries its own token: the one in live_view_url is refused on cdp_url, and the other way round.
  • It is valid for token_expires_in_seconds, 1800 when issued, and can be reused until then.
  • The URLs are returned when the session is created and by the call below. Reading a session with GET does not return them.

POST/v1/sessions/{id}/tokens returns new URLs for a running session.

curl
curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/tokens" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"
200
{
  "cdp_url": "wss://api.example/v1/sessions/sess_9f2c.../cdp?token=...",
  "live_view_url": "https://api.example/v1/sessions/sess_9f2c.../view?token=...",
  "token_expires_in_seconds": 1800
}

When a credential is rejected

A missing or invalid key fails with 401. The body has the same shape as every other error.

401
{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "request_id": "req_5d1c0e7a9b3f"
  }
}

A bad or expired token fails with 403 invalid_token. On cdp_url that is a failed WebSocket handshake, so the client reports a connection error. Mint a new URL and connect again.

HTTPCodeWhen
401unauthorizedMissing or invalid API key
403invalid_tokenBad or expired token on cdp_url or live_view_url
404session_not_foundNo such session for this key
429concurrency_limitToo many live sessions for this key. Retry-After is set
429mcp_connection_limitToo many open MCP connections for this key. Retry-After is set
429connection_limitToo many open connections to one session: 10 on cdp_url, 5 on the live view. Retry-After is set

A path that no route serves answers 404 not_found, and a route called with the wrong method answers 405 method_not_allowed. Neither checks the key.

Request IDs

Every response has an X-Request-Id header, and every error body repeats it as request_id. Quote it when you report a problem.

Next

  • Quickstart: make a first request with the key.
  • Live view: watch or embed a session with live_view_url.
  • Errors: every code and its HTTP status.