# Omnius REST Quick Reference

Start:

```bash
omnius serve
```

Base:

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

Docs:

```text
GET /docs
GET /api/docs
GET /openapi.json
GET /openapi.yaml
GET /redoc
```

Auth header:

```text
Authorization: Bearer <key>
```

Local global installs create a daemon bootstrap key at `~/.omnius/api.key`.
Inside Omnius, run `/apikey show` to display it, `/apikey copy` to copy it, and
`/apikey mint run` to create a project runtime key for agents or MCP-style
REST clients.

## Health

```bash
curl -s http://127.0.0.1:11435/health
curl -s http://127.0.0.1:11435/health/ready
curl -s http://127.0.0.1:11435/version
```

## Discovery

```bash
curl -s http://127.0.0.1:11435/v1/discovery/bootstrap
curl -s 'http://127.0.0.1:11435/v1/discovery?q=bring%20your%20own%20inference'
curl -s http://127.0.0.1:11435/v1/discovery/tool.web-search
```

## Models

```bash
curl -s http://127.0.0.1:11435/v1/models
curl -s -X POST http://127.0.0.1:11435/v1/config/model/check
```

## Chat

```bash
curl -s http://127.0.0.1:11435/v1/chat \
  -H 'content-type: application/json' \
  -d '{"message":"Summarize this repo in one paragraph.","tools":true}'
```

## Realtime Chat

```bash
curl -s http://127.0.0.1:11435/v1/chat \
  -H 'content-type: application/json' \
  -d '{"message":"Keep this short for voice.","realtime":true}'
```

Text-only ASR/TTS adapter:

```bash
curl -s http://127.0.0.1:11435/v1/realtime \
  -H 'content-type: application/json' \
  -d '{"message":"Give me one short spoken reply."}'
```

## Session History

```bash
curl -s 'http://127.0.0.1:11435/v1/chat/sessions?root=/absolute/workspace'
curl -s 'http://127.0.0.1:11435/v1/chat/sessions/tui%3Asession-id?root=/absolute/workspace'
curl -s 'http://127.0.0.1:11435/v1/chat/sessions/tui%3Asession-id/status?since=0'
```

## OpenAI-Compatible Chat

```bash
curl -s http://127.0.0.1:11435/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"qwen3:4b","messages":[{"role":"user","content":"hello"}]}'
```

## Ollama-Compatible Generate

```bash
curl -s http://127.0.0.1:11435/v1/generate \
  -H 'content-type: application/json' \
  -d '{"model":"qwen3:4b","prompt":"Return one sentence."}'
```

## Agentic Run

```bash
curl -s -X POST http://127.0.0.1:11435/v1/run \
  -H 'content-type: application/json' \
  -d '{"task":"Run tests and report failures.","sandbox":"none"}'
```

## Events

```bash
curl -N http://127.0.0.1:11435/v1/events
curl -N 'http://127.0.0.1:11435/v1/events?type=tool.*'
```

## Skills

```bash
curl -s http://127.0.0.1:11435/v1/skills
curl -s http://127.0.0.1:11435/v1/skills/omnius-rest-docs
```

## Tool Call

First inspect `direct_callable`:

```bash
curl -s http://127.0.0.1:11435/v1/tools/memory_search
```

```bash
curl -s -X POST http://127.0.0.1:11435/v1/tools/memory_search/call \
  -H 'content-type: application/json' \
  -d '{"args":{"query":"rest api docs"}}'
```

`web_search` is agent-bound. Offer it to `/v1/run`, `/v1/chat`, or
`/v1/chat/completions` with `agent_loop: true` and
`include_daemon_tools: ["read"]`; do not infer direct-call support from the
presence of its schema.

Deterministic bookkeeping without an agent run:

```bash
curl -s -X POST http://127.0.0.1:11435/v1/tools/todo_write/call \
  -H 'content-type: application/json' \
  -H 'x-omnius-session-id: tracking-turn-123' \
  -d '{"profile":"bookkeeping-tracking","args":{"todos":[{"content":"Create report","status":"in_progress"}]}}'
```

## Voice TTS

```bash
curl -s -X POST http://127.0.0.1:11435/v1/voice/tts \
  -H 'content-type: application/json' \
  -d '{"text":"Hello from Omnius.","format":"wav"}' \
  --output speech.wav
```

## ASR Registry And Test

```bash
curl -s http://127.0.0.1:11435/v1/asr/engines
curl -s http://127.0.0.1:11435/v1/asr/status
curl -s -X POST http://127.0.0.1:11435/v1/asr/activate \
  -H 'content-type: application/json' \
  -d '{"engine_id":"transcribe-cli"}'
```

## Verified Global Update

```bash
curl -s http://127.0.0.1:11435/v1/update
curl -s -X POST http://127.0.0.1:11435/v1/update \
  -H 'content-type: application/json' \
  -d '{"version":"1.2.3"}'
```

The POST requires an exact semver. Poll the GET route for live phase/output and
package, executable, daemon, hash, restart, and tray verification.

## Runtime Key Minting

Requires admin scope:

```bash
curl -s -X POST http://127.0.0.1:11435/v1/keys \
  -H 'authorization: Bearer admin-secret' \
  -H 'content-type: application/json' \
  -d '{"scope":"run","project":"myactuator","rpm":60,"tpd":100000,"max_jobs":3}'
```