Eldric AIOS 5.0 — Public API Surface

Version: 5.0.0 (alpha118) Last regenerated: 2026-05-14 Scope: The endpoints reachable from the Internet through https://chat.eldric.ai. Every entry is one line. Companion: api-reference.md holds the full, LAN-only included reference.

Public endpoints require an X-API-Key (tenant scope) unless explicitly marked anonymous. Cross-tenant attempts return 403 (see kernel::tenant_guard). Admin / cluster / PKI / backup / migration / replication / federation / marketplace / dreams / telemetry-write / theme-write / system / discovery paths are not reachable here and return 401 — by design.

OpenAI-compatible

GET /v1/models — aggregated model catalogue across every reachable worker + cloud backend.
POST /v1/chat/completions — OpenAI chat completions (streaming via stream:true; honours tools, tool_choice, response_format).
POST /v1/completions — legacy completions for older OpenAI SDKs.
POST /v1/embeddings — embedding generation.
GET /v1/models/{id} — model detail (template, system prompt, parameters).
POST /api/v1/models/show — same detail by request body.

Chat shell

GET /chat — webchat single-page app.
GET /login — login form when API-key auth is required.
GET /api/v1/health — health check (anonymous).
GET /api/v1/conversations — list my conversations.
POST /api/v1/conversations — create a conversation.
GET /api/v1/conversations/{id} — fetch conversation with messages.
PATCH /api/v1/conversations/{id} — update title / pin / metadata.
DELETE /api/v1/conversations/{id} — delete conversation.
POST /api/v1/conversations/{id}/messages — append a message.
GET /api/v1/conversations/{id}/messages — page through messages.
POST /api/v1/conversations/{id}/branch — branch off at a message.
POST /api/v1/conversations/{id}/share — issue a signed share-link.
GET /api/v1/share/{token} — read-only resolved transcript.
GET /api/v1/conversations/{id}/artifacts — inline artifacts (§114).
GET /api/v1/conversations/{id}/artifacts/{aid} — fetch one artifact.

Account

GET /api/v1/me/settings — my settings.
PUT /api/v1/me/settings — update settings.
GET /api/v1/me/preferences — webchat preferences.
PUT /api/v1/me/preferences — update preferences.
GET /api/v1/me/quotas — quota / usage snapshot.
GET /api/v1/me/tools — tools my role may call (§113 picker).
GET /api/v1/me/models — models I'm allowed to call.

Identity

GET /api/v1/identity/me — my EIS namespace map.
POST /api/v1/identity/register — register a device under my tenant.
DELETE /api/v1/identity/{eis} — unregister a device.

Auth

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.

Data (per-tenant; tenant-guard enforced)

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.
POST /api/v1/upload/init — reserve chunked upload (§107).
POST /api/v1/upload/chunk — ship one chunk.
POST /api/v1/upload/finalize — commit.
GET /api/v1/upload/{id}/progress — resume offset.
DELETE /api/v1/upload/{id} — cancel + free chunks.

Vector / RAG

GET /api/v1/vector/namespaces/{tenant} — list namespaces.
POST /api/v1/vector/namespaces/{tenant} — create 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 + 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/hybrid-search — BM25 + vector.
POST /api/v1/vector/ingest — auto-chunk + ingest.

Memory

POST /api/v1/memory/store — store association into matrix + vector backup.
POST /api/v1/memory/recall — matrix recall, vector refinement.
POST /api/v1/memory/forget — remove one entry.

Agent

GET /api/v1/agent/sessions — list sessions.
POST /api/v1/agent/sessions — create session.
GET /api/v1/agent/sessions/{id} — session detail.
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.
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.
POST /api/v1/agent/knowledge-bases/{id}/search — search a KB.

Media

POST /api/v1/stt/transcribe — transcribe audio file/URL.
POST /api/v1/stt/stream — streaming transcription.
POST /api/v1/tts/synthesize — synthesize speech.
POST /api/v1/tts/stream — stream audio.
GET /api/v1/tts/voices — available voices.
POST /api/v1/voice/chat — voice-in → STT → LLM → TTS → voice-out.
POST /api/v1/video/transcribe — extract + transcribe video.

Communication

GET /api/v1/comm/accounts — list accounts.
POST /api/v1/comm/messages — send message (email/SMS/WhatsApp/Signal/Teams).
POST /api/v1/comm/search — semantic search across messages.
POST /api/v1/comm/calls/start — outbound voice call.

Science (registry + tools)

GET /api/v1/science/sources — enabled sources (filter by category).
GET /api/v1/science/sources/categories — 16-category taxonomy.
POST /api/v1/science/sources/request — request admin enable a source.
GET /api/v1/science/tools — role-filtered tool schemas.
POST /api/v1/science/tools/execute — dispatch a science tool.
GET /api/v1/{category}/sources — category alias (one of 16 categories).

IoT

GET /api/v1/iot/devices — list devices (Netatmo, HomeKit, Matter, OPC-UA, Modbus, MQTT).
POST /api/v1/iot/devices/{id}/read — read attribute.
POST /api/v1/iot/devices/{id}/write — write attribute.

Swarm

GET /api/v1/swarms — list swarms.
POST /api/v1/swarms — create swarm.
POST /api/v1/swarms/{id}/goal — set goal.

Theming (read-only public)

GET /api/v1/tenants/{tid}/theme — read tenant theme (chat shell pulls this).
GET /api/v1/tenants/{tid}/branding/logo — read tenant logo.

What is not public

These endpoints exist, but the Edge enforces 401. They are listed here so external integrators don't waste time on them.

/api/v1/cluster/* (peers, workers, updates, migrate, discover)
/api/v1/system/* (upgrade, drain, checkpoint, rollback)
/api/v1/pki/* (CA, ACME, certificate lifecycle)
/api/v1/backups/* (snapshot / verify / restore)
/api/v1/replication/* (data replication policy)
/api/v1/training/federated/* (FL orchestration)
/api/v1/marketplace/* (plugin install / uninstall)
/api/v1/dreams/* (dream engine config & runs)
/api/v1/telemetry/config (OTLP write; read still admin)
/api/v1/security/* (policy, sandbox, tool-whitelist)
/api/v1/audit/* (audit ledger)
/api/v1/tenants/*/theme (PUT; GET is public)
/api/v1/license/* (activate, validate)
/api/v1/identity/domains, /api/v1/identity/devices (catalogues; admin-only)

Use the LAN endpoints documented in api-reference.md when you are running inside the cluster's private network.

Rate limits & quotas

Quota enforcement runs at the Edge:

Global RPM, per-IP RPM, per-key RPM, plus a sliding window (default 60 s).
Tenant feature flags gate higher-cost endpoints (themes, pki-management, webhooks, file-storage).
See /api/v1/me/quotas to read your live counters.

Errors

The Edge sanitises every error to avoid disclosing internal LAN IPs, hostnames, ports or admin paths. A 503 from the Edge usually means the upstream module is not configured for that path. A 401 on a clearly-private path is intentional and not a bug.

The Internet-reachable surface.