API v1 · live

Saffron Browser developer surface

A high-concurrency sovereign headless browser, 100% wire-compatible with the Steel.dev API. Zero cloud markup, live SSE screencast, and a four-vector proxy mesh, with the same SDK you already use.

01Start in 45 seconds

Grab a free key from the homepage (1,000 requests, no card), then run your first scrape. Pick your stack:

scrape.sh

$ curl https://api.saffronbrowser.com/v1/scrape \
  -H "Authorization: Bearer sb_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "format": "markdown",
    "proxy": { "tier": "v6spray" }
  }'

# pip install steel-sdk
from steel import Steel

client = Steel(
    steel_api_key="sb_live_your_key",
    base_url="https://api.saffronbrowser.com/v1",
)

res = client.scrape(
    url="https://example.com/pricing",
    format="markdown",
    proxy={"tier": "v6spray"},
)
print(res.markdown)  # clean, LLM-ready

// npm i steel-sdk
import { Steel } from "steel-sdk";

const client = new Steel({
  apiKey: process.env.SAFFRON_KEY,
  baseUrl: "https://api.saffronbrowser.com/v1",
});

const res = await client.scrape({
  url: "https://example.com/pricing",
  format: "markdown",
  proxy: { tier: "v6spray" },
});
console.log(res.markdown);

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "saffron-browser": {
      "command": "npx",
      "args": ["-y", "@saffron/browser-mcp"],
      "env": { "SAFFRON_BROWSER_KEY": "sb_live_your_key" }
    }
  }
}

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "saffron-browser": {
      "command": "npx",
      "args": ["-y", "@saffron/browser-mcp"],
      "env": { "SAFFRON_BROWSER_KEY": "sb_live_your_key" }
    }
  }
}

02Switch from Steel in one line

Saffron speaks a 100% Steel.dev-compatible superset. Migrating existing code means changing exactly one parameter: base_url. Everything else (sessions, scrape, screenshot, CDP) is wire-identical.

python · main.py

- client = Steel(steel_api_key=KEY, base_url="https://api.steel.dev")

+ client = Steel(steel_api_key="sb_live_…", base_url="https://api.saffronbrowser.com/v1")

typescript · scraper.ts

- const steel = new Steel({ apiKey: process.env.STEEL_KEY });

+ const steel = new Steel({ apiKey: process.env.SAFFRON_KEY, baseUrl: "https://api.saffronbrowser.com/v1" });

Existing code immediately inherits Saffron's $0/GB egress, zero-charge block guarantee, and transatlantic residential mesh.

03Model Context Protocol (MCP)

Wire Saffron directly into an agent runtime. The MCP server exposes scrape, screenshot, and session tools to Claude Desktop and Cursor. Config lives in the Cursor MCP and Claude Desktop tabs of the quickstart above: one block, one key.

Package @saffron/browser-mcp, run with npx -y @saffron/browser-mcp.
Auth via SAFFRON_BROWSER_KEY=sb_live_… in the server env.
Restart the host app; the agent gets a browser without leaving its runtime.

04Authentication

Pass your Saffron key on every request. Three header names are accepted for drop-in compatibility:

header

Authorization: Bearer sb_live_your_key

x-steel-key: sb_live_your_key

x-grid-key: sb_live_your_key

Keys are prefixed sb_live_. Treat them as secrets: set them in env vars, never commit them. A blocked request (403/429) is billed $0.00.

05API reference

POST/v1/scrape

One-shot stateless scrape. Converts a target page into clean, LLM-ready markdown, through Cloudflare and bot shields, on the proxy tier you choose.

Request

request.json

{
  "url": "https://example.com/pricing",
  "format": "markdown",
  "proxy": {
    "tier": "v6spray"   // direct · v6spray · tor · residential
  }
}

{
  "ok": true,
  "url": "https://example.com/pricing",
  "title": "Example: Pricing",
  "markdown": "# Pricing\n\n- Starter: $10\n- Enterprise: Custom\n",
  "egressIp": "2a01:4f8:c17:…",
  "costCredits": 1
}

POST/v1/screenshot

Stateless full-page or viewport screenshot of any URL, returned as a signed asset link or base64. Same proxy tiers as scrape.

Response · 200 OK

{ "ok": true, "format": "png", "assetUrl": "https://cdn.saffronbrowser.com/s/9f2a1c…png", "width": 1280, "costCredits": 1 }

POST/v1/sessions

Launch an isolated, stateful browser session and receive a CDP websocket endpoint to drive it with Playwright or Puppeteer.

Response · 200 OK

{ "ok": true, "sessionId": "sess_5f3c…", "wsEndpoint": "wss://api.saffronbrowser.com/v1/cdp/sess_5f3c…", "region": "fsn" }

GET/v1/sessions/:id/screencast

Streams live JPEG frames over Server-Sent Events straight from Chrome DevTools Protocol at up to 10 FPS. Watch the agent browse in real time.

POST/v1/route/fetch

Multi-vector proxied HTTP fetch. Route a raw request through direct bare-metal, IPv6 spray ($0/GB), Tor, or US-East residential egress.