SPHYNX
esc
  • Loading
Open console

Get started

Quickstart

Create a session, read a page as Markdown and close the session.

At the end you have the content of a web page as Markdown, read by a hosted browser. You need an API key, curl and jq.

Set your key

Every snippet in these docs reads two environment variables: the base URL of your deployment and your API key.

Shell
export SPHYNX_URL=http://localhost:8080   # your deployment's base URL
export SPHYNX_API_KEY=sx_live_...

Create a session

POST/v1/sessions starts a browser and returns 201 once it is ready. Every field is optional. This one asks for a Mac fingerprint and keeps the session 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 '{"os": "mac"}' | jq -r .id)

Read a page

POST/v1/sessions/{id}/extract with a url loads the page and returns its main content as Markdown.

curl
curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/extract" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}'
200
{
  "url": "https://example.com/",
  "title": "Example Domain",
  "markdown": "This domain is for use in documentation examples...",
  "truncated": false
}

Add | jq -r .markdown to the command to print the Markdown on its own.

Close the session

A session runs until you delete it, it reaches timeout_seconds (3600 by default) or it sits idle for idle_timeout_seconds (300 by default). Delete it when you are done. The call returns 204 and is safe to repeat.

curl
curl -s -X DELETE "$SPHYNX_URL/v1/sessions/$SESSION" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"

The same with Playwright

The session you create also returns a cdp_url. Connect Playwright to it, drive the page with the code you already have, and read the page with the same extract call. Install playwright-core for TypeScript or playwright and requests for Python. No local browser is needed.

import { chromium } from "playwright-core";

const base = process.env.SPHYNX_URL;
const headers = {
  Authorization: `Bearer ${process.env.SPHYNX_API_KEY}`,
  "Content-Type": "application/json",
};

const created = await fetch(`${base}/v1/sessions`, {
  method: "POST",
  headers,
  body: JSON.stringify({ os: "mac" }),
});
const session = await created.json();

const browser = await chromium.connectOverCDP(session.cdp_url);
// Always use the existing context and page.
const page = browser.contexts()[0].pages()[0];
await page.goto("https://example.com");

const read = await fetch(`${base}/v1/sessions/${session.id}/extract`, {
  method: "POST",
  headers,
  body: JSON.stringify({ formats: ["markdown"] }),
});
const { markdown } = await read.json();
console.log(markdown);

await browser.close(); // disconnects only; the session keeps running
await fetch(`${base}/v1/sessions/${session.id}`, { method: "DELETE", headers });

Without a url, extract reads the page the session is already on, which here is the one Playwright opened.

What can go wrong

HTTPCodeWhen
401unauthorizedThe key is missing or invalid
429concurrency_limitToo many live sessions for this key. Retry-After is set
502navigation_failedDNS failure, connection refused, TLS error
504navigation_timeoutThe page did not load in timeout_ms (30000 by default)

Every error has the same shape: see Errors.

Next

  • Concepts: when a session ends, identities, proxies and locators.
  • Connect Playwright: the rules that keep the fingerprint intact.
  • Fill a form: find fields, fill them and submit over HTTP.
  • MCP: give the browser to an agent.