API reference

An unknown model does not fail. If no backend serves the model you asked for, the request is answered by a different one rather than rejected. Measured 2026-08-20 on two nodes with a made-up id:

X-Eldric-Model-Substitution: totally-made-up-model-xyz->mistral-large-3:675b
X-Eldric-Model-Substitution: totally-made-up-model-xyz->qwen3.5:397b

Two things follow for a client. The response's model field names the model that answered, not the one you requested — so comparing it against your request is how you detect a swap in the body. And the substitute is not fixed: it depends on which node serves the request and on which models that node currently has loaded — the same made-up id returned qwen3.5:397b from one node on 19 August and mistral-large-3:675b from the same node a day later. Do not cache the mapping.

If you need the model you asked for, check the header or the model field before trusting the answer. A 200 is not a confirmation that your model ran. Substitution works the same way with stream: true — the header is sent and every frame's model field names the substitute (verified on two nodes, 2026-08-20).

Streaming errors do not arrive as an error status. When a request fails after the stream has been opened, the HTTP status can be 200 and the failure arrives inside the first frame — sometimes as a JSON string nested in detail, so it needs decoding twice. Measured on two nodes, 2026-08-20, omitting messages:

stream: false -> 400  {"error":{"message":"[] is too short - 'messages' …"}}
stream: true  -> 200  data: {"detail":"{"error":{"message":"[] is too short …"}}"}

Not every error diverges — a missing model returns 400 on both paths. So with stream: true, read the first frame before treating a 200 as success.

Return the model catalogue available to the caller. There is no per-model detail endpoint on this API and no legacy /v1/completions; use /v1/chat/completions.

Create a chat completion. Supports streaming and compatible tool fields where enabled.

Create embeddings.

Return model detail by request body.

Open the browser chat shell.

Open the login form when session authentication is used.

Public health check — reachable without a token, and the quickest confirmation that the daemon is up. It reports the running version. Note the path has no /api/v1 prefix.

List the caller's own conversations.

Create one. JSON body optional; title is honoured when present.

Rename. JSON body; a malformed body is rejected with 400.

Delete the caller's own conversations. Self-scoped by session — this is the "clear my history" action and the Article 17 erasure path.

Messages of one conversation. Requires ?id=; without it the call returns 400.

Append a message. The JSON body carries conversation_id.

Flat list of {conversation_id, title, role, snippet, ts}, newest first. No pagination — capped at 50 hits.

Export a conversation as markdown or plain JSON.

The caller's conversations as the controller sees them.

List conversations visible to the caller.

Create a conversation.

Fetch a conversation and its visible metadata.

Update title, pin state or metadata.

Delete a conversation.

Append a message.

Page through messages.

Branch a conversation from a message.

Create a signed read-only share link.

Resolve a shared transcript.

List inline artifacts.

Fetch one artifact.

Read caller settings.

Update caller settings.

Read webchat preferences.

Update webchat preferences.

Read quota and usage snapshot.

List tools allowed for the caller.

List models allowed for the caller.

Read caller identity namespace mapping.

Register a device under the caller tenant.

Unregister a device identity.

Create an authenticated session.

Refresh a session token.

Invalidate a session.

Enroll a second factor where enabled.

Verify a second factor code.

Read a tenant-scoped file.

Write a tenant-scoped file.

Delete a tenant-scoped file.

List tenant-scoped files.

Reserve a chunked upload.

Upload one chunk.

Commit an upload.

Read upload progress.

Cancel an upload.

List vector namespaces.

Create a namespace.

Delete a namespace.

Add documents.

Get a document.

Replace and re-index a document.

Delete a document.

Run semantic search.

Run hybrid lexical and vector search.

Ingest and index content.

Store an association for later recall.

Recall stored context.

Remove one stored entry.

List agent sessions.

Create an agent session.

Read agent session detail.

Delete an agent session.

Run agentic RAG chat.

Run a multi-agent task.

Break a query into sub-questions.

List knowledge bases.

Create a knowledge base.

Search a knowledge base.

Transcribe audio.

Stream transcription.

Synthesize speech.

Stream synthesized audio.

List voices.

Run voice chat.

Transcribe video audio.

List communication accounts.

Send a message through an enabled channel.

Stub — returns no results, by construction. Measured 2026-08-20: the handler answers {"results":[],"count":0,"_stub":true}, and nothing in 5.0 persists a message for it to search — comm messages live in memory only (a capped inbox and an ephemeral outbox), and 4.x’s message store is on disk but not compiled into the daemon. Branch on _stub: an empty results array here does not mean “nothing matched”.

Start an outbound voice call.

List enabled science sources.

List science source categories.

Request source enablement.

List role-filtered science tool schemas.

Execute a science tool.

List enabled sources through a category alias.

List IoT devices.

Read a device attribute.

Write a device attribute.

List swarms.

Create a swarm.

Set a swarm goal.

Read tenant theme.

Read tenant logo.