Research API

01Quickstart

One request to POST /v1/research/run. Set $STELQ_KEY in your environment and run this as-is — it is generated from the live contract, not transcribed.

# 1) Submit the job — charged by depth on submit (quick $0.08 / balanced $0.25 / deep $0.40), returns a job handle.
curl -X POST https://api.stelq.com/v1/research/run \
  -H "Authorization: Bearer $STELQ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Map AI-native search startups and their moats","depth":"balanced","citations":true}'

# 2) Poll until status == "completed" (usually 5–15 min, ~40 sources).
curl https://api.stelq.com/v1/research/run/$JOB_ID \
  -H "Authorization: Bearer $STELQ_KEY"

02Authentication

Every request carries a bearer token in the Authorization header. Copied agent payloads reference the $STELQ_KEY environment variable, so set it in your agent's environment rather than pasting a live secret into a prompt or a chat log.

Authorization: Bearer $STELQ_KEY

03Parameters

{
  "query": "Map AI-native search startups and their moats",
  "depth": "balanced",
  "citations": true
}

04The job lifecycle

Lifecycle: queued → in_progress → completed (the terminal states are completed, failed, or cancelled). The submit call returns { id, status: "queued" } and is the billable event — The depth sets the price — quick $0.08, balanced $0.25, deep $0.40 — charged once on submit; polling is free. Poll GET /v1/research/run/{id} every 2–5 seconds until the status is terminal, then read result.outputText (fast, render-ready), result.reportMarkdown (long-form), and result.citations (source URLs). result.dossier carries the full structured sources for advanced use; error is populated only on failed/cancelled. A 502 on submit is safe to retry and is not charged; a 402 means top up your balance. To skip polling, pass a webhook and we'll notify you on completion — but polling always remains the source of truth.

{
  "id": "rsch_8K2mQ9vX3pLw",
  "status": "completed",
  "result": {
    "outputText": "AI-native search startups cluster around three moats: live indexing, citation fidelity, and agent-native delivery…",
    "reportMarkdown": "# AI-native search startups\n\n## Moats\n…full long-form report…",
    "citations": [
      "https://eur-lex.europa.eu/eli/reg/2024/1689",
      "https://example.com/ai-search-landscape"
    ],
    "dossier": {
      "…": "full structured retrieval packet — sources, synthesis, threads, gaps, stats"
    }
  }
}

05Webhooks

Pass a webhook (https URL) on submit and STELQ POSTs a small signed event there the moment the job reaches a terminal state — so you don't have to poll. The event is a signal, not the result body: read data.result_url to fetch the finished job. Different jobs can point at different URLs (the URL is your return address for that one job). Webhooks are an optimization on top of polling, never a replacement.

{
  "id": "evt_01JX7Z9C2QH4",
  "type": "research.run.completed",
  "api_version": "2026-06-01",
  "occurred_at": "2026-06-14T10:32:04Z",
  "attempt": 1,
  "data": {
    "job_id": "rsch_8K2mQ9vX3pLw",
    "status": "completed",
    "result_url": "https://api.stelq.com/v1/research/run/rsch_8K2mQ9vX3pLw"
  }
}

Signature headers: webhook-id · webhook-timestamp · webhook-signature

Verify before you trust the body: recompute HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{rawBody} with your account signing secret (whsec_…, revealed any time under API Keys in the console), then constant-time compare it against the webhook-signature header (format v1,<base64>). Reject timestamps older than ~5 minutes, and always verify against the raw request bytes — not re-serialized JSON.

• At-least-once delivery — you may occasionally receive a duplicate. Dedupe on data.job_id (+ type) and process each completion exactly once.
• Acknowledge fast: return a 2xx within 10 seconds, then do any slow work asynchronously — otherwise we time out and retry.
• On any non-2xx or timeout we retry with exponential backoff, up to 8 attempts over ~24h, then dead-letter.
• Webhook down? Nothing is lost — the result stays available; just poll result_url.
• Exactly one terminal event per job: research.run.completed or research.run.failed. Treat it as final.

06Submit response

Submit returns a job handle instantly — the answer arrives on the poll above.

{
  "id": "rsch_8K2mQ9vX3pLw",
  "status": "queued"
}

07Errors

08Rate limits

Research is queue-backed: submit as many jobs as you need and they run as worker capacity frees up — submit returns instantly with a handle either way. If you submit faster than the queue accepts, you'll get a 429 with a Retry-After header; back off and retry.