API reference

The Atlas backend is a FastAPI service. The OpenAPI 3.1 schema is generated from the live route table — every endpoint, request body, and response shape comes straight from the source.

Interactive docs

Two UIs are exposed by default in development:

URL	Tool	Best for
http://localhost:8000/docs	Swagger UI	Trying endpoints with the Try it out form
http://localhost:8000/redoc	ReDoc	Reading the spec — clean side-by-side schema view
http://localhost:8000/openapi.json	Raw spec	Code generation, contract tests

Production

In production the docs UIs are disabled by default. Set ATLAS_DOCS_ENABLED=true only on environments where exposing the spec is intentional. The interactive UIs and /openapi.json all disappear together when the flag is off.

Authentication

The API uses two complementary credentials:

• Access token — short-lived (15 min) JWT, returned in the response body of POST /api/v1/auth/login. Send it as Authorization: Bearer <token>.
• Refresh token — long-lived (7 days), set as an httpOnly cookie named atlas_refresh. Rotated on every call to POST /api/v1/auth/refresh. Never readable from JavaScript.

Both schemes are documented under components.securitySchemes in the spec (BearerJWT and RefreshCookie).

Tag groups

The spec is organised into focused tag groups so navigation stays predictable:

• Health — liveness probes (no auth)
• Auth / Users — sign-in, profile, preferences
• Markets — Finnhub + EODHD-backed equity, FX, crypto data
• Geospatial — vessels (AIS), aircraft (ADS-B), events
• Alerts / Timeline / Search
• News / OSINT
• AI — context-aware chat
• Portfolio / Clients / Graphs
• Subscriptions / Webhooks
• Admin — operator-only
• Realtime — WebSocket entry points
• Debug — internal, removed in production

Versioning

All public endpoints live under /api/v1. Breaking changes go to /api/v2 rather than mutating /v1; the changelog (here) tracks each shift.

Rate limits

Per-account ceilings apply to authenticated endpoints. Read the headers — don't guess:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1714723200

When you hit the wall the API responds with 429 Too Many Requests and a Retry-After header.

Generating clients

The static spec at /openapi.json works with the standard generators:

# TypeScript fetch client
npx openapi-typescript http://localhost:8000/openapi.json -o atlas.d.ts

# Python sync client
openapi-generator-cli generate -i http://localhost:8000/openapi.json -g python -o ./client

Exporting the spec to a file

The backend ships a small script that boots the app in a degraded mode (no DB, no background tasks) and writes the schema to disk:

python backend/scripts/export_openapi.py --out openapi.json
python backend/scripts/export_openapi.py --out openapi.yaml --format yaml

Useful in CI for diffing breaking changes, or to drop a frozen spec next to this site for offline reading.