API reference
Every operation under https://sparkcrawl.com/api/v1, generated from the OpenAPI 3.1 document the server publishes.
The server publishes the OpenAPI 3.1 document these pages are generated from. Every call takes the organization key as Authorization: Bearer sc_live_… — see Authentication — and errors share one envelope, listed on Billing & errors. Each operation page has a playground that sends the request to https://sparkcrawl.com with your key.
40 operations
scrape
Single pages, batches and browser sessions
- POST
/api/v1/batchesEnqueue up to 100 independent requests - GET
/api/v1/batches/{id}/pagesRead the independent page results of a batch - POST
/api/v1/scrapeScrape one page synchronously or enqueue with async=1 - GET
/api/v1/sessionsList reusable browser sessions - POST
/api/v1/sessionsCreate a reusable browser session (cookies kept across scrapes) - GET
/api/v1/sessions/{id}Read a browser session - DELETE
/api/v1/sessions/{id}Delete a browser session
crawl
Same-host crawls, URL maps and recrawl schedules
- GET
/api/v1/crawlsList crawl jobs - POST
/api/v1/crawlsEnqueue a bounded same-host crawl - GET
/api/v1/crawls/{id}Read crawl progress, retention and cost - DELETE
/api/v1/crawls/{id}Cancel a crawl and keep the pages already captured - GET
/api/v1/crawls/{id}/exportStream every page of a crawl as JSON or JSON Lines - GET
/api/v1/crawls/{id}/pagesRead crawled pages, a page of results at a time - POST
/api/v1/mapsDiscover up to 1000 URLs under robots and budget limits - GET
/api/v1/maps/{id}/linksRead the URLs a map discovered, with their status - GET
/api/v1/schedulesList recrawl schedules when automation is enabled - POST
/api/v1/schedulesCreate a bounded recrawl schedule when automation is enabled - PATCH
/api/v1/schedules/{id}Pause or resume a recrawl schedule when automation is enabled - DELETE
/api/v1/schedules/{id}Pause a recrawl schedule when automation is enabled
search
Cited answers and judged results from the open web
research
Asynchronous multi-question research reports
jobs
Status, pages, exports and artifacts of any job
- GET
/api/v1/artifactsDownload a ready, unexpired artifact authorized for this job - GET
/api/v1/jobsList all authorized jobs - GET
/api/v1/jobs/{id}Read the status and result of any job - DELETE
/api/v1/jobs/{id}Cancel any queued or running job - GET
/api/v1/jobs/{id}/exportStream every page of a job as JSON or JSON Lines - GET
/api/v1/jobs/{id}/pagesRead the pages of any job, a page of results at a time
account
API keys, usage, metrics and capabilities
- GET
/api/v1/capabilitiesRead the capabilities and limits enabled on this deployment - GET
/api/v1/keysList scoped API keys; session only - POST
/api/v1/keysCreate a scoped key; secret returned once; session owner/admin only - DELETE
/api/v1/keys/{id}Revoke key; session owner/admin only - GET
/api/v1/metricsRead scraping metrics for the last 1–30 days - GET
/api/v1/openapiRead this OpenAPI document - GET
/api/v1/usageRead organization job, page and cost totals
billing
Balance, tariff and balance top-ups
- GET
/api/v1/billingOrganization balance, quotas and ledger - POST
/api/v1/checkoutStart a balance top-up checkout; session owner/admin only - GET
/api/v1/checkout/sessions/{id}Read whether a checkout session was paid and credited; session only - GET
/api/v1/pricingCurrent tariff and available plans - POST
/api/v1/pricing/simulateSimulate unit economics for a bounded sample - POST
/api/v1/webhooks/stripeInternal Stripe event receiver