One header, four scopes.
Every /api/v1 call is made by an organization API key in the Authorization header. Keys are scoped, shown once, and revocable by the organization's owners and admins.
The header
Send the key as a Bearer token on every request to https://sparkcrawl.com. A key is sc_live_ followed by 43 URL-safe characters; anything else is rejected before it reaches a lookup.
Authorization: Bearer sc_live_…The key acts for its organization: jobs, usage, quotas and charges belong to the organization, and every member sees them in the app.
Scopes
A key carries one to four scopes. An operation needs the scope it names; reading a job works with any scope the key has.
| scope | allows |
|---|---|
scrape | POST /scrape, batches, browser sessions, metrics, balance and pricing reads |
crawl | POST /crawls and crawl reads, maps, recrawl schedules |
search | POST /search |
research | POST /research |
| any | GET /jobs, job pages and exports, artifacts, usage, capabilities |
Managing keys
Keys are created, listed and revoked at /app/api by the organization's owners and admins. Those endpoints (/api/v1/keys) accept only a signed-in browser session — a key cannot mint or revoke keys. The same is true of checkout.
Store the secret as an environment variable or in your secret manager. Never ship it to a browser or a mobile app; if it leaks, revoke it and create a new one — revocation is immediate.
Auth errors
Errors share one envelope: { "error": { "code": "…" } }. The full list is on Billing & errors.
| status | code | meaning |
|---|---|---|
| 401 | unauthorized | Missing, malformed or revoked key — or a key without the scope this operation needs. |
| 403 | organization_required | The signed-in session has no organization yet. |
| 403 | forbidden | Key and checkout management need an owner or admin. |
| 403 | invalid_origin | A session mutation came from another origin. |
| 503 | auth_store_unavailable | Credentials could not be checked; retry. |
Safe retries
Job-creating calls accept an Idempotency-Key header (up to 128 characters of A–Z a–z 0–9 . _ ~ -). Retrying with the same key and body returns the original job with replayed: true; the same key with a different body answers 409 idempotency_conflict.
Quickstart
Sparkcrawl is a web data API — scrape a page, crawl a site, search with cited answers, or run a research report. Every call uses an organization API key and draws from one balance in US dollars.
Billing & errors
Every organization has a single balance in US dollars. The Playground, the API and the MCP server all draw from it at the same tariff, and you only pay for pages that succeed.