Files
OmniRoute/docs/reference/API_REFERENCE.md
diegosouzapw 61d8566911 Merge PR #19771 (recut/18731-capability-combo-routes) into merge train 2
# Conflicts:
#	open-sse/handlers/webFetch.ts
#	src/shared/validation/schemas/apiV1.ts
2026-11-14 02:52:53 -03:00

2549 lines
175 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: "API Reference"
version: 3.8.52
lastUpdated: 2026-10-05
---
# API Reference
🌐 **Languages:** 🇺🇸 [English](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇧🇦 [Bosanski](../i18n/bs/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md)
Core reference for the OmniRoute API. It covers the public `/v1` surface and the most-used management endpoints; the machine-readable [`docs/openapi.yaml`](../openapi.yaml) and the route tree under `src/app/api/` are the exhaustive sources.
For the focused OpenAI-compatible protocol and provider capability matrix, see
[`OPENAI_COMPATIBILITY.md`](./OPENAI_COMPATIBILITY.md).
Each deployment serves its own copy of the spec at `/openapi.yaml`, generated from `docs/openapi.yaml` during the build. It carries the build's version and a relative server URL (`./`), so requests stay on the host that served the document. A tool that imports the downloaded file has no such host, and needs the base URL set by hand.
---
## Table of Contents
- [Chat Completions](#chat-completions)
- [Exclusive Managed Session Leases](#exclusive-managed-session-leases)
- [Embeddings](#embeddings)
- [Image Generation](#image-generation)
- [Document OCR](#document-ocr)
- [List Models](#list-models)
- [Provider Plugin Manifest](#provider-plugin-manifest)
- [Compatibility Endpoints](#compatibility-endpoints)
- [Files API](#files-api)
- [Batches API](#batches-api)
- [Search API](#search-api)
- [WebSocket Streaming](#websocket-streaming)
- [Quotas & Issues Reporting](#quotas--issues-reporting)
- [Semantic Cache](#semantic-cache)
- [CLIProxyAPI Management Compatibility](#cliproxyapi-management-compatibility)
- [Dashboard & Management](#dashboard--management)
- [Combo Management](#combo-management)
- [Webhooks](#webhooks)
- [Registered Keys (Auto-Management)](#registered-keys-auto-management)
- [Agents Protocol](#agents-protocol)
- [Management Proxies](#management-proxies)
- [Resilience (extended)](#resilience-extended)
- [Skills](#skills)
- [Memory](#memory)
- [MCP Server](#mcp-server)
- [A2A Server](#a2a-server)
- [Cloud, Evals & Assess](#cloud-evals--assess)
- [Request Processing](#request-processing)
- [Authentication](#authentication)
---
## Chat Completions
```bash
POST /v1/chat/completions
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "cc/claude-opus-4-6",
"messages": [
{"role": "user", "content": "Write a function to..."}
],
"stream": true
}
```
### Custom Headers
| Header | Direction | Description |
| ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache |
| `x-omniroute-no-memory` | Request | Set to `true` to skip memory + skills injection for this request (mirrors no-cache; avoids the per-call token/cost overhead) |
| `X-OmniRoute-Progress` | Request | Set to `true` for progress events |
| `X-Session-Id` | Request | Sticky session key for external session affinity |
| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) |
| `X-OmniRoute-Session-Id` | Request | Caller-supplied session/conversation tag (also feeds memory). When present, persisted verbatim to `call_logs.session_tag` for per-session cost attribution (#8249) — never synthesized when absent |
| `Idempotency-Key` | Request | Dedup key (5s window) |
| `X-Request-Id` | Request | Alternative dedup key |
| `x-omniroute-connection` | Request | Pin a single-model request to one provider connection (account) by its id — see [Account pinning per request](#account-pinning-per-request) |
| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) |
| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated |
| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on |
| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute |
| `X-OmniRoute-Request-Id` | Response | Request correlation id (when known) |
| `X-OmniRoute-Version` | Response | OmniRoute build version (always present) |
| `X-OmniRoute-Cost-Saved` | Response | USD the cache avoided on a HIT (cache hits only) |
| `X-OmniRoute-Decision` | Response | Routing trace: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` is the combo strategy, or `single` for a non-combo request) — always present on completion responses |
> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers on;`.
#### Account pinning per request
When a provider has several connections (accounts or keys), OmniRoute normally picks one
through its account-selection strategy. A request can instead pin one specific connection
with the `x-omniroute-connection` header:
```bash
curl http://localhost:20128/v1/chat/completions \
-H "Authorization: Bearer <your OmniRoute API key>" \
-H "Content-Type: application/json" \
-H "x-omniroute-connection: <connection id>" \
-d '{"model": "codex/gpt-5.5", "messages": [{"role": "user", "content": "hi"}]}'
```
- **Where to find the id.** Open the provider page in the dashboard
(**Dashboard → Providers → <provider>**) and click the `xxxxxxxx…` id chip on a connection
row — it copies the full connection id.
- **Which requests honor it.** Single-model requests (`provider/model`) on
`/v1/chat/completions`, `/v1/messages` and `/v1/responses`. Combos ignore the header: pin
an account per combo step through the step's own connection instead.
- **The pin is strict, not a preference.** The pinned connection is used exclusively. A
failure inside the request records the account's cooldown but does **not** rotate to a
sibling account of the same provider.
- **Cooldown and quota release the pin.** While the pinned connection is cooling down,
quota-exhausted or blocked by a quota policy, later requests fall back to the provider's
other connections, exactly like unpinned traffic.
- **Unknown or disabled ids fail.** An id that is not in the provider's active pool (deleted,
deactivated, or belonging to another provider) leaves no eligible account, so the request
fails instead of silently routing elsewhere.
Claude Code sends custom headers through `ANTHROPIC_CUSTOM_HEADERS`. Put it in the `env` block
of `~/.claude/settings.json`, or in a project-level `.claude/settings.json` to pin a different
account per project:
```jsonc
{
"env": {
"ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
"ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
"ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: <connection id>",
},
}
```
Source: `src/sse/handlers/chat.ts` (header read), `src/sse/services/auth.ts` and
`src/sse/services/sessionAffinityPin.ts` (pin release and the missing-from-pool check).
> **Cost telemetry headers:** non-streaming success responses also carry the `X-OmniRoute-*` cost-telemetry set — `X-OmniRoute-Response-Cost` (USD, fixed 10 decimals; `0.0000000000` for free/unpriced), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit`, and `X-OmniRoute-Fallback-Attempts` (only when > 0), plus `X-OmniRoute-Request-Id` and `X-OmniRoute-Version`. These are emitted by chat completions, `/v1/responses`, `/v1/messages`, **and the media endpoints** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations`, and `/v1/moderations` (always cost `0`). Media cost is computed per modality (per-image, per-second, per-character, per search-unit) when pricing is available, otherwise `0` (fail-open).
> **Cache-hit cost semantics:** on a semantic-cache HIT (`X-OmniRoute-Cache-Hit: true`) no upstream call is made, so `X-OmniRoute-Response-Cost` is `0.0000000000` (the **incremental** cost of serving the hit). The original/would-have-been cost is reported separately in `X-OmniRoute-Cost-Saved`. Billing consumers should sum `X-OmniRoute-Response-Cost` (hits cost nothing); cache analytics can aggregate `X-OmniRoute-Cost-Saved`.
## Exclusive Managed Session Leases
Exclusive managed session leasing is an opt-in, client-neutral routing contract: one active owner
holds one eligible OmniRoute connection. It does not lease a model, require OAuth, identify a
particular client, or require a particular provider.
The authenticating API key must have scope `lease:exclusive` and an explicit non-empty
`allowedConnections` list. The database mutation boundary enforces both fields together on key
creation and partial updates.
```http
POST /api/v1/session-leases
Authorization: Bearer <managed-api-key>
Content-Type: application/json
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
{"action":"acquire","model":"glm/glm-4.6"}
```
Successful acquire, renew, and release responses expose timestamps, `state`, and the exact positive
`generation`, but never the selected connection or credentials. Renew and release supply the
generation in the JSON body:
```json
{ "action": "renew", "generation": 1 }
```
```json
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
```
An active lease owner can explicitly request privacy-safe display metadata for its current binding:
```json
{ "action": "status", "generation": 1 }
```
```json
{
"state": "ACTIVE",
"generation": 1,
"acquiredAt": "2026-08-28T12:00:00.000Z",
"renewedAt": "2026-08-28T12:00:30.000Z",
"expiresAt": "2026-08-28T12:02:30.000Z",
"connection": {
"displayName": "Primary Codex",
"provider": "codex"
}
}
```
This opt-in status action is fenced by the opaque owner, authenticated managed API key, and exact
active generation in one database transaction. `displayName` is only the trimmed configured
connection name; it is `null` when no safe configured name exists. OmniRoute never substitutes an
email or generated account identity. The provider value is a non-sensitive display label and never
a generated compatible-provider identifier. Credentials, tokens, cookies, raw connection or API
key ids, owner hashes, fencing secrets, and internal routing data are excluded.
Wrong-key, wrong-owner, stale-generation, missing, expired, released, and invalidated lookups all
return the same `409 LEASE_FENCE_STALE` error without connection metadata. A client that received the capacity-wait response has no active binding to inspect. When routing transitions an active lease,
the same generation remains valid and status atomically returns the new binding, never the old one.
Existing clients remain unchanged because acquire, renew, release, and waiting responses retain
their previous shapes.
This server contract does not change stock OpenAI Codex `/status`. Stock Codex currently reports its
model provider and built-in authentication/account state but does not render arbitrary custom
provider account metadata; a later client integration must call this action and decide how to
display `connection.displayName`.
Every managed inference request then supplies both control headers:
```http
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
```
The exact owner, generation, active connection, and authenticated API key are fenced immediately
before each supported upstream attempt. Replaying owner and generation with another key fails even
when that key permits the same connection. Raw owners are not persisted, logged, retained in the
request snapshot, or forwarded upstream.
Temporary contention returns HTTP `429` with `Retry-After` and:
```json
{
"state": "WAITING_FOR_CAPACITY",
"error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
"reason": "NO_FREE_ELIGIBLE_CONNECTION",
"retryAfter": 30
}
```
This response only means that the ordinary eligible set was non-empty and every free candidate was
held by a foreign active lease. Unsupported models/providers, policy mismatch, cooldown, quota,
health, and other ordinary eligibility failures retain their existing OmniRoute responses.
### `x-omniroute-compression`
Per-request override of the compression plan. Highest precedence — beats the routing-combo
override, the active profile, auto-trigger, and the panel Default. Values:
| Value | Effect |
| ------------- | ------------------------------------------------------------------------------------------- |
| `off` | No compression for this request. |
| `default` | The panel-derived Default profile (ignores the active profile). Lossy engines are left off. |
| `safe` | Dedup and whitespace folding only. |
| `allow-lossy` | Keep the operator plan for this request, including summaries and style rewrites. |
| `engine:<id>` | A single engine when enabled, e.g. `engine:rtk`. Per-request opt-in for that engine. |
| `<combo>` | A named combo, matched by name (case-insensitive) first, then by id. |
Notes:
- Unknown values are ignored (the request is never rejected); resolution falls through to the normal operator precedence.
- If multiple combos share a name, pass the combo **id** for a deterministic match.
- A combo whose name is `off` or `default` cannot be selected by name (those keywords are interpreted first); reference such a combo by its id.
- The master compression switch is a hard gate: when compression is disabled globally, this header cannot enable it.
The applied plan is echoed back in the response header:
```
X-OmniRoute-Compression: <mode>; source=<source>
```
where `<source>` is one of `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, or `off`.
---
## Embeddings
```bash
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "nebius/Qwen/Qwen3-Embedding-8B",
"input": "The food was delicious"
}
```
Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.
Catalog ids are `provider/model` (example: `jina-ai/jina-embeddings-v5-omni-small`). Bare Jina model ids that appear in the registry (for example `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) also resolve. Jina embed/rerank/classify/segment use dashboard `jina-ai` credentials first; `JINA_AI_API_KEY` is a fallback only when no dashboard key exists. The `jina-reader` card is Reader / `r.jina.ai` only (`POST /v1/web/fetch`) and never serves embeddings or rerank.
Registry models that advertise multimodal support also accept up to 32 provider-neutral structured
items. Media item types are `text`, `image`, `audio`, `video`, and `document`. Their media `source`
is either `{"type":"url","url":"https://..."}` or
`{"type":"base64","data":"...","media_type":"..."}`.
Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`,
and the family alias `jina-ai/jina-embeddings-v5-omni` → omni-small) also accepts Jina's native
EmbeddingsV5Request docs and **forwards them intact** to `https://api.jina.ai/v1/embeddings`:
```json
{
"model": "jina-ai/jina-embeddings-v5-omni-small",
"task": "retrieval.query",
"normalized": true,
"input": [
{ "text": "a red bicycle" },
{ "image": "https://example.com/bike.png" },
{ "content": [{ "text": "caption" }, { "image": "data:image/png;base64,..." }] }
]
}
```
Native `{ image | audio | video | pdf }` values may be a public HTTPS URL, a `data:` URI, or raw
base64. OmniRoute does not stringify those objects or fetch native image URLs — Jina retrieves
public media itself. Extra Jina fields (`task`, `normalized`, `truncate`, `embedding_type`) are
forwarded. Text-only Jina SKUs still reject non-text docs.
Security and transport bounds:
- Remote media URLs must be public HTTPS. Canonical `{type,source:url}` items are fetched
server-side (redirect revalidation, timeout, size limits, public DNS, connection pinning) and
inlined before the provider call. Jina-native `{image:"https://..."}` items are forwarded as-is
after the same public-HTTPS check; Jina fetches the URL.
- Inline base64 media is limited to 8 MiB decoded per item and 16 MiB decoded across the request.
Provider translation (canonical items are never forwarded unchanged):
- Jina multimodal models: each top-level item becomes one modality-keyed object
(`text` / `image` / `audio` / `video` / `pdf`) using data URIs for inline media; one vector per
top-level item.
- Gemini Embedding 2 family: one top-level array becomes a single native
`models/{model}:embedContent` request with `content.parts` (`text` or `inline_data`).
- llama.cpp (`llama-cpp/<model>`, any model the local server loaded): canonical `text` items
become plain strings, and `image` / `audio` / `video` become one
`{"content": [part]}` object each, using llama-server's chat content parts (`image_url`,
`input_audio` with format `wav` / `mp3` / `flac`, `input_video`) with inline data; one vector
per top-level item. The server must run with `--embedding --mmproj …`; without a projector it
rejects media itself. `document` is not supported.
- Unknown/dynamic models without explicit modality metadata reject structured input with HTTP 400.
```json
{
"model": "jina-ai/jina-embeddings-v5-omni-small",
"input": [
{ "type": "text", "text": "A red bicycle" },
{
"type": "image",
"source": { "type": "url", "url": "https://example.com/bicycle.png" }
}
],
"dimensions": 512,
"encoding_format": "float"
}
```
Unsupported model/modality combinations return HTTP 400 rather than coercing the item. Non-input
extension fields on legacy string/token requests continue to pass through unchanged.
```bash
# List all embedding models
GET /v1/embeddings
```
---
## Image Generation
```bash
POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "openai/gpt-image-2",
"prompt": "A beautiful sunset over mountains",
"size": "1024x1024"
}
```
Available providers include OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, **ZenMux**, SD WebUI (local), ComfyUI (local).
`n` returns `n` images in `data[]`. Providers whose upstream API returns one image per call
(Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik,
NVIDIA NIM, Cloudflare Workers AI) get `n` separate upstream calls, at most 4 in flight. A
fixed `seed` is offset by call index (`seed`, `seed + 1`, …), so the images differ but stay
reproducible. `n` is capped at 10. The request fails as a whole if any call fails. The list
of fan-out formats is `SINGLE_IMAGE_FANOUT_FORMATS` in
`open-sse/handlers/imageGeneration/fanOut.ts`.
ZenMux reuses the existing API-key connection and accepts `zenmux/` or `zm/` prefixes:
- `zenmux/openai/gpt-image-2` uses ZenMux's OpenAI Images API. Options include `size`,
`quality`, `n`, `output_format`, `output_compression`, `background`, and `response_format`.
- Other publishers, such as `zm/meta/muse-image-1.0`, use ZenMux's Vertex AI `:predict`
endpoint. `n` maps to `sampleCount`, `aspect_ratio` to `aspectRatio`, and `image_size`
(`1K`, `2K`, `4K`) to `sampleImageSize`. A pixel `size` supplies only an aspect ratio,
not guaranteed pixel dimensions. Supported ratios, resolutions, and counts vary by model.
- `zm/inclusionai/ming-image-0.1-design` chooses its own dimensions. Omit `size`,
`aspect_ratio`, and `image_size`; explicit values return HTTP 400. PNG, JPEG, and WebP
can be requested with `output_format`.
This integration supports text-to-image generation, not reference-image editing. Vertex
output is normalized to `data[].b64_json`; `response_format: "url"` returns an upstream
HTTPS URL or a base64 data URL when only image bytes are available. Empty/filtered outputs
return an error rather than an empty success. Model access depends on the ZenMux account.
See [ZenMux's Vertex API](https://docs.zenmux.ai/api/vertexai/generate-images) and
[OpenAI Images API](https://docs.zenmux.ai/api/openai/generate-an-image).
A Microsoft 365 Copilot sign-in connection serves `copilot-m365-web/m365-copilot-image`
through Copilot's built-in image tool: one Copilot turn per image (`n` 1–4), `size` steering
only the orientation, and images returned inline (`b64_json`, or a data URL for
`response_format: "url"`). See [Microsoft 365 Copilot](../providers/COPILOT-M365.md#image-generation).
```bash
# List all image models
GET /v1/images/generations
```
---
## Document OCR
```bash
POST /v1/ocr
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "mistral/mistral-ocr-latest",
"document": {
"type": "document_url",
"document_url": "https://example.com/invoice.pdf"
}
}
```
`model` selects the OCR provider via a `provider/model` prefix; a bare model id (e.g.
`mistral-ocr-latest`) resolves to its registered provider, and an omitted `model` defaults to
Mistral (`mistral-ocr-latest`). Registered providers (`open-sse/config/ocrRegistry.ts`):
| Provider id | Model id | `model` value | Notes |
| ----------------------------- | -------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (or bare `mistral-ocr-latest`) | Synchronous — the response is returned directly from the single upstream call. |
| `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Asynchronous upstream (`analyze` + poll) — see below. |
| `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Synchronous, via Vertex AI's `openapi/chat/completions` partner endpoint — see below for auth/URL. |
All three providers respond in the same Mistral-shaped body:
```json
{
"pages": [{ "index": 0, "markdown": "# Extracted text..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
```
### Azure Document Intelligence poll flow
Azure Document Intelligence's `analyze` API is asynchronous: the initial request returns an
`Operation-Location` header instead of a body, and the result must be polled for. The handler
(`open-sse/handlers/ocr.ts`) polls that URL every second for up to 30 attempts, fails fast (does
not keep polling) on a non-`ok` poll response or a `"failed"` status, and returns `504` if the
operation is still running after the attempt budget is exhausted. The final Azure response is
normalized into the same `pages`/`markdown` shape used by Mistral before being returned to the
caller, so client code does not need to special-case the provider.
### Vertex AI DeepSeek OCR auth and endpoint resolution
`vertex-deepseek-ocr` reuses the same Vertex AI authentication OmniRoute already supports for
chat/image traffic (`open-sse/executors/vertex.ts`): the connection's API key is either a
Service Account JSON credential (exchanged for a short-lived OAuth access token via the JWT-bearer
flow) or an already-minted OAuth access token used as-is. The upstream endpoint URL is Vertex's
generic `openapi/chat/completions` partner endpoint, built from the connection's project and
region — an explicit `providerSpecificData.project`/`providerSpecificData.region` always wins;
otherwise the project is derived from the Service Account JSON's `project_id` and the region
defaults to `us-central1`. Both resolutions happen in `open-sse/handlers/ocr.ts`
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`), consumed by
`src/app/api/v1/ocr/route.ts` before dispatching to `handleOcr`.
---
## List Models
```bash
GET /v1/models
Authorization: Bearer your-api-key
→ Returns all chat, embedding, and image models + combos in OpenAI format
```
### Model prices (`pricing`)
An entry carries a `pricing` object when OmniRoute knows the model's price. The price comes
from the pricing table that cost accounting uses: built-in defaults, synced prices, and
overrides set through `/api/pricing`. These are list prices, so subscription providers also
show a per-token price.
```json
"pricing": {
"prompt": "0.000005",
"completion": "0.000025",
"input_cache_read": "0.0000005",
"input_cache_write": "0.00000625",
"input": 5,
"output": 25,
"cached": 0.5,
"cache_creation": 6.25
}
```
| Fields | Unit | Notes |
| --------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `prompt`, `completion`, `input_cache_read`, `input_cache_write` | USD per token, decimal string | OpenRouter-compatible, never in exponent notation. The two cache fields appear only when there is a cache price. |
| `input`, `output`, `cached`, `cache_creation` | USD per 1M tokens, number | Fields from earlier catalog versions, kept for existing clients. `reasoning` and `long_context` also appear when the pricing row has them. |
- **Combos** carry the price of their first visible target. Built-in `auto/*` combos pick a
target at request time, so they have no `pricing`.
- **Free models** show `"0"` (and `0`) when their price is zero. A model with no pricing row
also shows `"0"` when the catalog marks it free (`free: true`) or the built-in free-model
catalog lists it.
- **Unknown price:** the entry has no `pricing` key.
- **Credit-metered providers** (such as Kiro) bill per request rather than per token. Their
entries keep the numeric per-1M fields they had before and carry no per-token string fields.
- **Variants** (reasoning-effort ids, no-thinking aliases, discovery and gateway mirrors)
copy the price of the model they route to.
- The fields carry base rates only. Long-context tiers (the numeric `long_context` field) and
service-tier multipliers (for example Codex fast or flex) do not change `prompt` or
`completion`.
- The object is the same for every authentication style, including an Anthropic-style
request with `x-api-key` and `anthropic-version` (the response stays `{ "object": "list",
"data": [...] }`). Implementation: `src/app/api/v1/models/catalogPricing.ts`.
### Model id prefixes (`?prefix=`)
Most models are advertised under a **provider prefix**. Which prefix you get is controlled by
the `MODELS_CATALOG_PREFIX_MODE` feature flag, and can be overridden **per request** with a
query parameter — useful for a client that wants a clean list without changing the server-wide
setting for everyone else:
```bash
GET /v1/models?prefix=alias # one id per model — the short alias prefix
GET /v1/models?prefix=dual # both forms (server default)
GET /v1/models?prefix=canonical # only the full provider-id prefix
```
| Mode | Emits | Notes |
| ----------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual` | `cc/claude-sonnet-4-6` **and** `claude/claude-sonnet-4-6` | **Default.** Both ids route to the same model; kept so client configs that hardcoded either form keep working. Roughly doubles the catalog. |
| `alias` | `cc/claude-sonnet-4-6` | One entry per model. Providers without a distinct alias still emit their entry, so nothing is lost. |
| `canonical` | `claude/claude-sonnet-4-6` | One entry per model under the full provider-id prefix. Providers without a distinct alias (e.g. `antigravity/…`, `agy/…`) emit their single id here too, so nothing is lost. |
A `dual`-mode mirror can also be recognised without the query parameter: it carries a `parent`
field pointing at the primary id.
Clients that render a model picker should request `?prefix=alias` — this is what the
[OmniCopilot VS Code extension](../guides/VSCODE-COPILOT.md) does.
### Discovery filters (`?capability=`, `?min_context=`, `?kind=`, `?q=`)
`GET /v1/models` accepts opt-in discovery filters. Without any of them the response is
unchanged. They narrow the catalog the caller already sees (API-key permissions apply first),
and they run before the OpenAI-style `limit` / `after` paging:
```bash
GET /v1/models?capability=vision&capability=tool_calling # every listed capability must be true
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding # catalog `type`; rows without one are `chat`
GET /v1/models?q=sonnet&limit=10 # case-insensitive match on id or name
```
| Param | Values |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `capability` | `attachment`, `reasoning`, `structured_output`, `temperature`, `thinking`, `tool_calling`, `vision` |
| `min_context` | non-negative integer, compared with `context_length` |
| `kind` | `chat`, `audio`, `embedding`, `image`, `moderation`, `music`, `rerank`, `video` |
| `q` | 1–200 characters |
An unknown value, or a `min_context` that is not a non-negative integer (for example `1.5`),
returns HTTP `400` and the message lists the valid values. Implementation:
`src/app/api/v1/models/catalogFilters.ts`.
### Model shortlist (`POST /v1/models/query`)
`POST /v1/models/query` returns a short, deterministic list from the same catalog, with the same
auth and per-key visibility as `GET /v1/models`:
```bash
POST /v1/models/query
Authorization: Bearer your-api-key
Content-Type: application/json
{ "capabilities": ["vision", "tool_calling"], "min_context": 128000, "max_output": 16000,
"kind": "chat", "q": "gpt", "owned_by": "openai", "exclude": ["openai/gpt-4o"], "limit": 5 }
→ { "object": "list", "data": [ ...models ] }
```
Every field is optional. `capabilities` and `exclude` take an array or a comma-separated string;
`max_output` compares with `max_output_tokens`. Results are sorted by `owned_by`, then `id`.
`limit` defaults to `20` and values above `100` are capped at `100`. Invalid JSON, an unknown
field or an invalid value returns HTTP `400`.
### Individually hidden chat models
A model marked **Hidden** on its provider page is excluded from the catalog and rejected
with HTTP `404` / `model_not_found` when requested explicitly. The check uses the resolved
provider and model, including provider aliases, compatible-provider node prefixes, and
connection defaults. A combo skips hidden targets and can use a visible sibling; when no
executable target remains it returns the same error code. Unhiding takes effect on the next
request. Image-only visibility overrides do not hide the chat model with the same ID.
This individual model setting is separate from the
[model exposure allow/deny lists](../routing/MODEL_EXPOSURE_LIST.md), which filter catalog
advertisement and auto-routing candidates while retaining explicit dispatch. API-key model
permissions continue to apply independently. The default catalog prefix mode remains `dual`.
### No-thinking model variants
For thinking-capable Claude models, `/v1/models` also advertises a **no-thinking** variant whose id is prefixed with `claude-3-omniroute-no-thinking/`:
```
claude-3-omniroute-no-thinking/<provider>/<model>
```
Selecting this id (e.g. in a Claude Code config that always attaches a `thinking` block) resolves back to the real `<provider>/<model>` with reasoning suppressed — `thinking:{type:"disabled"}` on the `/v1/messages` path, or the `reasoning`/`reasoning_effort` fields dropped on the `/v1/chat/completions` path. The variant is only listed for Claude-family models that support thinking **and** honor `disabled` (so e.g. adaptive-only models that reject `disabled` are excluded). Operators can force the variant on or off per model via `ModelSpec.noThinkingAlias`.
---
## Provider Plugin Manifest
```bash
GET /api/v1/provider-plugin-manifest
```
Returns the JSON-safe provider plugin manifest used by Bifrost, CLIProxyAPI, and
future sidecar routers. The response is generated from the TypeScript provider
registry and intentionally excludes OAuth client secrets, runtime environment
resolution, executor functions, request headers, and account data.
Use this endpoint when a sidecar runs out-of-process and cannot import
`open-sse/config/providerPluginManifestRegistry.ts` directly.
---
## ElevenLabs audio generation
Configure an `elevenlabs` provider connection in OmniRoute with your ElevenLabs API key.
Clients authenticate with their **OmniRoute** key (`Authorization: Bearer $OMNIROUTE_API_KEY`);
the gateway supplies the stored provider key as `xi-api-key`. Never send an ElevenLabs key
as the gateway bearer token.
| Method | Path | Response | API key endpoint category |
| ------ | --------------------------- | ------------------------------------------- | ------------------------- |
| POST | `/v1/sound-generation` | Native audio bytes | `elevenlabs` |
| POST | `/v1/music` | Native audio bytes | `music` |
| POST | `/v1/music/stream` | Streaming audio bytes | `music` |
| POST | `/v1/music/detailed` | Native multipart audio and composition plan | `music` |
| POST | `/v1/music/detailed/stream` | Native SSE metadata and audio chunks | `music` |
| POST | `/v1/music/plan` | JSON composition plan | `music` |
These endpoints complement the existing `/v1/audio/speech`, `/v1/audio/transcriptions`,
`/v1/voices`, `/v1/text-to-speech/{voiceId}` and `/v1/speech-to-text` routes. Native JSON fields
and query parameters such as `output_format` and `enable_logging` are preserved.
`/v1/music/detailed` responses retain their multipart boundaries; parse them as multipart.
`/v1/music/detailed/stream` returns `text/event-stream` with composition metadata and
base64 audio chunks in SSE events. All six routes support CORS preflight.
```bash
export OMNIROUTE_BASE_URL="http://localhost:20128"
export OMNIROUTE_API_KEY="your-omniroute-api-key"
# A short sound effect. Duration: 0.5 to 30 seconds.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/sound-generation?output_format=mp3_44100_128" \
-H "Authorization: Bearer $OMNIROUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"A single soft bell chime","duration_seconds":1,"model_id":"eleven_text_to_sound_v2"}' \
--output effect.mp3
# Music duration is expressed in milliseconds: 3000 to 600000.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music?output_format=mp3_44100_128" \
-H "Authorization: Bearer $OMNIROUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"Gentle instrumental piano","music_length_ms":10000,"force_instrumental":true,"model_id":"music_v1"}' \
--output music.mp3
```
Use `/v1/music/stream` with the same JSON body for incremental audio delivery. Composition
accepts exactly one of `prompt` or `composition_plan`; `/v1/music/plan` requires `prompt`
and optionally accepts `source_composition_plan`. The native schemas preserve additional
provider fields so composition-plan versions and fine-tuning options reach ElevenLabs.
The unified `/v1/music/generations` endpoint also accepts `elevenlabs/music_v1`,
`elevenlabs/music_v2` and `elevenlabs/music_v2_5`. With an active ElevenLabs connection,
these models are exposed by the music catalog. This endpoint returns
`{"created":...,"data":[{"b64_json":"...","format":"mp3"}]}`. Its `duration` field is in
seconds and maps to `music_length_ms`; an explicit `music_length_ms` takes precedence.
`instrumental` maps to `force_instrumental`, with the native field taking precedence.
Use the native streaming endpoints for streaming and the native composition endpoint
for requests driven only by a composition plan.
```bash
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music/generations" \
-H "Authorization: Bearer $OMNIROUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"elevenlabs/music_v1","prompt":"Gentle instrumental piano","duration":10,"instrumental":true}'
```
Endpoint, model, budget and connection restrictions apply before an upstream call. Native
routes return upstream status codes and error bodies unchanged, including `402` for a plan
restriction and `429` for a quota limit. The `character-cost`, `song-id`, `request-id` and `retry-after`
headers are preserved when present. A free credit balance does not guarantee access to every
music model, output format or API feature: ElevenLabs decides entitlement for each request.
The unified endpoint preserves error status codes in OmniRoute's normalized error envelope.
Upstream contracts: [sound effects](https://elevenlabs.io/docs/api-reference/text-to-sound-effects/convert),
[music composition](https://elevenlabs.io/docs/api-reference/music/compose) and
[streaming music details](https://elevenlabs.io/docs/api-reference/music/compose-detailed-stream).
---
## Compatibility Endpoints
| Method | Path | Format |
| ------ | ----------------------------------------- | ---------------------------------- |
| POST | `/v1/chat/completions` | OpenAI |
| POST | `/v1/messages` | Anthropic |
| POST | `/v1/responses` | OpenAI Responses |
| POST | `/v1/embeddings` | OpenAI |
| POST | `/v1/images/generations` | OpenAI Images |
| POST | `/v1/images/edits` | OpenAI Images (edit/inpaint) |
| POST | `/v1/videos/generations` | OpenAI-style video generation |
| POST | `/v1/music/generations` | OpenAI-style music generation |
| POST | `/v1/audio/transcriptions` | OpenAI Audio (STT) |
| POST | `/v1/audio/speech` | OpenAI TTS (returns audio body) |
| POST | `/v1/rerank` | Cohere/Voyage-style rerank |
| POST | `/v1/classify` | Jina classify (`api.jina.ai`) |
| POST | `/v1/segment` | Jina segmenter (`segment.jina.ai`) |
| POST | `/v1/moderations` | OpenAI Moderations |
| GET | `/v1/models` | OpenAI |
| POST | `/v1/models/query` | Filtered model shortlist |
| POST | `/v1/messages/count_tokens` | Anthropic |
| GET | `/v1beta/models` | Gemini |
| POST | `/v1beta/models/{...path}` | Gemini generateContent |
| POST | `/v1/api/chat` | Ollama |
| GET | `/api/v1/vscode/{token}/` | OpenAI catalog alias |
| GET | `/api/v1/vscode/{token}/models` | OpenAI models alias |
| POST | `/api/v1/vscode/{token}/chat/completions` | OpenAI tokenized alias |
| POST | `/api/v1/vscode/{token}/responses` | OpenAI Responses tokenized alias |
| POST | `/api/v1/vscode/{token}/api/chat` | Ollama tokenized alias |
| GET | `/api/v1/vscode/{token}/api/tags` | Ollama tags tokenized alias |
All POST routes follow the same shape: `Bearer your-api-key` + Zod-validated JSON body (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, etc., see `src/shared/validation/schemas.ts`). 4xx is returned on schema failure.
For clients that cannot attach `Authorization: Bearer ...`, OmniRoute also accepts API keys in the URL via either query-string compatibility (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) or the dedicated `/api/v1/vscode/{token}/...` endpoints documented below.
```bash
# Rerank (cloud registry provider, or an OpenAI-compatible provider node as "<prefix>/<model>")
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
# Jina classify (Foundation API credentials)
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
# Jina segmenter
POST /v1/segment { "content": "...", "return_chunks": true }
# Jina search (s.jina.ai; provider aliases: jina-search, jina-ai, jina)
POST /v1/search { "query": "...", "provider": "jina-search" }
# Moderations
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
# TTS — returns audio/mpeg (or requested format) body
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
# Soniox TTS requires a language and a voice: `language` defaults to "en"; a missing
# voice or an OpenAI stock voice name (alloy, nova, …) becomes "Adrian"
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }
# Image edit (multipart)
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
# Video / music generation (provider-prefixed model id)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations { "model": "kie/suno-v4.0", "prompt": "..." }
```
> **Rerank provider nodes:** `POST /v1/rerank` also routes to OpenAI-compatible provider nodes
> (oMLX, vLLM, Infinity, TEI behind a gateway, …) addressed as `<node-prefix>/<model>`. Loopback
> nodes (`localhost`, `127.0.0.1`, `172.16.0.0/12`) are always eligible, and so are hostnames the
> operator lists in `OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS` (e.g. a Docker/Compose service name such
> as `http://reranker:8080/v1`; these are called directly, never through `HTTP(S)_PROXY` or a
> connection's pinned proxy). Nodes on any other
> host — a LAN box or Tailscale peer — are eligible only when the operator enables the
> `RERANK_REMOTE_PROVIDER_NODES` feature flag **and** the node's base URL passes the provider
> outbound URL policy (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`).
> The memory engine's rerank step calls this route over
> loopback, so the same rule governs `rerankProviderModel` in the Memory settings.
>
> **Local server shapes:** the node is called at `<base>/v1/rerank` and, on 404, at `<base>/rerank`
> (Infinity, TEI). The upstream body carries both the Cohere/OpenAI spelling (`documents`,
> `return_documents`) and the TEI spelling (`texts`, `return_text`), and the upstream response is
> normalized to the Cohere envelope: TEI's bare `[{index, score, text}]`, `{results: [{index, score}]}`
> from thin gateways, and Voyage-style `{data: [...]}` all come back to the client as
> `{results: [{index, relevance_score, document?}]}`, sorted by score and capped at `top_n`.
> **Provider-node discovery:** models on an OpenAI-compatible provider node appear in `GET /v1/models`
> under the node prefix. Rows that carry no endpoint metadata (typical for local `/v1/models` listings)
> inherit the node's `apiType`, so an `embeddings` node's models are `type: "embedding"` and a
> `rerank` node's models are `type: "rerank"` instead of defaulting to chat; an explicit
> `supportedEndpoints` on a synced or manually added row still takes precedence.
### Dedicated Provider Routes
```bash
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
```
The provider prefix is auto-added if missing. Mismatched models return `400`.
---
## Files API
OpenAI-compatible files endpoint for batch input/output and file-purpose uploads.
| Method | Path | Description |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| POST | `/v1/files` | Upload a file (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — 512 MiB max |
| GET | `/v1/files` | List files for the authenticated API key |
| GET | `/v1/files/[id]` | Retrieve a file's metadata |
| DELETE | `/v1/files/[id]` | Delete a file |
| GET | `/v1/files/[id]/content` | Stream the raw file body back |
**Auth:** Bearer API key — files are scoped per-API-key via `getApiKeyRequestScope`. A key
sees, downloads and deletes its own files only; a dashboard session without a key reads the
whole instance; a file with no owner (anonymous or dashboard-session upload) is denied to every
non-session caller. `GET /v1/files` rejects an anonymous caller — and a presented key that does
not resolve — with `401` even when `REQUIRE_API_KEY=false`, instead of listing every tenant's
files (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).
---
## Batches API
OpenAI-compatible batch processing.
| Method | Path | Description |
| ------ | ------------------------- | --------------------------------------------------------------------------------------------------------- |
| POST | `/v1/batches` | Create batch — body validated by `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) |
| GET | `/v1/batches` | List batches |
| GET | `/v1/batches/[id]` | Retrieve batch status + `request_counts` |
| DELETE | `/v1/batches/[id]` | Delete a finished/failed batch |
| POST | `/v1/batches/[id]/cancel` | Cancel an in-progress batch |
**Auth:** Bearer API key. Batches are scoped per-API-key under the same three-way rule as
files: own key only, dashboard session instance-wide, null-owner records denied to every
non-session caller (retrieve, delete, cancel, and the `input_file_id` check on create).
`GET /v1/batches` rejects an anonymous caller with `401` even when `REQUIRE_API_KEY=false`.
---
## Search API
Web/search provider abstraction (Tavily, Brave, Exa, Serper, etc.).
| Method | Path | Description |
| ------ | ---------------------- | ------------------------------------------------------------------------------------ |
| GET | `/v1/search` | List configured search providers + capabilities |
| POST | `/v1/search` | Run a search query — body validated by `v1SearchSchema`, supports caching/coalescing |
| GET | `/v1/search/analytics` | Per-provider hit/latency/cache stats |
**Auth:** Bearer API key (`extractApiKey` + `isValidApiKey`). Search policy enforced via `enforceApiKeyPolicy`.
### Named search/fetch combinations
Both `POST /v1/search` and `POST /v1/web/fetch` accept `model` as a saved combo name.
Use either `model` or an explicit `provider`; sending both returns `400`.
Without either field, the existing automatic provider selection remains unchanged.
Both the Combo Builder and its Add Model catalog expose native web-operation entries
for connected providers, even when they have no LLM model list. Serper shows **Web search**;
Tavily shows **Web search / Page extraction**, and fetch-only providers show **Page extraction**.
Choose the entry and account as usual. A single Tavily entry serves both web endpoints;
these operation entries are not added to chat-only client selectors or chat model probes.
For example, create a **priority** combo named `shared-free` with these ordered targets:
1. `openai/gpt-4o`
2. `tavily-search/web`
3. `serper-search/web`
4. `jina-reader/fetch`
Then use the same name on each surface:
```json
{ "model": "shared-free", "query": "Open source speech recognition", "max_results": 5 }
```
```json
{ "model": "shared-free", "url": "https://example.com", "format": "markdown" }
```
Search considers Tavily then Serper; fetch considers Tavily then Jina Reader;
chat skips the dedicated search/fetch providers and considers OpenAI. Compatibility
comes from the search/fetch executor registries, not from words in a model name.
Filtering precedes credential selection and dispatch, and never edits the saved combo.
Non-chat capability routes support `priority`, `fill-first`, `round-robin`, `weighted`,
`random`, `strict-random`, `least-used`, and `p2c`. Chat-only synthesis strategies such as
`fusion`, `pipeline`, and `context-relay` are rejected on non-chat routes rather than being
silently applied to search or generated media.
The existing combo engine handles ordered fallback, including upstream quota failures,
and retains step IDs, account pins, per-step account allowlists, nested references,
caller connection/quota scopes and combo access policy. Results retain their native
search/fetch schema, including the actual provider; `X-OmniRoute-Combo-Trace` identifies
the routing decision. Unknown combos return `404`; inactive combos and combinations
with no compatible targets return `400`.
Each combo attempt uses one explicit provider. It cannot invoke the native automatic
provider pool behind the combo's back. Explicit-provider requests retain their existing
single-provider behavior. Direct chat requests targeting dedicated search/fetch providers
return an actionable JSON `400` instead of falling through to an OpenAI-style executor.
### Capability-specific combo routes
Saved combos may contain a `routes` object whose keys are API capabilities. Every route owns
its target list, strategy, and runtime config. The top-level `models`, `strategy`, and `config`
remain the legacy-compatible Chat plan; old combos without `routes` continue to work unchanged.
Supported route keys are `chat`, `search`, `web-fetch`, `embeddings`, `rerank`, `images`,
`image-edits`, `videos`, `music`, `ocr`, `audio-speech`, `audio-transcriptions`,
`audio-translations`, and `audio-generation`. Endpoint projection happens before credential
selection, scoring, or dispatch. Nested combo references select the child combo's route for the
same capability.
`POST /v1/music/generations` and `POST /v1/ocr` accept a combo name in `model`. The native
ElevenLabs-compatible `POST /v1/music` also accepts a combo name in `model_id`, but every usable
target on that native endpoint must be an ElevenLabs music model so its binary response contract
is preserved. `POST /v1/sound-generation` accepts an `audio-generation` combo in `model_id` under
the same native-binary constraint. Use `/v1/music/generations` for heterogeneous music providers.
**Auto-select:** without `provider`, the cheapest provider with a configured connection runs
first and the next cheapest is the failover. Free last-resort providers (`duckduckgo-free`) are
used only when nothing else is configured. A self-hosted SearXNG counts as configured once its
connection stores a real `baseUrl` (not the catalog default `http://localhost:8888/search`): it
then ranks as a $0 provider ahead of keyed ones, with the cheapest keyed provider as failover,
including when SearXNG answers 400, 401, 403 or 404. A `baseUrl` that is not a valid `http(s)` URL
or that points at a cloud-metadata address does not count. A SearXNG connection that stores a token
ranks this way only over `https://` or loopback `http://`. Over remote plain `http://` it is never
a failover and stays a last resort, used only when no other provider is configured or when
requested by name, so it does send the token in cleartext in those two cases.
### Exa and Tavily `provider_options`
Exa and Tavily read provider-specific fields from a namespaced bag:
`provider_options.exa` (or `provider_options["exa-search"]`) and `provider_options.tavily`
(or `provider_options["tavily-search"]`). Only the keys below are forwarded. Each one is
checked against its own Zod schema in `open-sse/handlers/search/providerOptionsPassthrough.ts`,
and a key with the wrong type is dropped. Any other key is ignored, including auth, base URL,
`stream` and `outputSchema`. The flat keys used by other providers (`cx`, `depth`, ...) work
as before.
| Provider | Top-level fields | Nested |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Exa | `type`, `category`, `userLocation`, `moderation`, `additionalQueries`, `objective`, `systemPrompt`, `compliance` (flat primitives), `startPublishedDate`, `endPublishedDate` | `contents.{text, highlights, summary, extras, livecrawlTimeout, maxAgeHours}` merged over the default `{ text: true, highlights: true }` |
| Tavily | `search_depth`, `chunks_per_source`, `time_range`, `start_date`, `end_date`, `include_published_date`, `filter_by_published_date`, `include_answer`, `include_raw_content`, `include_images`, `include_image_descriptions`, `include_favicon`, `include_domains_mode`, `language`, `filter_by_language`, `auto_parameters`, `exact_match`, `include_usage`, `safe_search` | — |
The generic fields always win: `query`, `max_results`, `filters` (domains), `country` and the
topic derived from `search_type`. On Exa, `search_type: "news"` keeps `category: "news"`.
Tavily also accepts `search_type: "finance"` (`topic: "finance"`).
Firecrawl search cost is recorded per started block of 10 returned results, at $0.002 (2
credits) a block and at least one block per call
([Firecrawl billing](https://docs.firecrawl.dev/billing)): 11 results cost $0.004.
The generic `time_range` now reaches both providers: Exa gets `startPublishedDate` (ISO
timestamp) and Tavily gets `start_date` (`YYYY-MM-DD`). An explicit date in `provider_options`
overrides the mapped one.
Exa results keep `id`, `highlights` (every highlight, not only the first one used as the
`snippet`), `highlight_scores`, `summary`, `subpages`, `entities` and `extras` in
`provider_raw`. Tavily results keep `images` and `favicon`.
Linkup search cost is recorded at $0.005 for `depth` `fast` and `standard` and $0.05 for
`deep` ([Linkup pricing](https://docs.linkup.so/pages/documentation/development/pricing)),
whether `depth` comes from `provider_options` or the connection's settings.
Exa `type: "lite"` (Exa 3.0) accepts a smaller set of fields and rejects the whole request
when any other field is set. For lite, `additionalQueries`, `systemPrompt` and every
`contents` key except `text` and `highlights` are dropped before the call. The deprecated
`subpages`, `subpageTarget`, `highlights.numSentences` and `highlights.highlightsPerUrl` are no
longer forwarded.
Cost accounting is the flat registry `costPerQuery`, except for Exa, which follows Exa's
own pricing: $0.007 per call for `auto` (and the legacy `fast`) or $0.004 for `lite` (and the
legacy `instant`), covering 10 results; $0.001 for each further result; and $0.001 per
returned result when `contents.summary` is set. Tavily is recorded at 1 credit ($0.008) for
`search_depth` `basic`, `fast` and `ultra-fast`, and 2 credits ($0.016) for `advanced`
([Tavily API credits](https://docs.tavily.com/documentation/api-credits)). A call with
`auto_parameters: true` that Tavily upgrades to advanced is still recorded at 1 credit.
---
## Web Fetch API
Extract content from a URL via a configured web-fetch provider (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract, Keenable Fetch).
Parallel Extract (`parallel-search`, same API key as Parallel Search) returns Markdown
only — any other `format` is a `400` — and caps content at 100,000 characters. When
the target page itself cannot be extracted, the upstream reports it inside an HTTP 200;
OmniRoute surfaces that as a `422` with a fixed message.
Keenable Fetch (`keenable-search`) also returns Markdown only (any other `format` is a
`400`) and caps content at 100,000 characters. It works without a key: an explicit
`provider: "keenable-search"` request with no connection uses Keenable's keyless endpoint
(per-IP rate limits). A configured key only lifts those limits; auto-select uses Keenable
only when a key is configured.
| Method | Path | Description |
| ------ | --------------- | --------------------------------------------------------- |
| POST | `/v1/web/fetch` | Fetch/scrape a URL — body validated by `v1WebFetchSchema` |
**Auth:** Bearer API key (`extractApiKey` + `isValidApiKey`). Policy enforced via `enforceApiKeyPolicy`.
Named combinations use the [`model` routing contract](#named-searchfetch-combinations)
above, preserving fetch-specific options and responses.
**Quota-aware fallback (#8297):** when neither `provider` nor `model` is given, the pool
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search` →
`parallel-search` → `keenable-search`) is
walked in fixed
priority order (fill-first) — a rate-limited-but-configured provider is skipped
instead of short-circuiting the request, and a retryable/quota upstream failure
(HTTP 429 always; 402/403 for Firecrawl/Tavily/TinyFish quota-style free tiers —
not for Jina Reader, and never for a plain 400 bad request) falls through to the
next untried credentialed provider at request time. When every provider in the
pool is exhausted, the endpoint returns a single `429` (with a `Retry-After`
header) instead of the previous generic `400`. When an explicit `provider` is
requested, there is **no** silent fallback — a rate-limited or failing explicit
provider surfaces its own error (`429` if rate-limited, otherwise the upstream
status).
---
## WebSocket Streaming
```bash
GET /v1/ws?handshake=1
```
Validates a WebSocket upgrade handshake and returns the wire protocol example messages (`request`, `cancel`). Actual WS frames are handled by the bundled WS server outside the Next.js route table.
**Auth:** Bearer API key during handshake.
### Responses API over WebSocket (codex only)
```bash
# Same host:port as the HTTP API (default 20128); upgrade the connection:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (or: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")
# First frame MUST be response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```
A Responses-API-over-WebSocket proxy is wired **exclusively to `codex`** (ChatGPT
backend). It listens on the same port as the API/dashboard at paths `/v1/responses`,
`/responses`, and `/api/v1/responses`. On the first `response.create` frame it
authenticates + prepares via the internal `codex-responses-ws` bridge, selects a
codex OAuth connection, and tunnels to `wss://chatgpt.com/backend-api/codex/responses`
via the `wreq-js` transport. **Non-codex models are rejected** (`codex_ws_provider_required`).
For quota-share routing use `model: "qtSd/<group>/codex/<model>"`. Implemented in
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.
**Auth:** Bearer API key during handshake. The bundled HTTP server (`server-ws.mjs`)
must be the active entrypoint (it is, by default, when `app/server-ws.mjs` exists).
#### Model id: use the bare ChatGPT id (no `codex/` prefix)
The OpenAI **Codex CLI** validates the model name client-side when
`supports_websockets = true` and **rejects provider-prefixed ids** like
`codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`). Send the **bare** id (e.g. `gpt-5.5`). OmniRoute's bridge is
codex-only, so it re-resolves a bare id as a codex model
(`resolveCodexWsModelInfo`) before tunneling upstream — even though a bare
`gpt-5.5` would otherwise route to another provider over HTTP.
#### Configuring the OpenAI Codex CLI
Point the Codex CLI at OmniRoute by adding a custom provider with WebSocket
support to `~/.codex/config.toml` (use a separate `CODEX_HOME` to avoid touching
an existing config):
```toml
model = "gpt-5.5" # bare id — NOT "codex/gpt-5.5"
model_provider = "omniroute"
[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1" # no trailing slash; the WS URL is derived (use https/wss in production)
wire_api = "responses" # only supported value since Feb 2026
supports_websockets = true # enables the Responses-over-WS transport
env_key = "OMNIROUTE_API_KEY" # holds the OmniRoute API key (Bearer)
```
```bash
export OMNIROUTE_API_KEY=sk-... # an OmniRoute API key (any key if REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```
The CLI upgrades `base_url + /responses` to a WebSocket and OmniRoute tunnels it
to the selected codex OAuth connection. Validated end-to-end against the local
server: ChatGPT returns `codex.rate_limits` + `response.created` and streams the
completion.
---
## Quotas & Issues Reporting
| Method | Path | Description |
| ------ | ------------------- | ------------------------------------------------------------------------------------- |
| GET | `/v1/quotas/check` | Pre-validate quota for a `provider` + `accountId` before issuing a registered key |
| POST | `/v1/issues/report` | Report a quota/key issuance failure to GitHub (requires `GITHUB_ISSUES_REPO` + token) |
**Auth:** `/v1/quotas/check` takes a Bearer API key (`isAuthenticated`). `/v1/issues/report` is
management-only (`requireManagementAuth`), like `/api/v1/registered-keys`: a dashboard session,
the local CLI token, or an API key with `manage`/`admin` scope; inference-only API keys get `403`.
### Quota session recovery (opt-in)
A non-streaming `POST /v1/chat/completions` or `POST /v1/responses` that fails with a
terminal quota error (`402`/`429`/`503` whose body says the quota or credits are exhausted)
can be parked and replayed later instead of returning the error. The caller opts in per
request with three headers:
| Header | Value |
| ---------------------------- | --------------------------------------------- |
| `x-omniroute-quota-recovery` | `auto` |
| `x-omniroute-session` | session id, `[A-Za-z0-9._:-]{1,128}` |
| `x-omniroute-recovery-turn` | turn id unique within the session (same rule) |
Only `stream: false` turns with no tools, tool history or `previous_response_id`, and no
`x-omniroute-connection` pin, are eligible, and `STORAGE_ENCRYPTION_KEY` must be set (the
request is stored encrypted for up to 24 h). The response is then `202` with
`recovery.poll`; poll `GET /v1/quota-recoveries/{id}` (`202` while pending, `200` with the
recovered body when completed) or cancel with `DELETE`. Tickets are visible only to the API
key that created them. A replay whose outcome is uncertain ends in `needs_confirmation`
instead of being sent twice. Source: `src/lib/quota/quotaSessionRecovery.ts`.
---
## Self-service usage (`/api/usage/om-usage`)
Any API key can read **its own** usage and quotas — no management auth. This is the endpoint a
client (CLI, the OmniCopilot panel) uses to show a key holder their spend.
```bash
# Text form (the historical contract — plain text for a terminal)
curl -H "Authorization: Bearer <your-api-key>" \
http://localhost:20128/api/usage/om-usage
# Structured form — what a UI consumes
curl -H "Authorization: Bearer <your-api-key>" \
"http://localhost:20128/api/usage/om-usage?format=json"
```
The key must have **`allowUsageCommand`** enabled (off by default — the dashboard's API-key
manager toggles it per key). Without it the endpoint answers `403`.
`?format=json` returns a discriminated shape so a caller never reads a data field off a
refusal. On success:
```jsonc
{
"allowed": true,
// present only when the key opted into per-key usage limits (daily/weekly/5-hour USD):
"personal": {
"dailySpentUsd": 1.25,
"dailyLimitUsd": 5,
"dailyResetAtIso": "…",
"weeklySpentUsd": 8,
"weeklyLimitUsd": 20,
"weeklyResetAtIso": "…" /* … */,
},
// the selected provider quota snapshot, or null when nothing is cached yet:
"provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */} },
// every connection's snapshot, so a UI can render several providers side by side:
"providers": [
{ "connectionId": "…", "provider": "claude" /* … */ },
{ "provider": "codex" /* … */ },
],
}
```
On refusal (`401` bad key / `403` not allowed) the same route returns
`{ "allowed": false, "error": { "message": "…" } }` — a present-but-empty `personal`/`provider`
(key allowed, nothing learned yet) is a different state from a refusal, and only the JSON form
distinguishes them.
**Auth:** the caller's own Bearer API key, validated with `isValidApiKey` — this is _not_ the
management surface (`/api/keys/…`), which stays behind `requireManagementAuth`.
### Raw vs. Cutoff-Adjusted Quota Percentages
When consuming `/api/usage/om-usage`, callers should note the distinction between the
percentages presented by the **plain-text output** and the structured **JSON output**:
| Aspect | Plain-text format (`/api/usage/om-usage` / `@@om-usage`) | JSON format (`?format=json`) |
| :------------------- | :----------------------------------------------------------------------------------- | :-------------------------------------------------------------------- |
| **Output field** | `NN% left` (e.g., `20% left`) | `provider.quotas` / `providers[].quotas` |
| **Measurement** | **Cutoff-adjusted usable allowance**: remaining capacity above the cutoff threshold | **Raw upstream quota**: unadjusted provider measurement |
| **Cutoff scaling** | Scaled via `effectiveRemainingPercent()` so the protected reserve reads as `0% left` | None (raw snapshot values as reported by the provider) |
| **Threshold data** | Incorporated into the displayed percentage | Stored in `quotaWindowThresholds` per connection (or server defaults) |
| **Primary consumer** | Interactive CLIs, terminal prompts, human operators | Programmatic integrations, dashboards, analytics, billing trackers |
#### The Cutoff Adjustment Formula
OmniRoute supports proactive quota cutoffs to prevent upstream exhaustion (configured via connection
`quotaWindowThresholds`, provider defaults, or global resilience settings). When a cutoff threshold
(e.g., `cutoff = 25%`) is active on a quota window, the text renderer calculates remaining allowance as:
- If `remaining <= cutoff`: returns `0%`.
- If `remaining > cutoff`: returns `((remaining - cutoff) / (100 - cutoff)) * 100`.
The formatted text output rounds this to the nearest integer (`Math.round(...)`).
#### Illustrative Example
Consider a provider window with **60% raw usage** (hence **40% raw remaining quota**) and a configured
**25% remaining-quota cutoff** threshold:
| Representation | Calculation | Remaining | Implied Used |
| :---------------------------- | :------------------------------------------------- | :-------: | :----------------------------------------: |
| **Raw JSON (`?format=json`)** | Upstream snapshot (`quotas[window]`) | **40%** | **60%** |
| **Text format (`NN% left`)** | `((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100` | **20%** | **80%** (if calculating `100 - remaining`) |
- **Why text shows 20% left:** Out of the 40% physical quota left on the account, 25% is reserved by the
cutoff policy. The caller has only 15% out of 75% usable headroom remaining before the router stops
routing to this connection. Scaling ensures the connection signals exhaustion (`0% left`) exactly when
routing will cease.
- **Why JSON preserves raw values:** The JSON payload returns the exact provider snapshot (`UsageSnapshot`)
so external tools have access to ground-truth upstream utilization and connection-level
`quotaWindowThresholds` without server-side lossy scaling.
#### Consumer Migration Guidance
If an external integration (such as an editor plugin or agent extension) previously scraped the text
endpoint (`NN% left`) and computed used percentage as `100 - NN`, migrating to `?format=json` means:
- Reading raw JSON values will reflect **actual upstream consumption** (60% used in the example above).
- If the integration wishes to preserve the text endpoint's usable-allowance semantics, it can evaluate
the effective remaining formula client-side using `quotaWindowThresholds` for connection-level overrides.
---
## Semantic Cache
```bash
# Get cache stats
GET /api/cache/stats
# Clear all caches
DELETE /api/cache/stats
```
Response example:
```json
{
"semanticCache": {
"memorySize": 42,
"memoryMaxSize": 500,
"dbSize": 128,
"hitRate": 0.65
},
"idempotency": {
"activeKeys": 3,
"windowMs": 5000
}
}
```
### Latency impact
A semantic cache HIT serves the response from cache **without an upstream
call**, so the reported `X-OmniRoute-Response-Latency` is near-zero
(regardless of the original upstream latency). Latency-sensitive clients
(benchmarking, p50/p99 monitoring) should check the
`X-OmniRoute-Cache-Latency` response header:
| Value | Meaning |
| ----------- | ------------------------------------------------------------- |
| `synthetic` | Response served from cache; latency is not real upstream time |
| _(absent)_ | Response from real upstream call |
### Per-key cache bypass
API keys can opt out of semantic cache reads via `cacheDefaultMode`:
| Value | Behavior |
| -------- | ----------------------------------------------- |
| `legacy` | Normal cache behavior (default) |
| `bypass` | Skip cache lookup entirely; always hit upstream |
Set at key creation (`POST /api/keys`) or update (`PATCH /api/keys/[id]`):
```json
{ "cacheDefaultMode": "bypass" }
```
### Per-request bypass
Any request can bypass the cache regardless of key settings:
```
X-OmniRoute-No-Cache: true
```
---
## CLIProxyAPI Management Compatibility
OmniRoute answers the three [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)
management endpoints that usage dashboards call to read Claude and Codex subscription limits
(for example T3 Code's `cliproxy` usage-limit source). Point the client's base URL at
OmniRoute and use an API key with the `manage` scope as its management key. The routes are
served at `/v0/management/*` and at `/api/v0/management/*`.
| Method | Path | Description |
| ------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/v0/management/auth-files` | Claude and Codex OAuth connections as `{ files: [{ id, auth_index, provider, email, disabled, id_token }] }`. No tokens |
| POST | `/v0/management/api-call` | Body `{ auth_index, method, url, header?, data? }`. Sends one allowlisted request with the account's token and returns `{ status_code, body }` |
| POST | `/v0/management/reset-quota` | Body `{ auth_index }`. Clears the connection cooldown, model lockouts and Codex per-scope cooldowns of one account |
- `auth_index` is the OmniRoute connection id. `provider` is `claude` or `codex` (OAuth
connections only; the `anthropic` API-key provider is not listed). For Codex,
`id_token.chatgpt_account_id` is the stored workspace id and `plan_type` the stored plan.
- `api-call` is not a generic proxy. It accepts only Claude `GET
https://api.anthropic.com/api/oauth/usage` and Codex `GET
https://chatgpt.com/backend-api/wham/usage`, `GET .../wham/rate-limit-reset-credits` and
`POST .../wham/rate-limit-reset-credits/consume`, each only for an account of the matching
provider. Anything else returns `403` without contacting the upstream. The caller's
`Authorization` header (including the `$TOKEN$` placeholder) is ignored: OmniRoute injects
the connection's access token, refreshing it first when it is near expiry, and forwards only
allowlisted headers (`anthropic-beta`; `OpenAI-Beta`, `Originator`, `Chatgpt-Account-Id`;
`Accept`, `Content-Type`). A missing `Chatgpt-Account-Id` defaults to the stored workspace id.
Requests time out after 15 seconds and use the connection's proxy.
- `reset-quota` leaves terminal states (banned, expired, credits_exhausted) alone. An unknown
`auth_index` returns `404`.
**Auth:** dashboard session or a `manage`-scoped API key, required even when login is disabled
(the paths are in `ALWAYS_PROTECTED_API_PATHS`). Inference-only keys get `403`. Source:
`src/lib/cliproxyCompat/managementApi.ts`.
---
## Dashboard & Management
Management routes (`/api/*` except public auth/login) are **not** authorized by
ordinary inference API keys. Credential families, scopes, and curl examples:
[Management Authentication](../guides/MANAGEMENT-AUTH.md).
### Authentication
| Endpoint | Method | Description |
| ----------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/auth/login` | POST | Login |
| `/api/auth/logout` | POST | Logout |
| `/api/settings/require-login` | GET/POST | Login status (GET, public). POST sets the password / toggles login: operator-only once a password exists (dashboard session, local CLI, or login disabled — API keys and `oma_` tokens get `403`); a dashboard session sends `currentPassword` to replace the password |
### Provider Management
| Endpoint | Method | Description |
| --------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/providers` | GET/POST | List / create providers |
| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider |
| `/api/providers/[id]/test` | POST | Test provider connection |
| `/api/providers/[id]/models` | GET | List provider models |
| `/api/providers/validate` | POST | Validate provider config |
| `/api/providers/bulk` | POST | Bulk-add API keys for ONE provider |
| `/api/providers/import` | POST | Import a heterogeneous provider LIST from a parsed CSV/JSON file (#6836); per-row partial-failure results |
| `/api/provider-nodes*` | Various | Provider node management |
| `/api/provider-models` | GET/POST/PUT/PATCH/DELETE | Custom models and per-model overrides (add, update, hide/show, delete) |
| `/api/provider-models/validate-and-add` | POST | Management-authenticated, opt-in strict-connection validation and atomic custom-model registration; see [Model validation](../guides/MODEL-VALIDATION.md) |
For synced/imported models, `PUT /api/provider-models` accepts `provider`, `modelId`, and
`maxOutputTokenOverride`: a positive integer sets the manual output-token cap, and `null`
clears it to restore the default. `GET /api/provider-models?provider=<provider>` returns these
values in `modelOutputOverrides`, including models without a custom-model row. The override
uses the runtime `max_output_tokens` capability and survives a model re-sync. The OpenAI-compatible
provider page offers the same edit/clear controls and marks models with explicit vision support.
On a compatible provider node, the write paths (`POST`, `PUT`, `PATCH`, `DELETE` and
`/api/provider-models/validate-and-add`) store the model id as the bare upstream id: an id
pasted from a prefixed listing has any leading stack of the node's own prefix collapsed, and
responses echo the stored id. Canonical providers' slashed ids (e.g. `nvidia/nemotron-…`) are
stored verbatim. `/v1/models` never emits a stacked `<prefix>/<prefix>/<model>` id.
Custom Chat Completions nodes adapt explicit reasoning opt-outs to the upstream backend. A
successful connection test automatically selects chat-template controls for each exact model ID
whose `/models` entry proves a recognized `owned_by` value: `vllm`, `sglang`, or `llamacpp`.
Transparent OpenAI-compatible wrappers may preserve the original model entry inside a nested
`openai` object; detection follows up to three such envelopes. Models with missing, unknown, or
conflicting ownership keep ordinary OpenAI behavior. Detection reuses the existing catalog request,
generates no completion tokens, and is invalidated when the connection endpoint changes.
To pin the behavior for a backend that does not expose that metadata, use the existing partial
provider update API:
```json
{
"providerSpecificData": {
"reasoningControl": "chat-template"
}
}
```
Send that body with `PUT /api/providers/<connection-id>`. On that connection, an explicit
reasoning effort of `none` is sent as `chat_template_kwargs.thinking=false` and
`chat_template_kwargs.enable_thinking=false`. Explicit native template values remain authoritative
unless a server-side reasoning rule forces an effort. The setting applies only when a custom
OpenAI-compatible connection dispatches a Chat Completions body; Responses requests and ordinary
providers keep their native request shape. Set `reasoningControl` to `openai` to force ordinary OpenAI
`reasoning_effort` passthrough, or omit it/set it to `null` to use automatic detection.
Claude Code auto-mode classifier requests default native thinking to disabled when they contain
no explicit reasoning controls. Detection uses the classifier's system marker in Claude-format
requests, not model names or completion limits. Explicit body controls, supported effort/thinking
headers, routing rules, and resolved model effort keep their existing priority. Both classifier
stages retain their prompts, completion limits, stop sequences, and real upstream permission
verdicts; the second stage can still produce its requested visible reasoning as ordinary text.
### OAuth Flows
| Endpoint | Method | Description |
| -------------------------------- | ------- | ----------------------- |
| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth |
### Routing & Config
| Endpoint | Method | Description |
| --------------------- | -------- | ----------------------------- |
| `/api/models` | GET/PUT | Model list / alias update |
| `/api/models/alias` | GET/POST | Model aliases |
| `/api/models/catalog` | GET | All models by provider + type |
| `/api/combos*` | Various | Combo management |
| `/api/keys*` | Various | API key management |
| `/api/pricing` | GET | Model pricing |
#### Model limit provenance
`GET /api/models?withLimits=1` (also `true`; `0`/`false` or omitting it keeps the default
payload unchanged) adds `contextWindow`, `maxInputTokens`, `maxOutputTokens` and a `capsSource`
object to every model row. `capsSource` names the rule that supplied each limit, so a
surprising limit (for example 128k on a 1M model) can be traced to its origin. The resolved
values are the same ones routing uses; the flag only adds fields and never changes a value.
Any other `withLimits` value is rejected with `400`.
| `capsSource` value | Origin |
| -------------------------------------------- | ---------------------------------------------------------------------- |
| `override:context` | Persisted context-window override (`model_context_overrides`) |
| `override:max_input` / `override:max_output` | Persisted `max_input_tokens` / `max_output_tokens` capability override |
| `static-authoritative:<provider>/<model>` | Static authoritative context-window table |
| `synced:<provider>/<model>` | models.dev synced capability row |
| `registry:<provider>/<model>` | Provider registry entry |
| `spec:<model>` | Static model spec |
| `effort-base:` prefix | Row borrowed from the base model of an effort-suffixed variant |
| `none` | No source declares the limit (value is `null`) |
Implementation: `getResolvedModelCapabilitiesWithLimitSources()` in `src/lib/modelCapabilities.ts`
and the precedence chains in `src/lib/modelCapabilityLimits.ts`.
### Usage & Analytics
| Endpoint | Method | Description |
| -------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history` | GET | Usage history |
| `/api/usage/logs` | GET | Usage logs |
| `/api/usage/request-logs` | GET | Request-level logs |
| `/api/usage/[connectionId]` | GET | Per-connection usage |
| `/api/usage/token-limits` | GET/POST/DELETE | Per-API-key token-limit budgets |
| `/api/usage/model-latency-stats` | GET | Rolling per-provider/model latency aggregate (avg/p50/p95/p99, success rate); filters: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) |
| `/api/usage/cache-health` | GET | Prompt-cache health summary over `call_logs` — write/read ratio, p50/p90/p99 write-size distribution, heavy-write concentration, per-model split, and a `healthy`/`degraded`/`thrash`/`no-data` verdict; query params `range` (`1h`\|`24h`\|`7d`\|`30d`, default `24h`) and optional `model` (#8827) |
### API key permissions
`PATCH /api/keys/{id}` updates an existing key's permissions. Like every `/api/keys*` route it needs management authorization (see [Management Authentication](../guides/MANAGEMENT-AUTH.md)), not an inference key. Send only the fields you want to change; a request with none of them is rejected with `No valid fields to update`. The accepted fields are defined by `updateKeyPermissionsSchema` in `src/shared/validation/schemas/keys.ts`.
| Field | Type | Notes |
| ------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string, 1-200 chars | |
| `isActive` | boolean | |
| `isBanned` | boolean | |
| `expiresAt` | ISO 8601 datetime or `null` | `null` clears the expiry |
| `modelAccessMode` | `all` \| `restricted` | `allowedModels` must be empty when the mode is `all` |
| `allowedModels`, `blockedModels` | array of strings, up to 1000 | |
| `allowedCombos` | array of strings, up to 500 | Gates which combos the key may call; direct models are governed by `modelAccessMode` / `allowedModels` |
| `connectionAccessMode` | `all` \| `restricted` | `allowedConnections` must be non-empty when `restricted` and empty when `all` |
| `allowedConnections` | array of UUIDs, up to 100 | |
| `allowAutoCombos` | boolean | `false` rejects requests for `auto/*` models with this key; keys that never set it are allowed |
| `catalogScope` | `all` \| `combos` \| `models` | What `GET /v1/models` lists for this key (combos only, models only, or both); it does not change what the key may call |
| `forcedModel` | string up to 300 chars, or `null` | Routes chat requests to this model/combo, over `X-Route-Model` and `body.model`; the key's limits still apply |
| `noLog`, `autoResolve` | boolean | |
| `throttleDelayMs` | integer, 0-300000 | |
| `maxSessions` | integer, 0-10000 | |
| `rateLimits` | array of `{ limit, window }` (positive integers, up to 50) or `null` | `null` clears the limits |
| `accessSchedule` | schedule object or `null` | `null` clears the schedule |
| `scopes` | array of strings, up to 32 | |
| `allowedEndpoints` | array of strings, up to 20 | |
| `streamDefaultMode` | `legacy` \| `json` | |
| `cacheDefaultMode` | `legacy` \| `bypass` | See [Per-key cache bypass](#per-key-cache-bypass) |
| `compressionEnabled` | boolean | |
| `codexServiceMode` | one of the Codex service modes | |
| `disableNonPublicModels` | boolean | |
| `allowUsageCommand` | boolean | |
| `usageLimitEnabled` | boolean | |
| `dailyUsageLimitUsd`, `weeklyUsageLimitUsd` | number >= 0 or `null` | |
| `fiveHourUsageLimitUsd` | number >= 0 or `null` | Rolling 5-hour USD budget, enforced like the daily and weekly limits (`usageLimitEnabled`, `UNPRICED_USAGE_BUDGET_POLICY`). `retry-after` is when the oldest spend in the window ages out, which can leave a key far over its limit still blocked. |
| `chaosModeEnabled` | boolean | |
```bash
curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \
-H "Authorization: Bearer <management-credential>" \
-H "Content-Type: application/json" \
-d '{ "allowAutoCombos": false, "catalogScope": "combos" }'
```
### Settings
| Endpoint | Method | Description |
| ------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings` | GET/PUT/PATCH | General settings. Security-policy keys (`requireLogin`, `newPassword`, `oidc*`, `corsOrigins`, `bruteForceProtection`) need `currentPassword` and an operator credential — API keys and `oma_` tokens get `403`; every mutation needs the `admin` access-token scope |
| `/api/settings/proxy` | GET/PUT | Network proxy config |
| `/api/settings/proxy/test` | POST | Test proxy connection |
| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist |
| `/api/settings/thinking-budget` | GET/PUT | Thinking/reasoning **request** rewrite mode (passthrough / auto-strip / custom / adaptive). Independent of compression. See [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). |
| `/api/settings/system-prompt` | GET/PUT | Global system prompt |
| `/api/settings/compression` | GET/PUT | Global compression config |
| `/api/settings/purge-request-history` | POST | Clear request log rows and local call-log artifacts |
### Context & Compression
| Endpoint | Method | Description |
| -------------------------------------- | -------------- | ------------------------------------------------------------------------ |
| `/api/compression/preview` | POST | Preview off/lite/standard/aggressive/ultra/RTK/stacked compression |
| `/api/compression/language-packs` | GET | List available Caveman language packs |
| `/api/compression/rules` | GET | List Caveman rule metadata |
| `/api/context/caveman/config` | GET/PUT | Caveman-specific settings alias |
| `/api/context/rtk/config` | GET/PUT | RTK-specific settings, including custom filters and raw-output retention |
| `/api/context/rtk/filters` | GET | RTK filter catalog and custom-filter diagnostics |
| `/api/context/rtk/test` | POST | Run RTK preview/test against a text payload |
| `/api/context/rtk/raw-output/[id]` | GET | Read retained redacted raw output by pointer id |
| `/api/context/combos` | GET/POST | Compression combo list/create |
| `/api/context/combos/[id]` | GET/PUT/DELETE | Compression combo detail/update/delete |
| `/api/context/combos/[id]/assignments` | GET/PUT | Assign compression combos to routing combos |
| `/api/context/analytics` | GET | Compression analytics alias |
### Monitoring
| Endpoint | Method | Description |
| ------------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions` | GET | Active session tracking |
| `/api/rate-limits` | GET | Per-account rate limits |
| `/api/monitoring/health` | GET | Health check + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Management view includes `credentialHealth`: probe-cache scalars, `failedConnections` when `failed>0`, and `staleDbNonOkCount` (SQLite sticky `test_status`, not the gauge). See [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). |
| `/api/cache/stats` | GET/DELETE | Cache stats / clear |
| `/api/modality-bridge/stats` | GET | In-memory `attempts`, successes/`bridged`, failures, cache hits, `totalLatencyMs`, `latencySamples`, sample-denominated `averageLatencyMs`, and last-use time (reset on restart; management auth) |
| `/api/modality-bridge/video/runtime` | GET | Strict trusted-loopback check before management auth/probe; sanitized FFmpeg/ffprobe availability and versions (no-store) |
| `/api/modality-bridge/video/extract` | POST | Internal authenticated trusted-loopback byte broker; 50 MiB input, bounded queue/32 MiB output, `503` capacity, `499` disconnect, `504` deadline; not a public upload API |
### Video frame drill-down
`GET /api/v1/video-bridge/drilldown` reads a tenant-bound opaque handle returned in
`x-omniroute-video-drilldown` after an explicitly consented Video Bridge request.
Both reads and `DELETE` always require a valid API key and the operator's independent
`modalityBridgeVideoDrilldownRemoteEnabled` permission. Production retention additionally
requires `modalityBridgeVideoDrilldownEnabled` and strict per-part `drilldown: true`.
If the key has a nonempty endpoint allowlist, it must include `video` for both
GET and DELETE, whether the caller uses `/v1` or `/api/v1`.
GET query: required `handle`; optional `variant` (`preview`, `standard`, `detail`),
`limit` (1–8; legacy `frames` is accepted but cannot be combined with `limit`),
zero-based `page`, and `start`/`end` seconds. When both focus bounds
are supplied, `end` must be greater than `start`. Duplicate/unknown query keys are
rejected. Successful responses contain `derivation`, `durationSeconds`, `frames`,
`hasMore`, `page`, `variant`, and optional `focusWindow`; no-store JSON is capped at
32 MiB including Base64. Oversized output returns 413; request fewer frames.
`DELETE /api/v1/video-bridge/drilldown?handle=...` returns `{ "removed": 0|1 }`.
Unknown, expired and cross-key GETs are indistinguishable 404 responses; cross-key
DELETE cannot remove the owner's entry. Disabled access returns 403, missing/invalid
authentication 401, invalid queries 400, cancellation 499 and temporary errors 503.
Handles are process-local, expire after ten minutes, and do not survive a restart.
New handles use `v1.` plus a 32-byte random Base64URL token; only token hashes are
retained. Legacy 64-hex tokens remain syntactically readable for compatibility.
See [Video Bridge guardrails](../security/GUARDRAILS.md#video-bridge-videobridgets-videobridgepipelinets)
for consent, quotas and variant derivation details.
### Backup & Export/Import
| Endpoint | Method | Description |
| --------------------------- | ------ | ----------------------------------------------------------------------- |
| `/api/db-backups` | GET | List available backups |
| `/api/db-backups` | PUT | Create a manual backup |
| `/api/db-backups` | POST | Restore from a specific backup |
| `/api/db-backups` | PATCH | Save backup retention settings (operator-only) |
| `/api/db-backups` | DELETE | Prune stored backups to the retention settings (operator-only) |
| `/api/db-backups/export` | GET | Download database as .sqlite file |
| `/api/db-backups/import` | POST | Upload .sqlite file to replace database (`?dryRun=true` validates only) |
| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive |
`/api/db-backups/export`, `/api/db-backups/exportAll` and `/api/settings/export-json` hand out
every stored credential, so they require the dashboard session or the local CLI (or login
disabled). API keys of any scope and `oma_` access tokens get `403`. The restores hold the same
boundary: `POST /api/db-backups/import` (`dryRun=true` included), `POST /api/db-backups` (restore
by id) and `POST /api/settings/import-json` replace the live database or settings, so a machine
credential gets `403` there too; `omniroute sync import` sends the local CLI credential. So do
`DELETE /api/db-backups` (prune stored backups) and `PATCH /api/db-backups` (retention settings:
the persisted values drive the automatic pruning after every backup). Listing (`GET`) and creating
a manual backup (`PUT`) keep ordinary management auth.
### Cloud Sync
| Endpoint | Method | Description |
| ---------------------- | ------- | --------------------- |
| `/api/sync/cloud` | Various | Cloud sync operations |
| `/api/sync/initialize` | POST | Initialize sync |
| `/api/cloud/*` | Various | Cloud management |
### Tunnels
| Endpoint | Method | Description |
| -------------------------- | ------ | ----------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard |
| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) |
| `/api/tunnels/ngrok` | GET | Read ngrok Tunnel runtime status for the dashboard |
| `/api/tunnels/ngrok` | POST | Enable or disable the ngrok Tunnel (`action=enable/disable`) |
### CLI Tools
| Endpoint | Method | Description |
| ---------------------------------- | ------ | ------------------- |
| `/api/cli-tools/claude-settings` | GET | Claude CLI status |
| `/api/cli-tools/codex-settings` | GET | Codex CLI status |
| `/api/cli-tools/droid-settings` | GET | Droid CLI status |
| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status |
| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime |
CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
### ACP Agents
| Endpoint | Method | Description |
| ----------------- | ------ | -------------------------------------------------------- |
| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status |
| `/api/acp/agents` | POST | Add custom agent or refresh detection cache |
| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param |
GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom).
### Resilience & Rate Limits
| Endpoint | Method | Description |
| --------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/resilience` | GET/PATCH | Get/update request queue, connection cooldown, provider breaker, and wait settings |
| `/api/resilience/reset` | POST | Reset provider circuit breakers |
| `/api/resilience/model-cooldowns` | GET | List active per-(provider, connection, model) lockouts, sorted by remaining time |
| `/api/resilience/model-cooldowns` | DELETE | Clear a model lockout — body `{provider, model}` or `{all: true}` to wipe everything |
| `/api/rate-limits` | GET/POST | Per-account rate limit status (GET) or toggle rate-limit protection for a connection (POST `{connectionId, enabled}`). Supported write path for `rateLimitProtection` (never modified via `PUT /api/providers/[id]`). Note: `enabled: false` disables explicit protection but does not opt an active API-key connection out of the global auto-enable safety net (`autoEnableApiKeyProviders`). |
| `/api/rate-limit` | GET | Global rate limit configuration (deprecated; alias to `/api/rate-limits`) |
> All four `/api/resilience/*` routes require **management auth** (`requireManagementAuth`). See [Resilience (extended)](#resilience-extended) for a full breakdown of provider breaker vs connection cooldown vs model lockout.
### Evals
| Endpoint | Method | Description |
| ------------ | -------- | --------------------------------- |
| `/api/evals` | GET/POST | List eval suites / run evaluation |
### Policies
| Endpoint | Method | Description |
| --------------- | --------------- | ----------------------- |
| `/api/policies` | GET/POST/DELETE | Manage routing policies |
### Compliance
| Endpoint | Method | Description |
| --------------------------- | ------ | ----------------------------- |
| `/api/compliance/audit-log` | GET | Compliance audit log (last N) |
### v1beta (Gemini-Compatible)
| Endpoint | Method | Description |
| -------------------------- | ------ | --------------------------------- |
| `/v1beta/models` | GET | List models in Gemini format |
| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint |
These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility.
### Internal / System APIs
| Endpoint | Method | Description |
| ------------------------ | ------ | ------------------------------------------------------ |
| `/api/init` | GET | Start background sync services (management auth) |
| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) |
| `/api/restart` | POST | Trigger graceful server restart |
| `/api/shutdown` | POST | Trigger graceful server shutdown |
| `/api/system/env/repair` | POST | Repair OAuth provider environment variables |
| `/api/system/version` | GET | Current/latest version, update status, release channel |
| `/api/system/version` | POST | Start a deployment-aware update to the latest version |
> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users.
### OAuth Environment Repair _(v3.6.1+)_
```bash
POST /api/system/env/repair
Content-Type: application/json
{
"provider": "claude-code"
}
```
Repairs missing or corrupted OAuth environment variables for a specific provider. Returns:
```json
{
"success": true,
"repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
"backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}
```
### Version and Release Channel
```bash
GET /api/system/version
```
Loopback-only management route (admin auth). Returns the running version, the latest
published version and the auto-update status. `releaseChannel` and `channels` are additive
fields (rail 3.8.54); `channel` keeps its meaning — the deployment mode the dashboard updater
uses (`npm`, `source` or `docker-compose`).
```json
{
"current": "3.8.52",
"latest": "3.8.52",
"updateAvailable": false,
"channel": "npm",
"autoUpdateSupported": true,
"autoUpdateError": null,
"news": null,
"releaseChannel": "latest",
"channels": { "latest": "3.8.52", "next": "3.8.53-rc.1" }
}
```
- `releaseChannel` — npm channel of the running build: `nightly` for `-nightly.*` versions,
`next` for other pre-releases (`-rc.*`, `-beta.*`, `-alpha.*`), `lts` for a stable version of an
older major than `channels.latest`, otherwise `latest`. Same rules as
`scripts/release/dist-tag.mjs`, which picks the npm dist-tag at publish time.
- `channels` — published head of each dist-tag, from `npm view omniroute dist-tags` (registry
HTTP fallback), cached with the same 10-minute TTL as `latest`. `latest` is always present
(falls back to the `latest` field, then `"unavailable"`); `next`, `nightly` and `lts` appear
only when that dist-tag exists. A `Cache-Control: no-cache` request refreshes both lookups.
The channel model (`latest` = v3 until the 4.0 GA, `next` = rc, `nightly` = `develop` builds,
`lts` = v3 patches after the 4.0 GA) is described in `docs/ops/RELEASE_STRATEGY.md`.
---
## Audio Transcription
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
```
Transcribe audio files using any configured STT provider. The first path
segment selects the native provider (`openai/…`, `deepgram/…`). Gateways that
re-export another vendor's model use a qualified id
(`openrouter/deepgram/nova-3`).
**Request:**
```bash
curl -X POST http://localhost:20128/v1/audio/transcriptions \
-H "Authorization: Bearer your-api-key" \
-F "file=@recording.mp3" \
-F "model=openai/whisper-1"
```
**Response:**
```json
{
"text": "Hello, this is the transcribed audio content.",
"task": "transcribe",
"language": "en",
"duration": 12.5
}
```
**Example model ids:** `openai/whisper-1` (requires an OpenAI key),
`openrouter/deepgram/nova-3` (requires an OpenRouter key),
`deepgram/nova-3` (requires a native Deepgram key). A bare
`deepgram/nova-3` request does **not** use OpenRouter.
**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
**Gemini Live (`gemini/gemini-3.5-transcribe-live`):** file-mode transcription over the Gemini Live
WebSocket (requires a Gemini API key). The upload is converted to 16 kHz mono PCM with `ffmpeg`
(must be on `PATH`, unless the file is already a 16 kHz mono PCM WAV), streamed to the session and
the finalized text is returned as `{ "text": "..." }`. Optional `language` and `prompt` form fields
are forwarded. Limits: uploads above 25 MiB or decoded audio longer than 10 minutes answer
`413`; a conversion that runs longer than 60 s is killed and answers `504`. The API key is sent
in the `x-goog-api-key` header only, never in the WebSocket URL.
---
## Ollama Compatibility
For clients that use Ollama's API format:
```bash
# Chat endpoint (Ollama format)
POST /v1/api/chat
# Model listing (Ollama format)
GET /api/tags
```
Requests are automatically translated between Ollama and internal formats.
## Tokenized VS Code / Headerless Aliases
Use these aliases when an integration cannot inject an `Authorization` header and needs the API key embedded in the base URL.
```bash
# OpenAI-style catalog alias
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models
# OpenAI-style chat aliases
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses
# Ollama-style aliases
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```
Example:
```bash
curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'
```
Notes:
- The tokenized aliases reuse the same handlers as `/v1/*` and `/api/tags`; response shapes stay identical.
- Prefer `Authorization: Bearer ...` whenever the client supports custom headers.
- URL-based tokens may appear in reverse-proxy logs, browser history, and telemetry outside OmniRoute. Treat them as a compatibility option, not the default authentication mode.
---
## Telemetry
```bash
# Get latency telemetry summary (p50/p95/p99 per provider)
GET /api/telemetry/summary
```
**Response:**
```json
{
"providers": {
"claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
"github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
}
}
```
---
## Budget
```bash
# Get budget status for all API keys
GET /api/usage/budget
# Set or update a budget
POST /api/usage/budget
Content-Type: application/json
{
"apiKeyId": "key-123",
"dailyLimitUsd": 5.00,
"weeklyLimitUsd": 30.00,
"monthlyLimitUsd": 100.00,
"warningThreshold": 0.8,
"resetInterval": "monthly"
}
```
> **Schema notes** (`setBudgetSchema`): `apiKeyId` is required; at least one of `dailyLimitUsd`, `weeklyLimitUsd`, or `monthlyLimitUsd` must be greater than zero. Optional fields: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). The legacy `{keyId, limit, period}` shape returns `400 Bad Request`.
## Token Limits
Per-API-key **token** budgets (distinct from the USD-based Budget above). Enforced inline on the request path: when a key's current window usage reaches its limit, requests are rejected with `429 Too Many Requests`. Limits can be scoped to a specific `model`, a `provider`, or applied `global`ly across the key; when several limits match a request, the most restrictive one wins.
```bash
# List a key's token limits (includes live window usage)
GET /api/usage/token-limits?apiKeyId=key-123
# Create or update a token limit
POST /api/usage/token-limits
Content-Type: application/json
{
"apiKeyId": "key-123",
"scopeType": "model",
"scopeValue": "openai/gpt-4o",
"tokenLimit": 1000000,
"resetInterval": "monthly",
"enabled": true
}
# Delete a token limit by id
DELETE /api/usage/token-limits?id=tl-abc
```
> **Schema notes** (`setTokenLimitSchema`): `apiKeyId` and `scopeType` (`model` | `provider` | `global`) are required. `scopeValue` is required unless `scopeType` is `global` (e.g. a model id for `model` scope, a provider id for `provider` scope). `tokenLimit` must be a positive integer (coerced from string). Optional: `id` (omit to create, supply to update), `resetInterval` (`daily` | `weekly` | `monthly`, default `monthly`), `resetTime` (`HH:MM`), `enabled` (default `true`). `GET` responses enrich each limit with `tokensUsed`, `remaining`, `windowStart`, `periodStartAt`, and `nextResetAt`. This is a management-class endpoint (auth enforced centrally by the authz pipeline).
## Request Processing
1. Client sends request to `/v1/*`
2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration`
3. Model is resolved (direct provider/model or alias/combo)
4. Credentials selected from local DB with account availability filtering
5. For chat: `handleChatCore` checks semantic/signature cache and resolves combo compression settings
6. Proactive compression runs before provider translation when enabled (`lite`, Caveman, RTK, or stacked)
7. Provider executor sends upstream request
8. Response translated back to client format (chat) or returned as-is (embeddings/images/audio)
9. Usage, compression analytics, and request logs are recorded
10. Fallback applies on errors according to combo rules
Full architecture reference: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)
---
## Combo Management
Higher-level routing combos (already summarized under `/api/combos*`) can also be mapped 1:1 from a model id pattern, allowing transparent redirection of an OpenAI-style model id to a combo.
| Method | Path | Description |
| ------ | -------------------------------- | ------------------------------------------------------------------------------ |
| GET | `/api/model-combo-mappings` | List all model→combo mappings |
| POST | `/api/model-combo-mappings` | Create mapping — body: `{pattern, comboId, priority?, enabled?, description?}` |
| GET | `/api/model-combo-mappings/[id]` | Retrieve a single mapping |
| PUT | `/api/model-combo-mappings/[id]` | Update fields of an existing mapping |
| DELETE | `/api/model-combo-mappings/[id]` | Remove a mapping |
**Auth:** management session/API key (`requireManagementAuth`).
---
## Webhooks
Outbound webhook subscriptions for OmniRoute events (request completion, quota exhaustion, key rotation, etc.).
| Method | Path | Description |
| ------ | ------------------------- | --------------------------------------------------------------------- |
| GET | `/api/webhooks` | List webhooks (secrets are masked to `<prefix>...`) |
| POST | `/api/webhooks` | Create webhook — body: `{url, events?: ["*"], secret?, description?}` |
| GET | `/api/webhooks/[id]` | Retrieve a webhook |
| PUT | `/api/webhooks/[id]` | Update url/events/secret/description |
| DELETE | `/api/webhooks/[id]` | Remove a webhook |
| POST | `/api/webhooks/[id]/test` | Send a test payload to the webhook URL and return delivery status |
**Auth:** management session/API key (`requireManagementAuth`).
---
## Registered Keys (Auto-Management)
Used by the auto-key management subsystem to issue and rotate API keys against a backing provider/account, with daily/hourly quotas.
| Method | Path | Description |
| ------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/registered-keys` | List registered keys (masked prefix only) |
| POST | `/api/v1/registered-keys` | Issue a new registered key — body: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Returns the raw key **once**. Returns `429` on quota refusal. |
| GET | `/api/v1/registered-keys/[id]` | Retrieve a registered key's metadata (no raw material) |
| DELETE | `/api/v1/registered-keys/[id]` | Revoke a registered key |
| POST | `/api/v1/registered-keys/[id]/revoke` | Explicit revoke endpoint (same effect as DELETE) |
| GET | `/api/v1/providers/[provider]/limits` | Read the provider's issuance caps |
| PUT | `/api/v1/providers/[provider]/limits` | Set the provider's issuance caps — body: `{maxActiveKeys?, dailyIssueLimit?, hourlyIssueLimit?}` |
| GET | `/api/v1/accounts/[id]/limits` | Read the account's issuance caps |
| PUT | `/api/v1/accounts/[id]/limits` | Set the account's issuance caps — same body as the provider route |
**Auth:** management session/API key (`requireManagementAuth`) — the same guard as `/api/keys`: a dashboard session, the local CLI token, or an API key with `manage`/`admin` scope; inference-only API keys get `403`. See also `/v1/quotas/check` and `/v1/issues/report`.
---
## Agents Protocol
Cloud agent tasks (Claude Code, Codex Cloud, OpenHands, etc.) executed remotely on behalf of OmniRoute users.
| Method | Path | Description |
| ------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/agents/tasks` | List tasks — optional `?provider=`, `?status=`, `?limit=` (1–500, default 50) |
| POST | `/api/v1/agents/tasks` | Create task — body validated by `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Returns `201` with task envelope |
| DELETE | `/api/v1/agents/tasks?id=...` | Delete a task |
| GET | `/api/v1/agents/tasks/[id]` | Read task — synchronously refreshes status from the upstream cloud agent when an `external_id` is set |
| POST | `/api/v1/agents/tasks/[id]` | Discriminated action: `{action: "approve"}`, `{action: "message", message}`, or `{action: "cancel"}` |
| DELETE | `/api/v1/agents/tasks/[id]` | Delete a specific task by id |
> **Auth:** management auth required on every method (`requireCloudAgentManagementAuth`). Prior to v3.8.0 these were unauthenticated — see commit `588a0333` for the breaking change.
```bash
# Create a Claude Code cloud task
curl -X POST http://localhost:20128/api/v1/agents/tasks \
-H "Authorization: Bearer your-management-key" \
-H "Content-Type: application/json" \
-d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'
```
---
## Management Proxies
Outbound HTTP(S)/SOCKS proxies that can be assigned to providers, accounts, or globally.
| Method | Path | Description |
| ------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/v1/management/proxies` | List proxies (with `?id=` returns one; with `?id=&where_used=1` returns the assignment graph) |
| POST | `/api/v1/management/proxies` | Create proxy — body validated by `createProxyRegistrySchema` |
| PATCH | `/api/v1/management/proxies` | Update proxy — body validated by `updateProxyRegistrySchema` (requires `id`) |
| DELETE | `/api/v1/management/proxies?id=...&force=1` | Delete proxy (use `force=1` to detach assignments) |
| GET | `/api/v1/management/proxies/assignments` | List assignments — filterable by `proxy_id`, `scope`, `scope_id`; pass `resolve_connection_id=<id>` to resolve the active proxy for a connection |
| PUT | `/api/v1/management/proxies/assignments` | Assign — body validated by `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Clears dispatcher cache |
| PUT | `/api/v1/management/proxies/bulk-assign` | Bulk-assign — body validated by `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) |
| GET | `/api/v1/management/proxies/health?hours=24` | Aggregate proxy health (success/fail counts, latency) over a window |
**Auth:** management session/API key on every route (`requireManagementAuth`).
> The task description's `POST /api/v1/management/proxies/[id]/assignments` and `POST /api/v1/management/proxies/[id]/health` are served by the flat `/assignments` and `/health` routes shown above — there are no per-id subroutes in the codebase.
---
## Resilience (extended)
OmniRoute exposes three independent temporary-failure mechanisms; the management endpoints below let operators read and override them:
| Scope | State storage | Read | Reset / clear |
| ------------------- | ------------------------------------------ | ----------------------------------------- | ------------------------------------------- |
| Provider breaker | `domain_circuit_breakers` + in-memory | `/api/monitoring/health` | `POST /api/resilience/reset` |
| Connection cooldown | `rateLimitedUntil` on provider connections | `/api/rate-limits`, `/api/providers/[id]` | (re-enables lazily; clear via provider PUT) |
| Model lockout | In-memory model-availability registry | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` |
`PATCH /api/resilience` accepts provider breaker overrides under `providerBreaker.oauth` and `providerBreaker.apikey`. Each profile supports `degradationThreshold`, `failureThreshold`, and `resetTimeoutMs`; the same fields are exposed in Dashboard → Settings → Resilience.
```bash
# Clear a single model lockout
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-H "Content-Type: application/json" \
-d '{"provider":"openai","model":"gpt-4o-mini"}'
# Wipe every lockout
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-d '{"all":true}'
```
Full conceptual reference and breaker defaults: see [`CLAUDE.md`](../../CLAUDE.md) → "Resilience Runtime State" and [`docs/architecture/RESILIENCE_GUIDE.md`](../architecture/RESILIENCE_GUIDE.md).
### Rate-Limit Queue & Auto-Enable Safety Net
- **Supported write path**: `POST /api/rate-limits` with body `{"connectionId": "<id>", "enabled": true|false}` is the supported management endpoint to toggle rate-limit protection for a connection. `PUT /api/providers/[id]` deliberately does not modify or flip `rateLimitProtection` (#11278).
- **Semantics of `enabled: false`**: Setting `enabled: false` removes explicit protection for the connection, but **does not** opt an active API-key connection out of the global auto-enable safety net (`autoEnableApiKeyProviders = true`). In `reconcileEnabledConnections` (`open-sse/services/rateLimitManager.ts`), `false` and `undefined` are equivalent; active API-key connections without explicit protection remain protected under the auto-enable safety net.
- **Global disable**: To run API-key connections without rate-limit queues, disable the safety net globally via `RATE_LIMIT_AUTO_ENABLE=false` (env) or `resilienceSettings.requestQueue.autoEnableApiKeyProviders = false` (Settings → Resilience / `PATCH /api/resilience`).
---
## Skills
Skill framework for extending OmniRoute with custom executable handlers, plus marketplace integrations.
| Method | Path | Description |
| ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/skills` | List installed skills — filterable by `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, paginated |
| GET | `/api/skills/[id]` | Retrieve one skill |
| PUT | `/api/skills/[id]` | Update skill (name, description, mode, schema, handler, tags) |
| DELETE | `/api/skills/[id]` | Uninstall a skill |
| POST | `/api/skills/install` | Install a skill from a raw manifest — body: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
| GET | `/api/skills/executions` | List recent skill executions (audit trail with inputs/outputs/duration) |
| GET | `/api/skills/marketplace?q=...` | Search/popular list from the SkillsMP marketplace (requires `skillsmpApiKey` setting) |
| POST | `/api/skills/marketplace/install` | Install a skill by id from SkillsMP |
| GET | `/api/skills/skillssh?q=&limit=` | Search the skills.sh registry |
| POST | `/api/skills/skillssh/install` | Install a skill by id from skills.sh |
**Auth:** management session/API key. Marketplace search routes accept either management auth or a Bearer API key (`isAuthenticated`).
---
## Memory
Persistent conversational/factual memory store, scoped per API key / session.
| Method | Path | Description |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------ |
| GET | `/api/memory` | List memories — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, with `offset/limit` or `page/limit` pagination |
| POST | `/api/memory` | Create memory — body validated by Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET | `/api/memory/[id]` | Retrieve one memory |
| DELETE | `/api/memory/[id]` | Delete a memory |
| GET | `/api/memory/health` | Memory subsystem health (DB connectivity, embeddings backend, vector index status) |
**Auth:** management session/API key (`requireManagementAuth`). `type` enum: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (see `MemoryType` in `src/lib/memory/types.ts`).
---
## MCP Server
OmniRoute ships an embedded Model Context Protocol server with 3 transports (stdio, SSE, streamable-http) and scoped tools. The dashboard endpoints below read status/audit data and proxy the HTTP transports.
| Method | Path | Description |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Heartbeat, transport, online state, last call, top tools, 24h success rate |
| GET | `/api/mcp/tools` | List of MCP tools with `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
| GET | `/api/mcp/sse` | Open SSE stream for the SSE transport (returns `503` if MCP disabled or transport mismatch) |
| POST | `/api/mcp/sse` | Send JSON-RPC frame on the SSE transport |
| GET | `/api/mcp/stream` | Open SSE side of the Streamable HTTP transport (server-initiated messages) |
| POST | `/api/mcp/stream` | Send JSON-RPC frame on the Streamable HTTP transport |
| DELETE | `/api/mcp/stream` | End a Streamable HTTP session |
| GET | `/api/mcp/audit` | Query audit log — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | Aggregate audit stats (totals, success rate, avg duration, top tools) |
**Auth:** the `sse`/`stream` transports honor the MCP-specific auth surface (Bearer API key with `mcp` scope); the `status`/`tools`/`audit*` routes are readable from the dashboard (no extra auth required beyond reaching the dashboard host).
> Both HTTP transports are gated by `settings.mcpEnabled` and `settings.mcpTransport` — a transport mismatch returns `400`, an MCP disabled state returns `503`.
---
## A2A Server
OmniRoute exposes an A2A (Agent-to-Agent) JSON-RPC 2.0 endpoint plus a REST wrapper for inspection/dashboard use.
### JSON-RPC
```bash
POST /a2a
Authorization: Bearer your-api-key # optional unless OMNIROUTE_API_KEY is set
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "message/send",
"params": {
"skill": "smart-routing",
"messages": [{"role": "user", "content": "Route this coding task"}]
}
}
```
Supported methods (all gated on `settings.a2aEnabled`):
| Method | Description |
| ---------------- | ------------------------------------------------------------------ |
| `message/send` | Synchronous skill execution; returns `{task, artifacts, metadata}` |
| `message/stream` | Streaming SSE execution of the same skill set |
| `tasks/get` | Fetch a task by `taskId` |
| `tasks/cancel` | Cancel a task by `taskId` |
Built-in skills: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.
### Agent Card
```bash
GET /.well-known/agent.json
```
Returns the public A2A agent card (name, description, capabilities, skill catalog, auth scheme) — cached publicly for 1h. No auth required.
### REST helpers
| Method | Path | Description |
| ------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
| GET | `/api/a2a/status` | A2A enabled + task stats + cached agent card summary |
| GET | `/api/a2a/tasks` | List tasks — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST | `/api/a2a/tasks` | (Not implemented as a REST helper — create via JSON-RPC `message/send`) |
| GET | `/api/a2a/tasks/[id]` | Retrieve one task |
| POST | `/api/a2a/tasks/[id]/cancel` | Cancel a task |
**Auth:** the REST helpers run without management auth (dashboard-readable); the JSON-RPC `/a2a` route uses Bearer `OMNIROUTE_API_KEY` if configured.
---
## Cloud, Evals & Assess
| Method | Path | Description |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Verify a Bearer key and return masked provider connections + model aliases for cloud sync clients |
| POST | `/api/cloud/credentials/update` | Update encrypted credentials for a cloud-synced provider |
| POST | `/api/cloud/model/resolve` | Resolve a logical model id to a concrete provider/model using the local routing table |
| GET | `/api/cloud/models/alias` | List model aliases as exposed to cloud sync |
| GET | `/api/assess` | Read latest assessment categorizations (per-provider/model) |
| POST | `/api/assess` | Run an assessment — body: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | List built-in eval suites + most recent runs |
| POST | `/api/evals` | Trigger an eval run |
| POST | `/api/evals/suites` | Create a custom eval suite — body validated by `evalSuiteSaveSchema` |
| GET | `/api/evals/suites/[id]` | Retrieve a custom eval suite |
**Auth:** `/api/cloud/auth` validates a Bearer key directly and returns the masked key and `projectId` of each connection only for a key with the `manage` / `admin` scope; the other `/api/cloud/*`, `/api/evals/*`, and `/api/assess` routes require management session/API key. `/api/assess` POST uses `validateBody` with a discriminated-union scope schema.
---
## ACP (Agent Client Protocol) Management
as child processes. These endpoints manage ACP agent detection and custom agent
registration.
| Method | Path | Description |
| ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/acp/agents` | List all known CLI agents (built-in + custom) with installation status, version, binary |
| POST | `/api/acp/agents` | Register a custom ACP agent or refresh cache — body: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` or `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Remove a custom ACP agent — query param: `?id=<agentId>` |
**Response example** (`GET /api/acp/agents`):
```json
{
"agents": [
{
"id": "claude",
"name": "Claude Code CLI",
"binary": "claude",
"version": "1.0.45",
"installed": true,
"protocol": "stdio",
"providerAlias": "claude",
"isCustom": false
},
{
"id": "my-custom-cli",
"name": "My Custom CLI",
"installed": false,
"protocol": "stdio",
"providerAlias": "my-provider",
"isCustom": true
}
],
"cacheTtlMs": 60000,
"cacheAge": 1234
}
```
**Auth:** Requires management session (dashboard `auth_token` cookie) or a
management-scoped API key.
See [ACP Framework](../frameworks/ACP.md) for full details.
---
## Analytics & Observability
Real-time analytics endpoints for monitoring routing, compression, and provider
diversity. These power the `/dashboard/analytics/*` pages.
### Auto-routing analytics
| Method | Path | Description |
| ------ | ------------------------------------ | -------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/auto-routing` | Aggregate auto-routing stats: total calls, strategy distribution, tier distribution, top providers |
| GET | `/api/analytics/auto-routing?days=7` | Time-windowed stats (default 24h) |
**Response example**:
```json
{
"window": "24h",
"totalCalls": 1234,
"strategyBreakdown": {
"rules": 800,
"cost": 200,
"latency": 150,
"sla-aware": 50,
"lkgp": 34
},
"tierBreakdown": {
"ultra": 100,
"pro": 500,
"standard": 400,
"free": 234
},
"topProviders": [
{ "provider": "openai", "calls": 500, "avgLatencyMs": 850 },
{ "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 }
]
}
```
### Compression analytics
| Method | Path | Description |
| ------ | ---------------------------- | ------------------------------------------------------------------------------------- |
| GET | `/api/analytics/compression` | Aggregate compression stats: tokens saved, savings %, mode distribution, engine usage |
**Response example**:
```json
{
"window": "24h",
"totalOriginalTokens": 5000000,
"totalCompressedTokens": 3500000,
"totalSavings": 1500000,
"savingsPct": 30.0,
"modeBreakdown": {
"lite": 400,
"standard": 600,
"aggressive": 100,
"ultra": 50,
"rtk": 84
},
"engineBreakdown": {
"caveman": 800,
"rtk": 434
}
}
```
### Provider diversity tracking
| Method | Path | Description |
| ------ | -------------------------- | -------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/diversity` | Shannon entropy-based diversity tracking: prevents single points of failure by measuring provider spread |
**Response example**:
```json
{
"window": "24h",
"shannonEntropy": 2.45,
"maxEntropy": 3.17,
"diversityRatio": 0.77,
"providerUsage": {
"openai": 0.4,
"anthropic": 0.25,
"google": 0.2,
"kiro": 0.15
},
"warnings": ["OpenAI accounts for 40% of traffic — consider diversifying"]
}
```
**Auth:** Requires management session or management-scoped API key.
---
## Admin Operations
Admin-only endpoints for operational management.
| Method | Path | Description |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------- |
| GET | `/api/admin/concurrency` | Read current concurrency limits (global + per-provider) |
| POST | `/api/admin/concurrency` | Update concurrency limits — body: `{global?: number, perProvider?: Record<string, number>}` |
**Auth:** Requires management session with admin scope.
---
## CLI Tools Management
Manage CLI tools that integrate with OmniRoute (antigravity, commandCode,
devin-cli, etc.). See [Provider Reference](./PROVIDER_REFERENCE.md) for the full list.
| Method | Path | Description |
| ------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/cli-tools/all-statuses` | Status of all CLI tools (installed, version, last seen) |
| GET | `/api/cli-tools/status` | Status detail for one CLI tool (`?tool=` query) |
| POST | `/api/cli-tools/apply` | Write a tool's generated config (`dryRun` previews; `422` + `containerEphemeralTarget` when containerized; `migration` notes a legacy Codex YAML) |
| GET | `/api/cli-tools/backups` | List CLI tool configuration backups |
| POST | `/api/cli-tools/backups` | Create a backup of all CLI tool configurations |
| POST | `/api/cli-tools/backups` | Restore: same endpoint with `{tool, backupId}` in the body restores that backup |
| GET | `/api/cli-tools/antigravity-mitm` | Antigravity MITM proxy status (the "antigravity-mitm" CLI tool) |
| POST | `/api/cli-tools/antigravity-mitm/alias` | Configure antigravity-mitm aliases |
**Auth:** Requires management session.
---
## Agent Skills
Manage AI agent skills (similar to OpenAI's custom GPTs but for agents).
| Method | Path | Description |
| ------ | ---------------------------- | --------------------------------------------------------------------------------------- |
| GET | `/api/agent-skills` | List all agent skills (built-in + custom) |
| GET | `/api/agent-skills/[id]` | Get a specific agent skill |
| POST | `/api/agent-skills` | Create a custom agent skill — body: `{name, description, prompt, model?, temperature?}` |
| PUT | `/api/agent-skills/[id]` | Update a custom agent skill |
| DELETE | `/api/agent-skills/[id]` | Delete a custom agent skill |
| GET | `/api/agent-skills/[id]/raw` | Get raw prompt + metadata (no execution) |
| POST | `/api/agent-skills/generate` | AI-generate a new skill from a natural language description |
**Auth:** Requires management session or management-scoped API key.
---
## Cache Management
Manage the semantic cache and reasoning cache.
| Method | Path | Description |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------------- |
| GET | `/api/cache` | Cache overview: total entries, hit rate, size on disk |
| GET | `/api/cache/entries` | List cached entries (with pagination) |
| DELETE | `/api/cache/entries` | Delete cache entries (filter by query parameters) |
| GET | `/api/cache/stats` | Detailed cache statistics (per-provider, per-model) |
| GET | `/api/cache/reasoning` | Reasoning cache status (for reasoning replay) |
| DELETE | `/api/cache/reasoning` | Clear reasoning cache — query params: `?toolCallId=<id>` (single) or `?provider=<p>` or no params (all) |
**Auth:** Requires management session.
---
## Memory System
Manage persistent memory (FTS5 + vector embeddings).
| Method | Path | Description |
| ------ | ------------------ | ----------------------------------------------------------------------- |
| GET | `/api/memory` | List memory entries (filter by scope, type, search query) |
| POST | `/api/memory` | Create a new memory entry — body: `{scope, type, content, metadata?}` |
| GET | `/api/memory/[id]` | Get a specific memory entry |
| PUT | `/api/memory/[id]` | Update a memory entry |
| DELETE | `/api/memory/[id]` | Delete a memory entry |
| GET | `/api/memory?q=` | Search memory (FTS5 + vector) — stats are included in the same response |
**Auth:** Requires management session or management-scoped API key.
---
## Webhooks
Manage webhook subscriptions for events.
| Method | Path | Description |
| ------ | ------------------------------- | ------------------------------------------------------------------------- |
| GET | `/api/webhooks` | List all webhook subscriptions |
| POST | `/api/webhooks` | Create a webhook subscription — body: `{url, events[], secret?, active?}` |
| GET | `/api/webhooks/[id]` | Get a specific webhook subscription |
| PUT | `/api/webhooks/[id]` | Update a webhook subscription |
| DELETE | `/api/webhooks/[id]` | Delete a webhook subscription |
| GET | `/api/webhooks/[id]/deliveries` | List delivery history for a webhook (success/failure log) |
| POST | `/api/webhooks/[id]/test` | Send a test event to a webhook |
**Auth:** Requires management session.
See [Webhooks Framework](../frameworks/WEBHOOKS.md) for full event types.
---
## Skills Framework
Manage Skills (the agentic extensions framework).
| Method | Path | Description |
| ------ | ------------------------ | --------------------------------------------------------------------------------------- |
| GET | `/api/skills` | List all installed skills (built-in + custom) |
| POST | `/api/skills/install` | Install a skill from a local path or URL |
| DELETE | `/api/skills/[id]` | Uninstall a skill |
| PUT | `/api/skills/[id]` | Enable or disable a skill — body: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST | `/api/skills/executions` | Execute a skill — body: `{skillName, apiKeyId, input?, sessionId?}` |
| GET | `/api/skills/executions` | List execution history for all skills (filter by `?apiKeyId=`) |
**Auth:** Requires management session or management-scoped API key.
See [Skills Framework](../frameworks/SKILLS.md) for full details.
---
## Plugins
Manage OmniRoute plugins (third-party extensions).
| Method | Path | Description |
| ------ | ---------------------------------- | ------------------------------------- |
| GET | `/api/plugins` | List installed plugins |
| POST | `/api/plugins/marketplace/install` | Install a plugin from the marketplace |
| DELETE | `/api/plugins/[name]` | Uninstall a plugin |
| POST | `/api/plugins/[name]/activate` | Activate a plugin |
| POST | `/api/plugins/[name]/deactivate` | Deactivate a plugin |
| GET | `/api/plugins/[name]/config` | Get plugin configuration |
| PUT | `/api/plugins/[name]/config` | Update plugin configuration |
**Auth:** Requires management session.
See [Plugins Framework](../frameworks/PLUGIN_SDK.md) for full details.
---
## Shadow Routing
Shadow / A-B comparison of providers is **not a standalone REST surface** — it is configured through combo routing (see [Auto-Combo](../routing/AUTO-COMBO.md)). Per-combo comparison metrics are served by `GET /api/combos/metrics`.
---
## Guardrails
Inspect the runtime guardrails (PII detection, prompt injection detection, vision bridging). Guardrails run on every request; per-call opt-out is via the `x-omniroute-disabled-guardrails` request header — there is no persisted enable/disable surface.
| Method | Path | Description |
| ------ | ---------------------- | ---------------------------------------------------------------------------------------- |
| GET | `/api/guardrails` | List the registered guardrails and their status (name / enabled / priority) |
| POST | `/api/guardrails/test` | Dry-run the pre-call pipeline over a sample input — body: `{input, disabledGuardrails?}` |
**Auth:** Requires management session.
See [Security > Guardrails](../security/GUARDRAILS.md) for full details.
---
---
## Authentication
See [Management Authentication](../guides/MANAGEMENT-AUTH.md) for the four
credential families (dashboard session, local CLI token, `oma_live_…` Access
Token, manage-scoped API key) and how they differ from inference keys.
- Dashboard routes (`/dashboard/*`) use `auth_token` cookie
- Login uses saved password hash; fallback to `INITIAL_PASSWORD`
- `requireLogin` toggleable via `/api/settings/require-login`
- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true`
- "management token" / "management-scoped API key" in this reference means one of the families in that guide — not an undefined extra secret type
> **Breaking change (v3.8.0)** — `/api/v1/agents/tasks/*` and the cooldown management endpoints now require **management auth** (dashboard `auth_token` cookie or a management-scoped API key). Clients that previously called these routes unauthenticated will receive `401 Unauthorized`. See commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).