# Chat And Inference Endpoints

## Endpoint Summary

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/models` | List aggregated models |
| `POST` | `/v1/chat/completions` | OpenAI-compatible chat completions |
| `POST` | `/realtime` | Text-only voice-adapter brain: transcript text in, short reply text out |
| `POST` | `/v1/realtime` | Auth-scoped alias for `/realtime` |
| `POST` | `/v1/embeddings` | Generate embeddings |
| `POST` | `/v1/chat` | Stateful Omnius chat with optional full agent tools |
| `POST` | `/v1/generate` | Ollama-compatible one-shot generation |
| `POST` | `/api/generate` | Ollama-compatible alias |
| `GET` | `/v1/chat/sessions` | List persisted browser chats plus quality-filtered importable TUI sessions |
| `GET` | `/v1/chat/sessions/{id}` | Hydrate full session history, transcript, and in-flight state |
| `DELETE` | `/v1/chat/sessions/{id}` | Permanently delete a canonical chat or TUI history session |
| `POST` | `/v1/chat/sessions/{id}/summarize` | Generate and cache a clean title/summary |
| `GET` | `/v1/chat/sessions/{id}/status` | Read live state and unseen deltas since a sequence number |
| `POST` | `/v1/chat/suggest-followup` | Suggest one short next message |
| `POST` | `/v1/chat/check-in` | Send a steering check-in to the active chat session |
| `POST` | `/v1/chat/attachments` | Upload an attachment for a stateful chat |

## `/v1/models`

Returns an OpenAI-style model list aggregated from enabled endpoints. Model discovery should include local Ollama, configured external endpoints, sponsor endpoints, and COHERE/passthrough models where enabled.

## `/v1/chat/completions`

This is the OpenAI-compatible endpoint. It forwards standard chat-completion fields and adds Omnius controls.

Important body fields:

| Field | Type | Purpose |
| --- | --- | --- |
| `model` | string | Backend model name |
| `messages` | array | OpenAI-style messages |
| `stream` | boolean | SSE streaming when supported |
| `realtime` | boolean | Enable Omnius realtime conversation mode |
| `realtime_options` | object | Realtime history and max-token defaults |
| `tools` | array | OpenAI-shape tools array |
| `tool_choice` | any | OpenAI-shape tool choice |
| `parallel_tool_calls` | boolean | Forwarded to backend |
| `timeout_s` | number | Per-request timeout |
| `agent_loop` | boolean | Run server-side tool loop |
| `include_daemon_tools` | array | Permit the bounded core daemon-tool catalog by scope: `read`, `run`, `admin` |
| `daemon_tool_names` | array | Exact daemon-tool allowlist; recommended for local models |
| `agent_timeout_s` | number | Whole-loop deadline, default 45 seconds and maximum 600 |
| `agent_max_tool_rounds` | integer | Daemon tool rounds before forced final synthesis; default 1 |
| `agent_prefetch_web_search` | boolean | Explicit one-generation web-search prefetch; factual-first enables it automatically |
| `max_turns` | integer | Server-side agent loop turn cap |
| `prompt_template` | string | Optional template such as `factual-first` |

Realtime example:

```json
{
  "model": "qwen3:4b",
  "realtime": true,
  "realtime_options": {
    "max_history_messages": 12,
    "max_tokens": 160
  },
  "messages": [
    { "role": "user", "content": "Make that shorter for voice." }
  ]
}
```

## `/v1/chat`

This is the Omnius stateful chat endpoint. By default it runs the full Omnius agent stack with tools, memory, skills, and multi-agent context. Set `tools: false` to use the fast direct backend path. `realtime: true` also uses the direct backend path.

Body fields:

| Field | Type | Purpose |
| --- | --- | --- |
| `message` | string | User message |
| `model` | string | Optional model override |
| `session_id` | string | Reuse or name a session |
| `stream` | boolean | Stream when supported |
| `tools` | boolean | Full agent stack by default |
| `realtime` | boolean | Short ASR/TTS conversation mode |
| `realtime_options` | object | Realtime settings |

## Session History And Recovery

`GET /v1/chat/sessions` is a workspace history index, not merely an active-run
list. `?root=/absolute/workspace` selects the project and `?include_tui=0`
excludes TUI history. The default result combines canonical browser chats with
TUI sessions that pass quality checks. Exit-only commands such as `/quit` and
`/exit`, manual-save placeholders, empty/noise-only histories, and duplicate
normalized transcripts are not emitted as chats.

Open a row with `GET /v1/chat/sessions/{id}`. The response contains all public
messages, the imported TUI transcript when applicable, identity/source/project
metadata, token counts, timestamps, and an in-flight job snapshot with a bounded
partial-output tail. Poll `GET /v1/chat/sessions/{id}/status?since=<seq>` while a
run is active to catch up without rerunning it. `DELETE` is admin-scoped and
removes canonical daemon history; hiding a row in browser-local organization is
not a server deletion.

## `/v1/generate` And `/api/generate`

These endpoints provide one-shot Ollama-compatible generation. They are useful for clients that speak Ollama's generate shape rather than OpenAI chat messages. The route has no session history and can still use Omnius' backend routing layer.

Common body fields:

| Field | Type | Purpose |
| --- | --- | --- |
| `model` | string | Optional model override |
| `prompt` | string | Prompt text |
| `stream` | boolean | Stream when supported |

## Realtime Behavior

When `realtime: true`, Omnius:

- Builds a compact system prompt from `SOUL.md` or `.aiwg/SOUL.md`.
- Reads a compact voice profile from `.aiwg/voices/` when present.
- Keeps only recent non-system history.
- Preserves caller system messages under the realtime contract.
- Defaults to short response settings.
- Removes Omnius-only realtime fields before backend proxying.

Use this for live voice clients, not long coding tasks.

For ASR/TTS systems that only need the text brain, use `/realtime` or `/v1/realtime` with `message`, `text`, `recent_turn`, `asr_text`, or `callerText`. Optional `soul_md` supplies adapter-local SOUL.md content. Set `Accept: text/plain` or `format: "text"` to receive only the reply string.

## Server-Side Agent Loop

`/v1/chat/completions` can run an internal tool loop when `agent_loop: true`. This lets clients collapse multiple model/tool round trips into one daemon request. Daemon tool calls execute inline; client-owned tool calls can still be yielded in OpenAI-compatible shape.

Ollama-backed loops use its native `/api/chat` tool protocol. `timeout_s` applies to each backend round, while `agent_timeout_s` bounds the complete loop and defaults to 45 seconds. For a normal loop, the planning turn is capped at 96 output tokens; one daemon-tool round is the default, after which Omnius removes daemon schemas for final synthesis. `prompt_template: "factual-first"` skips that model-planning round entirely: Omnius executes the already-mandated, authorized `web_search` using the latest user turn, inserts the protocol-correct tool evidence, and performs one grounded synthesis generation. `agent_prefetch_web_search: true` opts into the same path directly. Generic/deeper tool workflows remain available through `agent_max_tool_rounds`. Omnius returns typed HTTP 504/508 failures, caps tool evidence at 6,000 characters, and limits the implicit catalog unless `daemon_tool_names` requests exact additions.