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.

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"