# API Reference (Igbo)

🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇧🇦 [bs](../../../bs/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)

---

🌐 **Asụsụ:** 🇺🇸 [Bekee](./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)

Ntụaka bụ isi maka OmniRoute API. Ọ na-akọwa elu ọhaneze `/v1` na ebe njedebe njikwa ndị a na-ejikarị eme ihe; [`docs/openapi.yaml`](../openapi.yaml) nke igwe nwere ike ịgụ na osisi ụzọ dị n'okpuru `src/app/api/` bụ isi mmalite zuru ezu.

Maka usoro nkwukọrịta dakọtara na OpenAI na matriks ikike ndị na-eweta ọrụ, lee
[`OPENAI_COMPATIBILITY.md`](./OPENAI_COMPATIBILITY.md).

---

## Ndepụta Ihe Dị N'ime

- [Mmecha Mkparịtaụka](#chat-completions)
- [Mgbazinye Oge Nnọkọ A Na-achịkwa Nanị Ya](#exclusive-managed-session-leases)
- [Embeddings](#embeddings)
- [Imepụta Onyonyo](#image-generation)
- [OCR Akwụkwọ](#document-ocr)
- [Ndepụta Ụdị](#list-models)
- [Manifest Ngwa Mgbakwunye Onye Na-eweta Ọrụ](#provider-plugin-manifest)
- [Ebe Njikọ Ndakọrịta](#compatibility-endpoints)
- [API Faịlụ](#files-api)
- [API Batches](#batches-api)
- [API Ọchụchọ](#search-api)
- [Mgbasa WebSocket](#websocket-streaming)
- [Kwọta & Ịkọ Nsogbu](#quotas--issues-reporting)
- [Cache Semantic](#semantic-cache)
- [Dashboard & Nchịkwa](#dashboard--management)
- [Nchịkwa Combo](#combo-management)
- [Webhooks](#webhooks)
- [Igodo E Debanyere Aha (Nchịkwa Akpaaka)](#registered-keys-auto-management)
- [Protocol Ndị Agent](#agents-protocol)
- [Proxies Nchịkwa](#management-proxies)
- [Ike Iguzogide Nsogbu (gbasawanyere)](#resilience-extended)
- [Nkà](#skills)
- [Ebe Ncheta](#memory)
- [Sava MCP](#mcp-server)
- [Sava A2A](#a2a-server)
- [Cloud, Evals & Assess](#cloud-evals--assess)
- [Nhazi Arịrịọ](#request-processing)
- [Nyocha Njirimara](#authentication)

---

## Mmecha Mkparịtaụka

```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
}
```

### Headers Ahaziri Ahazi

| Header                   | Ntụziaka  | Nkọwa                                                                                                                                                                                                              |
| ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `X-OmniRoute-No-Cache`   | Arịrịọ    | Tọọ ya ka ọ bụrụ `true` iji gafere cache                                                                                                                                                                           |
| `x-omniroute-no-memory`  | Arịrịọ    | Tọọ ya ka ọ bụrụ `true` iji kwụsị itinye ebe ncheta + nkà maka arịrịọ a (ọ na-eme ka no-cache; ọ na-ezere mgbakwunye token/ọnụahịa nke oku ọ bụla)                                                                 |
| `X-OmniRoute-Progress`   | Arịrịọ    | Tọọ ya ka ọ bụrụ `true` maka mmemme ọganihu                                                                                                                                                                        |
| `X-Session-Id`           | Arịrịọ    | Igodo nnọkọ na-adịgide maka njikọ nnọkọ mpụga                                                                                                                                                                      |
| `x_session_id`           | Arịrịọ    | A na-anabatakwa ụdị nwere akara underscore (HTTP ozugbo)                                                                                                                                                           |
| `X-OmniRoute-Session-Id` | Arịrịọ    | Akara nnọkọ/mkparịtaụka onye na-akpọ nyere (ọ na-enyekwa ebe ncheta ozi). Mgbe ọ dị, a na-echekwa ya kpọmkwem na `call_logs.session_tag` maka ịkọ ọnụahịa n'otu nnọkọ (#8249) — anaghị emepụta ya mgbe ọ na-adịghị |
| `Idempotency-Key`        | Arịrịọ    | Igodo iwepụ oyiri (oghere oge 5s)                                                                                                                                                                                  |
| `X-Request-Id`           | Arịrịọ    | Igodo iwepụ oyiri ọzọ                                                                                                                                                                                              |
| `X-OmniRoute-Cache`      | Nzaghachi | `HIT` ma ọ bụ `MISS` (na-enweghị mgbasa)                                                                                                                                                                           |
| `X-OmniRoute-Idempotent` | Nzaghachi | `true` ma ọ bụrụ na ewepụla oyiri                                                                                                                                                                                  |
| `X-OmniRoute-Progress`   | Nzaghachi | `enabled` ma ọ bụrụ na agbanyere nsuso ọganihu                                                                                                                                                                     |
| `X-OmniRoute-Session-Id` | Nzaghachi | ID nnọkọ dị irè nke OmniRoute ji mee ihe                                                                                                                                                                           |
| `X-OmniRoute-Request-Id` | Nzaghachi | ID njikọ arịrịọ (mgbe a maara ya)                                                                                                                                                                                  |
| `X-OmniRoute-Version`    | Nzaghachi | Ụdị build OmniRoute (ọ na-adị mgbe niile)                                                                                                                                                                          |
| `X-OmniRoute-Cost-Saved` | Nzaghachi | USD nke cache zere na HIT (naanị cache hits)                                                                                                                                                                       |
| `X-OmniRoute-Decision`   | Nzaghachi | Ndekọ ụzọ: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` bụ atụmatụ combo, ma ọ bụ `single` maka arịrịọ na-abụghị combo) — ọ na-adị mgbe niile na nzaghachi mmecha                                 |

> Ndetu Nginx: ọ bụrụ na ị dabere na headers nwere akara underscore (dịka ọmụmaatụ `x_session_id`), gbanye `underscores_in_headers on;`.

> **Nkụnye-isi telemetrị ọnụahịa:** nzaghachi ihe ịga nke ọma na-abụghị streaming na-ebukwa nchịkọta telemetrị ọnụahịa `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, ọnụọgụ ntụpọ 10 kwụ ọtọ; `0.0000000000` maka nke efu/nke a na-enyeghị ọnụahịa), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit`, na `X-OmniRoute-Fallback-Attempts` (naanị mgbe > 0), tinyere `X-OmniRoute-Request-Id` na `X-OmniRoute-Version`. Chat completions, `/v1/responses`, `/v1/messages`, **yana endpoints mgbasa ozi** na-ewepụta ha — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations`, na `/v1/moderations` (ọnụahịa ya bụ `0` mgbe niile). A na-agbakọ ọnụahịa mgbasa ozi dabere n'ụdị modality ọ bụla (kwa onyonyo, kwa sekọnd, kwa mkpụrụedemede, kwa nkeji ọchụchọ) mgbe ọnụahịa dị; ma ọ bụghị ya, ọ bụ `0` (fail-open).

> **Nkọwa ọnụahịa cache-hit:** mgbe semantic-cache bụ HIT (`X-OmniRoute-Cache-Hit: true`), a naghị akpọ upstream, ya mere `X-OmniRoute-Response-Cost` bụ `0.0000000000` (ọnụahịa **mgbakwunye** nke izipu hit ahụ). A na-akọ ọnụahịa mbụ/ọnụahịa ọ gaara abụ iche na `X-OmniRoute-Cost-Saved`. Ndị na-eji data ịgba ụgwọ kwesịrị ịchịkọta `X-OmniRoute-Response-Cost` (hits anaghị efu ego); nyocha cache nwere ike ịchịkọta `X-OmniRoute-Cost-Saved`.

## Ntinye Akwụkwọ Nnọkọ a na-achịkwa nke Pụrụ Iche

Ntinye akwụkwọ nnọkọ a na-achịkwa nke pụrụ iche (Exclusive managed session leasing) bụ nkwekọrịta ntụzịaka nke ntinye aka n'onwe ya, nke na-adịghị ele onye ahịa ọ bụla anya n'ihu: otu onye nwe ya na-arụ ọrụ na-ejide otu njikọ OmniRoute tozuru oke. Ọ naghị agbazite model, ọ naghị achọ OAuth, ọ naghị amata otu onye ahịa, ma ọ bụ chọọ otu onye na-enye ọrụ (provider) pụrụ iche.

Igodo API na-eme nkwenye ga-enwerịrị scope `lease:exclusive` na ndepụta `allowedConnections` doro anya nke na-abaghị uru. Oke mgbanwe nchekwa data na-amanye ubi abụọ ahụ ọnụ na mmepụta igodo na mmelite akụkụ ụfọdụ.

```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"}
```

Nzaghachi nweta (acquire), megharịa (renew), na hapụ (release) nke gara nke ọma na-egosipụta akara oge (timestamps), `state`, na `generation` ziri ezi, mana ọ dịghị mgbe ọ na-egosipụta njikọ ma ọ bụ nzere (credentials) ahọpụtara. Renew na release na-enye generation n'ime JSON body:

```json
{ "action": "renew", "generation": 1 }
```

```json
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
```

Onye nwe lease na-arụ ọrụ nwere ike ịrịọ metadata ngosipụta na-echekwa nzuzo n'ụzọ doro anya maka njikọ ya ugbu a:

```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"
  }
}
```

Omume ọkwa ntinye aka a bụ nke onye nwe ya na-adịghị ahụ anya (opaque owner), igodo API a kwadoro, na ọgbọ (generation) na-arụ ọrụ ziri ezi gbachiri gburugburu n'ime otu azụmahịa nchekwa data. `displayName` bụ naanị aha njikọ ahaziri ahazi nke a kpụchara akpụcha; ọ bụ `null` mgbe ọ dịghị aha ahaziri ahazi dị mma dị. OmniRoute anaghị eji email ma ọ bụ njirimara akaụntụ emepụtara dochie anya ya. Uru provider bụ akara ngosipụta na-adịghị emetụ n'ahụ ma ọ bụghị njirimara compatible-provider emepụtara. Ewepụrụ nzere (credentials), tokens, cookies, njikọ raw ma ọ bụ id igodo API, hash ndị nwe ya, ihe nzuzo fencing, na data ntụzịaka ime n'ime.

Nchọgharị igodo na-ezighi ezi, onye nwe ya na-ezighi ezi, ọgbọ merela ochie (stale-generation), nke na-efu efu, nke kubiela ume, nke a tọhapụrụ, na nke emebiri emebi niile na-eweghachi otu njehie `409 LEASE_FENCE_STALE` na-enweghị metadata njikọ. Onye ahịa natara nzaghachi nchere ikike (capacity-wait) enweghị njikọ na-arụ ọrụ ọ ga-enyocha. Mgbe ntụzịaka na-agbanwe lease na-arụ ọrụ, otu ọgbọ ahụ na-anọgide na-adị irè ma ọkwa na-eweghachi njikọ ọhụrụ ahụ ozugbo, ọ dịghị mgbe ọ na-eweghachi nke ochie. Ndị ahịa dị adị na-anọgide n'agbanweghị agbanwe n'ihi na acquire, renew, release, na nzaghachi nchere na-ejigide ụdị ha mbụ.

Nkwekọrịta sava a anaghị agbanwe OpenAI Codex `/status` nke nkịtị. Codex nkịtị na-akọ ugbu a model provider ya na ọnọdụ nkwenye/akaụntụ arụnyere n'ime ya mana ọ naghị egosipụta metadata akaụntụ onye na-enye ọrụ ọ bụla; njikọ onye ahịa mechara ga-akpọ omume a ma kpebie otu a ga-esi gosipụta `connection.displayName`.

Arịrịọ nkwubi okwu (inference request) ọ bụla a na-achịkwa na-enyezi header njikwa abụọ ahụ:

```http
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
```

Onye nwe ya ziri ezi, ọgbọ, njikọ na-arụ ọrụ, na igodo API a kwadoro ka a na-agbachi gburugburu ozugbo tupu nnwale upstream ọ bụla akwadoro. Iji onye nwe ya na ọgbọ ọzọ nwere igodo ọzọ na-ada ada ọbụlagodi mgbe igodo ahụ kwere ka otu njikọ ahụ. A naghị echekwa ndị nwe raw, na-edeba ha na log, na-ejigide ha na snapshot arịrịọ, ma ọ bụ na-eziga ha na upstream.

Esemokwu nwa oge na-eweghachi HTTP `429` yana `Retry-After` na:

```json
{
  "state": "WAITING_FOR_CAPACITY",
  "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
  "reason": "NO_FREE_ELIGIBLE_CONNECTION",
  "retryAfter": 30
}
```

Nzaghachi a pụtara naanị na usoro tozuru oke nkịtị abụghị nke efu na onye ọ bụla nwere ike ịbụ onye nwe lease ọzọ na-arụ ọrụ na-ejide ya. Model/provider anaghị akwado, enweghị nkwekọrịta iwu, oge izu ike (cooldown), quota, ahụike, na ọdịda ntozu nkịtị ndị ọzọ na-ejigide nzaghachi OmniRoute ha dị adị.

### `x-omniroute-compression`

Nkagbu atụmatụ mkpakọ (compression plan) maka arịrịọ ọ bụla. Ibu ụzọ kachasị elu — ọ na-emeri nkagbu routing-combo, profile na-arụ ọrụ, auto-trigger, na Default nke panel. Uru ndị a:

| Uru           | Mmetụta                                                                                                                        |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `off`         | Enweghị mkpakọ maka arịrịọ a.                                                                                                  |
| `default`     | Profile Default sitere na panel (na-eleghara profile na-arụ ọrụ anya). A hapụrụ injin ndị na-atụfu data (lossy engines) n'èzí. |
| `safe`        | Mwepụ oyiri (Dedup) na mpịakọta ohere efu (whitespace folding) naanị.                                                          |
| `allow-lossy` | Debe atụmatụ onye ọrụ maka arịrịọ a, gụnyere nchịkọta na idegharị ụdị.                                                         |
| `engine:<id>` | Otu injin mgbe agbanyere ya, dịka ọmụmaatụ `engine:rtk`. Ntinye aka maka arịrịọ ọ bụla maka injin ahụ.                         |
| `<combo>`     | Combo nwere aha, nke a na-ejikọta site na aha (anaghị ele mkpụrụedemede ukwu/obere anya) na mbụ, emesịa site na id.            |

Ihe rịba ama:

- A na-eleghara uru ndị a na-amaghị anya (anaghị ajụ arịrịọ ahụ); mkpebi na-adaba na ibu ụzọ onye ọrụ nkịtị.
- Ọ bụrụ na ọtụtụ combo nwere otu aha, nyefee combo **id** maka njikọ doro anya.
- Combo nke aha ya bụ `off` ma ọ bụ `default` enweghị ike ịhọrọ site na aha (a na-ebu ụzọ kọwaa mkpụrụokwu ndị ahụ); zoo aka na combo dị otú ahụ site na id ya.
- Mgbanwe mkpakọ master bụ ọnụ ụzọ siri ike: mgbe agbanyụrụ mkpakọ n'ụwa niile, header a enweghị ike ịgbanye ya.

A na-egosipụta atụmatụ etinyere n'ime header nzaghachi:

```
X-OmniRoute-Compression: <mode>; source=<source>
```

ebe `<source>` bụ otu n'ime `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, ma ọ bụ `off`.

---

## Ntụnye

```bash
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "nebius/Qwen/Qwen3-Embedding-8B",
  "input": "The food was delicious"
}
```

Ndị na-enye ọrụ dị: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.

NJ katalọgụ bụ `provider/model` (ọmụmaatụ: `jina-ai/jina-embeddings-v5-omni-small`). NJ ụdị Jina na-enweghị aha onye na-enye ọrụ, ndị pụtara na ndekọ ahụ (dịka ọmụmaatụ `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`), na-arụkwa ọrụ. Ọrụ embed/rerank/classify/segment nke Jina na-ebu ụzọ jiri ozi nzere `jina-ai` dị na dashboard; a na-eji `JINA_AI_API_KEY` naanị dịka nhọrọ ndabere mgbe enweghị igodo dashboard. Kaadị `jina-reader` bụ naanị maka Reader / `r.jina.ai` (`POST /v1/web/fetch`), ọ naghị enye embeddings ma ọ bụ rerank ma ọlị.

Ụdị dị na ndekọ ndị na-egosi na ha na-akwado multimodal na-anabatakwa ihe ndị ahaziri n'ụdị na-anọpụtaghị onye na-enye ọrụ, ruo ihe 32.
Ụdị ihe mgbasa ozi bụ `text`, `image`, `audio`, `video`, na `document`. `source` nke mgbasa ozi ha
bụ ma `{"type":"url","url":"https://..."}` ma ọ bụ
`{"type":"base64","data":"...","media_type":"..."}`.

Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`,
na aha nnọchi ezinụlọ `jina-ai/jina-embeddings-v5-omni` → omni-small) na-anabatakwa docs EmbeddingsV5Request nke Jina n'onwe ya ma **na-ebuga ha n'enweghị mgbanwe** na `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,..." }]
    }
  ]
}
```

Ụkpụrụ `{ image | audio | video | pdf }` nke sistemụ ahụ n'onwe ya nwere ike ịbụ URL HTTPS ọha, URI `data:`, ma ọ bụ base64
na-enweghị nhazi ọzọ. OmniRoute anaghị agbanwe ihe ndị ahụ ka ha bụrụ eriri ma ọ bụ budata URL onyonyo nke sistemụ ahụ n'onwe ya — Jina na-ewepụta
mgbasa ozi ọha n'onwe ya. A na-ebuga mpaghara Jina ndị ọzọ (`task`, `normalized`, `truncate`, `embedding_type`).
SKU Jina ndị bụ naanị ederede ka na-ajụ docs ndị na-abụghị ederede.

Oke nchekwa na mbufe:

- URL mgbasa ozi dị anya ga-abụrịrị HTTPS ọha. A na-ebudata ihe `{type,source:url}` canonical
  n'akụkụ sava (nyochaghachi ntụgharị, oge nchere, oke nha, DNS ọha, na ịkpọgide njikọ) ma
  tinye ha n'ime arịrịọ tupu akpọọ onye na-enye ọrụ. A na-ebuga ihe `{image:"https://..."}` nke Jina n'onwe ya dịka ha dị
  mgbe emechara otu nyocha HTTPS ọha ahụ; Jina na-ebudata URL ahụ.
- Mgbasa ozi base64 e tinyere n'ime arịrịọ nwere oke 8 MiB mgbe a tọghatara ya n'otu ihe, yana 16 MiB mgbe a tọghatara ihe niile dị n'arịrịọ ahụ.

Ntughari maka onye na-enye ọrụ (anaghị ebuga ihe canonical n'enweghị mgbanwe):

- Ụdị multimodal nke Jina: ihe ọ bụla dị n'ọkwa kacha elu na-aghọ otu ihe nke e ji igodo modality hazie
  (`text` / `image` / `audio` / `video` / `pdf`), na-eji URI data maka mgbasa ozi e tinyere n'ime arịrịọ; otu vector maka
  ihe ọ bụla dị n'ọkwa kacha elu.
- Ezinaụlọ Gemini Embedding 2: otu array dị n'ọkwa kacha elu na-aghọ otu arịrịọ sistemụ ahụ n'onwe ya
  `models/{model}:embedContent`, nke nwere `content.parts` (`text` ma ọ bụ `inline_data`).
- llama.cpp (`llama-cpp/<model>`, ụdị ọ bụla sava mpaghara tinyere): ihe `text` canonical
  na-aghọ eriri nkịtị, ebe `image` / `audio` / `video` nke ọ bụla na-aghọ otu ihe
  `{"content": [part]}`, na-eji akụkụ ọdịnaya chat nke llama-server (`image_url`,
  `input_audio` nwere usoro `wav` / `mp3` / `flac`, `input_video`) yana data e tinyere n'ime ya; otu vector
  maka ihe ọ bụla dị n'ọkwa kacha elu. Sava ahụ ga-eji `--embedding --mmproj …` rụọ ọrụ; ma ọ bụrụ na enweghị projector,
  ọ ga-ajụ mgbasa ozi n'onwe ya. A naghị akwado `document`.
- Ụdị ndị amaghị/dynamic na-enweghị metadata modality doro anya na-ajụ input ahaziri n'ụdị site na 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"
}
```

Ngwakọta ụdị/modality ndị a na-akwadoghị na-eweghachi HTTP 400 kama ịmanye mgbanwe n'ihe ahụ. Mpaghara ndọtị ndị na-abụghị input
dị na arịrịọ string/token ochie ka na-agafe n'enweghị mgbanwe.

```bash
# Depụta ụdị embedding niile
GET /v1/embeddings
```

---

## Mmepụta Onyonyo

```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"
}
```

Ndị na-eweta ọrụ dịnụ gụnyere OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, **ZenMux**, SD WebUI (nke mpaghara), ComfyUI (nke mpaghara).

`n` na-eweghachi onyonyo `n` n'ime `data[]`. Maka ndị na-eweta ọrụ nke API ha dị n'elu na-eweghachi otu onyonyo n'otu oku
(Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik,
NVIDIA NIM, Cloudflare Workers AI), a na-akpọ API ha dị n'elu ugboro `n`, ma ọ bụghị karịa oku 4 na-aga n'otu oge. A
na-agbakwunye ndeksi oku na `seed` edobere (`seed`, `seed + 1`, …), ka onyonyo ndị ahụ wee dị iche ma nọgide
na-enwe ike imepụtaghachi otu nsonaazụ ahụ. Oke `n` bụ 10. Arịrịọ ahụ dum ga-ada ma ọ bụrụ na oku ọ bụla adaa. Ndepụta
usoro fan-out dị na `SINGLE_IMAGE_FANOUT_FORMATS` n'ime
`open-sse/handlers/imageGeneration/fanOut.ts`.

ZenMux na-eji njikọ API-key dị ugbu a eme ihe ọzọ ma na-anabata nganiihu `zenmux/` ma ọ bụ `zm/`:

- `zenmux/openai/gpt-image-2` na-eji OpenAI Images API nke ZenMux. Nhọrọ gụnyere `size`,
  `quality`, `n`, `output_format`, `output_compression`, `background`, na `response_format`.
- Ndị mbipụta ndị ọzọ, dịka `zm/meta/muse-image-1.0`, na-eji endpoint `:predict`
  nke Vertex AI nke ZenMux. `n` na-adaba na `sampleCount`, `aspect_ratio` na `aspectRatio`, ebe `image_size`
  (`1K`, `2K`, `4K`) na-adaba na `sampleImageSize`. `size` pikselụ na-enye naanị oke akụkụ,
  ọ naghị ekwe nkwa nha pikselụ. Oke akụkụ, mkpebi onyonyo, na ọnụọgụ ndị a na-akwado na-adị iche dịka model si dị.
- `zm/inclusionai/ming-image-0.1-design` na-ahọrọ nha nke ya. Ahapụla `size`,
  `aspect_ratio`, na `image_size`; ụkpụrụ e nyere kpọmkwem ga-eweghachi HTTP 400. Enwere ike ịrịọ PNG, JPEG, na WebP
  site na `output_format`.

Njikọ a na-akwado imepụta onyonyo site na ederede, ọ bụghị idezi onyonyo ntụaka. A na-ahazi
nsonaazụ Vertex ka ọ bụrụ `data[].b64_json`; `response_format: "url"` na-eweghachi URL HTTPS
nke dị n'elu ma ọ bụ URL data base64 mgbe naanị bytes onyonyo dị. Nsonaazụ efu/azachapụrụ
na-eweghachi mperi kama ihe ịga nke ọma efu. Ịnweta model dabere na akaụntụ ZenMux.
Lee [Vertex API nke ZenMux](https://docs.zenmux.ai/api/vertexai/generate-images) na
[OpenAI Images API](https://docs.zenmux.ai/api/openai/generate-an-image).

```bash
# Depụta model onyonyo niile
GET /v1/images/generations
```

---

## OCR Akwụkwọ

```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` na-ahọrọ onye na-eweta OCR site na mbido `provider/model`; id ụdị nke kwụụrụ onwe ya (dịka
`mistral-ocr-latest`) na-ejikọta na onye na-eweta ya e debanyere aha, ma ọ bụrụ na ahapụrụ `model`, ndabara ya bụ
Mistral (`mistral-ocr-latest`). Ndị na-eweta e debanyere aha (`open-sse/config/ocrRegistry.ts`):

| Id onye na-eweta              | Id ụdị               | Uru `model`                                                       | Nkọwa                                                                                                                       |
| ----------------------------- | -------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `mistral`                     | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (ma ọ bụ naanị `mistral-ocr-latest`) | Mekọrịta ozugbo — a na-eweghachi nzaghachi ozugbo site n'otu oku upstream ahụ.                                              |
| `azure-document-intelligence` | `prebuilt-read`      | `azure-document-intelligence/prebuilt-read`                       | Upstream anaghị arụkọ ọrụ ozugbo (`analyze` + nyocha ugboro ugboro) — lee n'okpuru.                                         |
| `vertex-deepseek-ocr`         | `deepseek-ocr-maas`  | `vertex-deepseek-ocr/deepseek-ocr-maas`                           | Mekọrịta ozugbo, site na endpoint onye mmekọ `openapi/chat/completions` nke Vertex AI — lee n'okpuru maka nyocha ikike/URL. |

Ndị na-eweta ọrụ atọ ahụ niile na-azaghachi n'ime body nwere nhazi Mistral yiri ibe ha:

```json
{
  "pages": [{ "index": 0, "markdown": "# Extracted text..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}
```

### Usoro nyocha ugboro ugboro nke Azure Document Intelligence

API `analyze` nke Azure Document Intelligence anaghị arụkọ ọrụ ozugbo: arịrịọ mbụ na-eweghachi
header `Operation-Location` kama body, a ga-enyochakwa nsonaazụ ya ugboro ugboro. Handler ahụ
(`open-sse/handlers/ocr.ts`) na-enyocha URL ahụ kwa sekọnd ruo mbọ 30, kwụsị ozugbo (ọ
gaghị anọgide na-enyocha) ma ọ bụrụ na nzaghachi nyocha abụghị `ok` ma ọ bụ ọkwa bụ `"failed"`, ma na-eweghachi `504` ma ọ bụrụ na
ọrụ ahụ ka na-aga n'ihu mgbe ọnụọgụ mbọ e nyere gwụsịrị. A na-ahazi nzaghachi ikpeazụ nke Azure
ka ọ bụrụ otu nhazi `pages`/`markdown` nke Mistral na-eji tupu e weghachiri ya nye
onye kpọrọ ya, ya mere koodu client agaghị achọ ijikwa onye na-eweta ọrụ ahụ n'ụzọ pụrụ iche.

### Nnyocha ikike na mkpebi endpoint nke Vertex AI DeepSeek OCR

`vertex-deepseek-ocr` na-eji otu nyocha ikike Vertex AI ahụ OmniRoute kwadoro ugbua maka
okporo ụzọ chat/onyonyo (`open-sse/executors/vertex.ts`): API key nke njikọ ahụ bụ ma
credential JSON nke Service Account (nke a gbanwere ka ọ bụrụ token nnweta OAuth dị mkpụmkpụ site na usoro JWT-bearer)
ma ọ bụ token nnweta OAuth emepụtarala nke a na-eji dịka ọ dị. URL endpoint upstream bụ endpoint
onye mmekọ `openapi/chat/completions` izugbe nke Vertex, nke e ji project na
region nke njikọ ahụ wuo — `providerSpecificData.project`/`providerSpecificData.region` e kọwara kpọmkwem na-ebute ụzọ mgbe niile;
ma ọ bụghị ya, a na-enweta project site na `project_id` dị na JSON nke Service Account, ebe region
na-eji `us-central1` dịka ndabara. Mkpebi abụọ ahụ na-eme na `open-sse/handlers/ocr.ts`
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`), nke
`src/app/api/v1/ocr/route.ts` na-eji tupu iziga ya na `handleOcr`.

---

## Depụta Model Ndị Dị

```bash
GET /v1/models
Authorization: Bearer your-api-key

→ Na-eweghachi model nkata, embedding, na onyonyo niile + ngwakọta ha n'ụdị OpenAI
```

### Prefix id model (`?prefix=`)

A na-egosipụta ọtụtụ model n'okpuru **prefix onye na-enye ọrụ**. Ọ bụ feature flag
`MODELS_CATALOG_PREFIX_MODE` na-achịkwa prefix ị ga-enweta, a pụkwara iji query parameter
gbanwee ya **maka request ọ bụla** — nke a bara uru maka client chọrọ ndepụta dị ọcha n'ebughị
ntọala server niile maka onye ọ bụla ọzọ:

```bash
GET /v1/models?prefix=alias        # otu id maka model ọ bụla — prefix alias dị mkpụmkpụ
GET /v1/models?prefix=dual         # ụdị abụọ ahụ (ndabara server)
GET /v1/models?prefix=canonical    # naanị prefix provider-id zuru ezu
```

| Ọnọdụ       | Ihe ọ na-ewepụta                                         | Nkọwa                                                                                                                                                                                                      |
| ----------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual`      | `cc/claude-sonnet-4-6` **na** `claude/claude-sonnet-4-6` | **Ndabara.** Id abụọ ahụ na-eduga n'otu model ahụ; e debere ha ka nhazi client ndị tinyere otu n'ime ụdị ndị ahụ ozugbo nọgide na-arụ ọrụ. Ọ fọrọ nke nta ka ọ mụbaa katalọgụ okpukpu abụọ.                |
| `alias`     | `cc/claude-sonnet-4-6`                                   | Otu ntinye maka model ọ bụla. Ndị na-enye ọrụ na-enweghị alias pụrụ iche ka na-ewepụta ntinye ha, ya mere ọ dịghị ihe na-efu.                                                                              |
| `canonical` | `claude/claude-sonnet-4-6`                               | Otu ntinye maka model ọ bụla n'okpuru prefix provider-id zuru ezu. Ndị na-enye ọrụ na-enweghị alias pụrụ iche (dịka `antigravity/…`, `agy/…`) na-ewepụtakwa naanị id ha ebe a, ya mere ọ dịghị ihe na-efu. |

A pụkwara ịmata mirror nọ n'ọnọdụ `dual` na-enweghị query parameter: ọ nwere field `parent`
na-arụtụ aka na id bụ isi.

Client ndị na-egosi ebe ịhọrọ model kwesịrị ịrịọ `?prefix=alias` — nke a bụ ihe
[OmniCopilot VS Code extension](../guides/VSCODE-COPILOT.md) na-eme.

### Model nkata zoro ezo n'otu n'otu

A na-ewepụ model e nyere akara **Hidden** na peeji onye na-enye ya na katalọgụ, a ga-ajụkwa ya
site na HTTP `404` / `model_not_found` mgbe a rịọrọ ya kpọmkwem. Nlele ahụ na-eji onye na-enye ọrụ
na model e kpebisiri ike, gụnyere alias ndị na-enye ọrụ, prefix node nke compatible-provider, na
ndabara njikọ. Ngwakọta na-amafe target ndị zoro ezo ma nwee ike iji sibling a na-ahụ anya; mgbe ọ dịghị
target enwere ike imezu fọdụrụ, ọ na-eweghachi otu error code ahụ. Iwepụ izo ya na-amalite ịrụ ọrụ na
request na-esote. Mgbanwe visibility maka naanị onyonyo anaghị ezobe model nkata nwere otu ID ahụ.

Ntọala model nke otu a dị iche na
[ndepụta model exposure nke ikwe/gbochie](../routing/MODEL_EXPOSURE_LIST.md), nke na-enyocha mgbasa ozi
katalọgụ na ndị ga-ahọpụta maka auto-routing ma na-edobe iziga kpọmkwem. Ikikere model nke API-key
na-aga n'ihu ịrụ ọrụ n'onwe ya. Ọnọdụ prefix katalọgụ ndabara ka bụ `dual`.

### Ụdị model na-enweghị thinking

Maka model Claude nwere ikike thinking, `/v1/models` na-egosikwa ụdị **no-thinking** nke id ya ji `claude-3-omniroute-no-thinking/` malite:

```
claude-3-omniroute-no-thinking/<provider>/<model>
```

Ịhọrọ id a (dịka ọmụmaatụ, na nhazi Claude Code nke na-etinye block `thinking` mgbe niile) na-edughachi na ezigbo `<provider>/<model>` ebe a kwụsịrị reasoning — `thinking:{type:"disabled"}` n'ụzọ `/v1/messages`, ma ọ bụ wepụ field `reasoning`/`reasoning_effort` n'ụzọ `/v1/chat/completions`. A na-edepụta ụdị a naanị maka model ezinụlọ Claude ndị na-akwado thinking **ma** na-asọpụrụ `disabled` (ya mere, dịka ọmụmaatụ, a na-ewepụ model adaptive-only ndị na-ajụ `disabled`). Ndị na-ahụ maka sistemụ nwere ike iji `ModelSpec.noThinkingAlias` manye ụdị a ka ọ dị ọkụ ma ọ bụ gbanyụọ maka model ọ bụla.

---

## Manifest Ngwa Mgbakwunye Onye Na-enye Ọrụ

```bash
GET /api/v1/provider-plugin-manifest
```

Ọ na-eweghachi manifest JSON dị nchebe nke ngwa mgbakwunye onye na-enye ọrụ nke Bifrost, CLIProxyAPI, na ndị rawụta sidecar n'ọdịnihu na-eji. A na-emepụta nzaghachi ahụ site na ndekọ ndị na-enye ọrụ TypeScript, ma kpachapụ anya wepụ ihe nzuzo ndị ahịa OAuth, mkpebi gburugburu ebe a na-arụ ọrụ, ọrụ ndị mmezu, nkụnye isi arịrịọ, na data akaụntụ.

Jiri endpoint a mgbe sidecar na-arụ ọrụ n'èzí usoro ma ọ nweghị ike ibubata
`open-sse/config/providerPluginManifestRegistry.ts` ozugbo.

---

## Ebe Ngwụcha Ndakọrịta

| Usoro | Ụzọ                                       | Ọdịdị                                    |
| ----- | ----------------------------------------- | ---------------------------------------- |
| 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 (mmezi/inpaint)            |
| POST  | `/v1/videos/generations`                  | Mmepụta vidio n'ụdị OpenAI               |
| POST  | `/v1/music/generations`                   | Mmepụta egwu n'ụdị OpenAI                |
| POST  | `/v1/audio/transcriptions`                | OpenAI Audio (STT)                       |
| POST  | `/v1/audio/speech`                        | OpenAI TTS (na-eweghachi ahụ ọdịyo)      |
| POST  | `/v1/rerank`                              | Nhazigharị ọkwa n'ụdị Cohere/Voyage      |
| POST  | `/v1/classify`                            | Nkewasị Jina (`api.jina.ai`)             |
| POST  | `/v1/segment`                             | Onye nkewa Jina (`segment.jina.ai`)      |
| POST  | `/v1/moderations`                         | OpenAI Moderations                       |
| GET   | `/v1/models`                              | OpenAI                                   |
| 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}/`                 | Utu aha ọzọ nke katalọgụ OpenAI          |
| GET   | `/api/v1/vscode/{token}/models`           | Utu aha ọzọ nke ụdị OpenAI               |
| POST  | `/api/v1/vscode/{token}/chat/completions` | Utu aha ọzọ OpenAI nwere token           |
| POST  | `/api/v1/vscode/{token}/responses`        | Utu aha ọzọ OpenAI Responses nwere token |
| POST  | `/api/v1/vscode/{token}/api/chat`         | Utu aha ọzọ Ollama nwere token           |
| GET   | `/api/v1/vscode/{token}/api/tags`         | Utu aha ọzọ mkpado Ollama nwere token    |

Ụzọ POST niile na-agbaso otu nhazi ahụ: `Bearer your-api-key` + ahụ JSON nke Zod kwadoro (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, wdg., lee `src/shared/validation/schemas.ts`). A na-eweghachi 4xx ma ọ bụrụ na nkwado schema ada.

Maka ndị ahịa na-enweghị ike itinye `Authorization: Bearer ...`, OmniRoute na-anabatakwa igodo API n'ime URL site na ndakọrịta query-string (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) ma ọ bụ site na ebe njedebe `/api/v1/vscode/{token}/...` pụrụ iche akọwara n'okpuru.

```bash
# Nhazigharị ọkwa (onye na-eweta ndekọ igwe ojii, ma ọ bụ node onye na-eweta dakọtara na OpenAI dị ka "<prefix>/<model>")
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Nkewasị Jina (ozi nzere Foundation API)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Onye nkewa Jina
POST /v1/segment     { "content": "...", "return_chunks": true }

# Ọchụchọ Jina (s.jina.ai; utu aha ndị na-eweta: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# Nnyocha ọdịnaya
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — na-eweghachi ahụ audio/mpeg (ma ọ bụ ọdịdị a rịọrọ)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Soniox TTS chọrọ asụsụ na olu: `language` na-eji "en" dịka ndabara; olu na-adịghị
# ma ọ bụ aha olu ọkọlọtọ OpenAI (alloy, nova, …) na-aghọ "Adrian"
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }

# Mmezi onyonyo (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Mmepụta vidio / egwu (NJ ụdị nke nwere nganiihu onye na-eweta)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }
```

> **Node ndị na-eweta nhazigharị ọkwa:** `POST /v1/rerank` na-edugakwa arịrịọ gaa na node ndị na-eweta dakọtara na OpenAI
> (oMLX, vLLM, Infinity, TEI dị n'azụ gateway, …) nke a na-akpọ dị ka `<node-prefix>/<model>`. Node loopback
> (`localhost`, `127.0.0.1`, `172.16.0.0/12`) na-eru eru mgbe niile, otu ahụkwa ka hostname ndị
> onye njikwa depụtara na `OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS` (dịka aha ọrụ Docker/Compose
> dịka `http://reranker:8080/v1`; a na-akpọ ndị a ozugbo, ọ bụghị site na `HTTP(S)_PROXY` ma ọ bụ
> proxy e kegidere na njikọ). Node dị na host ọ bụla ọzọ
> — igbe LAN ma ọ bụ Tailscale peer — na-eru eru naanị mgbe onye njikwa gbanyere ọkọlọtọ atụmatụ
> `RERANK_REMOTE_PROVIDER_NODES` **ma** URL ntọala node ahụ gafere iwu URL mpụga nke onye na-eweta
> (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`).
> Nzọụkwụ nhazigharị ọkwa nke injin ebe nchekwa na-akpọ ụzọ a site na
> loopback, ya mere otu iwu ahụ na-achịkwa `rerankProviderModel` na ntọala Memory.
>
> **Nhazi sava mpaghara:** a na-akpọ node ahụ na `<base>/v1/rerank`, ma ọ bụrụ na ọ bụ 404, na `<base>/rerank`
> (Infinity, TEI). Ahụ upstream na-ebu ma nsụpe Cohere/OpenAI (`documents`,
> `return_documents`) ma nsụpe TEI (`texts`, `return_text`), a na-ahazikwa nzaghachi upstream
> ka ọ bụrụ envelopu Cohere: ndepụta nkịtị TEI `[{index, score, text}]`, `{results: [{index, score}]}`
> sitere na gateway ndị dị mfe, na ụdị Voyage `{data: [...]}` na-alaghachikwuru onye ahịa dịka
> `{results: [{index, relevance_score, document?}]}`, nke a haziri site na akara ma kpachie na `top_n`.

> **Nchọpụta ọnụ provider:** ụdịdị dị n’otu ọnụ provider dakọtara na OpenAI na-apụta na `GET /v1/models`
> n’okpuru prefix ọnụ ahụ. Ahịrị ndị na-enweghị metadata endpoint (dị ka ọ na-adịkarị na ndepụta `/v1/models` mpaghara)
> na-eketa `apiType` nke ọnụ ahụ, ya mere ụdịdị ọnụ `embeddings` bụ `type: "embedding"` ebe
> ụdịdị ọnụ `rerank` bụ `type: "rerank"` kama ịlaghachi na chat dịka ndabara; `supportedEndpoints` akọwapụtara
> n’ahịrị emekọrịtara ma ọ bụ nke ejiri aka tinye ka na-ebute ụzọ.

### Ụzọ Provider Pụrụ Iche

```bash
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
```

A na-agbakwunye prefix provider na-akpaghị aka ma ọ bụrụ na ọ dịghị. Ụdịdị na-adakọghị na-eweghachi `400`.

---

## Files API

Ebe njedebe faịlụ kwekọrọ na OpenAI maka ntinye/mmepụta n'ìgwè na nbugo faịlụ dịka ebumnuche ha si dị.

| Usoro  | Ụzọ                      | Nkọwa                                                                                                          |
| ------ | ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/files`              | Bulite faịlụ (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — kacha 512 MiB |
| GET    | `/v1/files`              | Depụta faịlụ maka igodo API e ji nyochaa njirimara                                                             |
| GET    | `/v1/files/[id]`         | Nweta metadata nke faịlụ                                                                                       |
| DELETE | `/v1/files/[id]`         | Hichapụ faịlụ                                                                                                  |
| GET    | `/v1/files/[id]/content` | Zighachi ọdịnaya faịlụ ahụ kpọmkwem dịka iyi data                                                              |

**Nyocha njirimara:** Igodo API Bearer — a na-ekewa faịlụ n'ogo igodo API site na `getApiKeyRequestScope`. Otu igodo
na-ahụ, na-ebudata ma na-ehichapụ naanị faịlụ nke ya; nnọkọ dashboard na-enweghị igodo na-agụ
instance ahụ niile; a na-ajụ onye ọ bụla na-akpọ oku na-abụghị site na nnọkọ ohere ịnweta faịlụ na-enweghị onye nwe ya (nke onye amaghị aha ma ọ bụ nke e bulitere site na nnọkọ dashboard).
`GET /v1/files` na-ajụ onye na-akpọ oku n'amaghị aha — yana igodo e nyere nke a na-enweghị ike
ịchọpụta — site na `401` ọbụlagodi mgbe `REQUIRE_API_KEY=false`, kama idepụta faịlụ nke ndị tenant
niile (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

## Batches API

Nhazi batch nke dakọtara na OpenAI.

| Usoro  | Ụzọ                       | Nkọwa                                                                                                         |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/batches`             | Mepụta batch — a na-eji `v1BatchCreateSchema` enyocha body (`input_file_id`, `endpoint`, `completion_window`) |
| GET    | `/v1/batches`             | Depụta batches                                                                                                |
| GET    | `/v1/batches/[id]`        | Nweta ọnọdụ batch + `request_counts`                                                                          |
| DELETE | `/v1/batches/[id]`        | Hichapụ batch nke mechara/daa                                                                                 |
| POST   | `/v1/batches/[id]/cancel` | Kagbuo batch a ka na-ahazi                                                                                    |

**Nnyocha ikike:** Bearer API key. A na-ekewa batches n’otu API key n’okpuru otu iwu ụzọ atọ ahụ dịka
faịlụ: naanị key nke onye nwe ya, nnọkọ dashboard nwere ikike n’ofe instance niile, a na-ajụkwa onye ọ bụla
na-abụghị onye na-akpọ site na nnọkọ ịnweta ndekọ null-owner (ịnweta, ihichapụ, ịkagbu, yana nyocha `input_file_id` mgbe a na-emepụta).
`GET /v1/batches` na-eji `401` ajụ onye na-akpọ na-enweghị njirimara ọbụna mgbe `REQUIRE_API_KEY=false`.

---

## API Ọchụchọ

Nchịkọta abstraction maka ndị na-eweta ọchụchọ/webụ (Tavily, Brave, Exa, Serper, wdg.).

| Usoro | Ụzọ                    | Nkọwa                                                                                |
| ----- | ---------------------- | ------------------------------------------------------------------------------------ |
| GET   | `/v1/search`           | Depụta ndị na-eweta ọchụchọ ahaziri + ikike ha                                       |
| POST  | `/v1/search`           | Mee ajụjụ ọchụchọ — `v1SearchSchema` na-enyocha body, ọ na-akwado caching/coalescing |
| GET   | `/v1/search/analytics` | Ọnụọgụ hit/latency/cache nke onye na-eweta ọ bụla                                    |

**Nyocha njirimara:** Bearer API key (`extractApiKey` + `isValidApiKey`). A na-amanye iwu ọchụchọ site na `enforceApiKeyPolicy`.

---

## Web Fetch API

Wepụta ọdịnaya site na URL site n’aka onye na-eweta ọrụ web-fetch ahaziri (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

| Usoro | Ụzọ             | Nkọwa                                                         |
| ----- | --------------- | ------------------------------------------------------------- |
| POST  | `/v1/web/fetch` | Weta/hichapụ ọdịnaya URL — `v1WebFetchSchema` na-enyocha body |

**Nkwenye:** Igodo API Bearer (`extractApiKey` + `isValidApiKey`). A na-amanye iwu site na `enforceApiKeyPolicy`.

**Ndaghachi azụ na-eburu oke n’uche (#8297):** mgbe enyeghị `provider` kpọmkwem, a na-agafe pool ahụ
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) n’usoro
mkpa edoziri
(fill-first) — a na-awụli onye na-eweta ọrụ ahaziri mana oke arịrịọ gbochiri ya
kama ịkwụsị arịrịọ ahụ ozugbo, ọdịda upstream a pụrụ ịnwale ọzọ/nke metụtara oke
(HTTP 429 mgbe niile; 402/403 maka ọkwa efu ndị nwere ụdị oke nke Firecrawl/Tavily/TinyFish —
ọ bụghị maka Jina Reader, ọ dịghịkwa mgbe ọ bụ arịrịọ ọjọọ 400 nkịtị) na-aga n’ihu ruo
onye na-eweta ọrụ ọzọ nwere nzere nke a na-anwalebeghị n’oge arịrịọ ahụ. Mgbe ndị na-eweta ọrụ niile dị na
pool agwụla, endpoint ahụ na-eweghachi naanị otu `429` (nwere header `Retry-After`)
kama `400` izugbe nke mbụ. Mgbe a rịọrọ `provider` kpọmkwem,
**enweghị** ndaghachi azụ zoro ezo — onye na-eweta ọrụ kpọmkwem nke oke arịrịọ gbochiri ma ọ bụ nke dara
na-egosi njehie nke ya (`429` ma ọ bụrụ na oke arịrịọ gbochiri ya, ma ọ bụghị ya, status
upstream).

---

## Mgbasa WebSocket

```bash
GET /v1/ws?handshake=1
```

Na-enyocha handshake nkwalite WebSocket ma weghachite ozi atụ nke protocol wire (`request`, `cancel`). Sava WS agbakwunyere, nke dị n’èzí tebụl route Next.js, na-ahụ maka frame WS ndị ahụ n’ezie.

**Nkwenye:** Igodo API Bearer n’oge handshake.

### Responses API site na WebSocket (naanị codex)

```bash
# Otu host:port ahụ nke HTTP API (ndabara 20128); kwalite njikọ ahụ:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (ma ọ bụ: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Frame mbụ GA-ABỤRỊRỊ response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```

E jikọtara proxy Responses-API-over-WebSocket **naanị na `codex`** (backend ChatGPT).
Ọ na-ege ntị n’otu port ahụ API/dashboard ji, n’ụzọ `/v1/responses`,
`/responses`, na `/api/v1/responses`. N’elu frame `response.create` mbụ, ọ
na-eme nkwenye + nkwadebe site na bridge `codex-responses-ws` dị n’ime, họrọ
njikọ OAuth codex, ma mepụta tunnel gaa `wss://chatgpt.com/backend-api/codex/responses`
site na transport `wreq-js`. **A na-ajụ model ndị na-abụghị codex** (`codex_ws_provider_required`).
Maka routing nkekọ oke, jiri `model: "qtSd/<group>/codex/<model>"`. E mejuputara ya na
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.

**Nkwenye:** Igodo API Bearer n’oge handshake. Sava HTTP agbakwunyere (`server-ws.mjs`)
ga-abụrịrị entrypoint na-arụ ọrụ (ọ bụ ya na ndabara mgbe `app/server-ws.mjs` dị).

#### NJ model: jiri NJ ChatGPT nkịtị (enweghị prefix `codex/`)

OpenAI **Codex CLI** na-enyocha aha model n’akụkụ client mgbe
`supports_websockets = true`, ma **na-ajụ NJ nwere prefix onye na-eweta ọrụ** dịka
`codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`). Zipu NJ **nkịtị** (dịka `gpt-5.5`). Bridge OmniRoute bụ
naanị maka codex, ya mere ọ na-ekpebi ọzọ na NJ nkịtị bụ model codex
(`resolveCodexWsModelInfo`) tupu o mepụta tunnel gaa upstream — n’agbanyeghị na
`gpt-5.5` nkịtị ga-aga onye na-eweta ọrụ ọzọ site na HTTP ma ọ bụghị ya.

#### Ịhazigharị OpenAI Codex CLI

Duzie Codex CLI na OmniRoute site n’ịtinye onye na-eweta ọrụ omenala nwere nkwado
WebSocket na `~/.codex/config.toml` (jiri `CODEX_HOME` dị iche ka ị ghara imetụ
config dị ugbu a aka):

```toml
model = "gpt-5.5"                 # NJ nkịtị — Ọ BỤGHỊ "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # enweghị slash n’azụ; a na-ewepụta URL WS site na ya (jiri https/wss na production)
wire_api = "responses"                    # naanị value a na-akwado kemgbe Feb 2026
supports_websockets = true                # na-eme ka transport Responses-over-WS rụọ ọrụ
env_key = "OMNIROUTE_API_KEY"             # na-ejide igodo API OmniRoute (Bearer)
```

```bash
export OMNIROUTE_API_KEY=sk-...           # igodo API OmniRoute (igodo ọ bụla ma ọ bụrụ na REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```

CLI na-akwalite `base_url + /responses` ka ọ bụrụ WebSocket, OmniRoute wee mepụta tunnel ya
gaa na njikọ OAuth codex ahọpụtara. E nyochara ya site na mmalite ruo na njedebe megide sava
mpaghara: ChatGPT na-eweghachi `codex.rate_limits` + `response.created` ma na-agbasa
mmecha ahụ.

---

## Oke ojiji & Ịkọ nsogbu

| Usoro | Ụzọ                 | Nkọwa                                                                                    |
| ----- | ------------------- | ---------------------------------------------------------------------------------------- |
| GET   | `/v1/quotas/check`  | Buru ụzọ nyochaa oke ojiji maka `provider` + `accountId` tupu inye igodo e debanyere aha |
| POST  | `/v1/issues/report` | Kọọrọ GitHub ọdịda nke oke ojiji/inye igodo (chọrọ `GITHUB_ISSUES_REPO` + token)         |

**Nyocha ikike:** Igodo API Bearer (`isAuthenticated`).

---

## Ojiji nke onwe (`/api/usage/om-usage`)

Igodo API ọ bụla nwere ike ịgụ ojiji na oke **nke ya** — enweghị njirimara njikwa. Nke a bụ endpoint nke
client (CLI, panel OmniCopilot) na-eji egosi onye ji igodo ego ole o mefuru.

```bash
# Ụdị ederede (nkwekọrịta mbụ — ederede nkịtị maka terminal)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Ụdị ahaziri ahazi — nke UI na-eji
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"
```

Igodo ahụ ga-enwerịrị **`allowUsageCommand`** agbanyere (a na-agbanyụ ya na ndabara — onye njikwa
igodo API nke dashboard na-agbanye ma ọ bụ gbanyụọ ya maka igodo ọ bụla). Na-enweghị ya, endpoint ahụ na-aza `403`.

`?format=json` na-eweghachi ụdị e ji ihe dị iche mara ka onye kpọrọ ya ghara ịgụ field data n'ime
ọjụjụ. Mgbe ọ gara nke ọma:

```jsonc
{
  "allowed": true,
  // ọ na-adị naanị mgbe igodo ahụ họọrọ oke ojiji kwa igodo (USD kwa ụbọchị/izu):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // snapshot oke provider ahọpụtara, ma ọ bụ null mgbe ọ dịghị ihe echekwara na cache:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // snapshot nke connection ọ bụla, ka UI nwee ike igosi ọtụtụ provider n'akụkụ ibe ha:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}
```

Mgbe a jụrụ ya (`401` igodo na-adịghị mma / `403` enyeghị ikike), route ahụ na-eweghachi
`{ "allowed": false, "error": { "message": "…" } }` — `personal`/`provider` dị ma bụrụ ihe efu
(enyere igodo ikike, mana ọ mụtabeghị ihe ọ bụla) bụ ọnọdụ dị iche na ọjụjụ, naanị ụdị JSON
na-amata ọdịiche ha.

**Auth:** igodo Bearer API nke onye kpọrọ ya n'onwe ya, nke `isValidApiKey` kwadoro — nke a _abụghị_
ebe njikwa (`/api/keys/…`), nke `requireManagementAuth` ka na-echebe.

### Pasent Oke Raw na Nke E Doziri Site na Cutoff

Mgbe ha na-eji `/api/usage/om-usage`, ndị na-akpọ ya kwesịrị ịma ọdịiche dị n'etiti pasent ndị
**mmepụta plain-text** na **mmepụta JSON** ahaziri ahazi na-egosi:

| Akụkụ                  | Ụdị plain-text (`/api/usage/om-usage` / `@@om-usage`)                                   | Ụdị JSON (`?format=json`)                                                                |
| :--------------------- | :-------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
| **Field mmepụta**      | `NN% left` (dịka ọmụmaatụ, `20% left`)                                                  | `provider.quotas` / `providers[].quotas`                                                 |
| **Ntụle**              | **Oke ojiji e doziri site na cutoff**: ikike fọdụrụ n'elu akara cutoff                  | **Oke upstream raw**: ntụle provider a na-edozighị                                       |
| **Mgbakọ cutoff**      | E ji `effectiveRemainingPercent()` mee mgbakọ ka mpaghara echekwara gụọ dị ka `0% left` | Ọ dịghị (ụkpụrụ snapshot raw dịka provider siri kọọ ha)                                  |
| **Data akara oke**     | E tinyere ya na pasent egosiri                                                          | E chekwara ya na `quotaWindowThresholds` maka connection ọ bụla (ma ọ bụ ndabara server) |
| **Onye isi na-eji ya** | CLI mmekọrịta, prompt terminal, ndị ọrụ mmadụ                                           | Njikọ mmemme, dashboard, nyocha data, ndị na-esochi ịkwụ ụgwọ                            |

#### Usoro Mgbakọ Ndozi Cutoff

OmniRoute na-akwado cutoff oke a na-eme tupu oge eruo iji gbochie oke upstream ịgwụ (a na-ahazi ya site na
`quotaWindowThresholds` nke connection, ndabara provider, ma ọ bụ ntọala resilience zuru ụwa ọnụ). Mgbe akara cutoff
(dịka ọmụmaatụ, `cutoff = 25%`) na-arụ ọrụ na windo oke, onye na-emepụta ederede na-agbakọ ikike fọdụrụ dịka:

- Ọ bụrụ na `remaining <= cutoff`: ọ na-eweghachi `0%`.
- Ọ bụrụ na `remaining > cutoff`: ọ na-eweghachi `((remaining - cutoff) / (100 - cutoff)) * 100`.

Mpụpụta ederede a haziri na-eme ka nke a ruo n'ọnụọgụ zuru ezu kacha nso (`Math.round(...)`).

#### Ihe Nlereanya

Tụlee windo provider nwere **ojiji raw 60%** (ya mere **oke raw fọdụrụ 40%**) yana akara
**cutoff nke oke fọdụrụ 25%** ahaziri:

| Ngosipụta                     | Mgbakọ                                             | Nke Fọdụrụ |               Ojiji A Na-atụ Aka Ya               |
| :---------------------------- | :------------------------------------------------- | :--------: | :-----------------------------------------------: |
| **JSON raw (`?format=json`)** | Snapshot upstream (`quotas[window]`)               |  **40%**   |                      **60%**                      |
| **Ụdị ederede (`NN% left`)**  | `((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100` |  **20%**   | **80%** (ọ bụrụ na a na-agbakọ `100 - remaining`) |

- **Ihe mere ederede ji egosi 20% fọdụrụ:** N'ime oke physical 40% fọdụrụ n'akaụntụ ahụ, iwu
  cutoff debere 25%. Onye kpọrọ ya nwere naanị 15% n'ime 75% ohere eji eme ihe fọdụrụ tupu router ahụ akwụsị
  iziga arịrịọ na connection a. Mgbakọ ahụ na-eme ka connection gosi na oke agwụla (`0% left`) kpọmkwem mgbe
  routing ga-akwụsị.
- **Ihe mere JSON ji echekwa ụkpụrụ raw:** Payload JSON na-eweghachi snapshot provider kpọmkwem (`UsageSnapshot`)
  ka ngwaọrụ mpụga nwee ike ịhụ ojiji upstream bụ eziokwu na
  `quotaWindowThresholds` nke ọkwa connection na-enweghị mgbakọ server na-ebelata izi ezi.

#### Nduzi Maka Mbugharị Ndị Na-eji Ya

Ọ bụrụ na njikọ mpụga (dịka plugin editor ma ọ bụ extension agent) na mbụ na-anakọta data site na endpoint
ederede (`NN% left`) ma gbakọọ pasent e jiri dị ka `100 - NN`, ịkwaga na `?format=json` pụtara:

- Ịgụ ụkpụrụ JSON raw ga-egosi **ojiji upstream n'ezie** (60% e jiri mee ihe n'ihe nlereanya dị n'elu).
- Ọ bụrụ na njikọ ahụ chọrọ idowe nkọwa ikike eji eme ihe nke endpoint ederede, ọ nwere ike ịgbakọ
  usoro effective remaining n'akụkụ client site n'iji `quotaWindowThresholds` maka mgbanwe nke ọkwa connection.

---

## Cache Semantic

```bash
# Nweta ọnụ ọgụgụ cache
GET /api/cache/stats

# Hichapụ cache niile
DELETE /api/cache/stats
```

Ọmụmaatụ nzaghachi:

```json
{
  "semanticCache": {
    "memorySize": 42,
    "memoryMaxSize": 500,
    "dbSize": 128,
    "hitRate": 0.65
  },
  "idempotency": {
    "activeKeys": 3,
    "windowMs": 5000
  }
}
```

### Mmetụta n'oge nzaghachi

Mgbe semantic cache HIT mere, ọ na-enye nzaghachi sitere na cache **na-enweghị ịkpọ
upstream**, ya mere `X-OmniRoute-Response-Latency` a kọọrọ na-adị nso na efu
(n'agbanyeghị oge nzaghachi upstream mbụ). Ndị client oge nzaghachi na-emetụta
(benchmarking, nlekota p50/p99) kwesịrị ịlele header nzaghachi
`X-OmniRoute-Cache-Latency`:

| Uru         | Ihe ọ pụtara                                                       |
| ----------- | ------------------------------------------------------------------ |
| `synthetic` | Enyere nzaghachi site na cache; oge ahụ abụghị oge upstream n'ezie |
| _(adịghị)_  | Nzaghachi sitere na oku upstream n'ezie                            |

### Ịgafe cache maka igodo ọ bụla

Igodo API nwere ike ịhọrọ ịghara ịgụ semantic cache site na `cacheDefaultMode`:

| Uru      | Omume                                               |
| -------- | --------------------------------------------------- |
| `legacy` | Omume cache nkịtị (ndabara)                         |
| `bypass` | Mafee nchọ cache kpamkpam; kpọọ upstream mgbe niile |

Tọọ ya mgbe a na-emepụta igodo (`POST /api/keys`) ma ọ bụ na-emelite ya (`PATCH /api/keys/[id]`):

```json
{ "cacheDefaultMode": "bypass" }
```

### Ịgafe cache maka arịrịọ ọ bụla

Arịrịọ ọ bụla nwere ike ịgafe cache n'agbanyeghị ntọala igodo:

```
X-OmniRoute-No-Cache: true
```

---

## Dashboard & Njikwa

Ụzọ njikwa (`/api/*` ewezuga auth/login ọha) anaghị anabata ikike sitere na
API keys nkịtị maka inference. Maka ụdị credential, scopes, na ihe atụ curl, lee:
[Otentikeshọn Njikwa](../guides/MANAGEMENT-AUTH.md).

### Otentikeshọn

| Endpoint                      | Usoro   | Nkọwa                    |
| ----------------------------- | ------- | ------------------------ |
| `/api/auth/login`             | POST    | Banye                    |
| `/api/auth/logout`            | POST    | Pụọ                      |
| `/api/settings/require-login` | GET/PUT | Gbanwee ma achọrọ ịbanye |

### Njikwa Provider

| Endpoint                                | Usoro                     | Nkọwa                                                                                                                                                                   |
| --------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/providers`                        | GET/POST                  | Depụta / mepụta providers                                                                                                                                               |
| `/api/providers/[id]`                   | GET/PUT/DELETE            | Jikwaa otu provider                                                                                                                                                     |
| `/api/providers/[id]/test`              | POST                      | Nwalee njikọ provider                                                                                                                                                   |
| `/api/providers/[id]/models`            | GET                       | Depụta models nke provider                                                                                                                                              |
| `/api/providers/validate`               | POST                      | Nyochaa ma config provider ziri ezi                                                                                                                                     |
| `/api/providers/bulk`                   | POST                      | Tinye ọtụtụ API keys maka OTU provider                                                                                                                                  |
| `/api/providers/import`                 | POST                      | Bubata NDEPỤTA providers dị iche iche site na faịlụ CSV/JSON a tụgharịrị (#6836); nsonaazụ ọdịda akụkụ n'ahịrị ọ bụla                                                   |
| `/api/provider-nodes*`                  | Dị iche iche              | Njikwa node provider                                                                                                                                                    |
| `/api/provider-models`                  | GET/POST/PUT/PATCH/DELETE | Models ahaziri iche na mgbanwe pụrụ iche maka model ọ bụla (tinye, melite, zoo/gosi, hichapụ)                                                                           |
| `/api/provider-models/validate-and-add` | POST                      | Nyocha njikọ siri ike nke chọrọ otentikeshọn njikwa ma a ga-ahọrọ iji ya, tinyere ndebanye custom-model n'ụzọ atomic; lee [Nyocha model](../guides/MODEL-VALIDATION.md) |

Maka models e mekọrịtara/e bubatara, `PUT /api/provider-models` na-anabata `provider`, `modelId`, na
`maxOutputTokenOverride`: integer dị mma na-edobe oke output-token nke aka, ebe `null`
na-ehichapụ ya iji weghachite ndabara. `GET /api/provider-models?provider=<provider>` na-eweghachi
ụkpụrụ ndị a n'ime `modelOutputOverrides`, gụnyere models na-enweghị ahịrị custom-model. Mgbanwe ahụ
na-eji ikike runtime `max_output_tokens` ma na-adịgide ọbụna mgbe e mekọrịtara model ọzọ. Peeji provider dakọtara na OpenAI
na-enye otu njikwa ndezi/nwepụ ahụ ma na-akara models nwere nkwado vision akọwapụtara nke ọma.

Nodes Custom Chat Completions na-eme ka ịjụ reasoning akọwapụtara kwekọọ na backend dị n'elu. Nnwale
njikọ gara nke ọma na-ahọrọ njikwa chat-template na-akpaghị aka maka model ID ọ bụla kpọmkwem
nke ntinye ya na `/models` gosiri ụkpụrụ `owned_by` a ma ama: `vllm`, `sglang`, ma ọ bụ `llamacpp`.
Wrappers dakọtara na OpenAI ma doo anya nwere ike idobe ntinye model mbụ n'ime object
`openai` dị n'ime; nchọpụta na-esochi ruo envelopes atọ dị otú ahụ. Models nwere ownership na-efu, a na-amaghị,
ma ọ bụ na-emegiderịta onwe ya na-edobe omume OpenAI nkịtị. Nchọpụta na-eji arịrịọ catalog dị adị ọzọ,
anaghị emepụta completion tokens, a na-emekwa ka ọ ghara ịdị irè mgbe endpoint njikọ gbanwere.

Iji kpọchie omume ahụ maka backend na-adịghị egosipụta metadata ahụ, jiri API mmelite provider
akụkụ dị adị:

```json
{
  "providerSpecificData": {
    "reasoningControl": "chat-template"
  }
}
```

Ziga body ahụ site na `PUT /api/providers/<connection-id>`. Na njikọ ahụ, a na-eziga
reasoning effort akọwapụtara dị ka `none` n'ụdị `chat_template_kwargs.thinking=false` na
`chat_template_kwargs.enable_thinking=false`. Ụkpụrụ native template akọwapụtara ka bụ ndị kacha nwee ikike
ọ gwụla ma iwu reasoning dị n'akụkụ server manyere otu effort. Ntọala ahụ na-emetụta naanị mgbe njikọ
ahaziri iche nke dakọtara na OpenAI na-eziga body Chat Completions; arịrịọ Responses na providers nkịtị
na-edobe ọdịdị arịrịọ native ha. Tọọ `reasoningControl` ka ọ bụrụ `openai` iji manye OpenAI nkịtị
ka o bufee `reasoning_effort` n'enweghị mgbanwe, ma ọ bụ hapụ ya/tọọ ya ka ọ bụrụ `null` iji nchọpụta akpaka.

Arịrịọ klasifaya auto-mode nke Claude Code na-eme ka ndabara native thinking bụrụ nke agbanyụrụ mgbe ha enweghị
njikwa reasoning ọ bụla akọwapụtara. Nchọpụta na-eji akara sistemụ nke klasifaya dị n'arịrịọ
usoro Claude, ọ bụghị aha model ma ọ bụ oke completion. Njikwa body akọwapụtara, headers effort/thinking
a na-akwado, iwu routing, na model effort e kpebiri na-edobe mkpa mbụ ha dị ugbu a. Usoro klasifaya
abụọ ahụ na-edobe prompts ha, oke completion, stop sequences, na mkpebi ikike upstream
ezigbo; usoro nke abụọ ka nwere ike iwepụta reasoning a na-ahụ anya ọ rịọrọ dị ka ederede nkịtị.

### Usoro OAuth

| Endpoint                         | Method       | Description                     |
| -------------------------------- | ------------ | ------------------------------- |
| `/api/oauth/[provider]/[action]` | Dị iche iche | OAuth akọwapụtara maka provider |

### Routing & Nhazi

| Endpoint              | Method       | Description                     |
| --------------------- | ------------ | ------------------------------- |
| `/api/models/alias`   | GET/POST     | Aha nnọchi model                |
| `/api/models/catalog` | GET          | Model niile dịka provider + ụdị |
| `/api/combos*`        | Dị iche iche | Njikwa combo                    |
| `/api/keys*`          | Dị iche iche | Njikwa API key                  |
| `/api/pricing`        | GET          | Ọnụahịa model                   |

### Ojiji & Nnyocha

| Endpoint                         | Method          | Description                                                                                                                                                                                                                                                                            |
| -------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history`             | GET             | Akụkọ ihe mere eme nke ojiji                                                                                                                                                                                                                                                           |
| `/api/usage/logs`                | GET             | Ndekọ ojiji                                                                                                                                                                                                                                                                            |
| `/api/usage/request-logs`        | GET             | Ndekọ n'ogo arịrịọ                                                                                                                                                                                                                                                                     |
| `/api/usage/[connectionId]`      | GET             | Ojiji nke njikọ ọ bụla                                                                                                                                                                                                                                                                 |
| `/api/usage/token-limits`        | GET/POST/DELETE | Mmefu oke token maka API key ọ bụla                                                                                                                                                                                                                                                    |
| `/api/usage/model-latency-stats` | GET             | Nchịkọta latency na-aga n'ihu maka provider/model ọ bụla (avg/p50/p95/p99, ọnụego ihe ịga nke ọma); nzacha: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873)                                                                                                            |
| `/api/usage/cache-health`        | GET             | Nchịkọta ahụike prompt-cache n'elu `call_logs` — oke write/read, nkesa nha write p50/p90/p99, mkpokọta heavy-write, nkewa nke model ọ bụla, na mkpebi `healthy`/`degraded`/`thrash`/`no-data`; query params `range` (`1h`\|`24h`\|`7d`\|`30d`, ndabara `24h`) na `model` nhọrọ (#8827) |

### Ikike API key

`PATCH /api/keys/{id}` na-emelite ikike key dị adị. Dịka route `/api/keys*` ọ bụla, ọ chọrọ ikike njikwa (lee [Nnyocha njirimara maka njikwa](../guides/MANAGEMENT-AUTH.md)), ọ bụghị inference key. Zipụ naanị fields ịchọrọ ịgbanwe; a ga-ajụ arịrịọ na-enweghị nke ọ bụla n'ime ha site na `No valid fields to update`. `updateKeyPermissionsSchema` dị na `src/shared/validation/schemas/keys.ts` na-akọwa fields a na-anabata.

| Field                                       | Type                                                                  | Notes                                                                                                                                |
| ------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `name`                                      | eriri, mkpụrụedemede 1-200                                            |                                                                                                                                      |
| `isActive`                                  | boolean                                                               |                                                                                                                                      |
| `isBanned`                                  | boolean                                                               |                                                                                                                                      |
| `expiresAt`                                 | ụbọchị na oge ISO 8601 ma ọ bụ `null`                                 | `null` na-ewepụ oge ngwụcha                                                                                                          |
| `modelAccessMode`                           | `all` \| `restricted`                                                 | `allowedModels` ga-abụrịrị ihe tọgbọ chakoo mgbe ọnọdụ ahụ bụ `all`                                                                  |
| `allowedModels`, `blockedModels`            | n'usoro eriri, ruo 1000                                               |                                                                                                                                      |
| `allowedCombos`                             | n'usoro eriri, ruo 500                                                | Na-achịkwa combos ndị key ahụ nwere ike ịkpọ; `modelAccessMode` / `allowedModels` na-achịkwa models kpọmkwem                         |
| `connectionAccessMode`                      | `all` \| `restricted`                                                 | `allowedConnections` agaghị abụ ihe tọgbọ chakoo mgbe ọ bụ `restricted`, ọ ga-abụkwa ihe tọgbọ chakoo mgbe ọ bụ `all`                |
| `allowedConnections`                        | n'usoro UUID, ruo 100                                                 |                                                                                                                                      |
| `allowAutoCombos`                           | boolean                                                               | `false` na-ajụ arịrịọ maka models `auto/*` ji key a; a na-ekwe ka keys ndị na-edobebeghị ya                                          |
| `catalogScope`                              | `all` \| `combos` \| `models`                                         | Ihe `GET /v1/models` na-edepụta maka key a (naanị combos, naanị models, ma ọ bụ ha abụọ); ọ naghị agbanwe ihe key ahụ nwere ike ịkpọ |
| `noLog`, `autoResolve`                      | boolean                                                               |                                                                                                                                      |
| `throttleDelayMs`                           | integer, 0-300000                                                     |                                                                                                                                      |
| `maxSessions`                               | integer, 0-10000                                                      |                                                                                                                                      |
| `rateLimits`                                | n'usoro `{ limit, window }` (integer ziri ezi, ruo 50) ma ọ bụ `null` | `null` na-ewepụ oke ndị ahụ                                                                                                          |
| `accessSchedule`                            | schedule object ma ọ bụ `null`                                        | `null` na-ewepụ schedule ahụ                                                                                                         |
| `scopes`                                    | n'usoro eriri, ruo 32                                                 |                                                                                                                                      |
| `allowedEndpoints`                          | n'usoro eriri, ruo 20                                                 |                                                                                                                                      |
| `streamDefaultMode`                         | `legacy` \| `json`                                                    |                                                                                                                                      |
| `cacheDefaultMode`                          | `legacy` \| `bypass`                                                  | Hụ [Ịgafe cache maka key ọ bụla](#per-key-cache-bypass)                                                                              |
| `compressionEnabled`                        | boolean                                                               |                                                                                                                                      |
| `codexServiceMode`                          | otu n'ime ọnọdụ ọrụ Codex                                             |                                                                                                                                      |
| `disableNonPublicModels`                    | boolean                                                               |                                                                                                                                      |
| `allowUsageCommand`                         | boolean                                                               |                                                                                                                                      |
| `usageLimitEnabled`                         | boolean                                                               |                                                                                                                                      |
| `dailyUsageLimitUsd`, `weeklyUsageLimitUsd` | number >= 0 ma ọ bụ `null`                                            |                                                                                                                                      |
| `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" }'
```

### Ntọala

| Endpoint                              | Method        | Nkọwa                                                                                                                                                                                            |
| ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/settings`                       | GET/PUT/PATCH | Ntọala izugbe                                                                                                                                                                                    |
| `/api/settings/proxy`                 | GET/PUT       | Nhazi proxy netwọkụ                                                                                                                                                                              |
| `/api/settings/proxy/test`            | POST          | Nwalee njikọ proxy                                                                                                                                                                               |
| `/api/settings/ip-filter`             | GET/PUT       | Ndepụta IP ndị e kwere/ndepụta ndị egbochiri                                                                                                                                                     |
| `/api/settings/thinking-budget`       | GET/PUT       | Ụdị idegharị **request** maka iche echiche/ịtụgharị uche (passthrough / auto-strip / custom / adaptive). Ọ nọọrọ onwe ya na compression. Lee [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). |
| `/api/settings/system-prompt`         | GET/PUT       | System prompt zuru ụwa ọnụ                                                                                                                                                                       |
| `/api/settings/compression`           | GET/PUT       | Nhazi compression zuru ụwa ọnụ                                                                                                                                                                   |
| `/api/settings/purge-request-history` | POST          | Hichapụ ahịrị ndekọ request na artifact ndekọ oku mpaghara                                                                                                                                       |

### Context & Compression

| Endpoint                               | Method         | Nkọwa                                                                 |
| -------------------------------------- | -------------- | --------------------------------------------------------------------- |
| `/api/compression/preview`             | POST           | Hụchalụ compression off/lite/standard/aggressive/ultra/RTK/stacked    |
| `/api/compression/language-packs`      | GET            | Depụta mkpọ asụsụ Caveman dị                                          |
| `/api/compression/rules`               | GET            | Depụta metadata iwu Caveman                                           |
| `/api/context/caveman/config`          | GET/PUT        | Aha nnọchi ntọala pụrụ iche nke Caveman                               |
| `/api/context/rtk/config`              | GET/PUT        | Ntọala pụrụ iche nke RTK, gụnyere filter custom na njigide raw-output |
| `/api/context/rtk/filters`             | GET            | Katalọgụ filter RTK na nchọpụta nsogbu filter custom                  |
| `/api/context/rtk/test`                | POST           | Mee nhụchalụ/nnwale RTK megide payload ederede                        |
| `/api/context/rtk/raw-output/[id]`     | GET            | Gụọ raw output e degharịrị e dekwara site na pointer id               |
| `/api/context/combos`                  | GET/POST       | Ndepụta/mepụta ngwakọta compression                                   |
| `/api/context/combos/[id]`             | GET/PUT/DELETE | Nkọwa/mmelite/nhichapụ ngwakọta compression                           |
| `/api/context/combos/[id]/assignments` | GET/PUT        | Kenye ngwakọta compression na ngwakọta routing                        |
| `/api/context/analytics`               | GET            | Aha nnọchi analytics compression                                      |

### Nlekọta

| Endpoint                             | Usoro      | Nkọwa                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions`                      | GET        | Nsochi nnọkọ ndị na-arụ ọrụ                                                                                                                                                                                                                                                                                                                                                                               |
| `/api/rate-limits`                   | GET        | Oke ọnụego maka akaụntụ ọ bụla                                                                                                                                                                                                                                                                                                                                                                            |
| `/api/monitoring/health`             | GET        | Nnyocha ọnọdụ + nchịkọta ndị na-eweta ọrụ (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Nlele njikwa gụnyere `credentialHealth`: ụkpụrụ nyocha-cache, `failedConnections` mgbe `failed>0`, na `staleDbNonOkCount` (`test_status` SQLite na-adịgide, ọ bụghị ihe nlele). Lee [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). |
| `/api/cache/stats`                   | GET/DELETE | Ọnụọgụ cache / hichapụ                                                                                                                                                                                                                                                                                                                                                                                    |
| `/api/modality-bridge/stats`         | GET        | `attempts` dị na ebe nchekwa, ihe ịga nke ọma/`bridged`, ọdịda, cache hits, `totalLatencyMs`, `latencySamples`, `averageLatencyMs` nke ọnụọgụ sample ji ekpebi, na oge eji ya ikpeazụ (a na-emegharị ya mgbe ebidogharịrị; chọrọ ikike njikwa)                                                                                                                                                            |
| `/api/modality-bridge/video/runtime` | GET        | Nnyocha trusted-loopback siri ike tupu ikike njikwa/nnyocha; nnweta na ụdị FFmpeg/ffprobe e mere ka ha ghara ikpughe ozi nzuzo (no-store)                                                                                                                                                                                                                                                                 |
| `/api/modality-bridge/video/extract` | POST       | Byte broker dị n'ime nke nwere nkwenye ikike ma tụkwasị trusted-loopback obi; ntinye 50 MiB, kwụ nwere oke/mmepụta 32 MiB, `503` mgbe ikike juru, `499` mgbe njikọ kwụsịrị, `504` mgbe oge gwụsịrị; ọ bụghị API bulite faịlụ ọha                                                                                                                                                                          |

### Ndabere & Mbupụ/Mbubata

| Endpoint                    | Usoro | Nkọwa                                                                             |
| --------------------------- | ----- | --------------------------------------------------------------------------------- |
| `/api/db-backups`           | GET   | Depụta ndabere ndị dị                                                             |
| `/api/db-backups`           | PUT   | Mepụta ndabere aka                                                                |
| `/api/db-backups`           | POST  | Weghachite site na ndabere akọwapụtara                                            |
| `/api/db-backups/export`    | GET   | Budata nchekwa data dịka faịlụ .sqlite                                            |
| `/api/db-backups/import`    | POST  | Bulite faịlụ .sqlite iji dochie nchekwa data (`?dryRun=true` na-eme naanị nkwado) |
| `/api/db-backups/exportAll` | GET   | Budata ndabere zuru ezu dịka ebe nchekwa .tar.gz                                  |

`/api/db-backups/export`, `/api/db-backups/exportAll` na `/api/settings/export-json` na-enye
nzere niile echekwara, ya mere ha chọrọ nnọkọ dashboard ma ọ bụ CLI mpaghara (ma ọ bụ ka agbanyụọ
nbanye). Igodo API nke scope ọ bụla na token nnweta `oma_` na-enweta `403`.

`/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.

### Mmekọrịta Cloud

| Endpoint               | Usoro Dị Iche Iche | Nkọwa               |
| ---------------------- | ------------------ | ------------------- |
| `/api/sync/cloud`      | Dị iche iche       | Ọrụ mmekọrịta cloud |
| `/api/sync/initialize` | POST               | Bido mmekọrịta      |
| `/api/cloud/*`         | Dị iche iche       | Njikwa cloud        |

### Ọwara

| Endpoint                   | Method | Nkọwa                                                                             |
| -------------------------- | ------ | --------------------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET    | Gụọ ọnọdụ nrụnye/ọrụ Cloudflare Quick Tunnel maka dashboard                       |
| `/api/tunnels/cloudflared` | POST   | Mee ka Cloudflare Quick Tunnel rụọ ọrụ ma ọ bụ kwụsị ya (`action=enable/disable`) |
| `/api/tunnels/ngrok`       | GET    | Gụọ ọnọdụ ọrụ ngrok Tunnel maka dashboard                                         |
| `/api/tunnels/ngrok`       | POST   | Mee ka ngrok Tunnel rụọ ọrụ ma ọ bụ kwụsị ya (`action=enable/disable`)            |

### Ngwaọrụ CLI

| Endpoint                           | Method | Nkọwa              |
| ---------------------------------- | ------ | ------------------ |
| `/api/cli-tools/claude-settings`   | GET    | Ọnọdụ Claude CLI   |
| `/api/cli-tools/codex-settings`    | GET    | Ọnọdụ Codex CLI    |
| `/api/cli-tools/droid-settings`    | GET    | Ọnọdụ Droid CLI    |
| `/api/cli-tools/openclaw-settings` | GET    | Ọnọdụ OpenClaw CLI |
| `/api/cli-tools/runtime/[toolId]`  | GET    | Ọrụ CLI izugbe     |

Nzaghachi CLI gụnyere: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.

### Ndị Ọrụ ACP

| Endpoint          | Method | Nkọwa                                                                                  |
| ----------------- | ------ | -------------------------------------------------------------------------------------- |
| `/api/acp/agents` | GET    | Depụta ndị ọrụ niile achọpụtara (ndị arụnyere n'ime ya + ndị omenala) tinyere ọnọdụ ha |
| `/api/acp/agents` | POST   | Tinye onye ọrụ omenala ma ọ bụ mee ka cache nchọpụta dị ọhụrụ                          |
| `/api/acp/agents` | DELETE | Wepụ onye ọrụ omenala site na query param `id`                                         |

Nzaghachi GET gụnyere `agents[]` (id, name, binary, version, installed, protocol, isCustom) na `summary` (total, installed, notFound, builtIn, custom).

### Nkwụsi Ike & Oke Ọnụọgụ Arịrịọ

| Endpoint                          | Method    | Nkọwa                                                                                         |
| --------------------------------- | --------- | --------------------------------------------------------------------------------------------- |
| `/api/resilience`                 | GET/PATCH | Nweta/melite kwụ arịrịọ, oge njikọ ji ajụ oyi, ihe nkwụsị provider, na ntọala nchere          |
| `/api/resilience/reset`           | POST      | Tọgharịa circuit breakers nke provider                                                        |
| `/api/resilience/model-cooldowns` | GET       | Depụta mkpọchi per-(provider, connection, model) ndị na-arụ ọrụ, haziri site n'oge fọdụrụ     |
| `/api/resilience/model-cooldowns` | DELETE    | Kpochapụ mkpọchi model — body `{provider, model}` ma ọ bụ `{all: true}` iji hichapụ ihe niile |
| `/api/rate-limits`                | GET       | Ọnọdụ oke ọnụọgụ arịrịọ nke akaụntụ ọ bụla                                                    |
| `/api/rate-limit`                 | GET       | Nhazi oke ọnụọgụ arịrịọ zuru ụwa ọnụ                                                          |

> Route `/api/resilience/*` anọ ahụ niile chọrọ **management auth** (`requireManagementAuth`). Lee [Nkwụsi Ike (gbasatụrụ)](#resilience-extended) maka nkọwa zuru ezu banyere ihe nkwụsị provider ma e jiri ya tụnyere oge njikọ ji ajụ oyi na mkpọchi model.

### Nnwale

| Endpoint     | Method   | Nkọwa                              |
| ------------ | -------- | ---------------------------------- |
| `/api/evals` | GET/POST | Depụta ngwugwu nnwale / mee nyocha |

### Atumatu

| Endpoint        | Method          | Nkọwa                       |
| --------------- | --------------- | --------------------------- |
| `/api/policies` | GET/POST/DELETE | Jikwaa atumatu ntụgharị ụzọ |

### Nrube Isi

| Endpoint                    | Method | Nkọwa                              |
| --------------------------- | ------ | ---------------------------------- |
| `/api/compliance/audit-log` | GET    | Ndekọ nyocha nrube isi (N ikpeazụ) |

### v1beta (Dakọtara na Gemini)

| Endpoint                   | Method | Nkọwa                             |
| -------------------------- | ------ | --------------------------------- |
| `/v1beta/models`           | GET    | Depụta model n'ụdị Gemini         |
| `/v1beta/models/{...path}` | POST   | Endpoint Gemini `generateContent` |

Endpoint ndị a na-eṅomi usoro API Gemini maka client ndị chọrọ ndakọrịta SDK Gemini mbụ.

### API Ime / Sistemu

| Endpoint                 | Method | Nkọwa                                                            |
| ------------------------ | ------ | ---------------------------------------------------------------- |
| `/api/init`              | GET    | Nyocha mbido ngwa (a na-eji ya n'ọrụ mbụ)                        |
| `/api/tags`              | GET    | Tags model dakọtara na Ollama (maka client Ollama)               |
| `/api/restart`           | POST   | Malite mweghachi server n'ụzọ dị nro                             |
| `/api/shutdown`          | POST   | Malite mmechi server n'ụzọ dị nro                                |
| `/api/system/env/repair` | POST   | Dozie environment variables nke provider OAuth                   |
| `/api/system/version`    | GET    | Version dị ugbu a/kacha ọhụrụ, ọnọdụ mmelite, channel mwepụta    |
| `/api/system/version`    | POST   | Malite mmelite maara ọnọdụ deployment gaa na version kacha ọhụrụ |

> **Rịba ama:** Sistemu na-eji endpoint ndị a n'ime ya ma ọ bụ maka ndakọrịta client Ollama. Ndị ọrụ ikpeazụ anaghị akpọkarị ha.

### Ndozi Environment OAuth _(v3.6.1+)_

```bash
POST /api/system/env/repair
Content-Type: application/json

{
  "provider": "claude-code"
}
```

Na-edozi environment variables OAuth na-efu efu ma ọ bụ ndị mebiri emebi maka otu provider kpọmkwem. Ọ na-eweghachi:

```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 na Channel Mwepụta

```bash
GET /api/system/version
```

Ụzọ njikwa nke loopback naanị (nkwenye admin). Ọ na-eweghachi ụdị na-agba ọsọ, ụdị kachasị ọhụrụ
ebipụtara na ọnọdụ mmelite akpaaka. `releaseChannel` na `channels` bụ mpaghara agbakwunyere
(rail 3.8.54); `channel` na-ejigide ihe ọ pụtara — usoro mbunye nke onye na-emelite dashboard
na-eji (`npm`, `source` ma ọ bụ `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 nke build na-agba ọsọ: `nightly` maka ụdị `-nightly.*`,
  `next` maka pre-release ndị ọzọ (`-rc.*`, `-beta.*`, `-alpha.*`), `lts` maka ụdị kwụsiri ike nke
  major ochie karịa `channels.latest`, ma ọ bụghị ya `latest`. Ọ na-agbaso otu iwu ndị dị na
  `scripts/release/dist-tag.mjs`, nke na-ahọrọ npm dist-tag n'oge mbipụta.
- `channels` — head ebipụtara nke dist-tag ọ bụla, sitere na `npm view omniroute dist-tags` (registry
  HTTP fallback), echekwara na cache site n'otu TTL nke nkeji 10 dịka `latest`. `latest` na-adị mgbe niile
  (ọ bụrụ na nke ahụ adịghị, ọ na-eji mpaghara `latest`, emesịa `"unavailable"`); `next`, `nightly` na `lts` na-apụta
  naanị mgbe dist-tag ahụ dị. Arịrịọ `Cache-Control: no-cache` na-eme ka nyocha abụọ ahụ dị ọhụrụ.

A kọwara channel model (`latest` = v3 ruo mgbe 4.0 GA, `next` = rc, `nightly` = build ndị sitere na `develop`,
`lts` = patch v3 mgbe 4.0 GA gasịrị) na `docs/ops/RELEASE_STRATEGY.md`.

---

## Ntụgharị Edemede Ọdịyo

```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
```

Jiri onye na-enye STT ọ bụla ahaziri iji tụgharị faịlụ ọdịyo gaa n'edemede. Akụkụ mbụ nke ụzọ ahụ
na-ahọrọ onye na-enye ọrụ ahụ kpọmkwem (`openai/…`, `deepgram/…`). Ọnụ ụzọ ndị
na-ebupụgharị ụdị nke onye nrụpụta ọzọ na-eji id a kọwara nke ọma
(`openrouter/deepgram/nova-3`).

**Arịrịọ:**

```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"
```

**Nzaghachi:**

```json
{
  "text": "Ndewo, nke a bụ ọdịnaya ọdịyo a tụgharịrị gaa n'edemede.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}
```

**Ihe atụ id ụdị:** `openai/whisper-1` (chọrọ igodo OpenAI),
`openrouter/deepgram/nova-3` (chọrọ igodo OpenRouter),
`deepgram/nova-3` (chọrọ igodo Deepgram kpọmkwem). Arịrịọ
`deepgram/nova-3` na-enweghị mgbakwunye **anaghị** eji OpenRouter.

**Ụdị ndị a na-akwado:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.

---

## Ndakọrịta Ollama

Maka ndị ahịa na-eji usoro API nke Ollama:

```bash
# Ebe njedebe nkata (usoro Ollama)
POST /v1/api/chat

# Ndepụta ụdị (usoro Ollama)
GET /api/tags
```

A na-atụgharị arịrịọ na-akpaghị aka n'etiti usoro Ollama na usoro dị n'ime.

## Aha Ọzọ VS Code Nwere Token / Na-enweghị Header

Jiri aha ndị ọzọ ndị a mgbe njikọ enweghị ike itinye header `Authorization` ma chọọ ka etinye igodo API n'ime URL ntọala.

```bash
# Aha ọzọ katalọgụ n'ụdị OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Aha ọzọ nkata n'ụdị OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Aha ndị ọzọ n'ụdị Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```

Ihe atụ:

```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"}]}'
```

Nkọwa:

- Aha ndị ọzọ nwere token na-ejikwa otu handlers ndị `/v1/*` na `/api/tags` na-eji; ọdịdị nzaghachi na-anọgide otu.
- Họrọ `Authorization: Bearer ...` mgbe ọ bụla onye ahịa na-akwado headers ahaziri iche.
- Tokens dabere na URL nwere ike ịpụta na ndekọ reverse-proxy, akụkọ ihe nchọgharị, na telemetry dị na mpụga OmniRoute. Were ha dịka nhọrọ ndakọrịta, ọ bụghị usoro nkwenye njirimara ndabara.

---

## Telemetry

```bash
# Nweta nchịkọta telemetry nke oge igbu oge (p50/p95/p99 maka onye na-enye ọrụ ọ bụla)
GET /api/telemetry/summary
```

**Nzaghachi:**

```json
{
  "providers": {
    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
  }
}
```

---

## Mmefu Ego

```bash
# Nweta ọnọdụ mmefu ego maka igodo API niile
GET /api/usage/budget

# Tọọ ma ọ bụ melite mmefu ego
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"
}
```

> **Nkọwa schema** (`setBudgetSchema`): `apiKeyId` dị mkpa; opekata mpe otu n'ime `dailyLimitUsd`, `weeklyLimitUsd`, ma ọ bụ `monthlyLimitUsd` ga-adịrịrị karịa efu. Fields nhọrọ: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Ọdịdị ochie `{keyId, limit, period}` na-eweghachi `400 Bad Request`.

## Oke Token

Mmefu **token** maka igodo API ọ bụla (dị iche na Mmefu dabere na USD dị n’elu). A na-amanye ya ozugbo n’ụzọ arịrịọ: mgbe ojiji igodo n’ime windo dị ugbu a ruru oke ya, a na-ajụ arịrịọ ndị ọzọ site na `429 Too Many Requests`. Enwere ike ịkọwapụta oke maka `model` kpọmkwem, `provider`, ma ọ bụ tinye ya n’ogo `global` n’ofe igodo ahụ; mgbe ọtụtụ oke dabara n’otu arịrịọ, nke kacha sie ike ga-emeri.

```bash
# Depụta oke token nke otu igodo (gụnyere ojiji windo dị ugbu a)
GET /api/usage/token-limits?apiKeyId=key-123

# Mepụta ma ọ bụ melite oke token
POST /api/usage/token-limits
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "scopeType": "model",
  "scopeValue": "openai/gpt-4o",
  "tokenLimit": 1000000,
  "resetInterval": "monthly",
  "enabled": true
}

# Hichapụ oke token site na id
DELETE /api/usage/token-limits?id=tl-abc
```

> **Nkọwa schema** (`setTokenLimitSchema`): `apiKeyId` na `scopeType` (`model` | `provider` | `global`) bụ ihe achọrọ. A chọrọ `scopeValue` ma e wezụga mgbe `scopeType` bụ `global` (dịka ọmụmaatụ, id model maka scope `model`, ma ọ bụ id provider maka scope `provider`). `tokenLimit` ga-abụrịrị integer dị mma (a na-agbanwe ya site na string). Nhọrọ ndị ọzọ: `id` (hapụ ya iji mepụta, tinye ya iji melite), `resetInterval` (`daily` | `weekly` | `monthly`, ndabara bụ `monthly`), `resetTime` (`HH:MM`), `enabled` (ndabara bụ `true`). Nzaghachi `GET` na-agbakwunye `tokensUsed`, `remaining`, `windowStart`, `periodStartAt`, na `nextResetAt` na oke ọ bụla. Nke a bụ endpoint nke klaasị njikwa (authz pipeline na-amanye auth n’etiti usoro).

## Nhazi Arịrịọ

1. Client na-eziga arịrịọ na `/v1/*`
2. Route handler na-akpọ `handleChat`, `handleEmbedding`, `handleAudioTranscription`, ma ọ bụ `handleImageGeneration`
3. A na-achọpụta model (provider/model kpọmkwem ma ọ bụ alias/combo)
4. A na-ahọrọ credentials site na DB mpaghara site n’iji nzacha nnweta account
5. Maka chat: `handleChatCore` na-enyocha semantic/signature cache ma na-achọpụta ntọala mkpakọ combo
6. Mkpakọ proactive na-arụ ọrụ tupu ntụgharị provider mgbe enyere ya ohere (`lite`, Caveman, RTK, ma ọ bụ ndị e jikọtara ọnụ)
7. Provider executor na-eziga arịrịọ upstream
8. A na-atụgharị nzaghachi laghachi n’usoro client (chat) ma ọ bụ weghachite ya otu ọ dị (embeddings/images/audio)
9. A na-edekọ ojiji, nyocha mkpakọ, na ndekọ arịrịọ
10. A na-etinye fallback mgbe njehie mere dịka iwu combo si dị

Ntụaka nhazi zuru ezu: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)

---

## Njikwa Combo

A pụkwara ịmapụta combo routing dị elu (nke a chịkọtalarị n’okpuru `/api/combos*`) 1:1 site na ụkpụrụ id model, nke na-enye ohere ibugharị id model ụdị OpenAI gaa na combo n’enweghị ihe mgbochi.

| Method | Path                             | Nkọwa                                                                          |
| ------ | -------------------------------- | ------------------------------------------------------------------------------ |
| GET    | `/api/model-combo-mappings`      | Depụta mappings model→combo niile                                              |
| POST   | `/api/model-combo-mappings`      | Mepụta mapping — body: `{pattern, comboId, priority?, enabled?, description?}` |
| GET    | `/api/model-combo-mappings/[id]` | Weta otu mapping                                                               |
| PUT    | `/api/model-combo-mappings/[id]` | Melite fields nke mapping dị adị                                               |
| DELETE | `/api/model-combo-mappings/[id]` | Wepụ mapping                                                                   |

**Auth:** session/API key njikwa (`requireManagementAuth`).

---

## Webhooks

Ndenye aha webhook ndị na-apụ apụ maka mmemme OmniRoute (mmecha arịrịọ, mmebi oke ojiji, mgbanwe igodo, wdg.).

| Usoro  | Ụzọ                       | Nkọwa                                                                |
| ------ | ------------------------- | -------------------------------------------------------------------- |
| GET    | `/api/webhooks`           | Depụta webhooks (a na-ekpuchi ihe nzuzo dịka `<prefix>...`)          |
| POST   | `/api/webhooks`           | Mepụta webhook — ahụ: `{url, events?: ["*"], secret?, description?}` |
| GET    | `/api/webhooks/[id]`      | Nweta otu webhook                                                    |
| PUT    | `/api/webhooks/[id]`      | Melite url/events/secret/description                                 |
| DELETE | `/api/webhooks/[id]`      | Wepụ otu webhook                                                     |
| POST   | `/api/webhooks/[id]/test` | Ziga payload nnwale na URL webhook ma weghachite ọnọdụ nnyefe        |

**Nkwenye njirimara:** nnọkọ njikwa/igodo API (`requireManagementAuth`).

---

## Igodo Ndị E Debanyere Aha (Nlekọta Akpaaka)

Usoro nta nke nlekọta igodo akpaaka na-eji nke a ewepụta ma na-agbanwe igodo API n'aka onye na-eweta ọrụ/akaụntụ ndabere, yana oke ojiji kwa ụbọchị/kwa elekere.

| Usoro  | Ụzọ                                   | Nkọwa                                                                                                                                                                                                                                                       |
| ------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/registered-keys`             | Depụta igodo ndị e debanyere aha (naanị nganiihu ezoro ezo)                                                                                                                                                                                                 |
| POST   | `/api/v1/registered-keys`             | Wepụta igodo ọhụrụ e debanyere aha — ahụ: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Ọ na-eweghachi igodo ahụ n'ụdị mbụ ya **naanị otu ugboro**. Ọ na-eweghachi `429` ma ọ bụrụ na a jụ ya n'ihi oke ojiji. |
| GET    | `/api/v1/registered-keys/[id]`        | Nweta metadata nke igodo e debanyere aha (enweghị ihe nzuzo mbụ nke igodo ahụ)                                                                                                                                                                              |
| DELETE | `/api/v1/registered-keys/[id]`        | Kagbuo igodo e debanyere aha                                                                                                                                                                                                                                |
| POST   | `/api/v1/registered-keys/[id]/revoke` | Endpoint maka ịkagbu n'ụzọ doro anya (otu mmetụta ahụ dị ka DELETE)                                                                                                                                                                                         |

**Nyocha ikike:** nnọkọ njikwa/igodo API (`requireManagementAuth`) — otu ihe nche ahụ dị ka `/api/keys`: nnọkọ dashboard, token CLI mpaghara, ma ọ bụ igodo API nwere scope `manage`/`admin`; igodo API ndị e ji naanị inference eme ihe na-enweta `403`. Hụkwa `/v1/quotas/check` na `/v1/issues/report`.

---

## Protokọlụ Ndị Ọrụ Nnọchiteanya

Ọrụ ndị ọrụ nnọchiteanya igwe ojii (Claude Code, Codex Cloud, OpenHands, wdg.) a na-arụ n'ebe dị anya n'aha ndị ọrụ OmniRoute.

| Usoro  | Ụzọ                           | Nkọwa                                                                                                                                               |
| ------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/agents/tasks`        | Depụta ọrụ — `?provider=`, `?status=`, `?limit=` bụ nhọrọ (1–500, ndabara bụ 50)                                                                    |
| POST   | `/api/v1/agents/tasks`        | Mepụta ọrụ — `CreateCloudAgentTaskSchema` na-enyocha body (`providerId`, `prompt`, `source`, `options?`). Ọ na-eweghachi `201` tinyere envelopu ọrụ |
| DELETE | `/api/v1/agents/tasks?id=...` | Hichapụ otu ọrụ                                                                                                                                     |
| GET    | `/api/v1/agents/tasks/[id]`   | Gụọ ọrụ — ọ na-emelite ọnọdụ ozugbo site n'aka onye ọrụ nnọchiteanya igwe ojii dị n'elu mgbe edobere `external_id`                                  |
| POST   | `/api/v1/agents/tasks/[id]`   | Omume a na-amata iche: `{action: "approve"}`, `{action: "message", message}`, ma ọ bụ `{action: "cancel"}`                                          |
| DELETE | `/api/v1/agents/tasks/[id]`   | Jiri id hichapụ otu ọrụ kpọmkwem                                                                                                                    |

> **Nyocha ikike:** a chọrọ nyocha ikike njikwa n'usoro ọ bụla (`requireCloudAgentManagementAuth`). Tupu v3.8.0, usoro ndị a achọghị nyocha ikike — lee commit `588a0333` maka mgbanwe na-emebi ndakọrịta.

```bash
# Mepụta ọrụ igwe ojii Claude Code
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":"..."}}'
```

---

## Proxy Njikwa

Proxy HTTP(S)/SOCKS na-apụ apụ nke enwere ike ikenye ndị na-eweta ọrụ, akaụntụ, ma ọ bụ n'ụwa niile.

| Usoro  | Ụzọ                                          | Nkọwa                                                                                                                                                 |
| ------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/management/proxies`                 | Depụta proxy (iji `?id=` na-eweghachi otu; iji `?id=&where_used=1` na-eweghachi eserese nke ikenye ha)                                                |
| POST   | `/api/v1/management/proxies`                 | Mepụta proxy — `createProxyRegistrySchema` na-enyocha body                                                                                            |
| PATCH  | `/api/v1/management/proxies`                 | Melite proxy — `updateProxyRegistrySchema` na-enyocha body (ọ chọrọ `id`)                                                                             |
| DELETE | `/api/v1/management/proxies?id=...&force=1`  | Hichapụ proxy (jiri `force=1` kewapụ ikenye ndị dị na ya)                                                                                             |
| GET    | `/api/v1/management/proxies/assignments`     | Depụta ikenye — enwere ike iji `proxy_id`, `scope`, `scope_id` nzacha ya; nyefee `resolve_connection_id=<id>` iji chọpụta proxy na-arụ ọrụ maka njikọ |
| PUT    | `/api/v1/management/proxies/assignments`     | Kenye — `proxyAssignmentSchema` na-enyocha body (`{scope, scopeId?, proxyId?}`). Ọ na-ehichapụ cache dispatcher                                       |
| PUT    | `/api/v1/management/proxies/bulk-assign`     | Kenye n'ìgwè — `bulkProxyAssignmentSchema` na-enyocha body (`{scope, scopeIds[], proxyId?}`)                                                          |
| GET    | `/api/v1/management/proxies/health?hours=24` | Chịkọta ọnọdụ ahụike proxy (ọnụọgụ ihe gara nke ọma/daara, oge nzaghachi) n'ime otu oge                                                               |

**Nyocha ikike:** a chọrọ session njikwa/igodo API n'ụzọ ọ bụla (`requireManagementAuth`).

> `POST /api/v1/management/proxies/[id]/assignments` na `POST /api/v1/management/proxies/[id]/health` dị na nkọwa ọrụ ahụ bụ ụzọ `/assignments` na `/health` kwụ ọtọ e gosiri n'elu na-ejere ha ozi — enweghị subroute kwa id na codebase ahụ.

---

## Nkwụsi ike (gbasatụrụ)

OmniRoute na-enye usoro atọ nọọrọ onwe ha maka ọdịda nwa oge; ebe njikwa ndị dị n'okpuru na-enye ndị na-ahụ maka sistemụ ohere ịgụ ma gbanwee ha:

| Oke                 | Ebe a na-echekwa steeti                 | Ịgụ                                       | Tọgharịa / hichapụ                                                |
| ------------------- | --------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------- |
| Ihe nkwụsị provider | `domain_circuit_breakers` + ebe nchekwa | `/api/monitoring/health`                  | `POST /api/resilience/reset`                                      |
| Oge nchere njikọ    | `rateLimitedUntil` na njikọ provider    | `/api/rate-limits`, `/api/providers/[id]` | (na-emegharị onwe ya mgbe e mesịrị; hichapụ site na provider PUT) |
| Mkpọchi model       | Ndebanye nnweta model dị na ebe nchekwa | `GET /api/resilience/model-cooldowns`     | `DELETE /api/resilience/model-cooldowns`                          |

`PATCH /api/resilience` na-anabata mgbanwe ihe nkwụsị provider n'okpuru `providerBreaker.oauth` na `providerBreaker.apikey`. Profaịlụ ọ bụla na-akwado `degradationThreshold`, `failureThreshold`, na `resetTimeoutMs`; a na-egosikwa otu mpaghara ndị a na Dashboard → Settings → Resilience.

```bash
# Hichapụ mkpọchi otu model
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"}'

# Hichapụ mkpọchi niile
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'
```

Maka ntụaka echiche zuru ezu na ụkpụrụ ndabara nke ihe nkwụsị: lee [`CLAUDE.md`](../../CLAUDE.md) → "Steeti Oge Ọrụ nke Nkwụsi Ike".

---

## Nkà

Usoro nkà maka iji njikwa a haziri ahazi nke enwere ike imepụta gbasaa OmniRoute, tinyere njikọ ahịa.

| Usoro  | Ụzọ                               | Nkọwa                                                                                                                                   |
| ------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`                     | Depụta nkà arụnyere — enwere ike iji `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local` nyochaa ya, ma kewaa ya na peeji |
| GET    | `/api/skills/[id]`                | Nweta otu nkà                                                                                                                           |
| PUT    | `/api/skills/[id]`                | Melite nkà (aha, nkọwa, ọnọdụ, schema, njikwa, mkpado)                                                                                  |
| DELETE | `/api/skills/[id]`                | Wepụ nkà arụnyere                                                                                                                       |
| POST   | `/api/skills/install`             | Wụnye nkà site na manifest raw — body: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}`                   |
| GET    | `/api/skills/executions`          | Depụta arụmọrụ nkà ndị mere nso nso a (ndekọ nyocha nwere ntinye/mmepụta/ogologo oge)                                                   |
| GET    | `/api/skills/marketplace?q=...`   | Chọọ/depụta ihe ndị ewu ewu site n'ahịa SkillsMP (chọrọ ntọala `skillsmpApiKey`)                                                        |
| POST   | `/api/skills/marketplace/install` | Wụnye nkà site na SkillsMP site na id                                                                                                   |
| GET    | `/api/skills/skillssh?q=&limit=`  | Chọọ n'akwụkwọ ndebanye skills.sh                                                                                                       |
| POST   | `/api/skills/skillssh/install`    | Wụnye nkà site na skills.sh site na id                                                                                                  |

**Nyocha ikike:** nnọkọ njikwa/igodo API. Ụzọ ọchụchọ ahịa na-anabata ma nyocha ikike njikwa ma ọ bụ igodo API Bearer (`isAuthenticated`).

---

## Ncheta

Ebe nchekwa ncheta mkparịta ụka/eziokwu na-adịgide adịgide, nke e kewara dịka API key / session si dị.

| Method | Path                 | Description                                                                                                              |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/memory`        | Depụta ncheta — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, yana nhazi ibe site na `offset/limit` ma ọ bụ `page/limit` |
| POST   | `/api/memory`        | Mepụta ncheta — Zod na-enyocha body: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}`               |
| GET    | `/api/memory/[id]`   | Nweta otu ncheta                                                                                                         |
| DELETE | `/api/memory/[id]`   | Hichapụ ncheta                                                                                                           |
| GET    | `/api/memory/health` | Ọnọdụ ahụike nke usoro nta ncheta (njikọ DB, backend embeddings, ọnọdụ vector index)                                     |

**Nyocha ikike:** management session/API key (`requireManagementAuth`). Enum `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (lee `MemoryType` na `src/lib/memory/types.ts`).

---

## Sava MCP

OmniRoute na-abịa na sava Model Context Protocol agbakwunyere nke nwere ụzọ mbufe 3 (stdio, SSE, streamable-http) na ngwaọrụ e kenyere oke. Endpoint dashboard ndị dị n'okpuru na-agụ data ọnọdụ/nyocha ma na-eme proxy maka ụzọ mbufe HTTP.

| Method | Path | Description |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Heartbeat, ụzọ mbufe, ọnọdụ online, oku ikpeazụ, ngwaọrụ kachasị eji, ọnụego ihe ịga nke ọma n'ime awa 24 |
| GET | `/api/mcp/tools` | Ndepụta ngwaọrụ MCP nwere `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
| GET | `/api/mcp/sse` | Mepee iyi SSE maka ụzọ mbufe SSE (na-eweghachi `503` ma ọ bụrụ na agbanyụghị MCP ma ọ bụ na ụzọ mbufe adabaghị) |
| POST | `/api/mcp/sse` | Zipụ fremụ JSON-RPC site n'ụzọ mbufe SSE |
| GET | `/api/mcp/stream` | Mepee akụkụ SSE nke ụzọ mbufe Streamable HTTP (ozi sava malitere) |
| POST | `/api/mcp/stream` | Zipụ fremụ JSON-RPC site n'ụzọ mbufe Streamable HTTP |
| DELETE | `/api/mcp/stream` | Kwụsị session Streamable HTTP |
| GET | `/api/mcp/audit` | Jụọ ndekọ nyocha — `?limit=`, `?offset=`, `?tool=`, `?success=true                                | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | Chịkọta ọnụ ọgụgụ nyocha (ngụkọta, ọnụego ihe ịga nke ọma, nkezi oge, ngwaọrụ kachasị eji) |

**Nyocha ikike:** ụzọ mbufe `sse`/`stream` na-agbaso usoro nyocha ikike pụrụ iche nke MCP (Bearer API key nwere scope `mcp`); enwere ike ịgụ route `status`/`tools`/`audit*` site na dashboard (ọ dịghị nyocha ikike ọzọ achọrọ ma e wezụga inwe ike iru host dashboard).

> `settings.mcpEnabled` na `settings.mcpTransport` na-achịkwa ụzọ mbufe HTTP abụọ ahụ — ụzọ mbufe na-adabaghị na-eweghachi `400`, ebe ọnọdụ MCP agbanyụghị na-eweghachi `503`.

---

## Sava A2A

OmniRoute na-ewepụta endpoint A2A (Agent-to-Agent) JSON-RPC 2.0 yana ihe mkpuchi REST maka nyocha/ojiji dashboard.

### JSON-RPC

```bash
POST /a2a
Authorization: Bearer your-api-key   # nhọrọ ma ọ bụrụ na edoghị OMNIROUTE_API_KEY
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Route this coding task"}]
  }
}
```

Ụzọ ndị akwadoro (ha niile dabere na `settings.a2aEnabled`):

| Ụzọ              | Nkọwa                                                           |
| ---------------- | --------------------------------------------------------------- |
| `message/send`   | Mmezu nka n'otu oge; na-eweghachi `{task, artifacts, metadata}` |
| `message/stream` | Mmezu SSE na-asọba nke otu nchịkọta nka ahụ                     |
| `tasks/get`      | Were ọrụ site na `taskId`                                       |
| `tasks/cancel`   | Kagbuo ọrụ site na `taskId`                                     |

Nka ndị etinyere n'ime ya: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.

### Kaadị Agent

```bash
GET /.well-known/agent.json
```

Na-eweghachi kaadị agent A2A ọhaneze (aha, nkọwa, ikike, katalọgụ nka, usoro auth) — a na-echekwa ya n'ihu ọha ruo 1h. Achọghị auth.

### Ndị enyemaka REST

| Ụzọ  | Path                         | Nkọwa                                                                                                           |
| ---- | ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
| GET  | `/api/a2a/status`            | A2A agbanyere + ọnụ ọgụgụ ọrụ + nchịkọta kaadị agent echekwara                                                  |
| GET  | `/api/a2a/tasks`             | Depụta ọrụ — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST | `/api/a2a/tasks`             | (Emebeghị ya dịka onye enyemaka REST — mepụta site na JSON-RPC `message/send`)                                  |
| GET  | `/api/a2a/tasks/[id]`        | Nweta otu ọrụ                                                                                                   |
| POST | `/api/a2a/tasks/[id]/cancel` | Kagbuo ọrụ                                                                                                      |

**Auth:** ndị enyemaka REST na-arụ ọrụ na-enweghị auth njikwa (dashboard nwere ike ịgụ ha); ụzọ JSON-RPC `/a2a` na-eji Bearer `OMNIROUTE_API_KEY` ma ọ bụrụ na ahaziri ya.

---

## Ígwé ojii, Nnwale & Ntụle

| Usoro | Ụzọ | Nkọwa |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Nyochaa igodo Bearer ma weghachite njikọ ndị na-eweta ọrụ e zoro akụkụ ha + aha ọzọ nke ụdị maka ndị ahịa mmekọrịta ígwé ojii |
| POST | `/api/cloud/credentials/update` | Melite nzere e zoro ezo maka onye na-eweta ọrụ emekọrịtara na ígwé ojii |
| POST | `/api/cloud/model/resolve` | Jiri tebụl ntụgharị ụzọ mpaghara kọwaa ID ụdị ezi uche ka ọ bụrụ onye na-eweta ọrụ/ụdị kpọmkwem |
| GET | `/api/cloud/models/alias` | Depụta aha ọzọ nke ụdị dịka e si egosi ha maka mmekọrịta ígwé ojii |
| GET | `/api/assess` | Gụọ nhazi otu nke nyocha kachasị ọhụrụ (maka onye na-eweta ọrụ/ụdị ọ bụla) |
| POST | `/api/assess` | Mee nyocha — ahụ: `{scope: {type:"all"}                                                   | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Depụta nchịkọta nnwale arụnyere n'ime + ọsọ ndị kachasị ọhụrụ |
| POST | `/api/evals` | Kpalite ọsọ nnwale |
| POST | `/api/evals/suites` | Mepụta nchịkọta nnwale ahaziri iche — a na-eji `evalSuiteSaveSchema` enyocha ahụ |
| GET | `/api/evals/suites/[id]` | Nweta nchịkọta nnwale ahaziri iche |

**Nnyocha ikike:** `/api/cloud/auth` na-enyocha igodo Bearer ozugbo ma weghachite naanị igodo e zoro akụkụ ya na `projectId` nke njikọ ọ bụla maka igodo nwere oke ikike `manage` / `admin`; ụzọ `/api/cloud/*`, `/api/evals/*`, na `/api/assess` ndị ọzọ chọrọ nnọkọ njikwa/igodo API. POST `/api/assess` na-eji `validateBody` nwere schema oke discriminated-union.

---

## Nchịkwa ACP (Agent Client Protocol)

dị ka usoro ụmụ. Ebe njedebe ndị a na-ahụ maka nchọpụta ndị nnọchi anya ACP na ndebanye aha ndị nnọchi anya ahaziri iche.

| Usoro  | Ụzọ               | Nkọwa                                                                                                                                                                                      |
| ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/acp/agents` | Depụta ndị nnọchi anya CLI niile a maara (ndị arụnyere n'ime ya + ndị ahaziri iche), tinyere ọnọdụ nrụnye, ụdị, na faịlụ binary                                                            |
| POST   | `/api/acp/agents` | Debanye aha onye nnọchi anya ACP ahaziri iche ma ọ bụ mee ka cache dị ọhụrụ — body: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` ma ọ bụ `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Wepụ onye nnọchi anya ACP ahaziri iche — query param: `?id=<agentId>`                                                                                                                      |

**Ọmụmaatụ nzaghachi** (`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
}
```

**Nkwenye njirimara:** Ọ chọrọ nnọkọ njikwa (dashboard `auth_token` cookie) ma ọ bụ igodo API nwere ikike njikwa.

Lee [Usoro ACP](../frameworks/ACP.md) maka nkọwa zuru ezu.

---

## Nnyocha Data & Nlele Ọnọdụ

Ebe njedebe nnyocha data ozugbo maka nyochaa ntụgharị ụzọ, mkpakọ, na ụdịdị dị iche iche nke ndị na-eweta ọrụ. Ndị a na-akwado peeji `/dashboard/analytics/*`.

### Nnyocha data ntụgharị ụzọ akpaaka

| Usoro | Ụzọ                                  | Nkọwa                                                                                                       |
| ----- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| GET   | `/api/analytics/auto-routing`        | Nchịkọta ọnụ ọgụgụ ntụgharị ụzọ akpaaka: oku niile, nkesa atụmatụ, nkesa ọkwa, ndị na-eweta ọrụ kachasị elu |
| GET   | `/api/analytics/auto-routing?days=7` | Ọnụ ọgụgụ dabere na windo oge (ndabara bụ awa 24)                                                           |

**Ọmụmaatụ nzaghachi**:

```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 }
  ]
}
```

### Nnyocha data mkpakọ

| Usoro | Ụzọ                          | Nkọwa                                                                                       |
| ----- | ---------------------------- | ------------------------------------------------------------------------------------------- |
| GET   | `/api/analytics/compression` | Nchịkọta ọnụ ọgụgụ mkpakọ: token echekwara, pasent ego echekwara, nkesa ọnọdụ, ojiji engine |

**Ọmụmaatụ nzaghachi**:

```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
  }
}
```

### Nsuso ụdịdị dị iche iche nke ndị na-eweta ọrụ

| Usoro | Ụzọ                        | Nkọwa                                                                                                               |
| ----- | -------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/analytics/diversity` | Nsuso ụdịdị dị iche iche dabere na entropy Shannon: na-egbochi otu ebe ọdịda site n'ịtụ mgbasa nke ndị na-eweta ọrụ |

**Ọmụmaatụ nzaghachi**:

```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"]
}
```

**Nkwenye njirimara:** Ọ chọrọ nnọkọ njikwa ma ọ bụ igodo API nwere ikike njikwa.

---

## Ọrụ Nchịkwa

Ebe njedebe ndị naanị onye nchịkwa nwere ike iji maka njikwa ọrụ.

| Usoro | Ụzọ                      | Nkọwa                                                                                   |
| ----- | ------------------------ | --------------------------------------------------------------------------------------- |
| GET   | `/api/admin/concurrency` | Gụọ oke concurrency dị ugbu a (nke zuru ụwa ọnụ + nke onye na-eweta ọ bụla)             |
| POST  | `/api/admin/concurrency` | Melite oke concurrency — ahụ: `{global?: number, perProvider?: Record<string, number>}` |

**Nyocha ikike:** Chọrọ nnọkọ njikwa nwere ikike onye nchịkwa.

---

## Njikwa Ngwaọrụ CLI

Jikwaa ngwaọrụ CLI ndị na-arụkọ ọrụ na OmniRoute (antigravity, commandCode,
devin-cli, wdg.). Hụ [Ntụaka Ndị Na-eweta Ọrụ](./PROVIDER_REFERENCE.md) maka ndepụta zuru ezu.

| Usoro | Ụzọ                                     | Nkọwa                                                                                                                                                                 |
| ----- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/cli-tools/all-statuses`           | Ọnọdụ ngwaọrụ CLI niile (arụnyere, ụdị, oge ikpeazụ a hụrụ ya)                                                                                                        |
| GET   | `/api/cli-tools/status`                 | Nkọwa ọnọdụ maka otu ngwaọrụ CLI (ajụjụ `?tool=`)                                                                                                                     |
| POST  | `/api/cli-tools/apply`                  | Dee nhazi emepụtara nke ngwaọrụ (`dryRun` na-egosi ihe ga-apụta; `422` + `containerEphemeralTarget` mgbe ọ dị n'ime container; `migration` na-akọwa Codex YAML ochie) |
| GET   | `/api/cli-tools/backups`                | Depụta ndabere nhazi ngwaọrụ CLI                                                                                                                                      |
| POST  | `/api/cli-tools/backups`                | Mepụta ndabere nke nhazi ngwaọrụ CLI niile                                                                                                                            |
| POST  | `/api/cli-tools/backups`                | Weghachite: otu endpoint ahụ nwere `{tool, backupId}` n'ime body na-eweghachite ndabere ahụ                                                                           |
| GET   | `/api/cli-tools/antigravity-mitm`       | Ọnọdụ proxy MITM nke Antigravity (ngwaọrụ CLI "antigravity-mitm")                                                                                                     |
| POST  | `/api/cli-tools/antigravity-mitm/alias` | Hazie alias nke antigravity-mitm                                                                                                                                      |

**Nyocha ikike:** Chọrọ session njikwa.

---

## Nkà Ndị Nnọchi Anya

Jikwaa nkà ndị nnọchi anya AI (dị ka GPT ahaziri iche nke OpenAI, mana maka ndị nnọchi anya).

| Usoro  | Ụzọ                          | Nkọwa                                                                                               |
| ------ | ---------------------------- | --------------------------------------------------------------------------------------------------- |
| GET    | `/api/agent-skills`          | Depụta nkà ndị nnọchi anya niile (nke arụnyere n'ime + nke ahaziri iche)                            |
| GET    | `/api/agent-skills/[id]`     | Nweta otu nkà onye nnọchi anya kpọmkwem                                                             |
| POST   | `/api/agent-skills`          | Mepụta nkà onye nnọchi anya ahaziri iche — ahụ: `{name, description, prompt, model?, temperature?}` |
| PUT    | `/api/agent-skills/[id]`     | Melite nkà onye nnọchi anya ahaziri iche                                                            |
| DELETE | `/api/agent-skills/[id]`     | Hichapụ nkà onye nnọchi anya ahaziri iche                                                           |
| GET    | `/api/agent-skills/[id]/raw` | Nweta prompt nke mbụ + metadata (enweghị mmezu)                                                     |
| POST   | `/api/agent-skills/generate` | Jiri AI mepụta nkà ọhụrụ site na nkọwa e dere n'asụsụ mmadụ                                         |

**Nyocha ikike:** Chọrọ nnọkọ njikwa ma ọ bụ igodo API nwere ikike njikwa.

---

## Njikwa Cache

Jikwaa cache semantic na cache ntụgharị uche.

| Method | Path                   | Nkọwa                                                                                                                       |
| ------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cache`           | Nchịkọta cache: ngụkọta ndenye, ọnụego hit, nha dị na diski                                                                 |
| GET    | `/api/cache/entries`   | Depụta ndenye ndị dị na cache (ya na pagination)                                                                            |
| DELETE | `/api/cache/entries`   | Hichapụ ndenye cache (jiri query parameters nyochaa)                                                                        |
| GET    | `/api/cache/stats`     | Nkọwa ọnụ ọgụgụ cache zuru ezu (maka provider ọ bụla, maka model ọ bụla)                                                    |
| GET    | `/api/cache/reasoning` | Ọnọdụ cache ntụgharị uche (maka ịkpọgharị ntụgharị uche)                                                                    |
| DELETE | `/api/cache/reasoning` | Hichapụ cache ntụgharị uche — query params: `?toolCallId=<id>` (otu) ma ọ bụ `?provider=<p>` ma ọ bụ enweghị params (niile) |

**Nkwenye:** Chọrọ session njikwa.

---

## Sistemụ Ncheta

Jikwaa ncheta na-adịgide adịgide (FTS5 + vector embeddings).

| Method | Path               | Nkọwa                                                                  |
| ------ | ------------------ | ---------------------------------------------------------------------- |
| GET    | `/api/memory`      | Depụta ndenye ncheta (jiri scope, type, search query nyochaa)          |
| POST   | `/api/memory`      | Mepụta ndenye ncheta ọhụrụ — body: `{scope, type, content, metadata?}` |
| GET    | `/api/memory/[id]` | Nweta otu ndenye ncheta akọwapụtara                                    |
| PUT    | `/api/memory/[id]` | Melite otu ndenye ncheta                                               |
| DELETE | `/api/memory/[id]` | Hichapụ otu ndenye ncheta                                              |
| GET    | `/api/memory?q=`   | Chọọ n'ime ncheta (FTS5 + vector) — agụnyere stats na response ahụ     |

**Nkwenye:** Chọrọ session njikwa ma ọ bụ API key nwere scope njikwa.

---

## Webhooks

Jikwaa ndebanye webhook maka events.

| Method | Path                            | Nkọwa                                                               |
| ------ | ------------------------------- | ------------------------------------------------------------------- |
| GET    | `/api/webhooks`                 | Depụta ndebanye webhook niile                                       |
| POST   | `/api/webhooks`                 | Mepụta ndebanye webhook — body: `{url, events[], secret?, active?}` |
| GET    | `/api/webhooks/[id]`            | Nweta otu ndebanye webhook akọwapụtara                              |
| PUT    | `/api/webhooks/[id]`            | Melite otu ndebanye webhook                                         |
| DELETE | `/api/webhooks/[id]`            | Hichapụ otu ndebanye webhook                                        |
| GET    | `/api/webhooks/[id]/deliveries` | Depụta akụkọ delivery maka webhook (ndekọ ihe ịga nke ọma/ọdịda)    |
| POST   | `/api/webhooks/[id]/test`       | Ziga test event na webhook                                          |

**Nkwenye:** Chọrọ session njikwa.

Lee [Framework Webhooks](../frameworks/WEBHOOKS.md) maka ụdị event niile.

---

## Usoro Skills

Jikwaa Skills (usoro ndọtị agentic).

| Usoro  | Ụzọ                      | Nkọwa                                                                                     |
| ------ | ------------------------ | ----------------------------------------------------------------------------------------- |
| GET    | `/api/skills`            | Depụta skills niile arụnyere (ndị e wuru n'ime ya + ndị ahaziri iche)                     |
| POST   | `/api/skills/install`    | Wụnye skill site n’ụzọ mpaghara ma ọ bụ URL                                               |
| DELETE | `/api/skills/[id]`       | Wepụ skill arụnyere                                                                       |
| PUT    | `/api/skills/[id]`       | Gbanye ma ọ bụ gbanyụọ skill — ahụ: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST   | `/api/skills/executions` | Mee skill — ahụ: `{skillName, apiKeyId, input?, sessionId?}`                              |
| GET    | `/api/skills/executions` | Depụta akụkọ mmezu maka skills niile (jiri `?apiKeyId=` nyochaa)                          |

**Nkwenye njirimara:** Ọ chọrọ nnọkọ njikwa ma ọ bụ API key nwere ikike njikwa.

Lee [Usoro Skills](../frameworks/SKILLS.md) maka nkọwa zuru ezu.

---

## Plugins

Jikwaa plugins OmniRoute (ndọtị ndị ọzọ mepụtara).

| Usoro  | Ụzọ                                | Nkọwa                    |
| ------ | ---------------------------------- | ------------------------ |
| GET    | `/api/plugins`                     | Depụta plugins arụnyere  |
| POST   | `/api/plugins/marketplace/install` | Wụnye plugin site n’ahịa |
| DELETE | `/api/plugins/[name]`              | Wepụ plugin arụnyere     |
| POST   | `/api/plugins/[name]/activate`     | Mee ka plugin rụọ ọrụ    |
| POST   | `/api/plugins/[name]/deactivate`   | Kwụsị plugin ịrụ ọrụ     |
| GET    | `/api/plugins/[name]/config`       | Nweta nhazi plugin       |
| PUT    | `/api/plugins/[name]/config`       | Melite nhazi plugin      |

**Nkwenye njirimara:** Ọ chọrọ nnọkọ njikwa.

Lee [Usoro Plugins](../frameworks/PLUGIN_SDK.md) maka nkọwa zuru ezu.

---

## Shadow Routing

Ntụnyere Shadow / A-B nke providers **abụghị REST surface kwụụrụ onwe ya** — a na-ahazi ya site na combo routing (lee [Auto-Combo](../routing/AUTO-COMBO.md)). A na-enye metrik ntụnyere nke combo ọ bụla site na `GET /api/combos/metrics`.

---

## Guardrails

Nyochaa guardrails nke runtime (nchọpụta PII, nchọpụta prompt injection, vision bridging). Guardrails na-arụ ọrụ na arịrịọ ọ bụla; ịpụ na ya maka otu ọkpụkpọ bụ site na request header `x-omniroute-disabled-guardrails` — enweghị ebe echekwara maka ịgbanye/ịgbanyụọ ya.

| Usoro | Ụzọ                    | Nkọwa                                                                                            |
| ----- | ---------------------- | ------------------------------------------------------------------------------------------------ |
| GET   | `/api/guardrails`      | Depụta guardrails ndị e debanyere aha na ọnọdụ ha (aha / agbanyere / mkpa)                       |
| POST  | `/api/guardrails/test` | Mee nnwale akọrọ nke pipeline tupu ọkpụkpọ n’elu input atụ — ahụ: `{input, disabledGuardrails?}` |

**Nkwenye njirimara:** Ọ chọrọ nnọkọ njikwa.

Lee [Nchekwa > Guardrails](../security/GUARDRAILS.md) maka nkọwa zuru ezu.

---

---

## Nkwenye njirimara

Lee [Nkwenye Njirimara Njikwa](../guides/MANAGEMENT-AUTH.md) maka ezinụlọ nzere anọ ahụ (nnọkọ dashboard, token CLI mpaghara, Token Nnweta `oma_live_…`, API key nwere oke njikwa) na etu ha si dị iche na igodo inference.

- Ụzọ dashboard (`/dashboard/*`) na-eji kuki `auth_token`
- Nbanye na-eji hash okwuntughe echekwara; ma ọ bụrụ na nke ahụ ada, ọ na-eji `INITIAL_PASSWORD`
- Enwere ike ịgbanwuo `requireLogin` site na `/api/settings/require-login`
- Ụzọ `/v1/*` nwere ike ịchọ Bearer API key mgbe `REQUIRE_API_KEY=true`
- “token njikwa” / “API key nwere oke njikwa” n'ime ntụaka a pụtara otu n'ime ezinụlọ ndị dị na ntuziaka ahụ — ọ bụghị ụdị nzuzo ọzọ a na-akọwaghị

> **Mgbanwe na-emebi ndakọrịta (v3.8.0)** — `/api/v1/agents/tasks/*` na endpoint njikwa cooldown chọrọzi **nkwenye njirimara njikwa** (kuki dashboard `auth_token` ma ọ bụ API key nwere oke njikwa). Ndị ahịa kpọburu ụzọ ndị a na-enweghị nkwenye njirimara ga-enweta `401 Unauthorized`. Lee commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).