API documentation

Get started

Send a scientific question to /v1/research; poll or webhook for the result; receive a Markdown report.

Quick start

python

from sparkit import SparkitClient

client = SparkitClient(api_key="sk_sparkit_YOUR_API_KEY")

response = client.research(
    "What is the role of BRCA1 in homologous recombination?"
)
print(response)

Authentication

All requests require a Bearer API key. Mint one in the dashboard under API keys.

http

Authorization: Bearer sk_sparkit_...

Endpoints

Method	Path	Description
POST	/v1/research	Submit a question. Returns a job_id immediately.
GET	/v1/research/{job_id}	Poll status. Returns the result when complete.
DELETE	/v1/research/{job_id}	Cancel an in-flight job.
GET	/v1/usage	Current usage, quota, and billing summary.

Delivery

Jobs run async. Pass a callback_url to receive a webhook on completion, or poll GET /v1/research/{job_id}. Typical end-to-end is 5–50 minutes.

Idempotency

Send Idempotency-Key on every request (any string ≤128 chars). Retrying the same key within 24h returns the original job_id instead of creating a duplicate billed job.

Full specification

The complete spec — request schema, error codes, idempotency, rate limits, webhook delivery — lives in the repository while the dedicated docs site is being built.

View API_SPEC.md on GitHub

A first-party documentation site at docs.sparkit.science is on the roadmap.