API Reference

Terranoetis exposes 360+ REST endpoints (398 handler registrations across app/router verbs under server/; GET/POST/PUT/DELETE/PATCH) plus real-time WebSocket (/ws/agent, /ws/voice) and SSE channels. All API routes are served under /api. Authentication uses JWT bearer tokens with role-based access control (RBAC).

Site views: API reference · Simulation job API & parameter contracts · machine-readable spec at GET /api/openapi.json. The tables below are the curated prose map; per-endpoint behaviour is cited in the reference pages.

---

Table of Contents

• Conventions
• Authentication
• Agent & Cognition
• Analytical Models
• Live Data Feeds
• Intelligence & Pulse
• Simulations & Scenarios
• Explainability & Governance
• Memory & Knowledge
• Admin & Operations
• Local GGUF Model
• WebSocket
• Error Handling

---

Conventions

• Base URL: /api
• Content-Type: application/json
• Auth: Authorization: Bearer <JWT>
• Rate limiting: per-IP and per-user limits apply on public + authenticated routes
• Public routes (no auth): /auth/login, /auth/dev-login, /auth/refresh, /health, /ready, /live, /metrics, /config/apis, /openapi.json, /docs. In addition, read-only live-data endpoints (e.g. /earthquakes, /weather/*, /flights, /ais, /satellites/tle, /kaggle/*, /analytical-models search + detail, plus /multimodal/* and /simulate/*) are public with server-side rate limiting (publicDataRateLimit, 300/min/IP). Shared-session reads (/shared/*, share-token scoped), map tiles (/tiles/*, /tilejson), /pulse/* and most foundation-model endpoints (/fm/*, /road-traffic/*, /spacex/*, /bayfire/*) are public but unthrottled. /social/stream authenticates via ?token= (SSE).

---

Authentication

Passwords are hashed with scrypt (RFC 7914, scrypt$N=16384,r=8,p=1) — no plaintext storage, no external crypto dependency.

---

Agent & Cognition

The agent pipeline routes natural-language queries through intent recognition (System 1 / System 2) and executes tool chains against live data.

---

Analytical Models

150 equation engines grounded in primary literature across 26 domains and 7 parts.

The analytical pipeline applies a 7-stage workflow (input validation → preprocessing → computation → post-processing → quality control → uncertainty estimation → interpretation), defined in server/analytical-models/toolWorkflows.ts.

---

Live Data Feeds

---

Intelligence & Pulse

---

Simulations & Scenarios

---

Explainability & Governance

---

Memory & Knowledge

---

Admin & Operations

Local GGUF Model

The server ships with a built-in downloader for the LFM 2.5 2.6B Q4_K_M GGUF model (~1.6 GB). Once downloaded, the server auto-starts llama-server on port 11436, making the local model available as a fallback LLM provider.

Resume behaviour: if the download is interrupted (network drop, server restart), the partial file is kept at models/LFM2.5-2.6B-Q4_K_M.gguf.partial. Re-triggering the download sends an HTTP Range header to HuggingFace and appends to the partial file — no re-download from scratch.

Progress tracking: the status endpoint returns speedBytes (bytes/s), etaSeconds, percent, received, total, running, done, and resuming flags for real-time UI updates.

---

WebSocket

The WebSocket server (server/websocket.ts) streams live data and agent events to connected clients:

• Live entity updates (flights, vessels, satellites, earthquakes)
• Agent SSE-style streaming relayed over WS
• Presence (typing indicators)
• Pub/sub messages (alerts, fork state)

Connection: ws://<host>:3001 on paths /ws/agent and /ws/voice only (all other upgrade paths are destroyed); auth via Sec-WebSocket-Protocol bearer JWT (fallback ?token=); 30 s heartbeat / 35 s timeout; channel allowlist includes sentinel:raw, sentinel:alerts, correlation:alerts, fork:*, per-user ws:<id> (server/websocket.ts:18-20,63-69; upgrade + heartbeat :79-145). The event bus feeding it is the in-process pub/sub (server/pubsub.ts) — Redis is not required for realtime delivery.

---

Error Handling

Route handlers return { "error": "<message>" }; the central error middleware (body-parse 400/413/415, 404 not-found, unhandled 500s) returns { "error": { "code": "<CODE>", "message": "<message>" } }. Authentication failures return { "error": "Missing or invalid Authorization header..." }.