Quickstart

Quickstart

Go from zero to your first scrape and structured extraction in three calls. Everything below uses real endpoints and the x-api-key header.

Base URL: https://api.superscraper.dev · all endpoints are versioned under /v1/.

1. Get an API key

You have two ways to get a key.

Dashboard (humans)

Sign in at app.superscraper.dev (opens in a new tab), then go to Settings → API Keys → Create key. Copy the key immediately, the plaintext is shown only once.

Self-serve provisioning (agents / scripts)

POST /v1/keys/provision mints a fresh free-tier tenant and key with no sign-in. This is the path for AI agents that need to bootstrap themselves. It is IP-rate-limited and free-tier only.

curl -X POST https://api.superscraper.dev/v1/keys/provision \
  -H "Content-Type: application/json" \
  -d '{"label": "my-agent"}'

Response (HTTP 201), the key is shown once:

{
  "apiKey": "ss_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "tenantId": "8f3c…",
  "tier": "free",
  "note": "Free tier. Top up credits (POST /v1/billing) or pay per call (x402) for paid usage."
}

Store the apiKey value, it cannot be retrieved again. See Authentication for how the key is passed and kept secret.

The note field is returned verbatim by the API and points at POST /v1/billing; the actual route for a plan upgrade is POST /v1/billing/checkout.

2. Your first scrape

Turn any URL into clean markdown. By default the engine also runs the free JSON-LD listing extraction (no LLM cost).

curl -X POST https://api.superscraper.dev/v1/scrape \
  -H "x-api-key: ss_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
{
  "url": "https://example.com",
  "markdown": "# Example Domain\n\nThis domain is for use in illustrative examples...",
  "listing": null,
  "metadata": {
    "fetchMethod": "plain",
    "latencyMs": 312,
    "cached": false
  },
  "ok": true
}

metadata.fetchMethod tells you how the page was fetched: "plain", "playwright", or "stealth". The engine escalates automatically when a page needs JavaScript. See /v1/scrape for cookies, headers, formats[], content shaping, and caching options.

3. Your first extraction

/v1/extract returns the data plus how confident it is and where each value came from.

Schema-free runs the free JSON-LD → regex cascade (no LLM cost) and returns _confidence, _extraction_method, and _provenance:

curl -X POST https://api.superscraper.dev/v1/extract \
  -H "x-api-key: ss_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.yelp.com/biz/acme-plumbing-austin"}'
{
  "url": "https://www.yelp.com/biz/acme-plumbing-austin",
  "data": {
    "name": "Acme Plumbing",
    "phone": "(512) 555-0187",
    "city": "Austin",
    "state": "TX",
    "rating": 4.8,
    "_confidence": 0.92,
    "_extraction_method": "json-ld",
    "_provenance": "json-ld"
  }
}

Pass a schema to extract an exact JSON shape with an LLM (routed by your tier). See /v1/extract for the confidence + provenance fields in full, and model routing.

Next steps

IntroductionAuthentication