Query & synthesis

The synthesis endpoints answer questions with citation-validated output. All take an optional cost_cap_usd — a hard spend ceiling for the request (not a price). Scope: query:read (usage: usage:read; health is public).

POST /v1/query

Ask a question, get a cited answer. Two modes: speculative (fast retrieval-first synthesis, $0.01 — available on every tier, Free capped at 50/mo) and deliberate (deep multi-step synthesis, metered by depth and capped by your cost_cap_usd, default cap $1.00 — Team and above, Team capped at 100/mo). If the corpus can't support an answer, the response says insufficient_evidence — it never fabricates.

Measured latency (production, 19 August 2026): a fresh query runs ~30–150 s in either mode — pipeline cold start can account for up to ~70 s of that, and a query the corpus cannot answer sits at the top of the range because the pipeline still runs to completion to establish insufficient_evidence. A repeat of a query that answered is served from cache in ~1 s; a repeat of one that returned insufficient_evidence is not cached and costs the full fresh time again. Budget client timeouts for the fresh-query case.

Long responses are padded, not chunked. A request still running after 20 s begins receiving JSON whitespace every 10 s until the result is ready, so the connection is never idle and the CDN in front of this API does not time it out — its origin-silence limit is 125.2 s, measured 1 September 2026, and a deliberate query can exceed that. The body is still one JSON document: any normal parser (res.json(), json.loads, jq) skips leading whitespace and sees exactly what it saw before. Padded responses carry X-Forum-Keepalive. One honest consequence: once padding has started the status line is already sent, so a failure after that point arrives as 200 carrying the usual RFC 9457 problem body — read status from the body, which is what that member is for.

curl "https://api.forumatlas.com/v1/query" \
  -H "Authorization: Bearer $FORUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "Which mid-tier defense primes gained cyber contract share this quarter?", "mode": "speculative" }'

POST /v1/causal

Causal trace: how a shock to one entity propagates across the graph, each hop cited. Team and above (Team capped at 50/mo).

POST /v1/tutor

One conversational tutor turn — cited Q&A grounded in the corpus. Default cost_cap_usd 0.50. Available on every tier (Free capped at 20/mo). Starting a new session (no session_id) requires sector_id and topic; pass the returned session_id on later turns to resume.

# First turn — new session, so sector_id + topic are required
curl "https://api.forumatlas.com/v1/tutor" \
  -H "Authorization: Bearer $FORUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sector_id": "cyber", "topic": "zero-trust architecture", "message": "Why did CISA mandate it for federal agencies?" }'

# Later turns — resume with the session_id from the first response
curl "https://api.forumatlas.com/v1/tutor" \
  -H "Authorization: Bearer $FORUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "<session_id>", "message": "How does that differ from perimeter defense?" }'

GET /v1/health

Unauthenticated liveness probe. Returns service status; safe for uptime monitors.

GET /v1/usage

Your workspace's metered usage — what you'll be billed, queryable instead of a surprise. Scope: usage:read.

curl "https://api.forumatlas.com/v1/usage" \
  -H "Authorization: Bearer $FORUM_API_KEY"