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.

---

Table of Contents

1. Surface model
2. Authentication
3. Public OpenAI-compatible
4. Chat & Conversation
5. Identity & Account
6. Inference & Models
7. Routing
8. Data — Storage, Vector, RAG
9. Data — Matrix Memory
10. Data — NFS, Databases, Connectors
11. Agent Worker
12. Media Worker
13. Communication Worker
14. Science Worker
15. Training Worker
16. Native Inference (inferenced)
17. IoT Worker
18. Swarm
19. NOVA
20. System & Cluster
21. Cluster Operations
22. PKI & Security
23. Observability
24. Marketplace & Plugins
25. Theming & Branding
26. License
27. xLSTM Daemon (reserved)

---

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.