API overview
The Atlas backend is a FastAPI application (src/api/main.py) exposing a large surface of
domain routes — on the order of 26 routers and several hundred endpoints. Every authenticated
route is tenant-scoped and RLS-enforced. This section describes how the API is structured rather
than enumerating every endpoint; the routers themselves are the authoritative reference.
Conventions
- Base path — the frontend reaches the API at
/api(proxied in dev by Vite, in prod by nginx). The configured backend port is 8000. - Auth —
Authorization: Bearer <JWT>on every protected route; see Authentication. - Tenancy — the tenant is derived from the JWT and enforced by RLS; clients never pass a tenant id explicitly.
- Errors — domain exceptions map to meaningful status codes (see below).
- Async work — endpoints that start long-running work (investigations, reports, batch evaluations) return promptly and are polled.
Interactive API docs
FastAPI serves an OpenAPI schema and Swagger UI. The frontend embeds it at the API Docs page
(/api-docs, frontend/src/pages/ApiDocs.tsx), so the live, version-accurate endpoint reference is
always available from within the Console.
Error codes
| Status | Cause |
|---|---|
| 401 | Missing/invalid token or no tenant context (require_tenant) |
| 403 | Authenticated but lacking the required role |
| 404 | Not found — including rows hidden by RLS in another tenant |
| 424 | MissingTenantCredentialsError — provider credential not configured |
| 429 | Rate limited (slowapi) |
| 503 | PluginValidationError — a plugin is mis-authored (fail-closed) |
Health & readiness
| Endpoint | Purpose |
|---|---|
GET /health | Liveness — process is up |
GET /health/ready | Readiness — dependencies initialised (DB, schema, MCP) |
These back the Kubernetes liveness/readiness probes described in Operations → Deployment.
Where to go next
- Request lifecycle — how a request flows through middleware to a response.
- Routers — the catalogue of domain routers and what they cover.
- Authentication — tokens, tenants, and roles.
- Source contracts — declaring what providers may emit.