# Omnius REST API Docs

This directory is the human-readable REST API reference for Omnius. It is meant to be explored incrementally by agents and humans.

For intent-first lookup, start with
[Discovery](./endpoints/discovery.md), `GET /v1/discovery/bootstrap`,
`GET /v1/discovery`, or the bundled
[`DISCOVERY.json`](../DISCOVERY.json). Use this index after the catalog points
to an endpoint family.

Canonical sources:

- Runtime OpenAPI generator: `packages/cli/src/api/openapi.ts`
- Live OpenAPI document: `GET /openapi.json`
- Swagger UI: `GET /docs` or `GET /api/docs`
- ReDoc: `GET /redoc`
- AsyncAPI voicechat document: generated from `packages/cli/src/api/openapi.ts`

## How To Explore

Use this index first, then open the smallest relevant family file:

| Need | Read |
| --- | --- |
| Quick commands and examples | `docs/rest/QUICKREF.md` |
| Full maintained endpoint inventory | `docs/reference/rest-api.md` |
| Auth, scopes, rate limits, API keys | `docs/rest/auth-and-scopes.md` |
| Errors, pagination, ETags, request IDs | `docs/rest/errors-pagination-etags.md` |
| OpenAPI and docs renderers | `docs/rest/openapi-source.md` |
| Capability and documentation discovery | `docs/rest/endpoints/discovery.md` |
| Chat, realtime, OpenAI-compatible inference | `docs/rest/endpoints/chat.md` |
| Agentic jobs and run lifecycle | `docs/rest/endpoints/run.md` |
| Config, endpoints, keys, profiles, projects | `docs/rest/endpoints/config.md` |
| Memory, sessions, context | `docs/rest/endpoints/memory.md` |
| Skills and slash commands | `docs/rest/endpoints/skills.md` |
| AIWG cascade loader | `docs/rest/endpoints/aiwg.md` |
| Tools, MCP, code graph | `docs/rest/endpoints/tools.md` |
| Events, metrics, usage, audit, system | `docs/rest/endpoints/events.md` |
| Files | `docs/rest/endpoints/files.md` |
| Voice, audio, vision, voicechat WebSocket | `docs/rest/endpoints/voice-vision.md` |
| AIMS governance | `docs/rest/endpoints/aims.md` |
| Curl examples | `docs/rest/examples/curl.md` |
| OpenAI SDK examples | `docs/rest/examples/openai-sdk.md` |

## Start The Daemon

```bash
omnius serve
```

Default base URL:

```text
http://127.0.0.1:11435
```

Bind a custom port:

```bash
omnius serve --port 9000
```

Bind from environment:

```bash
OMNIUS_HOST=0.0.0.0:11435 omnius serve
```

## Auth Model

Local anonymous requests default to read behavior unless the runtime is configured for insecure loopback admin. Remote/shared deployments should use bearer keys.

```bash
OMNIUS_REST_API_KEY="admin-secret" omnius serve
OMNIUS_REST_API_KEYS="read-key:read:grafana,run-key:run:ci:60:100000:3,admin-key:admin:ops" omnius serve
```

Scopes:

- `read`: inspect models, health, usage, memory search, skills, tools metadata, events, and summaries.
- `run`: submit tasks and invoke permitted run-scope tools.
- `admin`: mutate config, keys, high-risk controls, and admin-only tools.

## Common Conventions

- Errors use RFC 7807-style Problem Details where implemented.
- List endpoints use `{ "data": [...], "pagination": { "limit": 50, "offset": 0, "total": 0, "has_more": false } }` where implemented.
- Cacheable GET responses may include `ETag`; send `If-None-Match` for conditional reads.
- Responses include `X-API-Version` and `X-Request-ID` where the API middleware can attach them.
- Use `Authorization: Bearer <key>` when auth is enabled.
- Use `X-Request-ID` to correlate client logs with the daemon audit log.

## Endpoint Families

| Family | Representative endpoints |
| --- | --- |
| Health | `/health`, `/health/ready`, `/health/startup`, `/version`, `/metrics` |
| Discovery | `/v1/discovery/bootstrap`, `/v1/discovery`, `/v1/discovery/{id}` |
| Inference and chat | `/v1/models`, `/v1/chat/completions`, `/v1/chat`, `/realtime`, `/v1/realtime`, `/v1/chat/sessions`, `/v1/chat/sessions/{id}`, `/v1/chat/check-in` |
| AIWG | `/v1/aiwg`, `/v1/aiwg/frameworks`, `/v1/aiwg/skills`, `/v1/aiwg/use`, `/v1/aiwg/expand` |
| Runs | `/v1/run`, `/v1/runs`, `/v1/runs/{id}`, `/v1/runs/{id}/output`, `/v1/todos`, `/v1/todos/{session_id}` |
| Config | `/v1/config`, `/v1/config/model`, `/v1/config/endpoint`, `/v1/config/endpoint/test`, `/v1/config/endpoint/history`, `/v1/share/generate` |
| Metering and audit | `/v1/usage`, `/v1/audit`, `/v1/cost`, `/v1/system` |
| Runtime keys | `/v1/keys`, `/v1/keys/{prefix}` |
| Profiles | `/v1/profiles`, `/v1/profiles/{name}` |
| Files | `/v1/files`, `/v1/files/read`, `/v1/files/raw` |
| Skills and commands | `/v1/skills`, `/v1/skills/{name}`, `/v1/commands`, `/v1/commands/{cmd}` |
| MCP | `/v1/mcps`, `/v1/mcps/{name}`, `/v1/mcps/{name}/call` |
| Tools | `/v1/tools`, `/v1/tools/{name}`, `/v1/tools/{name}/call`, `/v1/hooks`, `/v1/agents` |
| Memory | `/v1/memory`, `/v1/memory/search`, `/v1/memory/write`, `/v1/memory/ingest`, `/v1/memory/entities`, `/v1/memory/jobs/run`, `/v1/memory/feedback` |
| Events | `/v1/events` |
| Sessions and context | `/v1/sessions`, `/v1/sessions/{id}`, `/v1/context`, `/v1/context/window-dumps`, `/v1/context/window-dumps/{id}`, `/v1/context/save`, `/v1/context/restore`, `/v1/context/compact` |
| Nexus | `/v1/nexus/status`, `/v1/sponsors` |
| Ollama pool | `/v1/ollama/pool/processes`, `/v1/ollama/pool/cleanup` |
| Voice and audio | `/v1/voice/state`, `/v1/voice/models`, `/v1/voice/tts`, `/v1/audio/speech`, `/v1/asr/engines`, `/v1/asr/selection`, `/v1/asr/activate`, `/v1/asr/transcriptions`, `/v1/asr/test`, `/v1/audio/transcriptions`, `/v1/voicechat/ws`, `/v1/media/av/analyze` |
| Vision/audio/OCR | `/v1/vision/describe`, `/v1/vision/embed`, `/v1/audio/embed`, `/v1/audio/embed/health`, `/v1/audio/embed/setup` (all require `kind=acoustic|speaker|semantic`), `/v1/audio/diarization/live/readiness`, `/v1/audio/diarization/live/setup`, `/v1/audio/diarization/live`, `/v1/audio/diarization/live/cancel`, `/v1/audio/diarization/reconcile/readiness`, `/v1/audio/diarization/reconcile/setup`, `/v1/audio/diarization/reconcile`, `/v1/audio/diarization/reconcile/cancel`, `/v1/ocr/readiness`, `/v1/ocr/setup`, `/v1/ocr/advanced` |
| Projects | `/v1/projects`, `/v1/projects/current`, `/v1/projects/switch`, `/v1/projects/register`, `/v1/projects/rename`, `/v1/projects/scan`, `/v1/projects/preferences` |
| Code graph | `/v1/codegraph/snapshot`, `/v1/codegraph/events` |
| Scheduled jobs | `/v1/scheduled`, `/v1/scheduled/all`, `/v1/scheduled/status`, `/v1/scheduled/kill`, `/v1/scheduled/fixup`, `/v1/scheduled/reconcile` |
| Services and update | `/v1/services/systemd`, `/v1/services/systemd/{unit}`, `/v1/update` |
| AIMS | `/v1/aims`, `/v1/aims/policies`, `/v1/aims/roles`, `/v1/aims/resources`, `/v1/aims/impact-assessments`, `/v1/aims/lifecycle`, `/v1/aims/data-quality`, `/v1/aims/transparency`, `/v1/aims/usage`, `/v1/aims/suppliers`, `/v1/aims/incidents`, `/v1/aims/oversight`, `/v1/aims/decisions`, `/v1/aims/config-history` |

## Realtime REST Flag

`POST /v1/chat` and `POST /v1/chat/completions` accept:

```json
{
  "realtime": true,
  "realtime_options": {
    "max_history_messages": 12,
    "max_tokens": 160
  }
}
```

This applies Omnius realtime conversation mode before proxying to the configured backend. It is intended for ASR/TTS clients and short back-and-forth speech.