Quickstart

Your first /v1/query in 5 minutes.

1 — Get an API key

Sign in to your Forum Atlas workspace, navigate to API keys, and click New API key. Scope it to query:read for the quickstart (add brief:read and forecast:read when you start pulling briefs and forecasts). Endpoint availability and monthly caps vary by plan — deliberate mode, forecast generation, and causal traces need Team or above (see tier gates).

2 — Make your first call

bash

curl -X POST https://api.forumatlas.com/v1/query \
  -H "Authorization: Bearer $FORUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sectors": ["cyber"],
    "persona": "vendor_competitive_intel",
    "query": "<your question>"
  }'

3 — Read the response

json

{
  "request_id": "6f0a1c7d-...",
  "mode": "speculative",
  "brief_id": "b2f1c904-...",
  "headline": "<one-line answer>",
  "lede": "<two or three sentences, every assertion cited>",
  "sections": [
    {
      "heading": "<section heading>",
      "body": "...prose carrying [1]-style markers...",
      "claims": [ /* one entry per validated claim, with its citation */ ]
    }
  ],
  "sources": [
    {
      "index": 1,
      "title": "<document title>",
      "url": "<document url>",
      "publisher": "<publisher>",
      "date": "<ISO 8601 published_at>",
      "chunk_id": "847eaa08-...", "doc_id": "5181fa42-...", "source_id": "<source id>"
    }
  ],
  "confidence": "<high | medium | low | insufficient_evidence>",
  "data_freshness": "<the span the cited sources cover>",
  "validator": { "passed": true, "matched_claims": 5, "total_claims": 5, "failures": [] },
  "usage": {
    "events": [
      { "meter_name": "b2a2b_synthesis_query", "quantity": "1", "unit": "count",
        "unit_price_usd": "0.008", "total_cost_usd": "0.008000" },
      { "meter_name": "synthesis_input_tokens",  "quantity": "6579", "unit": "tokens" },
      { "meter_name": "synthesis_output_tokens", "quantity": "2869", "unit": "tokens" }
    ],
    "total_cost_usd": 0.008,
    "latency_ms": 43813
  }
}

Read the timings honestly. The example above is a real response, not a mock: a speculative query is retrieval + synthesis + verbatim claim validation, and it takes tens of seconds, not milliseconds. Budget for that in your client timeouts. Bill from usage.total_cost_usd and usage.events[] — there is no usage.cost_usd or usage.tokens field.

4 — Next steps

Wire webhooks for anomaly alerts into your own pipeline.

Use the TypeScript SDK (other languages talk to the same REST API).

Browse the recipes for "build a daily Slack digest in 50 lines."