# API Reference (Kiswahili)

🌐 **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) · 🇳🇬 [ig](../../../ig/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) · 🇮🇳 [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)

---

🌐 **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) · 🇳🇬 [ig](../../../ig/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) · 🇮🇳 [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)

Rejeleo kuu la API ya OmniRoute. Linahusu sehemu ya umma ya `/v1` na vituo vya mwisho vya usimamizi vinavyotumika zaidi; [`docs/openapi.yaml`](../openapi.yaml) inayoweza kusomeka na mashine pamoja na mti wa njia ulio chini ya `src/app/api/` ndiyo vyanzo kamili.

---

## Yaliyomo

- [Ukamilishaji wa Gumzo](#chat-completions)
- [Ukodishaji wa Kipekee wa Vipindi Vinavyodhibitiwa](#exclusive-managed-session-leases)
- [Upachikaji](#embeddings)
- [Uundaji wa Picha](#image-generation)
- [OCR ya Hati](#document-ocr)
- [Orodha ya Miundo](#list-models)
- [Manifesti ya Programu-jalizi ya Mtoa Huduma](#provider-plugin-manifest)
- [Vituo vya Mwisho vya Uoanifu](#compatibility-endpoints)
- [API ya Faili](#files-api)
- [API ya Makundi](#batches-api)
- [API ya Utafutaji](#search-api)
- [Utiririshaji wa WebSocket](#websocket-streaming)
- [Ripoti za Vikomo na Matatizo](#quotas--issues-reporting)
- [Akiba ya Kisemantiki](#semantic-cache)
- [Dashibodi na Usimamizi](#dashboard--management)
- [Usimamizi wa Mchanganyiko](#combo-management)
- [Webhooks](#webhooks)
- [Funguo Zilizosajiliwa (Usimamizi Otomatiki)](#registered-keys-auto-management)
- [Itifaki ya Mawakala](#agents-protocol)
- [Proksi za Usimamizi](#management-proxies)
- [Ustahimilivu (uliopanuliwa)](#resilience-extended)
- [Ujuzi](#skills)
- [Kumbukumbu](#memory)
- [Seva ya MCP](#mcp-server)
- [Seva ya A2A](#a2a-server)
- [Wingu, Tathmini na Upimaji](#cloud-evals--assess)
- [Uchakataji wa Maombi](#request-processing)
- [Uthibitishaji](#authentication)

---

## Ukamilishaji wa Gumzo

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

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Andika kitendakazi cha..."}
  ],
  "stream": true
}
```

### Vichwa Maalum

| Kichwa                   | Mwelekeo | Maelezo                                                                                                                                                                                                                                   |
| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache`   | Ombi     | Weka kuwa `true` ili kukwepa akiba                                                                                                                                                                                                        |
| `x-omniroute-no-memory`  | Ombi     | Weka kuwa `true` ili kuruka udungaji wa kumbukumbu + ujuzi kwa ombi hili (hufuata tabia ya kutotumia akiba; huepuka gharama ya tokeni/gharama kwa kila mwito)                                                                             |
| `X-OmniRoute-Progress`   | Ombi     | Weka kuwa `true` kwa matukio ya maendeleo                                                                                                                                                                                                 |
| `X-Session-Id`           | Ombi     | Ufunguo wa kipindi unaodumu kwa ajili ya uhusiano wa kipindi cha nje                                                                                                                                                                      |
| `x_session_id`           | Ombi     | Lahaja yenye mstari wa chini pia inakubaliwa (HTTP ya moja kwa moja)                                                                                                                                                                      |
| `X-OmniRoute-Session-Id` | Ombi     | Lebo ya kipindi/mazungumzo iliyotolewa na mwitaji (pia huingizwa kwenye kumbukumbu). Inapokuwepo, huhifadhiwa kama ilivyo katika `call_logs.session_tag` kwa uhusishaji wa gharama kwa kila kipindi (#8249) — haitungwi kamwe ikiwa haipo |
| `Idempotency-Key`        | Ombi     | Ufunguo wa kuondoa nakala (dirisha la sekunde 5)                                                                                                                                                                                          |
| `X-Request-Id`           | Ombi     | Ufunguo mbadala wa kuondoa nakala                                                                                                                                                                                                         |
| `X-OmniRoute-Cache`      | Jibu     | `HIT` au `MISS` (bila utiririshaji)                                                                                                                                                                                                       |
| `X-OmniRoute-Idempotent` | Jibu     | `true` ikiwa nakala iliondolewa                                                                                                                                                                                                           |
| `X-OmniRoute-Progress`   | Jibu     | `enabled` ikiwa ufuatiliaji wa maendeleo umewashwa                                                                                                                                                                                        |
| `X-OmniRoute-Session-Id` | Jibu     | Kitambulisho halisi cha kipindi kinachotumiwa na OmniRoute                                                                                                                                                                                |
| `X-OmniRoute-Request-Id` | Jibu     | Kitambulisho cha uhusianishaji wa ombi (kinapojulikana)                                                                                                                                                                                   |
| `X-OmniRoute-Version`    | Jibu     | Toleo la muundo wa OmniRoute (lipo kila wakati)                                                                                                                                                                                           |
| `X-OmniRoute-Cost-Saved` | Jibu     | Kiasi cha USD ambacho akiba iliepusha wakati wa `HIT` (kwa matumizi ya akiba pekee)                                                                                                                                                       |
| `X-OmniRoute-Decision`   | Jibu     | Rekodi ya uelekezaji: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` ni mkakati wa mchanganyiko, au `single` kwa ombi lisilo la mchanganyiko) — ipo kila wakati katika majibu ya ukamilishaji                              |

> Dokezo la Nginx: ikiwa unategemea vichwa vyenye mistari ya chini (kwa mfano `x_session_id`), washa `underscores_in_headers on;`.

> **Vichwa vya telemetria ya gharama:** majibu yaliyofaulu yasiyotiririshwa pia huwa na mkusanyiko wa telemetria ya gharama wa `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, tarakimu 10 zisizobadilika baada ya nukta ya desimali; `0.0000000000` kwa huduma za bure/zisizo na bei), `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` (ikiwa tu > 0), pamoja na `X-OmniRoute-Request-Id` na `X-OmniRoute-Version`. Hivi hutolewa na ukamilishaji wa gumzo, `/v1/responses`, `/v1/messages`, **pamoja na endpoints za midia** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations`, na `/v1/moderations` (gharama daima ni `0`). Gharama ya midia hukokotolewa kulingana na kila aina ya data (kwa kila picha, kwa kila sekunde, kwa kila herufi, kwa kila kitengo cha utafutaji) wakati bei inapatikana; vinginevyo ni `0` (fail-open).

> **Semantiki za gharama ya cache-hit:** kunapokuwa na HIT ya akiba ya kisemantiki (`X-OmniRoute-Cache-Hit: true`), hakuna ombi linalotumwa kwa mtoa huduma wa upstream, kwa hivyo `X-OmniRoute-Response-Cost` huwa `0.0000000000` (gharama ya **ziada** ya kutoa hit hiyo). Gharama ya awali/ambayo ingekuwepo huripotiwa kando katika `X-OmniRoute-Cost-Saved`. Watumiaji wa data ya utozaji wanapaswa kujumlisha `X-OmniRoute-Response-Cost` (hit hazigharimu chochote); uchanganuzi wa akiba unaweza kujumlisha `X-OmniRoute-Cost-Saved`.

## Mikataba ya Kipekee ya Kukodisha Vipindi Vinavyosimamiwa

Ukodishaji wa vipindi vinavyosimamiwa vya kipekee ni mkataba wa hiari, usioegemea mteja wa uelekezaji: mmiliki mmoja anayefanya kazi anashikilia muunganisho mmoja unaostahiki wa OmniRoute. Haikodishi modeli, haihitaji OAuth, haitambui mteja maalum, au haihitaji mtoa huduma maalum.

Kitufe cha API cha uthibitishaji lazima kiwe na wigo `lease:exclusive` na orodha wazi isiyo tupu ya `allowedConnections`. Mpaka wa mabadiliko ya hifadhidata unatekeleza sehemu zote mbili pamoja wakati wa kuunda kitufe na masasisho ya sehemu.

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

Majibu yenye mafanikio ya kupata, kusasisha, na kutoa yanaonyesha mihuri ya muda, `state`, na `generation` halisi chanya, lakini kamwe muunganisho uliochaguliwa au vitambulisho. Kusasisha na kutoa hutoa kizazi katika mwili wa JSON:

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

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

Mmiliki wa ukodishaji anayefanya kazi anaweza kuomba waziwazi metadata ya kuonyesha salama ya faragha kwa muunganisho wake wa sasa:

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

Kitendo hiki cha hali ya hiari kinalindwa na mmiliki asiyejulikana, kitufe cha API kinachosimamiwa kilichothibitishwa, na kizazi halisi kinachotumika katika muamala mmoja wa hifadhidata. `displayName` ni jina la muunganisho lililopunguzwa tu; ni `null` wakati hakuna jina salama lililosanidiwa. OmniRoute kamwe haibadilishi barua pepe au kitambulisho cha akaunti kilichozalishwa. Thamani ya mtoa huduma ni lebo ya kuonyesha isiyo nyeti na kamwe si kitambulisho cha mtoa huduma kinachooana kilichozalishwa. Vitambulisho, tokeni, vidakuzi, vitambulisho vya muunganisho ghafi au API, heshi za mmiliki, siri za uzio, na data ya uelekezaji wa ndani zimetengwa.

Utafutaji wa kitufe kibaya, mmiliki mbaya, kizazi kilichopitwa na wakati, kilichokosekana, kilichopitwa na muda, kilichotolewa, na kisichofaa vyote hurejesha hitilafu sawa ya `409 LEASE_FENCE_STALE` bila metadata ya muunganisho. Mteja aliyepokea jibu la kusubiri uwezo hana muunganisho amilifu wa kukagua. Wakati uelekezaji unabadilisha ukodishaji amilifu, kizazi kilekile kinabaki halali na hali hurejesha kiatomiki muunganisho mpya, kamwe sio wa zamani. Wateja waliopo wanabaki bila kubadilika kwa sababu majibu ya kupata, kusasisha, kutoa, na kusubiri yanabaki na maumbo yao ya awali.

Mkataba huu wa seva haubadilishi `/status` ya kawaida ya OpenAI Codex. Codex ya kawaida kwa sasa inaripoti mtoa huduma wake wa modeli na hali ya uthibitishaji/akaunti iliyojengwa ndani lakini haitoi metadata ya akaunti ya mtoa huduma maalum; ujumuishaji wa mteja wa baadaye lazima upige hatua hii na kuamua jinsi ya kuonyesha `connection.displayName`.

Kila ombi la utambuzi linalosimamiwa kisha hutoa vichwa vyote viwili vya udhibiti:

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

Mmiliki halisi, kizazi, muunganisho amilifu, na kitufe cha API kilichothibitishwa vinalindwa mara moja kabla ya kila jaribio la juu linaloungwa mkono. Kurudia mmiliki na kizazi kwa kitufe kingine kutashindwa hata kama kitufe hicho kinaruhusu muunganisho uleule. Wamiliki ghafi hawahifadhiwi, hawajaingizwa kwenye kumbukumbu, hawahifadhiwi kwenye picha ya ombi, au hawajasambazwa juu.

Mzozo wa muda hurejesha HTTP `429` na `Retry-After` na:

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

Jibu hili linamaanisha tu kwamba seti ya kawaida inayostahiki haikuwa tupu na kila mgombea huru alishikiliwa na ukodishaji amilifu wa kigeni. Modeli/watoa huduma wasioungwa mkono, kutolingana kwa sera, kupoa, kiasi, afya, na hitilafu zingine za kawaida za kustahiki zinabaki na majibu yao yaliyopo ya OmniRoute.

### `x-omniroute-compression`

Kubatilisha mpango wa mbano kwa kila ombi. Kipaumbele cha juu zaidi — kinashinda ubatilishaji wa mchanganyiko wa uelekezaji, profaili amilifu, kichochezi kiotomatiki, na paneli Chaguomsingi. Thamani:

| Thamani       | Athari                                                                                                              |
| :------------ | :------------------------------------------------------------------------------------------------------------------ |
| `off`         | Hakuna mbano kwa ombi hili.                                                                                         |
| `default`     | Profaili Chaguomsingi inayotokana na paneli (hupuuza profaili inayotumika). Injini zenye upotevu huachwa zimezimwa. |
| `safe`        | Kupunguza marudio na kukunja nafasi nyeupe pekee.                                                                   |
| `allow-lossy` | Weka mpango wa opereta kwa ombi hili, ikijumuisha muhtasari na uandishi upya wa mtindo.                             |
| `engine:<id>` | Injini moja inapowezeshwa, k.m. `engine:rtk`. Kujiunga kwa hiari kwa injini hiyo kwa kila ombi.                     |
| `<combo>`     | Mchanganyiko uliotajwa, unaolinganishwa kwa jina (bila kujali herufi kubwa/ndogo) kwanza, kisha kwa kitambulisho.   |

Vidokezo:

- Thamani zisizojulikana hupuuzwa (ombi halikataliwi kamwe); utatuzi huangukia kwenye kipaumbele cha kawaida cha opereta.
- Ikiwa michanganyiko mingi inashiriki jina, pitisha **kitambulisho** cha mchanganyiko kwa ulinganifu usiobadilika.
- Mchanganyiko ambao jina lake ni `off` au `default` hauwezi kuchaguliwa kwa jina (maneno hayo muhimu hutafsiriwa kwanza); rejelea mchanganyiko kama huo kwa kitambulisho chake.
- Swichi kuu ya mbano ni lango gumu: mbano inapozimwa kimataifa, kichwa hiki hakiwezi kuiwasha.

Mpango uliotumika unarudishwa kwenye kichwa cha jibu:

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

ambapo `<source>` ni mojawapo ya `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, au `off`.

---

## Upachikaji

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

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

Watoa huduma wanaopatikana: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.

Vitambulisho vya katalogi ni `provider/model` (mfano: `jina-ai/jina-embeddings-v5-omni-small`). Vitambulisho vya modeli za Jina visivyo na kiambishi cha mtoa huduma vinavyoonekana kwenye sajili (kwa mfano `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) pia vinatambulika. Operesheni za embed/rerank/classify/segment za Jina hutumia kwanza vitambulisho vya `jina-ai` vya dashibodi; `JINA_AI_API_KEY` hutumika kama mbadala tu wakati hakuna ufunguo wa dashibodi. Kadi ya `jina-reader` ni ya Reader / `r.jina.ai` pekee (`POST /v1/web/fetch`) na haitoi kamwe huduma za embeddings au rerank.

Modeli za sajili zinazotangaza usaidizi wa hali nyingi pia zinakubali hadi vipengee 32 vilivyoundwa kwa muundo usiotegemea mtoa huduma. Aina za vipengee vya midia ni `text`, `image`, `audio`, `video`, na `document`. `source` ya midia yake ni ama `{"type":"url","url":"https://..."}` au
`{"type":"base64","data":"...","media_type":"..."}`.

Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`,
na lakabu ya familia `jina-ai/jina-embeddings-v5-omni` → omni-small) pia inakubali hati asilia za EmbeddingsV5Request za Jina na **kuzituma bila kuzibadilisha** hadi `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,..." }]
    }
  ]
}
```

Thamani asilia za `{ image | audio | video | pdf }` zinaweza kuwa URL ya umma ya HTTPS, URI ya `data:`, au base64 ghafi. OmniRoute haibadilishi vitu hivyo kuwa mifuatano ya maandishi wala kuchukua URL asilia za picha — Jina yenyewe huchukua midia ya umma. Sehemu za ziada za Jina (`task`, `normalized`, `truncate`, `embedding_type`) zinatumwa kama zilivyo. SKU za Jina za maandishi pekee bado zinakataa hati zisizo za maandishi.

Mipaka ya usalama na usafirishaji:

- URL za midia za mbali lazima ziwe za HTTPS ya umma. Vipengee vya kawaida vya `{type,source:url}` huchukuliwa upande wa seva (uthibitishaji upya wa uelekezaji, muda wa kuisha, vikomo vya ukubwa, DNS ya umma, na ubandikaji wa muunganisho) na kupachikwa kabla ya ombi kwa mtoa huduma. Vipengee asilia vya Jina vya `{image:"https://..."}` hutumwa kama vilivyo baada ya ukaguzi uleule wa HTTPS ya umma; Jina huchukua URL.
- Midia ya base64 iliyopachikwa ina kikomo cha MiB 8 baada ya kusimbuliwa kwa kila kipengee na MiB 16 baada ya kusimbuliwa kwa ombi lote.

Ubadilishaji kwa mtoa huduma (vipengee vya kawaida havitumwi kamwe bila kubadilishwa):

- Modeli za Jina za hali nyingi: kila kipengee cha ngazi ya juu hubadilishwa kuwa kitu kimoja chenye ufunguo wa aina ya data (`text` / `image` / `audio` / `video` / `pdf`) kikitumia URI za data kwa midia iliyopachikwa; vekta moja kwa kila kipengee cha ngazi ya juu.
- Familia ya Gemini Embedding 2: safu moja ya ngazi ya juu hubadilishwa kuwa ombi moja asilia la `models/{model}:embedContent` lenye `content.parts` (`text` au `inline_data`).
- Modeli zisizojulikana/zilizoundwa kwa wakati halisi zisizo na metadata ya aina ya data iliyobainishwa hukataa ingizo lenye muundo kwa 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"
}
```

Mchanganyiko wa modeli/aina ya data usiotumika hurejesha HTTP 400 badala ya kulazimisha ubadilishaji wa kipengee. Sehemu za viendelezi zisizo za ingizo kwenye maombi ya zamani ya mifuatano ya maandishi/tokeni zinaendelea kupitishwa bila kubadilishwa.

```bash
# Orodhesha modeli zote za upachikaji
GET /v1/embeddings
```

---

## Uzalishaji wa Picha

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

Watoa huduma wanaopatikana: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (ya ndani), ComfyUI (ya ndani).

```bash
# Orodhesha miundo yote ya picha
GET /v1/images/generations
```

---

## OCR ya Hati

```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` huchagua mtoa huduma wa OCR kupitia kiambishi awali cha `provider/model`; kitambulisho cha modeli pekee (kwa mfano,
`mistral-ocr-latest`) huelekezwa kwa mtoa huduma wake aliyesajiliwa, na `model` ikiachwa nje hutumia
Mistral (`mistral-ocr-latest`) kama chaguo-msingi. Watoa huduma waliosajiliwa (`open-sse/config/ocrRegistry.ts`):

| Kitambulisho cha mtoa huduma  | Kitambulisho cha modeli | Thamani ya `model`                                           | Maelezo                                                                                                                       |
| ----------------------------- | ----------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `mistral`                     | `mistral-ocr-latest`    | `mistral/mistral-ocr-latest` (au `mistral-ocr-latest` pekee) | Sawazishi — jibu hurejeshwa moja kwa moja kutoka kwenye ombi moja la huduma ya juu.                                           |
| `azure-document-intelligence` | `prebuilt-read`         | `azure-document-intelligence/prebuilt-read`                  | Huduma ya juu isiyosawazishwa (`analyze` + upigaji kura) — tazama hapa chini.                                                 |
| `vertex-deepseek-ocr`         | `deepseek-ocr-maas`     | `vertex-deepseek-ocr/deepseek-ocr-maas`                      | Sawazishi, kupitia endpoint mshirika ya Vertex AI ya `openapi/chat/completions` — tazama hapa chini kuhusu uthibitishaji/URL. |

Watoa huduma wote watatu hujibu kwa muundo sawa wa ujumbe unaofanana na wa Mistral:

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

### Mtiririko wa upigaji kura wa Azure Document Intelligence

API ya `analyze` ya Azure Document Intelligence si sawazishi: ombi la awali hurejesha kichwa cha
`Operation-Location` badala ya ujumbe, na matokeo lazima yauliziwe mara kwa mara. Kishughulikiaji
(`open-sse/handlers/ocr.ts`) huulizia URL hiyo kila sekunde kwa hadi majaribio 30, hushindwa mara moja (bila
kuendelea kuulizia) endapo jibu la upigaji kura si `ok` au hali ni `"failed"`, na hurejesha `504` ikiwa
operesheni bado inaendelea baada ya idadi ya majaribio kuisha. Jibu la mwisho la Azure
husawazishwa kuwa katika muundo uleule wa `pages`/`markdown` unaotumiwa na Mistral kabla ya kurejeshwa kwa
mwombaji, hivyo msimbo wa mteja hauhitaji kushughulikia mtoa huduma kwa namna maalumu.

### Uthibitishaji na utatuzi wa endpoint wa Vertex AI DeepSeek OCR

`vertex-deepseek-ocr` hutumia tena uthibitishaji uleule wa Vertex AI ambao OmniRoute tayari inautumia kwa
trafiki ya gumzo/picha (`open-sse/executors/vertex.ts`): ufunguo wa API wa muunganisho ama ni
kitambulisho cha JSON cha Service Account (kinachobadilishwa kuwa tokeni ya ufikiaji ya OAuth ya muda mfupi kupitia mtiririko wa
JWT-bearer) au tokeni ya ufikiaji ya OAuth iliyokwisha kutolewa inayotumiwa kama ilivyo. URL ya endpoint ya huduma ya juu ni
endpoint mshirika ya jumla ya Vertex ya `openapi/chat/completions`, iliyoundwa kutoka kwa mradi na
eneo la muunganisho — `providerSpecificData.project`/`providerSpecificData.region` iliyobainishwa wazi daima hupewa kipaumbele;
vinginevyo, mradi hutokana na `project_id` ya JSON ya Service Account na eneo
hutumia `us-central1` kama chaguo-msingi. Utatuzi wote wawili hufanyika katika `open-sse/handlers/ocr.ts`
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`), na hutumiwa na
`src/app/api/v1/ocr/route.ts` kabla ya kutumwa kwa `handleOcr`.

---

## Orodhesha Modeli

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

→ Hurejesha modeli zote za gumzo, embedding na picha pamoja na michanganyiko yake katika umbizo la OpenAI
```

### Viambishi awali vya id ya modeli (`?prefix=`)

Modeli nyingi hutangazwa chini ya **kiambishi awali cha mtoa huduma**. Kiambishi awali unachopata hudhibitiwa na
alama ya kipengele ya `MODELS_CATALOG_PREFIX_MODE`, na kinaweza kubatilishwa **kwa kila ombi** kwa kutumia
kigezo cha hoja — jambo linalofaa kwa mteja anayetaka orodha safi bila kubadilisha mpangilio wa seva nzima
kwa kila mtu mwingine:

```bash
GET /v1/models?prefix=alias        # id moja kwa kila modeli — kiambishi awali kifupi cha jina mbadala
GET /v1/models?prefix=dual         # miundo yote miwili (chaguo-msingi la seva)
GET /v1/models?prefix=canonical    # kiambishi awali kamili cha id ya mtoa huduma pekee
```

| Hali        | Hutoa                                                    | Maelezo                                                                                                                                                                                                                       |
| ----------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual`      | `cc/claude-sonnet-4-6` **na** `claude/claude-sonnet-4-6` | **Chaguo-msingi.** id zote mbili huelekezwa kwenye modeli ileile; zimehifadhiwa ili usanidi wa wateja ulioweka mojawapo moja kwa moja uendelee kufanya kazi. Takribani huongeza ukubwa wa katalogi mara mbili.                |
| `alias`     | `cc/claude-sonnet-4-6`                                   | Ingizo moja kwa kila modeli. Watoa huduma wasio na jina mbadala tofauti bado hutoa ingizo lao, kwa hivyo hakuna kinachopotea.                                                                                                 |
| `canonical` | `claude/claude-sonnet-4-6`                               | Ingizo moja kwa kila modeli chini ya kiambishi awali kamili cha id ya mtoa huduma. Watoa huduma wasio na jina mbadala tofauti (kwa mfano `antigravity/…`, `agy/…`) pia hutoa id yao moja hapa, kwa hivyo hakuna kinachopotea. |

Kioo cha hali ya `dual` kinaweza pia kutambuliwa bila kigezo cha hoja: huwa na uga wa `parent`
unaoelekeza kwenye id ya msingi.

Wateja wanaoonyesha kiteuzi cha modeli wanapaswa kuomba `?prefix=alias` — hivi ndivyo
[kiendelezi cha OmniCopilot cha VS Code](../guides/VSCODE-COPILOT.md) hufanya.

### Vibadala vya modeli visivyo na kufikiri

Kwa modeli za Claude zenye uwezo wa kufikiri, `/v1/models` pia hutangaza kibadala **kisicho na kufikiri** ambacho id yake huanza na `claude-3-omniroute-no-thinking/`:

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

Kuchagua id hii (kwa mfano katika usanidi wa Claude Code ambao daima huambatisha kizuizi cha `thinking`) hurejea kwenye `<provider>/<model>` halisi huku utoaji wa hoja ukiwa umezimwa — `thinking:{type:"disabled"}` kwenye njia ya `/v1/messages`, au uga za `reasoning`/`reasoning_effort` huondolewa kwenye njia ya `/v1/chat/completions`. Kibadala huorodheshwa tu kwa modeli za familia ya Claude zinazotumia kufikiri **na** zinazoheshimu `disabled` (kwa hivyo, kwa mfano, modeli zinazotumia hali badilifu pekee na zinazokataa `disabled` hazijumuishwi). Waendeshaji wanaweza kulazimisha kibadala kuwashwa au kuzimwa kwa kila modeli kupitia `ModelSpec.noThinkingAlias`.

---

## Manifesti ya Programu-jalizi ya Mtoa Huduma

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

Hurejesha manifesti salama kwa JSON ya programu-jalizi ya mtoa huduma inayotumiwa na Bifrost, CLIProxyAPI, na vipanga-njia vya sidecar vya baadaye. Jibu huzalishwa kutoka kwenye sajili ya watoa huduma ya TypeScript na kwa makusudi halijumuishi siri za mteja wa OAuth, utatuzi wa mazingira wakati wa utekelezaji, vitendaji vya utekelezaji, vichwa vya maombi, na data ya akaunti.

Tumia endpoint hii wakati sidecar inaendeshwa nje ya mchakato na haiwezi kuleta
`open-sse/config/providerPluginManifestRegistry.ts` moja kwa moja.

---

## Vituo vya Upatanifu

| Method | Path                                      | Format                                                   |
| ------ | ----------------------------------------- | -------------------------------------------------------- |
| POST   | `/v1/chat/completions`                    | OpenAI                                                   |
| POST   | `/v1/messages`                            | Anthropic                                                |
| POST   | `/v1/responses`                           | Majibu ya OpenAI                                         |
| POST   | `/v1/embeddings`                          | OpenAI                                                   |
| POST   | `/v1/images/generations`                  | Picha za OpenAI                                          |
| POST   | `/v1/images/edits`                        | Picha za OpenAI (hariri/jaza)                            |
| POST   | `/v1/videos/generations`                  | Uzalishaji wa video wa mtindo wa OpenAI                  |
| POST   | `/v1/music/generations`                   | Uzalishaji wa muziki wa mtindo wa OpenAI                 |
| POST   | `/v1/audio/transcriptions`                | Sauti ya OpenAI (STT)                                    |
| POST   | `/v1/audio/speech`                        | OpenAI TTS (inrudisha mwili wa sauti)                    |
| POST   | `/v1/rerank`                              | Panga upya kwa mtindo wa Cohere/Voyage                   |
| POST   | `/v1/classify`                            | Panga Jina (`api.jina.ai`)                               |
| POST   | `/v1/segment`                             | Kigawanyaji cha Jina (`segment.jina.ai`)                 |
| POST   | `/v1/moderations`                         | Usimamizi wa OpenAI                                      |
| 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}/`                 | Jina mbadala la katalogi ya OpenAI                       |
| GET    | `/api/v1/vscode/{token}/models`           | Jina mbadala la miundo ya OpenAI                         |
| POST   | `/api/v1/vscode/{token}/chat/completions` | Jina mbadala la OpenAI lililowekwa tokeni                |
| POST   | `/api/v1/vscode/{token}/responses`        | Majibu ya OpenAI yaliyowekwa tokeni jina mbadala         |
| POST   | `/api/v1/vscode/{token}/api/chat`         | Jina mbadala la Ollama lililowekwa tokeni                |
| GET    | `/api/v1/vscode/{token}/api/tags`         | Vitambulisho vya Ollama vilivyowekwa tokeni jina mbadala |

Njia zote za POST zinafuata umbo sawa: `Bearer your-api-key` + mwili wa JSON uliothibitishwa na Zod (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, n.k., angalia `src/shared/validation/schemas.ts`). 4xx inarudishwa kwenye kushindwa kwa schema.

Kwa wateja ambao hawawezi kuambatisha `Authorization: Bearer ...`, OmniRoute pia inakubali funguo za API kwenye URL kupitia utangamano wa kamba ya swali (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) au vituo maalum vya `/api/v1/vscode/{token}/...` vilivyoelezwa hapa chini.

```bash
# Panga upya (mtoa huduma wa rejista ya wingu, au nodi ya mtoa huduma inayooana na OpenAI kama "<prefix>/<model>")
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Panga Jina (vitambulisho vya API ya Msingi)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Kigawanyaji cha Jina
POST /v1/segment     { "content": "...", "return_chunks": true }

# Utafutaji wa Jina (s.jina.ai; majina mbadala ya mtoa huduma: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# Usimamizi
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — inarudisha mwili wa audio/mpeg (au umbizo lililoombwa)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Hariri picha (sehemu nyingi)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Uzalishaji wa video / muziki (kitambulisho cha mfumo kilichotanguliwa na mtoa huduma)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }
```

> **Nodi za mtoa huduma wa kupanga upya:** `POST /v1/rerank` pia inaelekeza kwenye nodi za mtoa huduma zinazooana na OpenAI (oMLX, vLLM, Infinity, TEI nyuma ya lango, …) zinazoshughulikiwa kama `<node-prefix>/<model>`. Nodi za loopback (`localhost`, `127.0.0.1`, `172.16.0.0/12`) zinastahiki kila wakati. Nodi kwenye seva pangishi nyingine yoyote — sanduku la LAN au rika la Tailscale — zinastahiki tu wakati opereta anawasha bendera ya kipengele cha `RERANK_REMOTE_PROVIDER_NODES` **na** URL ya msingi ya nodi inapita sera ya URL ya nje ya mtoa huduma (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`); seva pangishi za metadata za wingu hazielekezwi kamwe. Hatua ya kupanga upya ya injini ya kumbukumbu inaita njia hii kupitia loopback, kwa hivyo sheria hiyo hiyo inasimamia `rerankProviderModel` katika mipangilio ya Kumbukumbu.
>
> **Maumbo ya seva ya ndani:** nodi inaitwa kwa `<base>/v1/rerank` na, kwenye 404, kwa `<base>/rerank` (Infinity, TEI). Mwili wa juu hubeba tahajia ya Cohere/OpenAI (`documents`, `return_documents`) na tahajia ya TEI (`texts`, `return_text`), na jibu la juu limerekebishwa kwa bahasha ya Cohere: `[{index, score, text}]` tupu ya TEI, `{results: [{index, score}]}` kutoka kwa lango nyembamba, na `{data: [...]}` ya mtindo wa Voyage zote zinarudi kwa mteja kama `{results: [{index, relevance_score, document?}]}`, zikipangwa kwa alama na kuwekewa kikomo kwa `top_n`.

> **Ugunduzi wa nodi ya mtoa huduma:** miundo kwenye nodi ya mtoa huduma inayooana na OpenAI inaonekana katika `GET /v1/models` chini ya kiambishi awali cha nodi. Safu ambazo hazina metadata ya kituo (kawaida kwa orodha za ndani za `/v1/models`) hurithi `apiType` ya nodi, kwa hivyo miundo ya nodi ya `embeddings` ni `type: "embedding"` na miundo ya nodi ya `rerank` ni `type: "rerank"` badala ya kuelekea kwenye gumzo; `supportedEndpoints` iliyo wazi kwenye safu iliyosawazishwa au iliyoongezwa mwenyewe bado inatanguliza.

### Njia Maalum za Mtoa Huduma

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

Kiambishi awali cha mtoa huduma huongezwa kiotomatiki kikikosekana. Miundo isiyolingana hurudisha `400`.

---

## API ya Faili

Endpointi ya faili inayooana na OpenAI kwa ingizo/tokeo la kundi na upakiaji wa faili kulingana na madhumuni.

| Mbinu  | Njia                     | Maelezo                                                                                                                 |
| ------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/files`              | Pakia faili (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — kiwango cha juu 512 MiB |
| GET    | `/v1/files`              | Orodhesha faili za ufunguo wa API uliothibitishwa                                                                       |
| GET    | `/v1/files/[id]`         | Pata metadata ya faili                                                                                                  |
| DELETE | `/v1/files/[id]`         | Futa faili                                                                                                              |
| GET    | `/v1/files/[id]/content` | Tiririsha mwili ghafi wa faili kurudi                                                                                   |

**Uthibitishaji:** Ufunguo wa API wa Bearer — faili zinawekewa upeo kwa kila ufunguo wa API kupitia `getApiKeyRequestScope`. Ufunguo
huona, hupakua na kufuta faili zake pekee; kipindi cha dashibodi kisicho na ufunguo husoma
mfumo mzima; faili isiyo na mmiliki (upakiaji usiojulikana au wa kipindi cha dashibodi) inakataliwa kwa kila
mwombaji asiye wa kipindi. `GET /v1/files` humkataa mwombaji asiyejulikana — pamoja na ufunguo uliowasilishwa ambao
hautambuliki — kwa `401` hata wakati `REQUIRE_API_KEY=false`, badala ya kuorodhesha faili za
wapangaji wote (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

## API ya Makundi

Uchakataji wa makundi unaooana na OpenAI.

| Mbinu  | Njia                      | Maelezo                                                                                                       |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/batches`             | Unda kundi — mwili unathibitishwa na `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) |
| GET    | `/v1/batches`             | Orodhesha makundi                                                                                             |
| GET    | `/v1/batches/[id]`        | Pata hali ya kundi + `request_counts`                                                                         |
| DELETE | `/v1/batches/[id]`        | Futa kundi lililokamilika/lililoshindwa                                                                       |
| POST   | `/v1/batches/[id]/cancel` | Ghairi kundi linaloendelea                                                                                    |

**Uthibitishaji:** Ufunguo wa API wa Bearer. Makundi yanawekewa upeo kwa kila ufunguo wa API chini ya kanuni ileile ya njia tatu kama
faili: ufunguo wenyewe pekee, kipindi cha dashibodi katika mfumo mzima, rekodi zisizo na mmiliki zinakataliwa kwa kila
mwombaji asiye wa kipindi (kupata, kufuta, kughairi, na ukaguzi wa `input_file_id` wakati wa kuunda).
`GET /v1/batches` humkataa mwombaji asiyejulikana kwa `401` hata wakati `REQUIRE_API_KEY=false`.

---

## API ya Utafutaji

Safu ya uondoaji utegemezi kwa watoa huduma za wavuti/utafutaji (Tavily, Brave, Exa, Serper, n.k.).

| Mbinu | Njia                   | Maelezo                                                                                                       |
| ----- | ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| GET   | `/v1/search`           | Orodhesha watoa huduma za utafutaji waliowekwa + uwezo wao                                                    |
| POST  | `/v1/search`           | Tekeleza hoja ya utafutaji — mwili unathibitishwa na `v1SearchSchema`, inasaidia uhifadhi wa muda/ujumuishaji |
| GET   | `/v1/search/analytics` | Takwimu za mafanikio/ucheleweshaji/akiba kwa kila mtoa huduma                                                 |

**Uthibitishaji:** Ufunguo wa API wa Bearer (`extractApiKey` + `isValidApiKey`). Sera ya utafutaji inatekelezwa kupitia `enforceApiKeyPolicy`.

---

## API ya Kuchota Maudhui ya Wavuti

Toa maudhui kutoka URL kupitia mtoa huduma wa kuchota maudhui ya wavuti aliyesanidiwa (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

| Mbinu | Njia            | Maelezo                                                                    |
| ----- | --------------- | -------------------------------------------------------------------------- |
| POST  | `/v1/web/fetch` | Chota/kusanya data kutoka URL — mwili unathibitishwa na `v1WebFetchSchema` |

**Uthibitishaji:** Ufunguo wa API wa Bearer (`extractApiKey` + `isValidApiKey`). Sera inatekelezwa kupitia `enforceApiKeyPolicy`.

**Urejeaji mbadala unaozingatia kiwango (#8297):** wakati hakuna `provider` mahususi aliyetolewa, kundi
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) linapitiwa
kwa mpangilio usiobadilika
wa kipaumbele (jaza-wa-kwanza) — mtoa huduma aliyesanidiwa lakini aliyewekewa kikomo cha kiwango anarukwa
badala ya kusitisha ombi mara moja, na hitilafu ya mfumo wa juu inayoweza kujaribiwa tena/ya kiwango
(HTTP 429 kila wakati; 402/403 kwa viwango vya bila malipo vya mtindo wa kiwango vya Firecrawl/Tavily/TinyFish —
si kwa Jina Reader, na kamwe si kwa ombi batili la kawaida la 400) huendelea hadi kwa
mtoa huduma anayefuata ambaye hajajaribiwa na mwenye kitambulisho wakati wa ombi. Wakati kila mtoa huduma katika
kundi ameishiwa, endpoint hurejesha `429` moja (ikiwa na kichwa cha `Retry-After`)
badala ya `400` ya jumla ya awali. Wakati `provider` mahususi ameombwa,
**hakuna** urejeaji mbadala wa kimyakimya — mtoa huduma mahususi aliyewekewa kikomo cha kiwango au aliyeshindwa
huonyesha hitilafu yake mwenyewe (`429` ikiwa amewekewa kikomo cha kiwango, vinginevyo hali ya
mfumo wa juu).

---

## Utiririshaji wa WebSocket

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

Huthibitisha handshake ya uboreshaji wa WebSocket na kurejesha ujumbe wa mfano wa itifaki ya waya (`request`, `cancel`). Fremu halisi za WS hushughulikiwa na seva ya WS iliyojumuishwa nje ya jedwali la njia la Next.js.

**Uthibitishaji:** Ufunguo wa API wa Bearer wakati wa handshake.

### API ya Responses kupitia WebSocket (codex pekee)

```bash
# Mpangishi:bandari sawa na API ya HTTP (chaguomsingi 20128); boresha muunganisho:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (au: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Fremu ya kwanza LAZIMA iwe response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```

Proksi ya Responses-API-over-WebSocket imeunganishwa **kwa `codex` pekee** (mfumo wa nyuma wa ChatGPT).
Husikiliza kwenye bandari sawa na API/dashibodi katika njia `/v1/responses`,
`/responses`, na `/api/v1/responses`. Katika fremu ya kwanza ya `response.create`,
huthibitisha + kuandaa kupitia daraja la ndani la `codex-responses-ws`, huchagua
muunganisho wa OAuth wa codex, na kutengeneza handaki kwenda `wss://chatgpt.com/backend-api/codex/responses`
kupitia usafirishaji wa `wreq-js`. **Modeli zisizo za codex zinakataliwa** (`codex_ws_provider_required`).
Kwa uelekezaji wa ushiriki wa kiwango tumia `model: "qtSd/<group>/codex/<model>"`. Imetekelezwa katika
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.

**Uthibitishaji:** Ufunguo wa API wa Bearer wakati wa handshake. Seva ya HTTP iliyojumuishwa (`server-ws.mjs`)
lazima iwe sehemu amilifu ya kuanzia (ndivyo ilivyo kwa chaguomsingi wakati `app/server-ws.mjs` ipo).

#### Kitambulisho cha modeli: tumia kitambulisho tupu cha ChatGPT (bila kiambishi awali cha `codex/`)

**Codex CLI** ya OpenAI huthibitisha jina la modeli upande wa mteja wakati
`supports_websockets = true` na **hukataa vitambulisho vyenye kiambishi awali cha mtoa huduma** kama
`codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`). Tuma kitambulisho **tupu** (k.m. `gpt-5.5`). Daraja la OmniRoute
ni la codex pekee, kwa hivyo hutatua upya kitambulisho tupu kama modeli ya codex
(`resolveCodexWsModelInfo`) kabla ya kutengeneza handaki kuelekea mfumo wa juu — ingawa
`gpt-5.5` tupu vinginevyo ingeelekezwa kwa mtoa huduma mwingine kupitia HTTP.

#### Kusanidi OpenAI Codex CLI

Elekeza Codex CLI kwa OmniRoute kwa kuongeza mtoa huduma maalum mwenye usaidizi wa WebSocket
kwenye `~/.codex/config.toml` (tumia `CODEX_HOME` tofauti ili kuepuka kugusa
usanidi uliopo):

```toml
model = "gpt-5.5"                 # kitambulisho tupu — SI "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # bila kufyeka mwishoni; URL ya WS inatolewa kutokana nayo (tumia https/wss katika uzalishaji)
wire_api = "responses"                    # thamani pekee inayotumika tangu Feb 2026
supports_websockets = true                # huwezesha usafirishaji wa Responses-over-WS
env_key = "OMNIROUTE_API_KEY"             # huhifadhi ufunguo wa API wa OmniRoute (Bearer)
```

```bash
export OMNIROUTE_API_KEY=sk-...           # ufunguo wa API wa OmniRoute (ufunguo wowote ikiwa REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```

CLI huboresha `base_url + /responses` kuwa WebSocket na OmniRoute huitengenezea handaki
kwenda kwenye muunganisho wa OAuth wa codex uliochaguliwa. Imethibitishwa mwanzo-hadi-mwisho dhidi ya seva ya
ndani: ChatGPT hurejesha `codex.rate_limits` + `response.created` na hutiririsha
ukamilishaji.

---

## Vikomo na Kuripoti Matatizo

| Mbinu | Njia                | Maelezo                                                                                            |
| ----- | ------------------- | -------------------------------------------------------------------------------------------------- |
| GET   | `/v1/quotas/check`  | Thibitisha mapema kikomo cha `provider` + `accountId` kabla ya kutoa ufunguo uliosajiliwa          |
| POST  | `/v1/issues/report` | Ripoti kushindwa kwa kikomo/utoaji wa ufunguo kwa GitHub (inahitaji `GITHUB_ISSUES_REPO` + tokeni) |

**Uthibitishaji:** Ufunguo wa API wa Bearer (`isAuthenticated`).

---

## Matumizi ya kujihudumia (`/api/usage/om-usage`)

Ufunguo wowote wa API unaweza kusoma matumizi na vikomo **vyake mwenyewe** — uthibitishaji wa usimamizi hauhitajiki. Hiki ndicho kituo ambacho
kiteja (CLI, paneli ya OmniCopilot) hutumia kumwonyesha mmiliki wa ufunguo matumizi yake.

```bash
# Muundo wa maandishi (mkataba wa awali — maandishi yasiyo na uumbizaji kwa ajili ya terminali)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Muundo wenye mpangilio — unaotumiwa na UI
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"
```

Ufunguo lazima uwe na **`allowUsageCommand`** iliyowezeshwa (imezimwa kwa chaguo-msingi — kidhibiti cha funguo za API cha dashibodi
huiwasha au kuizima kwa kila ufunguo). Bila hiyo, kituo hujibu `403`.

`?format=json` hurejesha muundo unaobainishwa ili mpigaji asiwahi kusoma uga wa data kutoka kwenye
jibu la kukataliwa. Inapofaulu:

```jsonc
{
  "allowed": true,
  // huwepo tu wakati ufunguo umechagua kutumia vikomo vya matumizi kwa kila ufunguo (USD kwa siku/wiki):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // muhtasari wa kikomo cha mtoa huduma aliyechaguliwa, au null ikiwa bado hakuna kilichohifadhiwa:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // muhtasari wa kila muunganisho, ili UI iweze kuonyesha watoa huduma kadhaa sambamba:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}
```

Inapokataliwa (`401` ufunguo batili / `403` hairuhusiwi), njia hiyo hiyo hurejesha
`{ "allowed": false, "error": { "message": "…" } }` — `personal`/`provider` iliyopo lakini tupu
(ufunguo umeruhusiwa, lakini bado hakuna taarifa iliyopatikana) ni hali tofauti na kukataliwa, na ni muundo wa JSON pekee
unaotofautisha hali hizo.

**Uthibitishaji:** ufunguo binafsi wa API wa Bearer wa mpigaji, unaothibitishwa kwa `isValidApiKey` — hii _si_
sehemu ya usimamizi (`/api/keys/…`), ambayo inaendelea kulindwa na `requireManagementAuth`.

---

## Akiba ya Kisemantiki

```bash
# Pata takwimu za akiba
GET /api/cache/stats

# Futa akiba zote
DELETE /api/cache/stats
```

Mfano wa jibu:

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

### Athari kwa muda wa kusubiri

HIT ya akiba ya kisemantiki hutoa jibu kutoka kwenye akiba **bila mwito kwa huduma ya juu**,
kwa hivyo `X-OmniRoute-Response-Latency` inayoripotiwa huwa karibu na sifuri
(bila kujali muda wa awali wa kusubiri wa huduma ya juu). Wateja wanaojali muda wa kusubiri
(upimaji wa utendaji, ufuatiliaji wa p50/p99) wanapaswa kukagua kichwa cha jibu cha
`X-OmniRoute-Cache-Latency`:

| Thamani     | Maana                                                                                 |
| ----------- | ------------------------------------------------------------------------------------- |
| `synthetic` | Jibu limetolewa kutoka kwenye akiba; muda wa kusubiri si muda halisi wa huduma ya juu |
| _(haipo)_   | Jibu limetoka kwenye mwito halisi wa huduma ya juu                                    |

### Kupitisha akiba kwa kila ufunguo

Funguo za API zinaweza kuchagua kutosoma akiba ya kisemantiki kupitia `cacheDefaultMode`:

| Thamani  | Tabia                                                               |
| -------- | ------------------------------------------------------------------- |
| `legacy` | Tabia ya kawaida ya akiba (chaguo-msingi)                           |
| `bypass` | Ruka kabisa utafutaji kwenye akiba; kila wakati tumia huduma ya juu |

Weka wakati wa kuunda ufunguo (`POST /api/keys`) au kusasisha (`PATCH /api/keys/[id]`):

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

### Kupitisha akiba kwa kila ombi

Ombi lolote linaweza kupitisha akiba bila kujali mipangilio ya ufunguo:

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

---

## Dashibodi na Usimamizi

Njia za usimamizi (`/api/*` isipokuwa uthibitishaji/uingiaji wa umma) **haziidhinishwi** na
funguo za kawaida za API za uelekezaji. Aina za vitambulisho, mawanda, na mifano ya curl:
[Uthibitishaji wa Usimamizi](../guides/MANAGEMENT-AUTH.md).

### Uthibitishaji

| Endpoint                      | Mbinu   | Maelezo                      |
| ----------------------------- | ------- | ---------------------------- |
| `/api/auth/login`             | POST    | Ingia                        |
| `/api/auth/logout`            | POST    | Toka                         |
| `/api/settings/require-login` | GET/PUT | Washa/zima sharti la kuingia |

### Usimamizi wa Watoa Huduma

| Endpoint                     | Mbinu                 | Maelezo                                                                                                                             |
| ---------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `/api/providers`             | GET/POST              | Orodhesha / unda watoa huduma                                                                                                       |
| `/api/providers/[id]`        | GET/PUT/DELETE        | Simamia mtoa huduma                                                                                                                 |
| `/api/providers/[id]/test`   | POST                  | Jaribu muunganisho wa mtoa huduma                                                                                                   |
| `/api/providers/[id]/models` | GET                   | Orodhesha modeli za mtoa huduma                                                                                                     |
| `/api/providers/validate`    | POST                  | Thibitisha usanidi wa mtoa huduma                                                                                                   |
| `/api/providers/bulk`        | POST                  | Ongeza kwa wingi funguo za API kwa mtoa huduma MMOJA                                                                                |
| `/api/providers/import`      | POST                  | Leta ORODHA mseto ya watoa huduma kutoka faili ya CSV/JSON iliyochanganuliwa (#6836); matokeo ya kushindwa kwa sehemu kwa kila safu |
| `/api/provider-nodes*`       | Mbalimbali            | Usimamizi wa nodi za watoa huduma                                                                                                   |
| `/api/provider-models`       | GET/POST/PATCH/DELETE | Modeli maalum (ongeza, sasisha, ficha/onyesha, futa)                                                                                |

### Mitiririko ya OAuth

| Endpoint                         | Mbinu      | Maelezo                      |
| -------------------------------- | ---------- | ---------------------------- |
| `/api/oauth/[provider]/[action]` | Mbalimbali | OAuth maalum kwa mtoa huduma |

### Uelekezaji na Usanidi

| Endpoint              | Mbinu      | Maelezo                                     |
| --------------------- | ---------- | ------------------------------------------- |
| `/api/models/alias`   | GET/POST   | Majina mbadala ya modeli                    |
| `/api/models/catalog` | GET        | Modeli zote kulingana na mtoa huduma + aina |
| `/api/combos*`        | Mbalimbali | Usimamizi wa mchanganyiko                   |
| `/api/keys*`          | Mbalimbali | Usimamizi wa funguo za API                  |
| `/api/pricing`        | GET        | Bei za modeli                               |

### Matumizi na Uchanganuzi

| Endpoint                         | Mbinu           | Maelezo                                                                                                                                                                                                                                                                                                                                                 |
| -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history`             | GET             | Historia ya matumizi                                                                                                                                                                                                                                                                                                                                    |
| `/api/usage/logs`                | GET             | Kumbukumbu za matumizi                                                                                                                                                                                                                                                                                                                                  |
| `/api/usage/request-logs`        | GET             | Kumbukumbu za kiwango cha ombi                                                                                                                                                                                                                                                                                                                          |
| `/api/usage/[connectionId]`      | GET             | Matumizi kwa kila muunganisho                                                                                                                                                                                                                                                                                                                           |
| `/api/usage/token-limits`        | GET/POST/DELETE | Bajeti za vikomo vya tokeni kwa kila ufunguo wa API                                                                                                                                                                                                                                                                                                     |
| `/api/usage/model-latency-stats` | GET             | Jumla endelevu ya ucheleweshaji kwa kila mtoa huduma/modeli (wastani/p50/p95/p99, kiwango cha mafanikio); vichujio: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873)                                                                                                                                                                     |
| `/api/usage/cache-health`        | GET             | Muhtasari wa afya ya akiba ya prompt katika `call_logs` — uwiano wa kuandika/kusoma, usambazaji wa ukubwa wa uandishi wa p50/p90/p99, mkusanyiko wa uandishi mzito, mgawanyo kwa kila modeli, na uamuzi wa `healthy`/`degraded`/`thrash`/`no-data`; vigezo vya hoja `range` (`1h`\|`24h`\|`7d`\|`30d`, chaguo-msingi `24h`) na `model` ya hiari (#8827) |

### Mipangilio

| Endpoint                              | Mbinu         | Maelezo                                                                                                                                                                                                                     |
| ------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings`                       | GET/PUT/PATCH | Mipangilio ya jumla                                                                                                                                                                                                         |
| `/api/settings/proxy`                 | GET/PUT       | Usanidi wa proksi ya mtandao                                                                                                                                                                                                |
| `/api/settings/proxy/test`            | POST          | Jaribu muunganisho wa proksi                                                                                                                                                                                                |
| `/api/settings/ip-filter`             | GET/PUT       | Orodha ya kuruhusu/kuzuia IP                                                                                                                                                                                                |
| `/api/settings/thinking-budget`       | GET/PUT       | Hali ya kuandika upya **ombi** la bajeti ya kufikiri/kutoa hoja (kupitisha bila kubadilisha / kuondoa kiotomatiki / maalum / inayobadilika). Haitegemei ubanaji. Tazama [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). |
| `/api/settings/system-prompt`         | GET/PUT       | Prompt ya mfumo wa kimataifa                                                                                                                                                                                                |
| `/api/settings/compression`           | GET/PUT       | Usanidi wa ubanaji wa kimataifa                                                                                                                                                                                             |
| `/api/settings/purge-request-history` | POST          | Futa safu za kumbukumbu za maombi na mabaki ya ndani ya kumbukumbu za miito                                                                                                                                                 |

### Muktadha na Ubanaji

| Endpoint                               | Mbinu          | Maelezo                                                                                  |
| -------------------------------------- | -------------- | ---------------------------------------------------------------------------------------- |
| `/api/compression/preview`             | POST           | Hakiki mgandamizo wa off/lite/standard/aggressive/ultra/RTK/stacked                      |
| `/api/compression/language-packs`      | GET            | Orodhesha vifurushi vya lugha vya Caveman vinavyopatikana                                |
| `/api/compression/rules`               | GET            | Orodhesha metadata ya kanuni za Caveman                                                  |
| `/api/context/caveman/config`          | GET/PUT        | Jina mbadala la mipangilio mahususi ya Caveman                                           |
| `/api/context/rtk/config`              | GET/PUT        | Mipangilio mahususi ya RTK, ikijumuisha vichujio maalum na uhifadhi wa matokeo ghafi     |
| `/api/context/rtk/filters`             | GET            | Katalogi ya vichujio vya RTK na uchunguzi wa vichujio maalum                             |
| `/api/context/rtk/test`                | POST           | Tekeleza hakikisho/jaribio la RTK dhidi ya data ya maandishi                             |
| `/api/context/rtk/raw-output/[id]`     | GET            | Soma matokeo ghafi yaliyohifadhiwa na kufichwa taarifa nyeti kwa kutumia id ya kielekezi |
| `/api/context/combos`                  | GET/POST       | Orodhesha/unda mikusanyiko ya mgandamizo                                                 |
| `/api/context/combos/[id]`             | GET/PUT/DELETE | Maelezo/sasisho/ufutaji wa mkusanyiko wa mgandamizo                                      |
| `/api/context/combos/[id]/assignments` | GET/PUT        | Husisha mikusanyiko ya mgandamizo na mikusanyiko ya uelekezaji                           |
| `/api/context/analytics`               | GET            | Jina mbadala la takwimu changanuzi za mgandamizo                                         |

### Ufuatiliaji

| Endpoint                             | Mbinu      | Maelezo                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions`                      | GET        | Ufuatiliaji wa vipindi vinavyotumika                                                                                                                                                                                                                                                                                                                                                                                                      |
| `/api/rate-limits`                   | GET        | Vikomo vya kiwango kwa kila akaunti                                                                                                                                                                                                                                                                                                                                                                                                       |
| `/api/monitoring/health`             | GET        | Ukaguzi wa afya + muhtasari wa watoa huduma (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Mwonekano wa usimamizi unajumuisha `credentialHealth`: thamani skala za akiba ya uchunguzi, `failedConnections` wakati `failed>0`, na `staleDbNonOkCount` (`test_status` ya SQLite inayodumu, si kipimo). Angalia [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). |
| `/api/cache/stats`                   | GET/DELETE | Takwimu za akiba / futa                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `/api/modality-bridge/stats`         | GET        | `attempts` za kwenye kumbukumbu, mafanikio/`bridged`, kushindwa, kupatikana kwa data kwenye akiba, `totalLatencyMs`, `latencySamples`, `averageLatencyMs` yenye sampuli kama kigawanyaji, na muda wa matumizi ya mwisho (huwekwa upya mfumo unapoanzishwa upya; uthibitishaji wa usimamizi)                                                                                                                                               |
| `/api/modality-bridge/video/runtime` | GET        | Ukaguzi mkali wa loopback inayoaminika kabla ya uthibitishaji/uchunguzi wa usimamizi; upatikanaji na matoleo yaliyosafishwa ya FFmpeg/ffprobe (no-store)                                                                                                                                                                                                                                                                                  |
| `/api/modality-bridge/video/extract` | POST       | Dalali wa ndani wa baiti mwenye uthibitishaji na loopback inayoaminika; ingizo la 50 MiB, foleni yenye kikomo/tokeo la 32 MiB, `503` kwa uwezo, `499` kwa kukatika kwa muunganisho, `504` kwa kikomo cha muda; si API ya umma ya kupakia faili                                                                                                                                                                                            |

### Hifadhi Nakala na Uhamishaji/Uingizaji

| Endpoint                    | Mbinu | Maelezo                                               |
| --------------------------- | ----- | ----------------------------------------------------- |
| `/api/db-backups`           | GET   | Orodhesha nakala rudufu zinazopatikana                |
| `/api/db-backups`           | PUT   | Unda nakala rudufu kwa mikono                         |
| `/api/db-backups`           | POST  | Rejesha kutoka nakala rudufu mahususi                 |
| `/api/db-backups/export`    | GET   | Pakua hifadhidata kama faili la .sqlite               |
| `/api/db-backups/import`    | POST  | Pakia faili la .sqlite ili kubadilisha hifadhidata    |
| `/api/db-backups/exportAll` | GET   | Pakua nakala rudufu kamili kama kumbukumbu ya .tar.gz |

### Usawazishaji wa Wingu

| Endpoint               | Mbinu      | Maelezo                             |
| ---------------------- | ---------- | ----------------------------------- |
| `/api/sync/cloud`      | Mbalimbali | Operesheni za usawazishaji wa wingu |
| `/api/sync/initialize` | POST       | Anzisha usawazishaji                |
| `/api/cloud/*`         | Mbalimbali | Usimamizi wa wingu                  |

### Vichuguu

| Endpoint                   | Mbinu | Maelezo                                                                       |
| -------------------------- | ----- | ----------------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET   | Soma hali ya usakinishaji/uendeshaji ya Cloudflare Quick Tunnel kwa dashibodi |
| `/api/tunnels/cloudflared` | POST  | Washa au zima Cloudflare Quick Tunnel (`action=enable/disable`)               |
| `/api/tunnels/ngrok`       | GET   | Soma hali ya uendeshaji ya ngrok Tunnel kwa dashibodi                         |
| `/api/tunnels/ngrok`       | POST  | Washa au zima ngrok Tunnel (`action=enable/disable`)                          |

### Zana za CLI

| Endpoint                           | Mbinu | Maelezo                                 |
| ---------------------------------- | ----- | --------------------------------------- |
| `/api/cli-tools/claude-settings`   | GET   | Hali ya Claude CLI                      |
| `/api/cli-tools/codex-settings`    | GET   | Hali ya Codex CLI                       |
| `/api/cli-tools/droid-settings`    | GET   | Hali ya Droid CLI                       |
| `/api/cli-tools/openclaw-settings` | GET   | Hali ya OpenClaw CLI                    |
| `/api/cli-tools/runtime/[toolId]`  | GET   | Mazingira ya jumla ya uendeshaji ya CLI |

Majibu ya CLI yanajumuisha: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.

### Mawakala wa ACP

| Endpoint          | Mbinu  | Maelezo                                                                             |
| ----------------- | ------ | ----------------------------------------------------------------------------------- |
| `/api/acp/agents` | GET    | Orodhesha mawakala wote waliogunduliwa (waliojengewa ndani + maalum) pamoja na hali |
| `/api/acp/agents` | POST   | Ongeza wakala maalum au onyesha upya kache ya ugunduzi                              |
| `/api/acp/agents` | DELETE | Ondoa wakala maalum kwa kigezo cha hoja cha `id`                                    |

Jibu la GET linajumuisha `agents[]` (id, name, binary, version, installed, protocol, isCustom) na `summary` (total, installed, notFound, builtIn, custom).

### Ustahimilivu na Vikomo vya Kasi

| Endpoint                          | Mbinu     | Maelezo                                                                                                                  |
| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ |
| `/api/resilience`                 | GET/PATCH | Pata/sasisha foleni ya maombi, kipindi cha kusubiri cha muunganisho, kikataji cha mtoa huduma, na mipangilio ya kusubiri |
| `/api/resilience/reset`           | POST      | Weka upya vikataji mzunguko vya watoa huduma                                                                             |
| `/api/resilience/model-cooldowns` | GET       | Orodhesha vizuizi amilifu vya kila (mtoa huduma, muunganisho, modeli), vilivyopangwa kwa muda uliosalia                  |
| `/api/resilience/model-cooldowns` | DELETE    | Ondoa kizuizi cha modeli — body `{provider, model}` au `{all: true}` ili kufuta kila kitu                                |
| `/api/rate-limits`                | GET       | Hali ya kikomo cha kasi kwa kila akaunti                                                                                 |
| `/api/rate-limit`                 | GET       | Usanidi wa kikomo cha kasi cha kimataifa                                                                                 |

> Njia zote nne za `/api/resilience/*` zinahitaji **uthibitishaji wa usimamizi** (`requireManagementAuth`). Tazama [Ustahimilivu (uliopanuliwa)](#resilience-extended) kwa uchanganuzi kamili wa kikataji cha mtoa huduma dhidi ya kipindi cha kusubiri cha muunganisho dhidi ya kizuizi cha modeli.

### Tathmini

| Endpoint     | Mbinu    | Maelezo                                       |
| ------------ | -------- | --------------------------------------------- |
| `/api/evals` | GET/POST | Orodhesha seti za tathmini / endesha tathmini |

### Sera

| Endpoint        | Mbinu           | Maelezo                    |
| --------------- | --------------- | -------------------------- |
| `/api/policies` | GET/POST/DELETE | Dhibiti sera za uelekezaji |

### Utiifu

| Endpoint                    | Mbinu | Maelezo                                       |
| --------------------------- | ----- | --------------------------------------------- |
| `/api/compliance/audit-log` | GET   | Kumbukumbu ya ukaguzi wa utiifu (N za mwisho) |

### v1beta (Inayotangamana na Gemini)

| Endpoint                   | Mbinu | Maelezo                                  |
| -------------------------- | ----- | ---------------------------------------- |
| `/v1beta/models`           | GET   | Orodhesha modeli katika umbizo la Gemini |
| `/v1beta/models/{...path}` | POST  | Endpoint ya Gemini `generateContent`     |

Endpoint hizi huakisi umbizo la API la Gemini kwa wateja wanaotarajia utangamano asilia na Gemini SDK.

### API za Ndani / Mfumo

| Endpoint                 | Mbinu | Maelezo                                                       |
| ------------------------ | ----- | ------------------------------------------------------------- |
| `/api/init`              | GET   | Ukaguzi wa uanzishaji wa programu (hutumika wakati wa kwanza) |
| `/api/tags`              | GET   | Lebo za modeli zinazooana na Ollama (kwa wateja wa Ollama)    |
| `/api/restart`           | POST  | Anzisha upya seva kwa utaratibu                               |
| `/api/shutdown`          | POST  | Zima seva kwa utaratibu                                       |
| `/api/system/env/repair` | POST  | Rekebisha vigezo vya mazingira vya mtoa huduma wa OAuth       |

> **Kumbuka:** Endpoint hizi hutumiwa ndani na mfumo au kwa uoanifu na wateja wa Ollama. Kwa kawaida haziitwi na watumiaji wa mwisho.

### Urekebishaji wa Mazingira ya OAuth _(v3.6.1+)_

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

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

Hurekebisha vigezo vya mazingira vya OAuth vinavyokosekana au vilivyoharibika kwa mtoa huduma mahususi. Hurejesha:

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

---

## Unukuzi wa Sauti

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

Nakili faili za sauti kwa kutumia mtoa huduma yeyote wa STT aliyesanidiwa. Sehemu ya kwanza ya njia
huchagua mtoa huduma asilia (`openai/…`, `deepgram/…`). Lango linalosambaza upya modeli ya
mtoa huduma mwingine hutumia kitambulisho chenye sifa kamili
(`openrouter/deepgram/nova-3`).

**Ombi:**

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

**Jibu:**

```json
{
  "text": "Hello, this is the transcribed audio content.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}
```

**Mifano ya vitambulisho vya modeli:** `openai/whisper-1` (inahitaji ufunguo wa OpenAI),
`openrouter/deepgram/nova-3` (inahitaji ufunguo wa OpenRouter),
`deepgram/nova-3` (inahitaji ufunguo asilia wa Deepgram). Ombi la moja kwa moja la
`deepgram/nova-3` **halitumii** OpenRouter.

**Miundo inayotumika:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.

---

## Uoanifu na Ollama

Kwa wateja wanaotumia umbizo la API la Ollama:

```bash
# Endpointi ya gumzo (umbizo la Ollama)
POST /v1/api/chat

# Orodha ya modeli (umbizo la Ollama)
GET /api/tags
```

Maombi hutafsiriwa kiotomatiki kati ya miundo ya Ollama na ya ndani.

## Majina Mbadala ya VS Code Yenye Tokeni / Yasiyo na Vichwa

Tumia majina haya mbadala wakati muunganisho hauwezi kuingiza kichwa cha `Authorization` na unahitaji ufunguo wa API kupachikwa kwenye URL ya msingi.

```bash
# Jina mbadala la katalogi katika mtindo wa OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Majina mbadala ya gumzo katika mtindo wa OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Majina mbadala katika mtindo wa Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```

Mfano:

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

Vidokezo:

- Majina mbadala yenye tokeni hutumia upya vishughulikiaji vilevile kama `/v1/*` na `/api/tags`; miundo ya majibu hubaki sawa.
- Pendelea `Authorization: Bearer ...` wakati wowote mteja anapotumia vichwa maalum.
- Tokeni zinazotegemea URL zinaweza kuonekana kwenye kumbukumbu za proksi ya kinyume, historia ya kivinjari na telemetria nje ya OmniRoute. Zichukulie kama chaguo la uoanifu, si hali chaguomsingi ya uthibitishaji.

---

## Telemetria

```bash
# Pata muhtasari wa telemetria ya ukawivu (p50/p95/p99 kwa kila mtoa huduma)
GET /api/telemetry/summary
```

**Jibu:**

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

---

## Bajeti

```bash
# Pata hali ya bajeti kwa funguo zote za API
GET /api/usage/budget

# Weka au sasisha bajeti
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"
}
```

> **Maelezo ya skima** (`setBudgetSchema`): `apiKeyId` inahitajika; angalau mojawapo ya `dailyLimitUsd`, `weeklyLimitUsd`, au `monthlyLimitUsd` lazima iwe kubwa kuliko sufuri. Sehemu za hiari: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Muundo wa zamani wa `{keyId, limit, period}` hurejesha `400 Bad Request`.

## Vikomo vya Tokeni

Bajeti za **tokeni** kwa kila ufunguo wa API (tofauti na Bajeti inayotegemea USD iliyo hapo juu). Hutekelezwa moja kwa moja kwenye njia ya ombi: matumizi ya dirisha la sasa la ufunguo yanapofikia kikomo chake, maombi hukataliwa kwa `429 Too Many Requests`. Vikomo vinaweza kuwekewa upeo wa `model` mahususi, `provider`, au kutumika kwa `global` kwenye ufunguo mzima; vikomo kadhaa vinapolingana na ombi, kile chenye masharti makali zaidi hutumika.

```bash
# Orodhesha vikomo vya tokeni vya ufunguo (inajumuisha matumizi ya moja kwa moja ya dirisha)
GET /api/usage/token-limits?apiKeyId=key-123

# Unda au sasisha kikomo cha tokeni
POST /api/usage/token-limits
Content-Type: application/json

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

# Futa kikomo cha tokeni kwa id
DELETE /api/usage/token-limits?id=tl-abc
```

> **Maelezo ya skima** (`setTokenLimitSchema`): `apiKeyId` na `scopeType` (`model` | `provider` | `global`) zinahitajika. `scopeValue` inahitajika isipokuwa `scopeType` iwe `global` (kwa mfano, id ya modeli kwa upeo wa `model`, id ya mtoa huduma kwa upeo wa `provider`). `tokenLimit` lazima iwe nambari kamili chanya (hubadilishwa kutoka kwa mfuatano). Si za lazima: `id` (iache ili kuunda, itoe ili kusasisha), `resetInterval` (`daily` | `weekly` | `monthly`, chaguo-msingi `monthly`), `resetTime` (`HH:MM`), `enabled` (chaguo-msingi `true`). Majibu ya `GET` huboresha kila kikomo kwa `tokensUsed`, `remaining`, `windowStart`, `periodStartAt`, na `nextResetAt`. Hii ni endpoint ya kiwango cha usimamizi (uthibitishaji wa ruhusa unatekelezwa kwa pamoja na mchakato wa authz).

## Uchakataji wa Ombi

1. Kiteja hutuma ombi kwa `/v1/*`
2. Kishughulikiaji cha njia huita `handleChat`, `handleEmbedding`, `handleAudioTranscription`, au `handleImageGeneration`
3. Modeli hutambuliwa (mtoa huduma/modeli ya moja kwa moja au jina mbadala/mchanganyiko)
4. Vitambulisho huchaguliwa kutoka DB ya ndani kwa kuchuja kulingana na upatikanaji wa akaunti
5. Kwa gumzo: `handleChatCore` hukagua kashe ya kisemantiki/sahihi na kubaini mipangilio ya ubanaji wa mchanganyiko
6. Ubanaji wa mapema huendeshwa kabla ya utafsiri wa mtoa huduma unapowashwa (`lite`, Caveman, RTK, au zilizopangwa kwa mrundikano)
7. Kitekelezaji cha mtoa huduma hutuma ombi kwenda kwa huduma ya juu
8. Jibu hutafsiriwa kurudi katika umbizo la kiteja (gumzo) au kurejeshwa jinsi lilivyo (embeddings/picha/sauti)
9. Matumizi, takwimu za uchanganuzi wa ubanaji, na kumbukumbu za maombi hurekodiwa
10. Njia mbadala hutumika kukitokea hitilafu kulingana na kanuni za mchanganyiko

Rejeleo kamili la usanifu: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)

---

## Usimamizi wa Michanganyiko

Michanganyiko ya uelekezaji ya kiwango cha juu (ambayo tayari imefupishwa chini ya `/api/combos*`) pia inaweza kuhusishwa 1:1 kutoka kwa ruwaza ya id ya modeli, na hivyo kuruhusu uelekezaji upya wa uwazi wa id ya modeli yenye mtindo wa OpenAI kwenda kwenye mchanganyiko.

| Mbinu  | Njia                             | Maelezo                                                                        |
| ------ | -------------------------------- | ------------------------------------------------------------------------------ |
| GET    | `/api/model-combo-mappings`      | Orodhesha mahusiano yote ya modeli→mchanganyiko                                |
| POST   | `/api/model-combo-mappings`      | Unda uhusiano — mwili: `{pattern, comboId, priority?, enabled?, description?}` |
| GET    | `/api/model-combo-mappings/[id]` | Pata uhusiano mmoja                                                            |
| PUT    | `/api/model-combo-mappings/[id]` | Sasisha sehemu za uhusiano uliopo                                              |
| DELETE | `/api/model-combo-mappings/[id]` | Ondoa uhusiano                                                                 |

**Uthibitishaji:** kipindi cha usimamizi/ufunguo wa API (`requireManagementAuth`).

---

## Webhooks

Usajili wa webhook zinazotoka kwa matukio ya OmniRoute (kukamilika kwa ombi, kuisha kwa mgao, kubadilisha ufunguo, n.k.).

| Mbinu  | Njia                      | Maelezo                                                                       |
| ------ | ------------------------- | ----------------------------------------------------------------------------- |
| GET    | `/api/webhooks`           | Orodhesha webhook (siri zimefichwa kuwa `<prefix>...`)                        |
| POST   | `/api/webhooks`           | Unda webhook — body: `{url, events?: ["*"], secret?, description?}`           |
| GET    | `/api/webhooks/[id]`      | Pata webhook                                                                  |
| PUT    | `/api/webhooks/[id]`      | Sasisha url/events/secret/description                                         |
| DELETE | `/api/webhooks/[id]`      | Ondoa webhook                                                                 |
| POST   | `/api/webhooks/[id]/test` | Tuma payload ya majaribio kwa URL ya webhook na urudishe hali ya uwasilishaji |

**Uthibitishaji:** kipindi cha usimamizi/ufunguo wa API (`requireManagementAuth`).

---

## Funguo Zilizosajiliwa (Usimamizi Otomatiki)

Hutumiwa na mfumo mdogo wa usimamizi otomatiki wa funguo kutoa na kubadilisha funguo za API kupitia mtoa huduma/akaunti ya msingi, kwa kutumia mgao wa kila siku/kila saa.

| Mbinu  | Njia                                  | Maelezo                                                                                                                                                                                                                          |
| ------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/registered-keys`             | Orodhesha funguo zilizosajiliwa (kiambishi-awali kilichofichwa pekee)                                                                                                                                                            |
| POST   | `/api/v1/registered-keys`             | Toa ufunguo mpya uliosajiliwa — body: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Hurejesha ufunguo halisi **mara moja**. Hurejesha `429` ombi linapokataliwa kwa sababu ya mgao. |
| GET    | `/api/v1/registered-keys/[id]`        | Pata metadata ya ufunguo uliosajiliwa (bila data halisi ya ufunguo)                                                                                                                                                              |
| DELETE | `/api/v1/registered-keys/[id]`        | Batilisha ufunguo uliosajiliwa                                                                                                                                                                                                   |
| POST   | `/api/v1/registered-keys/[id]/revoke` | Endpoint ya kubatilisha moja kwa moja (athari sawa na DELETE)                                                                                                                                                                    |

**Uthibitishaji:** ufunguo wa API wa Bearer (`isAuthenticated`). Tazama pia `/v1/quotas/check` na `/v1/issues/report`.

---

## Itifaki ya Mawakala

Majukumu ya mawakala wa wingu (Claude Code, Codex Cloud, OpenHands, n.k.) yanayotekelezwa kwa mbali kwa niaba ya watumiaji wa OmniRoute.

| Mbinu  | Njia                          | Maelezo                                                                                                                                                          |
| ------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/agents/tasks`        | Orodhesha majukumu — hiari `?provider=`, `?status=`, `?limit=` (1–500, chaguo-msingi 50)                                                                         |
| POST   | `/api/v1/agents/tasks`        | Unda jukumu — body inathibitishwa na `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Hurejesha `201` pamoja na kifurushi cha jukumu |
| DELETE | `/api/v1/agents/tasks?id=...` | Futa jukumu                                                                                                                                                      |
| GET    | `/api/v1/agents/tasks/[id]`   | Soma jukumu — huonyesha upya hali kwa usawazishaji kutoka kwa wakala wa wingu wa upstream wakati `external_id` imewekwa                                          |
| POST   | `/api/v1/agents/tasks/[id]`   | Kitendo bainifu: `{action: "approve"}`, `{action: "message", message}`, au `{action: "cancel"}`                                                                  |
| DELETE | `/api/v1/agents/tasks/[id]`   | Futa jukumu mahususi kwa id                                                                                                                                      |

> **Uthibitishaji:** uthibitishaji wa usimamizi unahitajika kwa kila mbinu (`requireCloudAgentManagementAuth`). Kabla ya v3.8.0 hizi hazikuhitaji uthibitishaji — tazama commit `588a0333` kwa mabadiliko yasiyoendana na matoleo ya awali.

```bash
# Unda jukumu la wingu la 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":"..."}}'
```

---

## Proksi za Usimamizi

Proksi za HTTP(S)/SOCKS za trafiki inayotoka ambazo zinaweza kugawiwa kwa watoa huduma, akaunti, au kwa mfumo mzima.

| Mbinu  | Njia                                         | Maelezo                                                                                                                                                      |
| ------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/v1/management/proxies`                 | Orodhesha proksi (ikiwa na `?id=` hurejesha moja; ikiwa na `?id=&where_used=1` hurejesha grafu ya migawo)                                                    |
| POST   | `/api/v1/management/proxies`                 | Unda proksi — body inathibitishwa na `createProxyRegistrySchema`                                                                                             |
| PATCH  | `/api/v1/management/proxies`                 | Sasisha proksi — body inathibitishwa na `updateProxyRegistrySchema` (inahitaji `id`)                                                                         |
| DELETE | `/api/v1/management/proxies?id=...&force=1`  | Futa proksi (tumia `force=1` kutenganisha migawo)                                                                                                            |
| GET    | `/api/v1/management/proxies/assignments`     | Orodhesha migawo — inaweza kuchujwa kwa `proxy_id`, `scope`, `scope_id`; pitisha `resolve_connection_id=<id>` ili kubaini proksi inayotumika kwa muunganisho |
| PUT    | `/api/v1/management/proxies/assignments`     | Gawa — body inathibitishwa na `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Hufuta akiba ya dispatcher                                            |
| PUT    | `/api/v1/management/proxies/bulk-assign`     | Gawa kwa wingi — body inathibitishwa na `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`)                                                        |
| GET    | `/api/v1/management/proxies/health?hours=24` | Kusanya hali ya proksi (idadi za mafanikio/kushindwa, ucheleweshaji) katika kipindi fulani                                                                   |

**Uthibitishaji:** kipindi cha usimamizi/ufunguo wa API unahitajika kwenye kila route (`requireManagementAuth`).

> `POST /api/v1/management/proxies/[id]/assignments` na `POST /api/v1/management/proxies/[id]/health` zilizo kwenye maelezo ya jukumu zinahudumiwa na route tambarare za `/assignments` na `/health` zilizoonyeshwa hapo juu — hakuna route ndogo za kila id katika codebase.

---

## Ustahimilivu (uliopanuliwa)

OmniRoute hutoa mbinu tatu huru za kushughulikia hitilafu za muda; sehemu za mwisho za usimamizi zilizo hapa chini huwawezesha waendeshaji kuzisoma na kuzibatilisha:

| Wigo                                 | Hifadhi ya hali                                         | Kusoma                                    | Kuweka upya / kufuta                                           |
| ------------------------------------ | ------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------- |
| Kikatiza cha mtoa huduma             | `domain_circuit_breakers` + kwenye kumbukumbu           | `/api/monitoring/health`                  | `POST /api/resilience/reset`                                   |
| Kipindi cha kusubiri cha muunganisho | `rateLimitedUntil` kwenye miunganisho ya mtoa huduma    | `/api/rate-limits`, `/api/providers/[id]` | (huwashwa tena inapohitajika; futa kupitia PUT ya mtoa huduma) |
| Uzuiaji wa modeli                    | Sajili ya upatikanaji wa modeli iliyo kwenye kumbukumbu | `GET /api/resilience/model-cooldowns`     | `DELETE /api/resilience/model-cooldowns`                       |

`PATCH /api/resilience` hukubali ubatilishaji wa kikatiza cha mtoa huduma chini ya `providerBreaker.oauth` na `providerBreaker.apikey`. Kila wasifu unaauni `degradationThreshold`, `failureThreshold`, na `resetTimeoutMs`; sehemu hizohizo zinapatikana katika Dashibodi → Mipangilio → Ustahimilivu.

```bash
# Futa uzuiaji wa modeli moja
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"}'

# Futa vizuizi vyote
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'
```

Kwa marejeleo kamili ya dhana na chaguo-msingi za vikatiza: tazama [`CLAUDE.md`](../../CLAUDE.md) → "Hali ya Wakati wa Utekelezaji ya Ustahimilivu".

---

## Ujuzi

Mfumo wa ujuzi wa kupanua OmniRoute kwa vidhibiti maalum vinavyoweza kutekelezwa, pamoja na miunganisho ya soko.

| Mbinu  | Njia                              | Maelezo                                                                                                                                                  |
| ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`                     | Orodhesha ujuzi uliosakinishwa — unaweza kuchujwa kwa `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, ukiwa umegawanywa katika kurasa |
| GET    | `/api/skills/[id]`                | Pata ujuzi mmoja                                                                                                                                         |
| PUT    | `/api/skills/[id]`                | Sasisha ujuzi (jina, maelezo, hali, skima, kidhibiti, lebo)                                                                                              |
| DELETE | `/api/skills/[id]`                | Sanidua ujuzi                                                                                                                                            |
| POST   | `/api/skills/install`             | Sakinisha ujuzi kutoka kwenye manifesti ghafi — mwili: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}`                    |
| GET    | `/api/skills/executions`          | Orodhesha utekelezaji wa hivi karibuni wa ujuzi (rekodi ya ukaguzi yenye ingizo/matokeo/muda)                                                            |
| GET    | `/api/skills/marketplace?q=...`   | Tafuta/orodhesha maarufu kutoka kwenye soko la SkillsMP (inahitaji mpangilio wa `skillsmpApiKey`)                                                        |
| POST   | `/api/skills/marketplace/install` | Sakinisha ujuzi kwa kitambulisho kutoka SkillsMP                                                                                                         |
| GET    | `/api/skills/skillssh?q=&limit=`  | Tafuta katika sajili ya skills.sh                                                                                                                        |
| POST   | `/api/skills/skillssh/install`    | Sakinisha ujuzi kwa kitambulisho kutoka skills.sh                                                                                                        |

**Uthibitishaji:** kipindi cha usimamizi/ufunguo wa API. Njia za utafutaji wa soko hukubali uthibitishaji wa usimamizi au ufunguo wa API wa Bearer (`isAuthenticated`).

---

## Kumbukumbu

Hifadhi endelevu ya kumbukumbu za mazungumzo/ukweli, iliyotengwa kwa kila ufunguo wa API / kipindi.

| Mbinu  | Njia                 | Maelezo                                                                                                                       |
| ------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/memory`        | Orodhesha kumbukumbu — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, kwa upangaji wa kurasa wa `offset/limit` au `page/limit` |
| POST   | `/api/memory`        | Unda kumbukumbu — mwili huthibitishwa na Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}`           |
| GET    | `/api/memory/[id]`   | Pata kumbukumbu moja                                                                                                          |
| DELETE | `/api/memory/[id]`   | Futa kumbukumbu                                                                                                               |
| GET    | `/api/memory/health` | Afya ya mfumo mdogo wa kumbukumbu (muunganisho wa DB, mfumo wa nyuma wa embeddings, hali ya faharasa ya vekta)                |

**Uthibitishaji:** kipindi cha usimamizi/ufunguo wa API (`requireManagementAuth`). enum ya `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (tazama `MemoryType` katika `src/lib/memory/types.ts`).

---

## Seva ya MCP

OmniRoute huja na seva iliyopachikwa ya Model Context Protocol yenye njia 3 za usafirishaji (stdio, SSE, streamable-http) na zana zenye mawanda maalum. Endpointi za dashibodi zilizo hapa chini husoma data ya hali/ukaguzi na kuwakilisha njia za usafirishaji za HTTP.

| Mbinu | Njia | Maelezo |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Mpigo wa moyo, usafirishaji, hali ya mtandaoni, simu ya mwisho, zana kuu, kiwango cha mafanikio cha saa 24 |
| GET | `/api/mcp/tools` | Orodha ya zana za MCP zenye `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
| GET | `/api/mcp/sse` | Fungua mtiririko wa SSE kwa usafirishaji wa SSE (hurudisha `503` ikiwa MCP imezimwa au usafirishaji haulingani) |
| POST | `/api/mcp/sse` | Tuma fremu ya JSON-RPC kupitia usafirishaji wa SSE |
| GET | `/api/mcp/stream` | Fungua upande wa SSE wa usafirishaji wa Streamable HTTP (ujumbe unaoanzishwa na seva) |
| POST | `/api/mcp/stream` | Tuma fremu ya JSON-RPC kupitia usafirishaji wa Streamable HTTP |
| DELETE | `/api/mcp/stream` | Maliza kipindi cha Streamable HTTP |
| GET | `/api/mcp/audit` | Hoji kumbukumbu ya ukaguzi — `?limit=`, `?offset=`, `?tool=`, `?success=true                                | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | Takwimu zilizojumlishwa za ukaguzi (jumla, kiwango cha mafanikio, wastani wa muda, zana kuu) |

**Uthibitishaji:** njia za usafirishaji za `sse`/`stream` hutumia mfumo maalum wa uthibitishaji wa MCP (ufunguo wa Bearer API wenye wigo wa `mcp`); njia za `status`/`tools`/`audit*` zinaweza kusomwa kutoka kwenye dashibodi (hakuna uthibitishaji wa ziada unaohitajika zaidi ya kufikia hosti ya dashibodi).

> Njia zote mbili za usafirishaji za HTTP zinadhibitiwa na `settings.mcpEnabled` na `settings.mcpTransport` — kutolingana kwa usafirishaji hurudisha `400`, na hali ambapo MCP imezimwa hurudisha `503`.

---

## Seva ya A2A

OmniRoute hutoa endpoint ya A2A (Agent-to-Agent) ya JSON-RPC 2.0 pamoja na kifungashio cha REST kwa matumizi ya ukaguzi/dashibodi.

### JSON-RPC

```bash
POST /a2a
Authorization: Bearer your-api-key   # si lazima isipokuwa OMNIROUTE_API_KEY imewekwa
Content-Type: application/json

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

Mbinu zinazotumika (zote hudhibitiwa na `settings.a2aEnabled`):

| Mbinu            | Maelezo                                                             |
| ---------------- | ------------------------------------------------------------------- |
| `message/send`   | Utekelezaji sawia wa ujuzi; hurejesha `{task, artifacts, metadata}` |
| `message/stream` | Utekelezaji wa mtiririko wa SSE wa seti ileile ya ujuzi             |
| `tasks/get`      | Huchukua jukumu kwa kutumia `taskId`                                |
| `tasks/cancel`   | Hukatisha jukumu kwa kutumia `taskId`                               |

Ujuzi uliojengewa ndani: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.

### Kadi ya Ajenti

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

Hurejesha kadi ya umma ya ajenti wa A2A (jina, maelezo, uwezo, katalogi ya ujuzi, mpango wa uthibitishaji) — huhifadhiwa kwenye akiba ya umma kwa saa 1. Uthibitishaji hauhitajiki.

### Visaidizi vya REST

| Mbinu | Njia                         | Maelezo                                                                                                                 |
| ----- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/a2a/status`            | A2A imewezeshwa + takwimu za majukumu + muhtasari wa kadi ya ajenti uliohifadhiwa kwenye akiba                          |
| GET   | `/api/a2a/tasks`             | Orodhesha majukumu — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST  | `/api/a2a/tasks`             | (Haijatekelezwa kama kisaidizi cha REST — unda kupitia JSON-RPC `message/send`)                                         |
| GET   | `/api/a2a/tasks/[id]`        | Chukua jukumu moja                                                                                                      |
| POST  | `/api/a2a/tasks/[id]/cancel` | Katisha jukumu                                                                                                          |

**Uthibitishaji:** visaidizi vya REST huendeshwa bila uthibitishaji wa usimamizi (vinaweza kusomwa na dashibodi); njia ya JSON-RPC `/a2a` hutumia Bearer `OMNIROUTE_API_KEY` ikiwa imesanidiwa.

---

## Wingu, Tathmini za Utendaji na Ukadiriaji

| Mbinu | Njia | Maelezo |
| ----- | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Thibitisha ufunguo wa Bearer na urejeshe miunganisho ya watoa huduma iliyofichwa kwa kiasi + lakabu za modeli kwa wateja wa usawazishaji wa wingu |
| POST | `/api/cloud/credentials/update` | Sasisha vitambulisho vilivyosimbwa kwa njia fiche vya mtoa huduma aliyesawazishwa na wingu |
| POST | `/api/cloud/model/resolve` | Geuza kitambulisho mantiki cha modeli kuwa mtoa huduma/modeli mahususi kwa kutumia jedwali la ndani la uelekezaji |
| GET | `/api/cloud/models/alias` | Orodhesha lakabu za modeli jinsi zinavyoonyeshwa kwa usawazishaji wa wingu |
| GET | `/api/assess` | Soma uainishaji wa hivi karibuni wa ukadiriaji (kwa kila mtoa huduma/modeli) |
| POST | `/api/assess` | Tekeleza ukadiriaji — mwili: `{scope: {type:"all"}                                                   | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Orodhesha seti za tathmini za utendaji zilizojengewa ndani + utekelezaji wa hivi karibuni |
| POST | `/api/evals` | Anzisha utekelezaji wa tathmini ya utendaji |
| POST | `/api/evals/suites` | Unda seti maalum ya tathmini ya utendaji — mwili huthibitishwa na `evalSuiteSaveSchema` |
| GET | `/api/evals/suites/[id]` | Chukua seti maalum ya tathmini ya utendaji |

**Uthibitishaji:** `/api/cloud/auth` huthibitisha ufunguo wa Bearer moja kwa moja; njia nyingine za `/api/cloud/*`, `/api/evals/*`, na `/api/assess` zinahitaji kipindi cha usimamizi/ufunguo wa API. POST ya `/api/assess` hutumia `validateBody` pamoja na skima ya upeo ya muungano wenye kibaguzi.

---

## Usimamizi wa ACP (Agent Client Protocol)

kama michakato tanzu. Endpointi hizi hudhibiti utambuzi wa mawakala wa ACP na usajili wa mawakala maalum.

| Mbinu  | Njia              | Maelezo                                                                                                                                                      |
| ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/acp/agents` | Orodhesha mawakala wote wa CLI wanaojulikana (waliojengewa ndani + maalum) pamoja na hali ya usakinishaji, toleo na faili tekelezi                           |
| POST   | `/api/acp/agents` | Sajili wakala maalum wa ACP au onyesha upya kache — mwili: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` au `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Ondoa wakala maalum wa ACP — parameta ya hoja: `?id=<agentId>`                                                                                               |

**Mfano wa jibu** (`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
}
```

**Uthibitishaji:** Inahitaji kipindi cha usimamizi (kidakuzi cha dashibodi cha `auth_token`) au ufunguo wa API wenye wigo wa usimamizi.

Tazama [Mfumo wa ACP](../frameworks/ACP.md) kwa maelezo kamili.

---

## Uchanganuzi na Uangalizi

Endpointi za uchanganuzi wa wakati halisi kwa ajili ya kufuatilia uelekezaji, mgandamizo na utofauti wa watoa huduma. Hizi huendesha kurasa za `/dashboard/analytics/*`.

### Uchanganuzi wa uelekezaji kiotomatiki

| Mbinu | Njia                                 | Maelezo                                                                                                                          |
| ----- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/analytics/auto-routing`        | Takwimu zilizojumlishwa za uelekezaji kiotomatiki: jumla ya miito, mgawanyo wa mikakati, mgawanyo wa viwango, watoa huduma wakuu |
| GET   | `/api/analytics/auto-routing?days=7` | Takwimu za kipindi maalum (chaguo-msingi saa 24)                                                                                 |

**Mfano wa jibu**:

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

### Uchanganuzi wa mgandamizo

| Mbinu | Njia                         | Maelezo                                                                                                                |
| ----- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/analytics/compression` | Takwimu zilizojumlishwa za mgandamizo: tokeni zilizookolewa, asilimia ya uokoaji, mgawanyo wa hali, matumizi ya injini |

**Mfano wa jibu**:

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

### Ufuatiliaji wa utofauti wa watoa huduma

| Mbinu | Njia                       | Maelezo                                                                                                                       |
| ----- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/analytics/diversity` | Ufuatiliaji wa utofauti unaotegemea entropia ya Shannon: huzuia sehemu moja ya hitilafu kwa kupima usambazaji wa watoa huduma |

**Mfano wa jibu**:

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

**Uthibitishaji:** Inahitaji kipindi cha usimamizi au ufunguo wa API wenye wigo wa usimamizi.

---

## Operesheni za Msimamizi

Endpointi za wasimamizi pekee kwa ajili ya usimamizi wa kiutendaji.

| Mbinu | Njia                     | Maelezo                                                                                                    |
| ----- | ------------------------ | ---------------------------------------------------------------------------------------------------------- |
| GET   | `/api/admin/concurrency` | Soma vikomo vya sasa vya utekelezaji sambamba (kwa jumla + kwa kila mtoa huduma)                           |
| POST  | `/api/admin/concurrency` | Sasisha vikomo vya utekelezaji sambamba — mwili: `{global?: number, perProvider?: Record<string, number>}` |

**Uthibitishaji:** Inahitaji kipindi cha usimamizi chenye wigo wa msimamizi.

---

## Usimamizi wa Zana za CLI

Dhibiti zana za CLI zinazounganishwa na OmniRoute (antigravity, commandCode,
devin-cli, n.k.). Tazama [Rejea ya Watoa Huduma](./PROVIDER_REFERENCE.md) kwa orodha kamili.

| Mbinu | Njia                                    | Maelezo                                                                                                                                                                         |
| ----- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/cli-tools/all-statuses`           | Hali ya zana zote za CLI (imesakinishwa, toleo, mara ya mwisho kuonekana)                                                                                                       |
| GET   | `/api/cli-tools/status`                 | Maelezo ya hali ya zana moja ya CLI (hoja ya swali ya `?tool=`)                                                                                                                 |
| POST  | `/api/cli-tools/apply`                  | Andika usanidi uliozalishwa wa zana (`dryRun` huonyesha hakikisho; `422` + `containerEphemeralTarget` ikiwa iko kwenye kontena; `migration` hubainisha YAML ya zamani ya Codex) |
| GET   | `/api/cli-tools/backups`                | Orodhesha nakala rudufu za usanidi wa zana za CLI                                                                                                                               |
| POST  | `/api/cli-tools/backups`                | Unda nakala rudufu ya usanidi wote wa zana za CLI                                                                                                                               |
| POST  | `/api/cli-tools/backups`                | Rejesha: endpointi hiyo hiyo ikiwa na `{tool, backupId}` kwenye kiini cha ombi hurejesha nakala hiyo rudufu                                                                     |
| GET   | `/api/cli-tools/antigravity-mitm`       | Hali ya proksi ya MITM ya Antigravity (zana ya CLI ya "antigravity-mitm")                                                                                                       |
| POST  | `/api/cli-tools/antigravity-mitm/alias` | Sanidi lakabu za antigravity-mitm                                                                                                                                               |

**Uthibitishaji:** Inahitaji kipindi cha usimamizi.

---

## Ujuzi wa Mawakala

Dhibiti ujuzi wa mawakala wa AI (sawa na GPT maalum za OpenAI lakini kwa ajili ya mawakala).

| Mbinu  | Njia                         | Maelezo                                                                                  |
| ------ | ---------------------------- | ---------------------------------------------------------------------------------------- |
| GET    | `/api/agent-skills`          | Orodhesha ujuzi wote wa mawakala (ulio ndani kwa chaguomsingi + maalum)                  |
| GET    | `/api/agent-skills/[id]`     | Pata ujuzi mahususi wa wakala                                                            |
| POST   | `/api/agent-skills`          | Unda ujuzi maalum wa wakala — mwili: `{name, description, prompt, model?, temperature?}` |
| PUT    | `/api/agent-skills/[id]`     | Sasisha ujuzi maalum wa wakala                                                           |
| DELETE | `/api/agent-skills/[id]`     | Futa ujuzi maalum wa wakala                                                              |
| GET    | `/api/agent-skills/[id]/raw` | Pata prompt ghafi + metadata (bila utekelezaji)                                          |
| POST   | `/api/agent-skills/generate` | Tumia AI kutengeneza ujuzi mpya kutokana na maelezo ya lugha asilia                      |

**Uthibitishaji:** Inahitaji kipindi cha usimamizi au ufunguo wa API wenye wigo wa usimamizi.

---

## Usimamizi wa Akiba

Dhibiti akiba ya kisemantiki na akiba ya uchanganuzi.

| Mbinu  | Njia                   | Maelezo                                                                                                         |
| ------ | ---------------------- | --------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cache`           | Muhtasari wa akiba: jumla ya maingizo, kiwango cha mafanikio, ukubwa kwenye diski                               |
| GET    | `/api/cache/entries`   | Orodhesha maingizo yaliyohifadhiwa kwenye akiba (kwa kurasa)                                                    |
| DELETE | `/api/cache/entries`   | Futa maingizo ya akiba (chuja kwa vigezo vya hoja)                                                              |
| GET    | `/api/cache/stats`     | Takwimu za kina za akiba (kwa kila mtoa huduma, kwa kila modeli)                                                |
| GET    | `/api/cache/reasoning` | Hali ya akiba ya uchanganuzi (kwa ajili ya kucheza upya uchanganuzi)                                            |
| DELETE | `/api/cache/reasoning` | Futa akiba ya uchanganuzi — vigezo vya hoja: `?toolCallId=<id>` (moja) au `?provider=<p>` au bila vigezo (zote) |

**Uthibitishaji:** Inahitaji kipindi cha usimamizi.

---

## Mfumo wa Kumbukumbu

Dhibiti kumbukumbu endelevu (FTS5 + upachikaji wa vekta).

| Mbinu  | Njia               | Maelezo                                                                        |
| ------ | ------------------ | ------------------------------------------------------------------------------ |
| GET    | `/api/memory`      | Orodhesha maingizo ya kumbukumbu (chuja kwa wigo, aina, hoja ya utafutaji)     |
| POST   | `/api/memory`      | Unda ingizo jipya la kumbukumbu — mwili: `{scope, type, content, metadata?}`   |
| GET    | `/api/memory/[id]` | Pata ingizo mahususi la kumbukumbu                                             |
| PUT    | `/api/memory/[id]` | Sasisha ingizo la kumbukumbu                                                   |
| DELETE | `/api/memory/[id]` | Futa ingizo la kumbukumbu                                                      |
| GET    | `/api/memory?q=`   | Tafuta kumbukumbu (FTS5 + vekta) — takwimu zimejumuishwa katika jibu hilo hilo |

**Uthibitishaji:** Inahitaji kipindi cha usimamizi au ufunguo wa API wenye wigo wa usimamizi.

---

## Webhooks

Dhibiti usajili wa webhook kwa matukio.

| Mbinu  | Njia                            | Maelezo                                                                           |
| ------ | ------------------------------- | --------------------------------------------------------------------------------- |
| GET    | `/api/webhooks`                 | Orodhesha usajili wote wa webhook                                                 |
| POST   | `/api/webhooks`                 | Unda usajili wa webhook — mwili: `{url, events[], secret?, active?}`              |
| GET    | `/api/webhooks/[id]`            | Pata usajili mahususi wa webhook                                                  |
| PUT    | `/api/webhooks/[id]`            | Sasisha usajili wa webhook                                                        |
| DELETE | `/api/webhooks/[id]`            | Futa usajili wa webhook                                                           |
| GET    | `/api/webhooks/[id]/deliveries` | Orodhesha historia ya uwasilishaji wa webhook (kumbukumbu ya mafanikio/kushindwa) |
| POST   | `/api/webhooks/[id]/test`       | Tuma tukio la majaribio kwa webhook                                               |

**Uthibitishaji:** Inahitaji kipindi cha usimamizi.

Angalia [Mfumo wa Webhooks](../frameworks/WEBHOOKS.md) kwa aina zote za matukio.

---

## Mfumo wa Skills

Dhibiti Skills (mfumo wa viendelezi vya kiwakala).

| Mbinu  | Njia                     | Maelezo                                                                                |
| ------ | ------------------------ | -------------------------------------------------------------------------------------- |
| GET    | `/api/skills`            | Orodhesha skills zote zilizosakinishwa (zilizojengewa ndani + maalum)                  |
| POST   | `/api/skills/install`    | Sakinisha skill kutoka kwenye njia ya ndani au URL                                     |
| DELETE | `/api/skills/[id]`       | Sanidua skill                                                                          |
| PUT    | `/api/skills/[id]`       | Wezesha au lemaza skill — mwili: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST   | `/api/skills/executions` | Tekeleza skill — mwili: `{skillName, apiKeyId, input?, sessionId?}`                    |
| GET    | `/api/skills/executions` | Orodhesha historia ya utekelezaji wa skills zote (chuja kwa `?apiKeyId=`)              |

**Uthibitishaji:** Inahitaji kipindi cha usimamizi au ufunguo wa API wenye wigo wa usimamizi.

Tazama [Mfumo wa Skills](../frameworks/SKILLS.md) kwa maelezo kamili.

---

## Programu-jalizi

Dhibiti programu-jalizi za OmniRoute (viendelezi vya wahusika wengine).

| Mbinu  | Njia                               | Maelezo                                    |
| ------ | ---------------------------------- | ------------------------------------------ |
| GET    | `/api/plugins`                     | Orodhesha programu-jalizi zilizosakinishwa |
| POST   | `/api/plugins/marketplace/install` | Sakinisha programu-jalizi kutoka sokoni    |
| DELETE | `/api/plugins/[name]`              | Sanidua programu-jalizi                    |
| POST   | `/api/plugins/[name]/activate`     | Washa programu-jalizi                      |
| POST   | `/api/plugins/[name]/deactivate`   | Zima programu-jalizi                       |
| GET    | `/api/plugins/[name]/config`       | Pata usanidi wa programu-jalizi            |
| PUT    | `/api/plugins/[name]/config`       | Sasisha usanidi wa programu-jalizi         |

**Uthibitishaji:** Inahitaji kipindi cha usimamizi.

Tazama [Mfumo wa Programu-jalizi](../frameworks/PLUGIN_SDK.md) kwa maelezo kamili.

---

## Uelekezaji Kivuli

Ulinganishaji wa kivuli / A-B wa watoa huduma **si kiolesura huru cha REST** — husanidiwa kupitia uelekezaji wa mchanganyiko (tazama [Mchanganyiko Otomatiki](../routing/AUTO-COMBO.md)). Vipimo vya ulinganishaji kwa kila mchanganyiko hutolewa na `GET /api/combos/metrics`.

---

## Vizuizi vya Usalama

Kagua vizuizi vya usalama vya wakati wa utekelezaji (utambuzi wa PII, utambuzi wa udungaji wa prompt, uunganishaji wa uwezo wa kuona). Vizuizi vya usalama hutekelezwa kwa kila ombi; kujiondoa kwa kila mwito hufanywa kupitia kichwa cha ombi cha `x-omniroute-disabled-guardrails` — hakuna kiolesura kinachohifadhiwa cha kuwezesha/kulemaza.

| Mbinu | Njia                   | Maelezo                                                                                                        |
| ----- | ---------------------- | -------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/guardrails`      | Orodhesha vizuizi vya usalama vilivyosajiliwa na hali zake (jina / kimewezeshwa / kipaumbele)                  |
| POST  | `/api/guardrails/test` | Endesha majaribio ya mchakato wa kabla ya mwito kwenye ingizo la mfano — mwili: `{input, disabledGuardrails?}` |

**Uthibitishaji:** Inahitaji kipindi cha usimamizi.

Tazama [Usalama > Vizuizi vya Usalama](../security/GUARDRAILS.md) kwa maelezo kamili.

---

---

## Uthibitishaji

Tazama [Uthibitishaji wa Usimamizi](../guides/MANAGEMENT-AUTH.md) kwa familia nne za
vitambulisho (kipindi cha dashibodi, tokeni ya ndani ya CLI, Tokeni ya Ufikiaji ya
`oma_live_…`, ufunguo wa API wenye wigo wa usimamizi) na jinsi zinavyotofautiana na funguo za uelekezaji.

- Njia za dashibodi (`/dashboard/*`) hutumia kidakuzi cha `auth_token`
- Kuingia hutumia heshi ya nenosiri iliyohifadhiwa; ikishindikana, hutumia `INITIAL_PASSWORD`
- `requireLogin` inaweza kuwashwa au kuzimwa kupitia `/api/settings/require-login`
- Njia za `/v1/*` zinaweza kuhitaji ufunguo wa API wa Bearer wakati `REQUIRE_API_KEY=true`
- "tokeni ya usimamizi" / "ufunguo wa API wenye wigo wa usimamizi" katika marejeleo haya humaanisha mojawapo ya familia zilizo kwenye mwongozo huo — si aina ya ziada ya siri ambayo haijafafanuliwa

> **Badiliko lisilooana na matoleo ya awali (v3.8.0)** — `/api/v1/agents/tasks/*` na ncha za usimamizi wa kipindi cha kusubiri sasa zinahitaji **uthibitishaji wa usimamizi** (kidakuzi cha dashibodi cha `auth_token` au ufunguo wa API wenye wigo wa usimamizi). Wateja ambao awali walitumia njia hizi bila uthibitishaji watapokea `401 Unauthorized`. Tazama commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).