# REST API Reference

This is the maintained human endpoint inventory for the Omnius daemon. The machine contract is generated by `packages/cli/src/api/openapi.ts` and served at `/openapi.json`.

Run the drift check before publishing docs:

```bash
pnpm docs:check
```

## Docs And Compatibility Aliases

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/docs` | Swagger UI |
| `GET` | `/api/docs` | Swagger UI alias |
| `GET` | `/openapi.json` | OpenAPI JSON |
| `GET` | `/openapi.yaml` | OpenAPI YAML |
| `GET` | `/v3/api-docs` | OpenAPI alias |
| `GET` | `/swagger.json` | Swagger-era alias |
| `GET` | `/api-docs` | OpenAPI alias |
| `GET` | `/swagger-ui` | Swagger UI alias |
| `GET` | `/redoc` | ReDoc renderer |

## Health And Observability

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/health` | Liveness probe |
| `GET` | `/health/ready` | Backend readiness |
| `GET` | `/health/startup` | Startup probe |
| `GET` | `/version` | Package version and platform |
| `GET` | `/metrics` | Prometheus metrics |
| `GET` | `/v1/events` | Server-sent event stream |
| `GET` | `/v1/usage` | Token usage and rate limits |
| `GET` | `/v1/audit` | Audit log query |
| `GET` | `/v1/cost` | Cost tracker |
| `GET` | `/v1/system` | CPU, RAM, GPU, and system snapshot |

## Inference And Chat

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/models` | Aggregated model list |
| `POST` | `/v1/chat/completions` | OpenAI-compatible chat completion |
| `POST` | `/v1/chat` | Stateful Omnius chat |
| `POST` | `/api/chat` | Ollama-compatible chat alias |
| `POST` | `/v1/generate` | Ollama-compatible one-shot generation |
| `POST` | `/api/generate` | Ollama-compatible generate alias |
| `POST` | `/v1/embeddings` | OpenAI-compatible embeddings |
| `POST` | `/api/embed` | Ollama-compatible embeddings alias |
| `GET` | `/api/tags` | Ollama-compatible model tags |
| `GET` | `/v1/chat/sessions` | Active chat sessions |
| `POST` | `/v1/chat/check-in` | Steering check-in for active chat |

## Agentic Runs

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/v1/run` | Submit agentic task |
| `GET` | `/v1/runs` | List runs |
| `GET` | `/v1/runs/{id}` | Get run details |
| `DELETE` | `/v1/runs/{id}` | Abort run |
| `POST` | `/v1/todos` | Create or update todos for current session |
| `GET` | `/v1/todos` | List sessions with todos |
| `GET` | `/v1/todos/{session_id}` | Get session todos |
| `DELETE` | `/v1/todos/{session_id}` | Delete session todos |
| `POST` | `/v1/evaluate` | Evaluate a run |
| `POST` | `/v1/index` | Trigger repository indexing |

## Configuration, Keys, Profiles, Projects

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/config` | Read daemon config |
| `PATCH` | `/v1/config` | Update daemon config |
| `GET` | `/v1/config/model` | Current model |
| `PUT` | `/v1/config/model` | Switch model |
| `POST` | `/v1/config/model/check` | Probe model readiness with non-empty text |
| `GET` | `/v1/config/endpoint` | Current endpoint |
| `PUT` | `/v1/config/endpoint` | Switch endpoint |
| `POST` | `/v1/config/endpoint/test` | Probe endpoint |
| `GET` | `/v1/config/endpoint/history` | Endpoint history |
| `DELETE` | `/v1/config/endpoint/history` | Remove endpoint history item |
| `POST` | `/v1/share/generate` | Generate remote-access share URL |
| `GET` | `/v1/keys` | List runtime API keys |
| `POST` | `/v1/keys` | Mint runtime API key |
| `DELETE` | `/v1/keys/{prefix}` | Revoke runtime API keys by prefix |
| `GET` | `/v1/profiles` | List tool profiles |
| `POST` | `/v1/profiles` | Create tool profile |
| `GET` | `/v1/profiles/{name}` | Get profile |
| `DELETE` | `/v1/profiles/{name}` | Delete profile |
| `GET` | `/v1/projects` | List known projects |
| `DELETE` | `/v1/projects` | Unregister a project |
| `GET` | `/v1/projects/current` | Current project |
| `POST` | `/v1/projects/switch` | Switch project |
| `POST` | `/v1/projects/register` | Register project |
| `POST` | `/v1/projects/rename` | Rename project |
| `GET` | `/v1/projects/preferences` | Read project preferences |
| `PUT` | `/v1/projects/preferences` | Patch project preferences |
| `DELETE` | `/v1/projects/preferences` | Reset project preferences |

## Skills, Commands, Tools, MCP

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/skills` | List skills |
| `GET` | `/v1/skills/{name}` | Load skill content |
| `GET` | `/v1/commands` | List slash commands |
| `POST` | `/v1/commands/{cmd}` | Execute slash command |
| `GET` | `/v1/tools` | List tools |
| `GET` | `/v1/tools/{name}` | Tool metadata |
| `POST` | `/v1/tools/{name}/call` | Call tool |
| `GET` | `/v1/mcps` | List MCP servers |
| `GET` | `/v1/mcps/{name}` | MCP server details |
| `POST` | `/v1/mcps/{name}/call` | Call MCP tool |
| `GET` | `/v1/hooks` | Hook registry |
| `GET` | `/v1/agents` | Agent type registry |
| `GET` | `/v1/codegraph/snapshot` | Code graph snapshot |
| `GET` | `/v1/codegraph/events` | Code graph SSE |

## AIWG

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/aiwg` | AIWG root and control map |
| `GET` | `/v1/aiwg/frameworks` | List frameworks |
| `GET` | `/v1/aiwg/frameworks/{name}` | Framework details |
| `GET` | `/v1/aiwg/frameworks/{name}/content` | Tier-aware content |
| `GET` | `/v1/aiwg/skills` | List AIWG skills |
| `GET` | `/v1/aiwg/skills/{name}` | Load AIWG skill |
| `GET` | `/v1/aiwg/agents` | List AIWG agents |
| `GET` | `/v1/aiwg/agents/{name}` | Load AIWG agent |
| `GET` | `/v1/aiwg/addons` | List AIWG addons |
| `POST` | `/v1/aiwg/use` | Tier-sized activation bundle |
| `POST` | `/v1/aiwg/expand` | Expand matching AIWG item |

## Memory, Sessions, Context

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/memory` | Memory backend summary |
| `POST` | `/v1/memory/search` | Search memory |
| `POST` | `/v1/memory/write` | Write memory |
| `GET` | `/v1/memory/episodes` | List episodes |
| `GET` | `/v1/memory/failures` | List failure records |
| `GET` | `/v1/sessions` | List task sessions |
| `GET` | `/v1/sessions/{id}` | Get session history |
| `GET` | `/v1/context` | Current context snapshot |
| `POST` | `/v1/context/save` | Save context entry |
| `GET` | `/v1/context/restore` | Build restore prompt |
| `POST` | `/v1/context/compact` | Request compaction |

## Files, Nexus, Ollama Pool

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/files` | List workspace directory |
| `POST` | `/v1/files/read` | Read workspace file |
| `GET` | `/v1/nexus/status` | Nexus peer state |
| `GET` | `/v1/sponsors` | Sponsor directory cache |
| `GET` | `/v1/ollama/pool/processes` | Ollama process inventory |
| `POST` | `/v1/ollama/pool/cleanup` | Cleanup stale Ollama pool processes |

## Voice, Audio, Vision

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/voice/state` | Voice runtime status |
| `GET` | `/v1/voice/models` | TTS models |
| `POST` | `/v1/voice/models/switch` | Switch TTS model |
| `GET` | `/v1/voice/supertonic-settings` | Voice tuning settings |
| `POST` | `/v1/voice/supertonic-settings` | Update voice tuning settings |
| `GET` | `/v1/voice/asr-models` | ASR models |
| `POST` | `/v1/voice/asr-models/switch` | Switch ASR model |
| `POST` | `/v1/voice/tts` | Synthesize speech |
| `POST` | `/v1/audio/speech` | OpenAI-compatible TTS alias |
| `POST` | `/v1/voice/transcribe` | Transcribe audio |
| `POST` | `/v1/audio/transcriptions` | OpenAI-compatible transcription alias |
| `POST` | `/v1/voice/transcribe/stream` | Streaming transcription |
| `POST` | `/v1/voice/clone-refs` | Upload voice clone reference |
| `GET` | `/v1/voice/clone-refs` | List clone references |
| `POST` | `/v1/voice/clone-refs/upload` | Upload clone reference |
| `POST` | `/v1/voice/clone-refs/from-url` | Fetch clone reference |
| `POST` | `/v1/voice/clone-refs/{filename}/activate` | Activate clone reference |
| `POST` | `/v1/voice/clone-refs/{filename}/rename` | Rename clone reference |
| `DELETE` | `/v1/voice/clone-refs/{filename}` | Delete clone reference |
| `POST` | `/v1/voice/speak` | Broadcast speech to voicechat clients |
| `GET` | `/v1/voicechat/ws` | WebSocket upgrade for full-duplex voicechat |
| `POST` | `/v1/vision/describe` | Vision describe placeholder |

## Engines And Scheduled Jobs

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/engines` | Long-running engine status |
| `GET` | `/v1/scheduled` | List scheduled jobs |
| `GET` | `/v1/scheduled/all` | List all scheduled jobs |
| `GET` | `/v1/scheduled/status` | Scheduler status |
| `POST` | `/v1/scheduled/kill` | Kill scheduled job |
| `POST` | `/v1/scheduled/fixup` | Reconcile scheduled state |
| `POST` | `/v1/scheduled/reconcile` | Force scheduled reconciliation |
| `GET` | `/v1/services/systemd` | Systemd service status |
| `GET` | `/v1/update` | Self-update status |

## AIMS Governance

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/aims` | AIMS root and endpoint index |
| `GET` | `/v1/aims/policies` | Policy register |
| `PUT` | `/v1/aims/policies` | Replace policy register |
| `GET` | `/v1/aims/roles` | Roles and responsibilities |
| `GET` | `/v1/aims/resources` | Resource inventory |
| `GET` | `/v1/aims/impact-assessments` | Impact assessments |
| `POST` | `/v1/aims/impact-assessments` | File impact assessment |
| `GET` | `/v1/aims/lifecycle` | Lifecycle state |
| `GET` | `/v1/aims/data-quality` | Data quality controls |
| `GET` | `/v1/aims/transparency` | Model cards and transparency |
| `GET` | `/v1/aims/usage` | AIMS usage view |
| `GET` | `/v1/aims/suppliers` | Supplier inventory |
| `GET` | `/v1/aims/incidents` | Incident records |
| `POST` | `/v1/aims/incidents` | File incident |
| `GET` | `/v1/aims/oversight` | Human oversight gates |
| `GET` | `/v1/aims/decisions` | Consequential decision log |
| `GET` | `/v1/aims/config-history` | Config change history |
