# Eldric AIOS 5.0 — Complete API Reference

> **Version:** 5.0.0 (alpha118)
> **Last regenerated:** 2026-05-14
> **Maintained by:** DOCS lane — see `MAIN-docs-orchestration.md` for the update protocol.
> **Scope:** Every HTTP endpoint served by the Eldric AIOS 5.0 stack — controller, edge, router, worker, data, agent, media, comm, science, training, inferenced, IoT, NOVA, swarm. Public Edge surface is highlighted in [api-public.md](api-public.md).

---

## Table of Contents

1. [Surface model](#surface-model)
2. [Authentication](#authentication)
3. [Public OpenAI-compatible](#1-public-openai-compatible-edge)
4. [Chat & Conversation](#2-chat--conversation-edge)
5. [Identity & Account](#3-identity--account)
6. [Inference & Models](#4-inference--models)
7. [Routing](#5-routing)
8. [Data — Storage, Vector, RAG](#6-data--storage-vector-rag)
9. [Data — Matrix Memory](#7-data--matrix-memory)
10. [Data — NFS, Databases, Connectors](#8-data--nfs-databases-connectors)
11. [Agent Worker](#9-agent-worker)
12. [Media Worker](#10-media-worker)
13. [Communication Worker](#11-communication-worker)
14. [Science Worker](#12-science-worker)
15. [Training Worker](#13-training-worker)
16. [Native Inference (inferenced)](#14-native-inference-inferenced)
17. [IoT Worker](#15-iot-worker)
18. [Swarm](#16-swarm)
19. [NOVA](#17-nova-experimental)
20. [System & Cluster](#18-system--cluster)
21. [Cluster Operations](#19-cluster-operations)
22. [PKI & Security](#20-pki--security)
23. [Observability](#21-observability)
24. [Marketplace & Plugins](#22-marketplace--plugins)
25. [Theming & Branding](#23-theming--branding)
26. [License](#24-license)
27. [xLSTM Daemon (reserved)](#25-xlstm-daemon-reserved-port-8884)

---

## Surface model

Two tiers exist. Every endpoint below is labelled with one:

- **Public** — reachable from the Internet through the Edge (`chat.eldric.ai`). Authentication is per-tenant.
- **LAN-only** — served by an internal daemon. The Edge **must not proxy** it. Admin/cluster/PKI/backup/migration/replication/federation/marketplace/dreams/telemetry/theme-write/system/discovery paths fall here, and have been audited 2026-05-10 to ensure `401` at the Edge.

| Tier | Reachability | Default auth |
|------|-------------|--------------|
| Public | nginx → Edge module → kernel | `X-API-Key` + tenant capability token; some endpoints anonymous |
| LAN-only | inter-node only on the cluster's private network | `X-Eldric-Cluster-Secret` (constant-time, lowercase fallback for HTTP/2) |

Ports (firewall reference):

| Port | Component |
|------|-----------|
| 443 / 80 | Edge |
| 2049 | Data NFS |
| 8880 | Controller |
| 8881 | Router |
| 8883 | Native Inferenced |
| 8884 | xLSTM Daemon (reserved) |
| 8885 / 8886 / 8887 | Swarm API / Agent invocation / Web edge |
| 8889 | Cloud Worker |
| 8890 | Worker |
| 8891 | IoT Worker |
| 8892 | Data Worker |
| 8893 | Agent Worker |
| 8894 | Media Worker |
| 8895 / 8896 | Comm Worker / Webhooks |
| 8897 | Science Worker |
| 8898 | Training Worker |
| 8899 | NOVA |

---

## Authentication

| Header | Purpose |
|--------|---------|
| `X-API-Key` | Tenant API key (Edge & most workers) |
| `X-Eldric-Tenant-Id` | Tenant scope hint (Edge proxy passes through) |
| `X-Eldric-Cluster-Secret` | Inter-node mutual auth (rolling upgrade, PKI, backup, replication, federation, marketplace) |
| `X-Eldric-Source` | EIS/ENS device-of-origin identifier |
| `X-Eldric-Signature: sha256=<hmac>` | HMAC-SHA256 over the raw body for outbound webhooks |
| `Authorization: Bearer <jwt>` | Short-lived capability token issued at login |

HTTP/2 lowercases all header names — every handler must look up both `X-Foo` and `x-foo`.

Tenant guard: `kernel::tenant_guard::deny_if_cross_tenant(auth_tid, path, res)` is invoked on data/storage/vector/memory/agent/comm/swarms/tenants prefixes. Cross-tenant attempts return `403`.

---

## 1. Public OpenAI-compatible (Edge)

OpenAI drop-in surface. Proxied Edge → Router → Worker (or Cloud Worker / Inferenced) with SSE streaming preserved end-to-end.

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/v1/models` | List models from every reachable worker + cloud backend; aggregated cluster view |
| POST | `/v1/chat/completions` | OpenAI chat (streaming via `stream:true`); honours `tools`, `tool_choice`, `response_format` |
| POST | `/v1/completions` | Legacy completions for older OpenAI SDKs |
| POST | `/v1/embeddings` | Embedding generation; routes to embedding provider on the chosen worker |
| GET | `/v1/models/{id}` | Detail (template, system prompt, parameters) |
| POST | `/api/v1/models/show` | Same detail by request body for clients that can't URL-encode model IDs |

---

## 2. Chat & Conversation (Edge)

Per-user conversation persistence and the webchat shell at `/chat`.

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/chat` | Webchat single-page app |
| GET | `/login` | Login page (when API-key auth required) |
| GET | `/api/v1/conversations` | List my conversations |
| POST | `/api/v1/conversations` | Create conversation |
| GET | `/api/v1/conversations/{id}` | Get conversation with messages |
| PATCH | `/api/v1/conversations/{id}` | Update title / pinning / metadata |
| DELETE | `/api/v1/conversations/{id}` | Delete conversation |
| POST | `/api/v1/conversations/{id}/messages` | Append message |
| GET | `/api/v1/conversations/{id}/messages` | Page through messages |
| POST | `/api/v1/conversations/{id}/branch` | Branch off the conversation at a given message |
| POST | `/api/v1/conversations/{id}/share` | Create a signed share-link |
| GET | `/api/v1/share/{token}` | Resolve signed share-link → read-only transcript |
| GET | `/api/v1/conversations/{id}/artifacts` | Inline artifact store entries (§114) |
| GET | `/api/v1/conversations/{id}/artifacts/{aid}` | Fetch single artifact |
| GET | `/api/v1/me/settings` | My settings |
| PUT | `/api/v1/me/settings` | Update my settings |
| GET | `/api/v1/me/preferences` | Webchat preferences (theme, font, sidebar) |
| PUT | `/api/v1/me/preferences` | Update preferences |
| GET | `/api/v1/me/quotas` | My quotas / usage |
| GET | `/api/v1/me/tools` | Tool permissions for my role (§113 picker) |
| GET | `/api/v1/me/models` | Models I'm allowed to call |

---

## 3. Identity & Account

EIS (Eldric Identity System, §95) + ENS (Eldric Namespace System, §96).

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/identity/domains` | 32 EIS domains |
| GET | `/api/v1/identity/devices` | 411 device codes |
| GET | `/api/v1/identity/lookup/{eis}` | Resolve EIS string → registered device |
| POST | `/api/v1/identity/register` | Register a device under my tenant |
| DELETE | `/api/v1/identity/{eis}` | Unregister a device |
| GET | `/api/v1/identity/me` | My EIS namespace map |
| GET | `/api/v1/ens/resolve` | ENS hostname → tenant + role |
| POST | `/api/v1/auth/login` | Email + password → JWT |
| POST | `/api/v1/auth/refresh` | Refresh JWT |
| POST | `/api/v1/auth/logout` | Invalidate session |
| POST | `/api/v1/auth/2fa/enroll` | Enroll TOTP |
| POST | `/api/v1/auth/2fa/verify` | Verify TOTP code |

---

## 4. Inference & Models

Worker (`8890`), Cloud Worker (`8889`), Inferenced (`8883`). The Edge OpenAI surface above sits on top of these.

### Worker (8890)

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/health` | Liveness |
| GET | `/api/v1/health` | Detailed health (backends, GPU, latency) |
| GET | `/api/v1/models` | Local models on this worker |
| POST | `/v1/chat/completions` | Direct worker chat |
| POST | `/v1/embeddings` | Direct worker embedding |
| POST | `/api/v1/inference/run` | Forward request to currently active backend |
| GET | `/api/v1/inference/backends` | Configured backends (Ollama/vLLM/TGI/Triton/etc) |
| POST | `/api/v1/inference/backends` | Add a backend |
| DELETE | `/api/v1/inference/backends/{id}` | Remove a backend |
| POST | `/api/v1/inference/backends/{id}/switch` | Set active backend |
| GET | `/api/v1/inference/local-backends/public` | Cluster-wide aggregation feed |
| POST | `/api/v1/swarm/task` | Receive a delegated swarm task |
| POST | `/api/v1/peers/register` | Register a pipeline peer |

### Cloud Worker (8889)

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/health` | Liveness |
| GET | `/dashboard` | Cloud backend admin dashboard |
| GET | `/v1/models` | Aggregated models across cloud backends |
| POST | `/v1/chat/completions` | Routed to OpenAI/Anthropic/xAI/Together/Groq/DeepSeek/Mistral/Cohere |
| POST | `/v1/embeddings` | Embedding via cloud provider |
| GET | `/api/v1/cloud/backends` | List configured cloud backends |
| POST | `/api/v1/cloud/backends` | Add cloud backend (provider, API key) |
| PUT | `/api/v1/cloud/backends/{id}` | Update cloud backend |
| DELETE | `/api/v1/cloud/backends/{id}` | Remove cloud backend |
| GET | `/api/v1/cloud/backends/public` | Public aggregation feed for the controller (added alpha74) |

---

## 5. Routing

Router daemon (`8881`) — load balancing, theme detection, intent classification, ensemble, session stickiness.

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/health` | Liveness |
| GET | `/metrics` | Latency/load metrics per worker |
| GET | `/v1/models` | Models reachable through this router |
| POST | `/v1/chat/completions` | Route an OpenAI request |
| GET | `/api/v1/workers` | Workers known to this router |
| POST | `/api/v1/routing/classify` | Classify request intent → worker class |
| GET | `/api/v1/routing/rules` | List routing rules |
| POST | `/api/v1/routing/rules` | Add rule |
| DELETE | `/api/v1/routing/rules/{id}` | Remove rule |
| GET | `/api/v1/themes` | Available themes |
| POST | `/api/v1/ensemble` | Fan-out to multiple models + synthesise |
| POST | `/api/v1/health/check` | Manual probe on a worker |
| POST | `/api/v1/ai/configure` | Set AI control mode (none/advisory/autonomous) |
| GET | `/api/v1/sessions` | Active sticky sessions |
| DELETE | `/api/v1/sessions/{sid}` | Drop a sticky session |

---

## 6. Data — Storage, Vector, RAG

Data worker (`8892`). Multi-tenant file storage and vector storage for RAG.

### Storage

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/data/sources` | List sources |
| POST | `/api/v1/data/sources` | Register source |
| GET | `/api/v1/data/storage/{tenant}/{path:.*}` | Read file |
| PUT | `/api/v1/data/storage/{tenant}/{path:.*}` | Write file |
| DELETE | `/api/v1/data/storage/{tenant}/{path:.*}` | Delete file |
| GET | `/api/v1/data/storage/{tenant}` | List files |
| GET | `/api/v1/data/tenants` | List tenants |
| POST | `/api/v1/data/tenants` | Create tenant |
| GET | `/api/v1/data/tenants/{id}/quota` | Quota status |
| PUT | `/api/v1/data/tenants/{id}/quota` | Update quota |
| POST | `/api/v1/upload/init` | Reserve chunked upload (§107) |
| POST | `/api/v1/upload/chunk` | Ship one chunk |
| POST | `/api/v1/upload/finalize` | Assemble + commit |
| GET | `/api/v1/upload/{id}/progress` | Resume offset |
| DELETE | `/api/v1/upload/{id}` | Cancel + free chunks |

### Vector / RAG

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/vector/health` | Vector subsystem health |
| GET | `/api/v1/vector/metrics` | Storage metrics |
| GET | `/api/v1/vector/config` | Read config |
| PUT | `/api/v1/vector/config` | Update config |
| GET | `/api/v1/vector/namespaces/{tenant}` | List namespaces |
| POST | `/api/v1/vector/namespaces/{tenant}` | Create namespace |
| GET | `/api/v1/vector/namespaces/{tenant}/{ns}` | Get namespace |
| DELETE | `/api/v1/vector/namespaces/{tenant}/{ns}` | Delete namespace |
| POST | `/api/v1/vector/documents/{tenant}/{ns}` | Add documents |
| GET | `/api/v1/vector/documents/{tenant}/{ns}/{doc}` | Get document |
| PUT | `/api/v1/vector/documents/{tenant}/{ns}/{doc}` | Replace document (re-embed; KB editor) |
| DELETE | `/api/v1/vector/documents/{tenant}/{ns}/{doc}` | Delete document |
| POST | `/api/v1/vector/search` | Semantic search |
| POST | `/api/v1/vector/search/peer` | Peer-fan-out search (alpha90) |
| POST | `/api/v1/vector/hybrid-search` | BM25 + vector |
| POST | `/api/v1/vector/embed` | Generate embeddings |
| POST | `/api/v1/vector/ingest` | Auto-chunk text + ingest |
| GET | `/api/v1/vector/sources/{tenant}/{ns}` | List documents by source |
| DELETE | `/api/v1/vector/sources/{tenant}/{ns}` | Delete documents by source |

---

## 7. Data — Matrix Memory

Hierarchical associative matrix memory (mLSTM-inspired). `.emm` binary format with WAL + checkpoint.

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/memory/health` | Subsystem health |
| GET | `/api/v1/memory/metrics` | Block counts, saturation, expansion events |
| POST | `/api/v1/memory/store` | Store key+value association into matrix + vector backup |
| POST | `/api/v1/memory/recall` | Matrix recall, optionally refined by vector retrieval |
| GET | `/api/v1/memory/matrices` | List matrices (domain → project → run) |
| POST | `/api/v1/memory/checkpoint` | Force checkpoint |
| POST | `/api/v1/memory/verify` | Verify block CRC + SHA-256 |
| POST | `/api/v1/memory/forget` | Delete one memory entry |

---

## 8. Data — NFS, Databases, Connectors

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/nfs/config` | NFS server config |
| PUT | `/api/v1/nfs/config` | Update config |
| GET | `/api/v1/nfs/exports` | List exports |
| POST | `/api/v1/nfs/exports` | Add export |
| DELETE | `/api/v1/nfs/exports/{id}` | Remove export |
| GET | `/api/v1/nfs/mounts` | Remote mounts |
| POST | `/api/v1/nfs/mounts` | Mount remote data worker |
| GET | `/api/v1/nfs/mounts/{id}` | Mount detail |
| DELETE | `/api/v1/nfs/mounts/{id}` | Unmount |
| GET | `/api/v1/nfs/ganesha-conf` | Preview generated ganesha.conf |
| POST | `/api/v1/nfs/apply` | Apply config + reload ganesha |
| GET | `/api/v1/nfs/status` | Daemon status |
| GET | `/api/v1/data/databases` | Registered DBs (SQLite, PostgreSQL, MySQL, DB2) |
| POST | `/api/v1/data/databases` | Register DB |
| POST | `/api/v1/data/databases/{id}/query` | Run query |
| POST | `/api/v1/data/databases/{id}/execute` | Run statement |
| POST | `/api/v1/data/databases/{id}/schema` | Inspect schema |
| GET | `/api/v1/replication/config` | Replication policy |
| PUT | `/api/v1/replication/config` | Update policy |
| GET | `/api/v1/replication/status` | Streams + last-sync |

---

## 9. Agent Worker

Agent worker (`8893`) — agentic RAG, multi-agent, workflows, training-data generation.

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/health` | Liveness |
| GET | `/dashboard` | Web dashboard |
| GET | `/api/v1/agent/sessions` | List sessions |
| POST | `/api/v1/agent/sessions` | Create session |
| GET | `/api/v1/agent/sessions/{id}` | Session detail + history |
| DELETE | `/api/v1/agent/sessions/{id}` | Delete session |
| POST | `/api/v1/agent/chat` | Agentic RAG chat (ReAct loop) |
| POST | `/api/v1/agent/multi` | Multi-agent run (researcher/coder/validator/planner) |
| POST | `/api/v1/agent/decompose` | Decompose query into sub-questions |
| GET | `/api/v1/agent/knowledge-bases` | List KBs |
| POST | `/api/v1/agent/knowledge-bases` | Create KB |
| GET | `/api/v1/agent/knowledge-bases/{id}` | KB detail |
| DELETE | `/api/v1/agent/knowledge-bases/{id}` | Delete KB |
| POST | `/api/v1/agent/knowledge-bases/{id}/search` | RAG search within a KB |
| POST | `/api/v1/agent/generate-training` | Generate training data from a KB |
| GET | `/api/v1/agent/workflows` | List workflows |
| POST | `/api/v1/agent/workflows` | Register workflow |
| POST | `/api/v1/agent/workflows/{id}/run` | Run workflow |
| GET | `/api/v1/agent/stats` | Usage stats |
| GET | `/api/v1/tenants` | List tenants (admin) |
| POST | `/api/v1/tenants` | Create tenant |
| POST | `/api/v1/swarm/task` | Inbound task from Swarm |
| POST | `/api/v1/swarm/workflow` | Inbound workflow from Swarm |
| GET | `/api/v1/swarm/status` | Status reporting to Swarm |
| GET | `/api/v1/swarm/workflows` | List registered swarm workflows |
| POST | `/api/v1/swarm/workflows` | Register swarm workflow |
| DELETE | `/api/v1/swarm/workflows/{id}` | Remove swarm workflow |
| POST | `/api/v1/swarm/tools` | Execute tools directly |

---

## 10. Media Worker

Media worker (`8894`) — STT, TTS, audio/video analysis, voice chat, multimedia RAG.

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/health` | Liveness |
| GET | `/dashboard` | Web dashboard |
| GET | `/api/v1/media/info` | Worker capabilities |
| POST | `/api/v1/stt/transcribe` | Transcribe audio file/URL |
| POST | `/api/v1/stt/stream` | Streaming transcription (SSE) |
| GET | `/api/v1/stt/models` | List STT models |
| POST | `/api/v1/tts/synthesize` | Generate speech |
| POST | `/api/v1/tts/stream` | Stream audio (SSE) |
| GET | `/api/v1/tts/voices` | List TTS voices |
| POST | `/api/v1/audio/analyze` | Sentiment, diarization, prosody |
| POST | `/api/v1/audio/embed` | Audio embedding |
| POST | `/api/v1/video/transcribe` | Extract audio + transcribe |
| POST | `/api/v1/video/analyze` | Scene detection + frame stats |
| POST | `/api/v1/video/extract-frames` | Extract keyframes |
| POST | `/api/v1/rag/ingest-audio` | Index audio content |
| POST | `/api/v1/rag/ingest-video` | Index video content |
| POST | `/api/v1/rag/search` | Search across multimedia RAG |
| POST | `/api/v1/voice/chat` | Voice-in → STT → LLM → TTS → voice-out |

---

## 11. Communication Worker

Comm worker (`8895`) + webhook port (`8896`). Email, SMS, WhatsApp, Signal, Teams, XMPP, VoIP.

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/health` | Liveness |
| GET | `/dashboard` | Web dashboard |
| GET | `/api/v1/comm/accounts` | List accounts |
| POST | `/api/v1/comm/accounts` | Add account |
| GET | `/api/v1/comm/accounts/{id}` | Get account |
| PUT | `/api/v1/comm/accounts/{id}` | Update account |
| DELETE | `/api/v1/comm/accounts/{id}` | Remove account |
| POST | `/api/v1/comm/accounts/{id}/test` | Test connection |
| POST | `/api/v1/comm/accounts/{id}/connect` | Connect/IDLE listener |
| GET | `/api/v1/comm/messages` | List messages |
| POST | `/api/v1/comm/messages` | Send message |
| GET | `/api/v1/comm/messages/{id}` | Get message |
| POST | `/api/v1/comm/messages/{id}/read` | Mark read |
| POST | `/api/v1/comm/messages/{id}/reply` | Reply |
| GET | `/api/v1/comm/conversations` | List conversations |
| GET | `/api/v1/comm/conversations/{id}/messages` | Conversation messages |
| POST | `/api/v1/comm/search` | Semantic search |
| GET | `/api/v1/comm/ai/queue` | Pending AI replies |
| POST | `/api/v1/comm/ai/queue/{id}/approve` | Approve AI reply |
| POST | `/api/v1/comm/ai/queue/{id}/reject` | Reject AI reply |
| POST | `/api/v1/comm/webhooks/whatsapp` | WhatsApp inbound webhook |
| POST | `/api/v1/comm/webhooks/twilio` | Twilio SMS webhook |
| POST | `/api/v1/comm/webhooks/teams` | Teams webhook |
| POST | `/api/v1/comm/calls/start` | Outbound voice call |
| POST | `/api/v1/comm/calls/answer` | Answer inbound call |
| POST | `/api/v1/comm/calls/hangup` | End call |
| POST | `/api/v1/comm/calls/hold` | Hold/resume |
| POST | `/api/v1/comm/calls/transfer` | Transfer |
| POST | `/api/v1/comm/calls/dtmf` | Send DTMF |
| GET | `/api/v1/comm/calls` | List active calls |
| GET | `/api/v1/comm/calls/{id}` | Call status |
| GET | `/api/v1/comm/voicemails` | List voicemails |
| GET | `/api/v1/comm/voicemails/{id}` | Voicemail detail |
| DELETE | `/api/v1/comm/voicemails/{id}` | Delete voicemail |
| POST | `/api/v1/comm/voicemails/{id}/read` | Mark voicemail read |
| POST | `/api/v1/comm/send` | Kernel-level fallback send (best-effort) |

---

## 12. Science Worker

Science worker (`8897`). 5.0 architecture per §43 Science Source Registry — unified registry + dispatcher + 16-category aliases + per-provider compat endpoints.

### Registry (§43)

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/science/sources` | Enabled sources (optionally filter by category) |
| GET | `/api/v1/science/sources/{id}` | One source detail |
| GET | `/api/v1/science/sources/categories` | 16-category taxonomy |
| POST | `/api/v1/science/sources/request` | Request admin enable a source |
| GET | `/api/v1/science/sources/my-requests` | My pending activation requests |
| GET | `/api/v1/science/tools` | Role-filtered tool schemas (5 user + 6 admin) |
| POST | `/api/v1/science/tools/execute` | Tool dispatch (`science_list_sources`, etc.) |
| POST | `/api/v1/science/sources` | Add source (admin) |
| PUT | `/api/v1/science/sources/{id}` | Update source (admin) |
| PUT | `/api/v1/science/sources/{id}/enabled` | Toggle (admin) |
| PUT | `/api/v1/science/sources/{id}/credentials` | Set API key (admin) |
| DELETE | `/api/v1/science/sources/{id}` | Remove source (admin) |
| GET | `/api/v1/science/sources/pending` | All pending requests (admin) |
| POST | `/api/v1/science/sources/approve/{id}` | Approve (admin) |
| POST | `/api/v1/science/sources/reject/{id}` | Reject with reason (admin) |

### Category aliases (read-only, enabled-only)

`GET /api/v1/{category}/sources` for each of the 16 categories:
`oa_papers`, `space`, `particle_physics`, `genomics`, `neuroscience`, `medical`, `chemistry`, `earth`, `climate`, `astronomy`, `archaeology`, `legal`, `patents`, `funder`, `industry`, `custom`.

### Per-provider compat endpoints

Still served while the registry-driven dispatcher fully takes over.

| Category | Path families |
|----------|--------------|
| Space Agencies | `/api/v1/nasa/*`, `/api/v1/esa/*`, `/api/v1/roscosmos/*`, `/api/v1/cnsa/*`, `/api/v1/jaxa/*`, `/api/v1/isro/*` |
| Telescopes | `/api/v1/hubble/*`, `/api/v1/jwst/*`, `/api/v1/spitzer/*`, `/api/v1/chandra/*` |
| Particle Physics | `/api/v1/cern/*`, `/api/v1/desy/*`, `/api/v1/fermilab/*`, `/api/v1/hepdata/*`, `/api/v1/inspire/*`, `/api/v1/pdg/*` |
| Gravitational Waves | `/api/v1/ligo/*`, `/api/v1/gwosc/*` |
| Astronomy | `/api/v1/eso/*`, `/api/v1/sdss/*`, `/api/v1/alma/*`, `/api/v1/panstarrs/*` |
| Earth Sciences | `/api/v1/earthquakes`, `/api/v1/volcanoes/*`, `/api/v1/noaa/*`, `/api/v1/seismic/*` |
| Quantum | `/api/v1/quantum/*`, `/api/v1/arxiv/quantum` |
| Materials | `/api/v1/materials/*`, `/api/v1/cod/*`, `/api/v1/nist/*` |
| Genomics | `/api/v1/ensembl/*`, `/api/v1/encode/*`, `/api/v1/gtex/*`, `/api/v1/hmdb/*` |
| Neuroscience | `/api/v1/allen-brain/*`, `/api/v1/openneuro/*`, `/api/v1/neuromorpho/*` |
| Climate | `/api/v1/gbif/*`, `/api/v1/obis/*`, `/api/v1/air-quality`, `/api/v1/ice-cores`, `/api/v1/glaciers/*` |
| Medical | `/api/v1/clinical-trials`, `/api/v1/who/*`, `/api/v1/gwas/*`, `/api/v1/openfda/*`, `/api/v1/pubmed/*` |
| Nuclear/Fusion | `/api/v1/iaea/*`, `/api/v1/iter/*`, `/api/v1/fusion/*` |
| Agriculture | `/api/v1/faostat/*`, `/api/v1/usda-plants`, `/api/v1/food/*` |
| Archaeology | `/api/v1/paleobio/*`, `/api/v1/archaeology/*`, `/api/v1/open-context` |
| Bioinformatics | `/api/v1/bio/analyze`, `/api/v1/bio/translate`, `/api/v1/bio/align`, `/api/v1/bio/blast`, `/api/v1/bio/variants` |
| Pharmaceutical | `/api/v1/pharma/compound`, `/api/v1/pharma/dock`, `/api/v1/pharma/admet`, `/api/v1/pharma/structure` |
| CRISPR | `/api/v1/crispr/design`, `/api/v1/crispr/offtargets`, `/api/v1/crispr/base-edit`, `/api/v1/crispr/prime-edit` |
| LIMS | `/api/v1/lims/samples`, `/api/v1/lims/experiments`, `/api/v1/lims/audit/*` |

---

## 13. Training Worker

Training worker (`8898`). LoRA/QLoRA/SFT/DPO/RLHF/Distillation. Backends: Unsloth, Axolotl, TRL, DeepSpeed, MLX, llama.cpp, xLSTM.

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/health` | Liveness |
| GET | `/dashboard` | Web dashboard |
| GET | `/dashboard/jobs` | Jobs view |
| GET | `/dashboard/chains` | Chains view |
| GET | `/dashboard/backends` | Backends view |
| GET | `/api/v1/jobs` | List jobs |
| POST | `/api/v1/jobs` | Create job |
| GET | `/api/v1/jobs/{id}` | Job detail |
| POST | `/api/v1/jobs/{id}/cancel` | Cancel |
| POST | `/api/v1/jobs/{id}/pause` | Pause |
| POST | `/api/v1/jobs/{id}/resume` | Resume |
| GET | `/api/v1/jobs/{id}/logs` | Stream logs |
| GET | `/api/v1/jobs/{id}/metrics` | Loss / lr / step metrics |
| GET | `/api/v1/chains` | List training chains |
| POST | `/api/v1/chains` | Create chain |
| GET | `/api/v1/chains/{id}` | Chain detail |
| DELETE | `/api/v1/chains/{id}` | Delete chain |
| POST | `/api/v1/chains/{id}/run` | Run chain |
| GET | `/api/v1/chains/templates` | Chain templates |
| GET | `/api/v1/backends` | Available training backends |
| GET | `/api/v1/gpus` | GPU inventory + utilisation |
| POST | `/api/v1/training/federated/jobs` | Create federated learning job (§44) |
| GET | `/api/v1/training/federated/jobs` | List FL jobs |
| GET | `/api/v1/training/federated/jobs/{id}` | FL round status |
| POST | `/api/v1/distill/run` | Model→EMM distillation (§50, admin) |

---

## 14. Native Inference (inferenced)

Inferenced (`8883`). Direct GGUF / xLSTM model loading with embedded llama.cpp.

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/health` | Liveness |
| GET | `/dashboard` | Web dashboard |
| GET | `/v1/models` | Loaded + available models |
| POST | `/v1/chat/completions` | Native chat (SSE) |
| POST | `/v1/embeddings` | Native embedding |
| POST | `/api/v1/models/load` | Load model into VRAM |
| POST | `/api/v1/models/unload` | Unload model |
| POST | `/api/v1/models/pull` | Pull from data worker |
| POST | `/api/v1/models/convert` | Convert HF → GGUF |
| POST | `/api/v1/models/import` | Import HF model |
| GET | `/api/v1/models/cache` | Cache status |
| GET | `/api/v1/gpu` | GPU live stats |
| POST | `/api/v1/swarm/task` | Inbound swarm task |
| POST | `/api/v1/peers/register` | Register pipeline peer |

---

## 15. IoT Worker

IoT worker (`8891`). Smart-home (Netatmo, HomeKit, Matter) + industrial (OPC-UA, Modbus, MQTT Sparkplug B).

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/health` | Liveness |
| GET | `/dashboard` | Web dashboard |
| GET | `/api/v1/iot/devices` | List discovered devices |
| POST | `/api/v1/iot/devices` | Register device |
| GET | `/api/v1/iot/devices/{id}` | Device detail |
| DELETE | `/api/v1/iot/devices/{id}` | Unregister |
| POST | `/api/v1/iot/devices/{id}/read` | Read tag/attribute |
| POST | `/api/v1/iot/devices/{id}/write` | Write tag/attribute |
| GET | `/api/v1/iot/alarms` | Active alarms |
| POST | `/api/v1/iot/alarms/{id}/ack` | Acknowledge |
| GET | `/api/v1/iot/historian/{tag}` | Time-series history |
| GET | `/api/v1/iot/recipes` | Recipes (manufacturing) |
| POST | `/api/v1/iot/recipes` | Add recipe |
| GET | `/api/v1/iot/oee` | OEE per asset |
| GET | `/api/v1/iot/predictive` | Predictive-maintenance scores |

---

## 16. Swarm

Swarm controller. Three ports: API (`8885`), Agent invocation/UAP (`8886`), Web edge (`8887`).

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/swarms` | List swarms |
| POST | `/api/v1/swarms` | Create swarm |
| GET | `/api/v1/swarms/{id}` | Swarm detail |
| DELETE | `/api/v1/swarms/{id}` | Delete swarm |
| POST | `/api/v1/swarms/{id}/goal` | Set a goal |
| GET | `/api/v1/swarms/{id}/agents` | Member agents |
| POST | `/api/v1/swarms/{id}/agents` | Add agent |
| DELETE | `/api/v1/swarms/{id}/agents/{aid}` | Remove agent |
| GET | `/api/v1/swarms/{id}/topology` | Topology (hierarchical / mesh / star / ring / p2p / hybrid) |
| PUT | `/api/v1/swarms/{id}/topology` | Update topology |
| GET | `/api/v1/swarms/{id}/logs` | Trace logs |
| GET | `/api/v1/mcp/servers` | MCP server registry |
| POST | `/api/v1/mcp/servers` | Register MCP server |
| GET | `/api/v1/agent-workers` | Linked agent workers |
| POST | `/api/v1/agent-workers` | Register agent worker |
| DELETE | `/api/v1/agent-workers/{id}` | Unregister |
| POST | `/api/v1/agent-workers/refresh` | Refresh health |
| POST | `/api/v1/agent-workers/chat` | Chat via auto-selected worker |
| POST | `/api/v1/agent-workers/{id}/chat` | Chat via specific worker |
| POST | `/api/v1/agents/invoke` | Invoke agent over UAP (port 8886) |

---

## 17. NOVA (experimental)

NOVA daemon (`8899`). Optional module — `BUILD_NOVA=ON`. Goals, episodic/semantic/procedural memory, reasoning, meta-learning, safety.

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/health` | Liveness |
| GET | `/dashboard` | Dashboard |
| GET | `/api/v1/nova/goals` | List goals |
| POST | `/api/v1/nova/goals` | Submit goal |
| GET | `/api/v1/nova/goals/{id}` | Goal detail |
| DELETE | `/api/v1/nova/goals/{id}` | Cancel goal |
| GET | `/api/v1/nova/memory/episodic` | Episodic memory |
| GET | `/api/v1/nova/memory/semantic` | Semantic memory |
| GET | `/api/v1/nova/memory/procedural` | Procedural memory |
| POST | `/api/v1/nova/reasoning/plan` | Generate plan |
| POST | `/api/v1/nova/reasoning/verify` | Verify plan |
| GET | `/api/v1/nova/safety/constraints` | Active safety constraints |
| POST | `/api/v1/nova/safety/kill` | Kill-switch |
| GET | `/api/v1/nova/meta/learner` | Meta-learner state |

---

## 18. System & Cluster

Controller (`8880`). Cluster orchestration, topology, peer registration, deployment.

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/health` | Liveness |
| GET | `/api/v1/health` | Detailed health |
| GET | `/api/v1/cluster/topology` | Full cluster topology |
| GET | `/api/v1/cluster/peers` | Known peer controllers |
| POST | `/api/v1/cluster/register` | Peer registers itself (every 30s, heartbeat-driven) |
| POST | `/api/v1/cluster/heartbeat` | Heartbeat |
| GET | `/api/v1/cluster/workers` | All workers cluster-wide |
| POST | `/api/v1/cluster/workers` | Deploy a worker via SSH |
| DELETE | `/api/v1/cluster/workers/{id}` | Decommission worker |
| GET | `/api/v1/cluster/routers` | Routers |
| GET | `/api/v1/cluster/discover` | mDNS / DNS-SD scan (§38) |
| GET | `/api/v1/models` | Aggregated model catalogue |
| GET | `/api/v1/workers` | Workers (controller view) |
| GET | `/api/v1/dashboard` | Controller dashboard |
| GET | `/api/v1/dashboard/swarm` | Swarm management dashboard |

---

## 19. Cluster Operations

Rolling upgrade, migration, backup, distillation, plugin marketplace. Master-orchestrated; peers respond on every node.

### Rolling upgrade (§70)

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/cluster/updates/check` | Check available upgrade |
| POST | `/api/v1/cluster/updates/apply` | Apply cluster-wide |
| GET | `/api/v1/cluster/updates/status` | Live progress (persisted in `cluster_update_runs`) |
| POST | `/api/v1/system/upgrade` | Peer: download + sha256 verify + install |
| POST | `/api/v1/system/upgrade/drain` | Peer: drain in-flight requests |
| POST | `/api/v1/system/upgrade/checkpoint` | Peer: snapshot state |
| POST | `/api/v1/system/upgrade/rollback` | Peer: revert to checkpoint |

### 4.x → 5.0 migration (§85)

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/v1/cluster/migrate/import` | Walk 4.x data tree, replay into 5.0 syscalls |

### Backup & DR (§40)

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/backups` | List snapshots |
| POST | `/api/v1/backups` | Create snapshot |
| GET | `/api/v1/backups/{name}` | Manifest |
| POST | `/api/v1/backups/{name}` | Re-run |
| POST | `/api/v1/backups/{name}/verify` | Recompute SHA-256, report bad blobs |
| POST | `/api/v1/backups/{name}/restore` | Restore in place |
| DELETE | `/api/v1/backups/{name}` | Remove (blocked if a child depends) |

---

## 20. PKI & Security

PKI (§39). Internal CA + ACME (certbot) issuance + renewal + cluster fan-out. Audit (§5) ledger.

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/pki/certificates` | List certificates |
| GET | `/api/v1/pki/certificates/expiring` | Expiring soon |
| POST | `/api/v1/pki/certificates/generate` | Mint self-signed |
| POST | `/api/v1/pki/certificates/{id}/deploy` | Push cert to nodes |
| POST | `/api/v1/pki/certificates/{id}/rotate` | Generate + deploy |
| DELETE | `/api/v1/pki/certificates/{id}` | Soft-delete |
| POST | `/api/v1/pki/acme/issue` | Request Let's Encrypt cert |
| POST | `/api/v1/pki/acme/renew/{cert_id}` | Renew via certbot |
| POST | `/api/v1/pki/peer/install` | Peer: install cert |
| POST | `/api/v1/pki/peer/reload` | Peer: reload server |
| GET | `/api/v1/audit/log` | Audit ledger |
| GET | `/api/v1/audit/log/{event_id}` | Event detail |
| POST | `/api/v1/audit/verify` | Verify chain |
| GET | `/api/v1/security/policy` | Active security policy |
| PUT | `/api/v1/security/policy` | Update policy |
| GET | `/api/v1/security/sandbox` | Sandbox status |
| GET | `/api/v1/security/tool-whitelist` | Tool whitelist |
| PUT | `/api/v1/security/tool-whitelist` | Update whitelist |

---

## 21. Observability

Telemetry / OTLP (§90), Dreams (§42), Webhooks (§75), mDNS discovery (§38).

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/telemetry/config` | Current OTLP config |
| PUT | `/api/v1/telemetry/config` | Update config |
| GET | `/api/v1/telemetry/stats` | Buffer depths, flush results |
| GET | `/api/v1/dreams/config` | Dream engine config |
| PUT | `/api/v1/dreams/config` | Update config (admin opt-in) |
| POST | `/api/v1/dreams/run` | Run one dream cycle |
| GET | `/api/v1/dreams/last-runs` | Recent dream reports |
| POST | `/api/v1/dreams/import-session` | Direct in-process import |
| GET | `/api/v1/webhooks/subscriptions` | List |
| POST | `/api/v1/webhooks/subscriptions` | Create |
| DELETE | `/api/v1/webhooks/subscriptions/{id}` | Remove |
| POST | `/api/v1/webhooks/subscriptions/{id}/test` | Test fire |
| GET | `/api/v1/webhooks/deliveries` | Audit log |
| GET | `/metrics` | Prometheus-compatible metrics |

---

## 22. Marketplace & Plugins

Plugin marketplace (§80) on the edge module; plugin host serves Tool/Filter/Pipe/Action/Widget plugin types.

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/marketplace/catalog` | Browse catalogue |
| GET | `/api/v1/marketplace/installed` | Installed plugins |
| POST | `/api/v1/marketplace/install` | Download + sha256 verify + extract + validate manifest |
| POST | `/api/v1/marketplace/uninstall` | Remove |
| POST | `/api/v1/marketplace/update` | Pull newer version |
| GET | `/api/v1/plugins` | List loaded plugins |
| POST | `/api/v1/plugins/{id}/enable` | Enable plugin |
| POST | `/api/v1/plugins/{id}/disable` | Disable plugin |
| GET | `/api/v1/plugins/{id}/valves` | Read plugin configuration |
| PUT | `/api/v1/plugins/{id}/valves` | Update plugin configuration |

---

## 23. Theming & Branding

Per-tenant theme + branding (§99). Public read, admin-gated writes.

| Method | Path | Access |
|--------|------|--------|
| GET | `/api/v1/tenants/{tid}/theme` | Public read (chat shell consumes) |
| PUT | `/api/v1/tenants/{tid}/theme` | Admin + `themes` license |
| POST | `/api/v1/tenants/{tid}/branding/logo` | Admin + Pro+ |
| GET | `/api/v1/tenants/{tid}/branding/logo` | Public read |

---

## 24. License

Controller-side license endpoints plus the external Eldric license-validation service.

### Controller side

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/license` | Current license status |
| POST | `/api/v1/license/activate` | Activate from local file |
| POST | `/api/v1/license/validate` | Verify signature + expiration (optional `server` for online check) |

### License server (admin)

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/licenses` | List all licenses |
| POST | `/api/v1/licenses` | Create license |
| GET | `/api/v1/licenses/{id}` | License detail |
| GET | `/api/v1/licenses/{id}/download` | Signed file download |
| POST | `/api/v1/licenses/{id}/revoke` | Revoke |

Admin auth requires three factors: `X-API-Key` + `X-Admin-Email` + `X-Admin-Password`.

---

## 25. xLSTM Daemon (reserved, port 8884)

Spec in flight 2026-05-14 (`PROMPT-MAIN-tech-xlstmd-coordination.md`). Endpoint set will land as `/api/v1/xlstm/policy/*`, `/api/v1/xlstm/forecast/*`, `/api/v1/xlstm/encode/*`, `/api/v1/xlstm/retrieve/*`. This section is a placeholder — DOCS updates once TECH section §5 finalises.

---

## Notes on accuracy

This reference is generated by walking the 5.0 module registration code (`cpp/src/modules/*/`), the legacy 4.x daemon surface still compiled in (`cpp/src/distributed/*/`), and the EldricOS section specifications at `~/Desktop/EldricOS/sections/`. Where CLAUDE.md and an EldricOS section disagree, the section wins (see `feedback_eldricos_authoritative_over_claudemd.md`).

When alphas land that add or rename endpoints, MAIN forwards the alpha note to DOCS which regenerates this file. See `MAIN-docs-orchestration.md` for the protocol.