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"const res = await fetch(`${process.env.SPHYNX_URL}/v1/usage`, {
headers: { Authorization: `Bearer ${process.env.SPHYNX_API_KEY}` },
});
const usage = await res.json();import os
import requests
res = requests.get(
f"{os.environ['SPHYNX_URL']}/v1/usage",
headers={"Authorization": f"Bearer {os.environ['SPHYNX_API_KEY']}"},
timeout=30,
)
usage = res.json(){
"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_urlis refused oncdp_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
GETdoes not return them.
POST/v1/sessions/{id}/tokens returns new URLs for a running session.
curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/tokens" \
-H "Authorization: Bearer $SPHYNX_API_KEY"{
"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.
{
"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.
| HTTP | Code | When |
|---|---|---|
| 401 | unauthorized | Missing or invalid API key |
| 403 | invalid_token | Bad or expired token on cdp_url or live_view_url |
| 404 | session_not_found | No such session for this key |
| 429 | concurrency_limit | Too many live sessions for this key. Retry-After is set |
| 429 | mcp_connection_limit | Too many open MCP connections for this key. Retry-After is set |
| 429 | connection_limit | Too 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.