API Reference
REST API · v1
Hand-written against the OpenAPI spec (packages/contracts/openapi.yaml); a CI drift gate keeps this surface 1:1 with the live app. Base URL: https://api.forumatlas.com/v1.
Query & synthesis
Ask cited questions, causal traces, tutor turns — the synthesis endpoints.
Briefs
Generate and retrieve per-persona daily briefs, with bibliographies.
Forecasts
Generate and retrieve Monte-Carlo probability distributions with driver attribution.
Entities
Cross-sector entity graph: search, resolve, traverse relationships.
Sources
Ingested public-source catalog with provenance + quality scores.
All endpoints
Every live route, its required scope (see Authentication), and where it's documented.
| Endpoint | Scope | Docs |
|---|---|---|
| GET /v1/health | — (public) | → |
| POST /v1/query | query:read | → |
| POST /v1/causal | query:read | → |
| POST /v1/tutor | query:read | → |
| GET /v1/usage | usage:read | → |
| POST /v1/brief | brief:write | → |
| GET /v1/briefs | brief:read | → |
| GET /v1/briefs/{id} | brief:read | → |
| GET /v1/briefs/{id}/bibliography | brief:read | → |
| POST /v1/forecast | forecast:write | → |
| GET /v1/forecasts | forecast:read | → |
| GET /v1/forecasts/{id} | forecast:read | → |
| GET /v1/entities/search | entities:read | → |
| GET /v1/entities/by_alias | entities:read | → |
| GET /v1/entities/cross_sector_matrix | entities:read | → |
| POST /v1/entities/resolve | entities:read | → |
| GET /v1/entities/{id} | entities:read | → |
| GET /v1/entities/{id}/relationships | entities:read | → |
| GET /v1/sources | sources:read | → |
| GET /v1/sources/{id} | sources:read | → |
| GET /v1/documents/{id} | sources:read | → |
| POST /v1/anomalies/subscribe | anomalies:write | → |
Common patterns
Pagination. Offset-based via offset + limit params. Default limit 20, max 100.
Errors. Problem Details (RFC 9457). { "type": "...", "title": "...", "status": 4xx, "detail": "..." }
Rate limits. Two layers: a per-key requests-per-second limit (set on the key) and a pre-auth per-IP limit. Exceeding either returns 429 with a Retry-After header — that is the only rate-limit header sent. Every response carries X-Request-Id; include it when reporting issues.
Versioning. Path-based /v1. Additive changes only within a major version.