REST & WebSocket API
Full description: Read the full narrative
The API is Express 4 mounted at /api with JWT bearer auth (RBAC via authGuard/requireRole), in-process IP + per-user rate limiting, zod validation and a canonical {error:{code,message}} envelope. A public allow-list covers health/metrics/config/OpenAPI plus read-only live-data routes rate-limited at 300 req/min/IP; tile, pulse and share-token routes are public by design and unthrottled; everything else requires a token. server/index.ts:373-487
- Route registrations
- 398 handler registrations (
(app|*Router).get/post/put/delete/patch() under server/ — grep count; API.md headline “360+” is consistent - Auth
- JWT TTL 1 h prod / 1 d dev · scrypt (N=16384, r=8, p=1) · login 5/15 min + 10-attempt lockout (HTTP 423)
- Errors
- 400 validation · 401 token · 403 role · 404 · 409 job-not-ready · 413 body-too-large · 423 locked · 429 limited · 500
- OpenAPI
- GET /api/openapi.json (generated) + /api/docs UI
Endpoint groups
| Group | Prefix / examples | Notes |
|---|---|---|
| Authentication | POST /api/auth/login · dev-login · refresh | dev-login returns 404 in production |
| Agent & cognition | POST /api/agent/ask (SSE) · cognize · pipeline · plan · approve · feedback · tiers · models · trace/:id | see AI chat & cognition |
| Analytical models | GET /api/analytical-models · /search · /:id · POST /api/analytical-models/:id/execute[-internal] | execute-internal is loopback-only (agent path) server/index.ts:316-371 |
| Simulation jobs | /api/kaggle/simulate · :id/stream · :id/results · :id/grid/:name · :id/geotiff/:name · /calibrate · /landslide/quantify · /volcano/* | full contract: Simulation job API |
| Live data | /api/earthquakes · /weather/* · /flights · /ais · /satellites/* · /firms · /eonet · /gdacs · /space-weather/* … | keyless sources public; per-source metadata in server/apiMetadata.ts |
| Scenarios & sandbox | /api/scenarios/* · /api/sandbox/* · /api/simulate/* | scenario generation + sandboxed code execution |
| Intelligence & pulse | /api/pulse/* · /api/correlation/* · economic feeds | market/energy/geopolitical panels |
| Memory & knowledge | /api/memory/* · /api/causal-graph · /api/kgV2/* · /api/predict/* | tiers, graph, forecast scoring |
| Explainability | /api/explain/* | traces, evidence, bias audits, human-override queue |
| Admin & ops | /api/admin/* · /api/metrics · /api/health · /api/ready · /api/live | plugins, GGUF model manager, audit logs |
Realtime transports
| Transport | Endpoint | Auth | Content |
|---|---|---|---|
| WebSocket | /ws/agent | JWT via Sec-WebSocket-Protocol (fallback ?token=) | entity updates, agent relay, presence, alert/fork channels (allow-list) server/websocket.ts:18-20,90-105 |
| WebSocket | /ws/voice | same | brokered OpenAI Realtime ⇄ Gemini Live audio bridge (PCM16 24 kHz) server/voiceRealtime.ts:24-27 |
| SSE | /api/agent/ask | authGuard | chat tokens + tool events; 15 s heartbeats; hard 150 s cap |
| SSE | /api/kaggle/simulate/:id/stream | public prefix | job status/progress server/kaggle/routes.ts:225 |
| SSE | /api/social/stream · /api/agent/events | ?token= (sseAuthGuard) | event relays; /agent/events deprecated in favour of WS server/middleware/auth.ts:205-233 |
The complete per-endpoint table lives in API.md; a machine-readable schema is served at /api/openapi.json. This page intentionally does not duplicate it.