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.
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.
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 -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"]}'{
"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 -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 });import os
import requests
from playwright.sync_api import sync_playwright
base = os.environ["SPHYNX_URL"]
headers = {"Authorization": f"Bearer {os.environ['SPHYNX_API_KEY']}"}
session = requests.post(
f"{base}/v1/sessions", headers=headers, json={"os": "mac"}, timeout=60
).json()
with sync_playwright() as p:
browser = p.chromium.connect_over_cdp(session["cdp_url"])
# Always use the existing context and page.
page = browser.contexts[0].pages[0]
page.goto("https://example.com")
read = requests.post(
f"{base}/v1/sessions/{session['id']}/extract",
headers=headers,
json={"formats": ["markdown"]},
timeout=60,
)
print(read.json()["markdown"])
browser.close() # disconnects only; the session keeps running
requests.delete(f"{base}/v1/sessions/{session['id']}", headers=headers, timeout=30)Without a url, extract reads the page the session is already on, which here is the one Playwright opened.
What can go wrong
| HTTP | Code | When |
|---|---|---|
| 401 | unauthorized | The key is missing or invalid |
| 429 | concurrency_limit | Too many live sessions for this key. Retry-After is set |
| 502 | navigation_failed | DNS failure, connection refused, TLS error |
| 504 | navigation_timeout | The 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.