Traduction en cours

Cette page est automatiquement reflétée depuis l'original en anglais jusqu'à ce qu'une traduction française arrive. Le contenu est en anglais — la navigation et l'interface sont déjà traduites.

API reference

Veytics runs three FastAPI service roles from the same versioned image. Each role generates an OpenAPI 3.1 schema from its own route table, so the contract contains only the endpoints that service actually exposes.

Role	Local URL	Main surface
core	http://localhost:8000	Authentication, OSINT, markets and platform admin
aggregator	http://localhost:8001	News feed, sources and AI editorial generation
publisher	http://localhost:8002	Publication queue, schedules and delivery controls

ATLAS_SERVICE_ROLE=all keeps the combined route table for local development and rollback. Production should use the three separated roles.

The Veytics 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 (14 days), backed by a Redis session and 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 — EODHD-backed equity, FX, crypto data (optional Finnhub for supplemental US quotes)
• Geospatial — vessels (AIS), aircraft (ADS-B), events
• Alerts / Timeline / Search
• News / OSINT
• AI — context-aware chat
• Portfolio / Clients / Graphs
• Subscriptions / Webhooks
• Admin — operator-only
• 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 veytics.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.