# 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](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](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.