API reference
Overview
The base URL, authentication and the conventions every endpoint follows.
The API is JSON over HTTP. Create a session, then use it three ways: connect Playwright or Puppeteer to its cdp_url, drive it with plain HTTP calls, or give it to an agent through the MCP server.
Base URL
Every route is under /v1 on the base URL of your deployment. The MCP server is at /mcp on the same host.
The examples in this reference read the base URL and the key from two environment variables.
export SPHYNX_URL=http://localhost:8080 # your deployment's base URL
export SPHYNX_API_KEY=sx_live_...Examples that work on a session keep its ID in SESSION.
SESSION=$(curl -s -X POST "$SPHYNX_URL/v1/sessions" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Content-Type: application/json" \
-d '{}' | jq -r .id)Authentication
Send the key as a bearer token on every /v1 route and on /mcp. Keys start with sx_live_. A missing or invalid key returns 401 unauthorized.
curl -s "$SPHYNX_URL/v1/usage" \
-H "Authorization: Bearer $SPHYNX_API_KEY"Two URLs carry a token of their own instead of the key: cdp_url and live_view_url. Both come back when you create a session and from POST/v1/sessions/{id}/tokens. See Connect.
Requests and responses
- Bodies are JSON in and JSON out. Send
Content-Type: application/jsonwith every body. - Field names are snake_case.
- Unknown fields are rejected with
invalid_request. - A path under
/v1or/mcpthat no endpoint serves answers 404not_found. An endpoint called with another method answers 405method_not_allowed, with the methods it takes in theAllowheader.
Units and timestamps
Numbers carry their unit in the name: timeout_seconds, timeout_ms, proxy_bytes.
Timestamps are RFC 3339 in UTC, for example 2026-11-21T10:00:00Z.
Lists
List endpoints take two query parameters and return one shape.
Query
- limitint, 1–100default20
How many items to return.
- cursorstring
The
next_cursorof the previous page.
{
"data": [],
"next_cursor": null
}next_cursor is a string while there are more items and null on the last page. Sessions and runs are listed newest first.
Request IDs
Every response has an X-Request-Id header. An error body carries the same value as request_id. Quote it when you report a problem.
Errors
Every failed request returns the same JSON shape, with a stable code and a message for people. The full list is on Errors.
{
"error": {
"code": "concurrency_limit",
"message": "concurrent session limit reached",
"request_id": "req_5d1c0e7a9b3f",
"details": { "limit": 5 }
}
}Session lifetime
A session ends when one of four things happens:
- you delete it with DELETE/v1/sessions/{id},
timeout_secondspasses since it was created,- it is idle for
idle_timeout_seconds, - the browser exits.
Disconnecting a CDP client does not end the session. A client that sends Browser.close does end it, with close_reason browser_closed. After it ends, close_reason on the session object says why.
The idle clock is reset by every CDP frame and every drive call. A session is not idle while a drive call is running on it, and an agent run resets the clock about every 10 s while it is running. Reading the session with GET and watching the live view do not reset it.
One drive call at a time
Drive calls on one session run one at a time. A second call waits up to 3 s for the first to finish, then fails with session_in_use. Retry it.
Endpoints
| Endpoint | What it does | Page |
|---|---|---|
POST /v1/sessions | Create a session | Sessions |
GET /v1/sessions/{id} | Get a session | Sessions |
GET /v1/sessions | List sessions | Sessions |
DELETE /v1/sessions/{id} | End a session | Sessions |
GET /v1/regions | List regions | Sessions |
GET /v1/proxy/countries | List residential proxy countries | Sessions |
POST /v1/sessions/{id}/tokens | Get a fresh cdp_url and live_view_url | Connect |
GET /v1/sessions/{id}/cdp | The CDP WebSocket behind cdp_url | Connect |
GET /v1/sessions/{id}/view | The page behind live_view_url | Connect |
POST /v1/sessions/{id}/navigate | Load a page | Navigate |
POST /v1/sessions/{id}/elements | List elements on the page | Elements |
POST /v1/sessions/{id}/actions | Run steps in order | Actions |
POST /v1/sessions/{id}/extract | Read the page | Extract |
POST /v1/sessions/{id}/screenshot | Capture the page | Screenshot |
GET /v1/sessions/{id}/tabs | List tabs | Tabs |
POST /v1/sessions/{id}/tabs | Open a tab | Tabs |
DELETE /v1/sessions/{id}/tabs/{tab_id} | Close a tab | Tabs |
POST /v1/screenshot | Capture a URL without a session | Stateless screenshot |
POST /v1/runs | Start an agent run | Runs |
GET /v1/runs/{id} | Get a run | Runs |
GET /v1/runs | List runs | Runs |
POST /v1/runs/{id}/cancel | Cancel a run | Runs |
GET /v1/runs/{id}/events | Read or stream a run's events | Runs |
GET /v1/usage | Usage for the current month | Usage |
POST /mcp | The MCP server | MCP tools |