SPHYNX
esc
  • Loading
Open console

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.

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

curl
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
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/json with every body.
  • Field names are snake_case.
  • Unknown fields are rejected with invalid_request.
  • A path under /v1 or /mcp that no endpoint serves answers 404 not_found. An endpoint called with another method answers 405 method_not_allowed, with the methods it takes in the Allow header.

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_cursor of the previous page.

200
{
  "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.

429
{
  "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_seconds passes 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

EndpointWhat it doesPage
POST /v1/sessionsCreate a sessionSessions
GET /v1/sessions/{id}Get a sessionSessions
GET /v1/sessionsList sessionsSessions
DELETE /v1/sessions/{id}End a sessionSessions
GET /v1/regionsList regionsSessions
GET /v1/proxy/countriesList residential proxy countriesSessions
POST /v1/sessions/{id}/tokensGet a fresh cdp_url and live_view_urlConnect
GET /v1/sessions/{id}/cdpThe CDP WebSocket behind cdp_urlConnect
GET /v1/sessions/{id}/viewThe page behind live_view_urlConnect
POST /v1/sessions/{id}/navigateLoad a pageNavigate
POST /v1/sessions/{id}/elementsList elements on the pageElements
POST /v1/sessions/{id}/actionsRun steps in orderActions
POST /v1/sessions/{id}/extractRead the pageExtract
POST /v1/sessions/{id}/screenshotCapture the pageScreenshot
GET /v1/sessions/{id}/tabsList tabsTabs
POST /v1/sessions/{id}/tabsOpen a tabTabs
DELETE /v1/sessions/{id}/tabs/{tab_id}Close a tabTabs
POST /v1/screenshotCapture a URL without a sessionStateless screenshot
POST /v1/runsStart an agent runRuns
GET /v1/runs/{id}Get a runRuns
GET /v1/runsList runsRuns
POST /v1/runs/{id}/cancelCancel a runRuns
GET /v1/runs/{id}/eventsRead or stream a run's eventsRuns
GET /v1/usageUsage for the current monthUsage
POST /mcpThe MCP serverMCP tools