# API Reference (Hausa)

🌐 **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) · 🇮🇱 [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) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)

---

🌐 **Harsuna:** 🇺🇸 [Turanci](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇧🇦 [Bosanski](../i18n/bs/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md)

Wannan shi ne babban bayanin OmniRoute API. Ya ƙunshi abubuwan da ake iya amfani da su na `/v1` da kuma fitattun wuraren kira na gudanarwa; [`docs/openapi.yaml`](../openapi.yaml) mai tsarin da inji zai iya karantawa da kuma itacen hanyoyin da ke ƙarƙashin `src/app/api/` su ne cikakkun tushe.

Don samun takamaiman bayani kan ƙa’idar da ta dace da OpenAI da jadawalin damar masu samarwa, duba
[`OPENAI_COMPATIBILITY.md`](./OPENAI_COMPATIBILITY.md).

Kowace tura tana ba da nata kwafin bayanin a `/openapi.yaml`, wanda ake samarwa daga `docs/openapi.yaml` yayin gina manhajar. Yana ɗauke da sigar ginin da kuma URL na uwar garke mai alaƙa (`./`), saboda haka buƙatun suna ci gaba da zuwa ga uwar garken da ta ba da takardar. Kayan aiki da ke shigo da fayil ɗin da aka sauke ba shi da irin wannan uwar garke, don haka ana buƙatar saita URL na tushe da hannu.

---

## Teburin Abubuwan Ciki

- [Kammala Tattaunawa](#chat-completions)
- [Hayar Zaman Gudanarwa Na Musamman](#exclusive-managed-session-leases)
- [Abubuwan Ƙayyadawa](#embeddings)
- [Ƙirƙirar Hoto](#image-generation)
- [OCR na Takardu](#document-ocr)
- [Jera Samfura](#list-models)
- [Bayanin Plugin na Mai Bayarwa](#provider-plugin-manifest)
- [Ƙarshen Dacewa](#compatibility-endpoints)
- [API na Fayiloli](#files-api)
- [API na Tarin Ayyuka](#batches-api)
- [API na Bincike](#search-api)
- [Yawo ta WebSocket](#websocket-streaming)
- [Rahoton Ƙayyadaddun Amfani da Matsaloli](#quotas--issues-reporting)
- [Ma'ajiyar Ma'ana](#semantic-cache)
- [Dacewar Gudanar da CLIProxyAPI](#cliproxyapi-management-compatibility)
- [Dashboard da Gudanarwa](#dashboard--management)
- [Gudanar da Haɗaka](#combo-management)
- [Webhooks](#webhooks)
- [Maɓallan da Aka Yi Rijista (Gudanarwa ta Atomatik)](#registered-keys-auto-management)
- [Ka'idar Agents](#agents-protocol)
- [Wakilan Gudanarwa](#management-proxies)
- [Juriya (faɗaɗɗe)](#resilience-extended)
- [Ƙwarewa](#skills)
- [Ƙwaƙwalwa](#memory)
- [Sabar MCP](#mcp-server)
- [Sabar A2A](#a2a-server)
- [Cloud, Evals da Assess](#cloud-evals--assess)
- [Tsarin Buƙata](#request-processing)
- [Tabbatarwa](#authentication)

---

## Kammala Tattaunawa

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

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Write a function to..."}
  ],
  "stream": true
}
```

### Kanun Kai na Musamman

| Header                   | Direction | Description                                                                                                                                                                                                               |
| ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache`   | Buƙata    | Saita zuwa `true` don ƙetare cache                                                                                                                                                                                        |
| `x-omniroute-no-memory`  | Buƙata    | Saita zuwa `true` don tsallake shigar da memory + skills ga wannan buƙatar (yana kama da no-cache; yana guje wa ƙarin kuɗin token/kudin kowane kira)                                                                      |
| `X-OmniRoute-Progress`   | Buƙata    | Saita zuwa `true` don abubuwan ci gaba                                                                                                                                                                                    |
| `X-Session-Id`           | Buƙata    | Maɓallin zaman da ba ya canzawa don daidaita zaman waje                                                                                                                                                                   |
| `x_session_id`           | Buƙata    | Hakanan ana karɓar sigar da ke amfani da alamar ƙasa (HTTP kai tsaye)                                                                                                                                                     |
| `X-OmniRoute-Session-Id` | Buƙata    | Alamar zaman/tattaunawar da mai kira ya samar (kuma tana ciyar da memory). Idan tana nan, ana adana ta yadda take a `call_logs.session_tag` don danganta kuɗi bisa zaman (#8249) — ba a taɓa ƙirƙirarta ba idan ba ta nan |
| `Idempotency-Key`        | Buƙata    | Maɓallin hana maimaitawa (tazarar sakan 5)                                                                                                                                                                                |
| `X-Request-Id`           | Buƙata    | Madadin maɓallin hana maimaitawa                                                                                                                                                                                          |
| `x-omniroute-connection` | Buƙata    | Kulle buƙatar samfurin guda zuwa haɗin mai bayarwa guda (asusun) ta ID ɗinsa — duba [Kulle asusu bisa buƙata](#account-pinning-per-request)                                                                               |
| `X-OmniRoute-Cache`      | Amsa      | `HIT` ko `MISS` (ba mai yawo ba)                                                                                                                                                                                          |
| `X-OmniRoute-Idempotent` | Amsa      | `true` idan an cire maimaitawa                                                                                                                                                                                            |
| `X-OmniRoute-Progress`   | Amsa      | `enabled` idan an kunna bin diddigin ci gaba                                                                                                                                                                              |
| `X-OmniRoute-Session-Id` | Amsa      | Ingantaccen ID ɗin zaman da OmniRoute ya yi amfani da shi                                                                                                                                                                 |
| `X-OmniRoute-Request-Id` | Amsa      | ID ɗin haɗa dangantakar buƙata (idan an san shi)                                                                                                                                                                          |
| `X-OmniRoute-Version`    | Amsa      | Sigar ginin OmniRoute (koyaushe tana nan)                                                                                                                                                                                 |
| `X-OmniRoute-Cost-Saved` | Amsa      | Adadin USD da cache ta guje wa kashewa a kan HIT (hits na cache kawai)                                                                                                                                                    |
| `X-OmniRoute-Decision`   | Amsa      | Bibiyar routing: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` dabarar haɗin ce, ko `single` don buƙatar da ba ta haɗuwa ba) — koyaushe tana nan a amsoshin kammalawa                                     |

> Bayanin Nginx: idan kuna dogara da headers masu amfani da alamar ƙasa (misali `x_session_id`), kunna `underscores_in_headers on;`.

#### Kulle asusu bisa buƙata

Lokacin da mai bayarwa yake da haɗi da yawa (asusun ko maɓallai), OmniRoute yawanci yana zaɓar ɗaya
ta hanyar dabararsa ta zaɓar asusu. A maimakon haka, buƙata na iya kulle takamaiman haɗi guda
ta amfani da header na `x-omniroute-connection`:

```bash
curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer <your OmniRoute API key>" \
  -H "Content-Type: application/json" \
  -H "x-omniroute-connection: <connection id>" \
  -d '{"model": "codex/gpt-5.5", "messages": [{"role": "user", "content": "hi"}]}'
```

- **Inda za a sami id.** Buɗe shafin mai samarwa a dashboard
  (**Dashboard → Providers → <provider>**) sannan ka danna guntun id na `xxxxxxxx…` a kan layin haɗi
  — hakan zai kwafi cikakken id ɗin haɗin.
- **Waɗanne buƙatu ne suke mutunta shi.** Buƙatun samfurin guda ɗaya (`provider/model`) a
  `/v1/chat/completions`, `/v1/messages` da `/v1/responses`. Haɗaɗɗun buƙatu suna yin watsi da taken: kulle
  asusu ɗaya ga kowane mataki na haɗin ta hanyar haɗin nasa.
- **Kullen yana da tsauri, ba fifiko ba ne.** Ana amfani da haɗin da aka kulle shi kaɗai. Idan
  kuskure ya faru a cikin buƙatar, ana yin rikodin lokacin jiran asusun, amma ba a
  juya zuwa wani asusun ɗan’uwan mai samarwa ɗaya ba.
- **Lokacin jiran aiki da ƙayyadadden kaso suna sakin kullen.** Yayin da haɗin da aka kulle yake cikin lokacin jiran aiki,
  ya ƙare ƙayyadadden kaso ko kuma an toshe shi saboda wata manufar ƙayyadadden kaso, buƙatu na gaba suna komawa ga
  sauran haɗe-haɗen mai samarwar, daidai kamar zirga-zirgar da ba a kulle ba.
- **Ids da ba a sani ba ko waɗanda aka kashe suna gaza.** Id ɗin da ba ya cikin rumbun haɗe-haɗen mai samarwa mai aiki (an
  share shi, an kashe shi, ko kuma na wani mai samarwa ne) ba ya barin wani asusu da ya cancanta, don haka buƙatar
  tana gaza maimakon a tura ta wani wuri ba tare da sanarwa ba.

Claude Code yana aika taken al'ada ta `ANTHROPIC_CUSTOM_HEADERS`. Sanya shi a cikin ɓangaren `env`
na `~/.claude/settings.json`, ko a cikin `.claude/settings.json` na matakin aiki domin kulle wani
asusu daban ga kowane aiki:

```jsonc
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
    "ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: <connection id>",
  },
}
```

Madogara: `src/sse/handlers/chat.ts` (karanta taken), `src/sse/services/auth.ts` da
`src/sse/services/sessionAffinityPin.ts` (sakin kullen da binciken abin da ya ɓace daga rumbun).

> **Taken bayanan farashi:** amsoshin nasara marasa yawo su ma suna ɗauke da saitin bayanan farashi na `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, ƙayyadaddun lambobi 10 bayan goma; `0.0000000000` idan kyauta/ne ba a saka farashi ba), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit`, da `X-OmniRoute-Fallback-Attempts` (kawai idan > 0), tare da `X-OmniRoute-Request-Id` da `X-OmniRoute-Version`. Ana fitar da waɗannan daga kammalawar hira, `/v1/responses`, `/v1/messages`, **da kuma ƙarshen kafofin watsa labarai** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations`, da `/v1/moderations` (koyaushe farashi `0`). Ana ƙididdige farashin kafofin watsa labarai bisa ga nau’in bayanan da ake sarrafawa (kowane hoto, kowane daƙiƙa, kowane hali, kowane rukunin bincike) idan ana da farashi, in ba haka ba `0` (fail-open).

> **Ma’anar farashi idan an samu cache:** a kan semantic-cache HIT (`X-OmniRoute-Cache-Hit: true`) ba a kira upstream ba, don haka `X-OmniRoute-Response-Cost` yana zama `0.0000000000` (farashin **ƙari** na bayar da amsar da aka samu). Ana bayar da ainihin/farashin da da an samu daban a cikin `X-OmniRoute-Cost-Saved`. Masu amfani da bayanan lissafin kuɗi su tara `X-OmniRoute-Response-Cost` (hits ba su da farashi); nazarin cache na iya tara `X-OmniRoute-Cost-Saved`.

## Leases na Zaman Gudanarwa na Musamman

Leasing na zaman gudanarwa na musamman kwangilar tura buƙatu ce ta zaɓi, wadda ba ta dogara da nau'in abokin ciniki ba: mai mallaka guda ɗaya mai aiki
yana riƙe haɗin OmniRoute guda ɗaya da ya cancanta. Ba ya lease samfurin, ba ya buƙatar OAuth, ba ya tantance
wani takamaiman abokin ciniki, kuma ba ya buƙatar wani takamaiman mai samarwa.

Maɓallin API da ke tantancewa dole ne ya kasance yana da scope `lease:exclusive` da jerin
`allowedConnections` bayyananne wanda ba komai ba. Iyakar sauya bayanai ta bayanan ajiya tana tabbatar da
filayen biyu tare yayin ƙirƙirar maɓalli da sabuntawa na wani ɓangare.

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

Amsoshin acquire, renew, da release masu nasara suna bayyana timestamps, `state`, da ainihin
`generation` mai kyau, amma ba sa taɓa bayyana haɗin da aka zaɓa ko bayanan tantancewa. Renew da release suna aika
generation a cikin jikin JSON:

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

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

Mai mallakar lease mai aiki zai iya neman bayanan nunawa masu kiyaye sirri a fili don binding ɗinsa na yanzu:

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

Wannan aikin status na zaɓi ana katange shi da opaque owner, ingantaccen managed API key, da ainihin
active generation a cikin mu’amalar bayanan ajiya guda ɗaya. `displayName` sunan haɗin da aka saita ne kawai bayan
an cire sararin gefe; yana zama `null` idan babu ingantaccen sunan da aka saita. OmniRoute ba ta taɓa maye gurbin
shi da imel ko wata alamar asusun da aka ƙirƙira ba. Ƙimar provider alamar nunawa ce da ba ta ƙunshi bayanan sirri ba, kuma ba ta taɓa
zama identifier na mai samarwa mai dacewa da aka ƙirƙira ba. An cire bayanan tantancewa, tokens, cookies, ɗanyen connection ko API
key ids, owner hashes, fencing secrets, da bayanan tura buƙatu na cikin gida.

Neman lookup da key mara daidai, owner mara daidai, generation da ya tsufa, wanda ya ɓace, wanda ya ƙare, wanda aka saki, ko wanda aka soke duk
suna mayar da kuskuren `409 LEASE_FENCE_STALE` iri ɗaya ba tare da metadata na haɗin ba. Abokin ciniki da ya karɓi amsar jiran
samun capacity ba shi da binding mai aiki da zai bincika. Lokacin da tura buƙatu ta sauya lease mai aiki,
generation ɗin nan ɗaya yana ci gaba da aiki, kuma status na mayar da sabon binding ta atomatik, ba tsohon ba.
Abokan ciniki da suke akwai ba su canza ba saboda acquire, renew, release, da amsoshin jira sun riƙe
siffofinsu na baya.

Wannan kwangilar uwar garke ba ta sauya stock OpenAI Codex `/status` ba. A halin yanzu Stock Codex yana bayar da
mai samar da samfurinsa da halin tantancewa/asusu da aka gina a ciki, amma ba ya nuna metadata na asusun mai samarwa na
musamman; haɗin abokin ciniki na gaba dole ne ya kira wannan aikin kuma ya yanke shawarar yadda zai
nuna `connection.displayName`.

Kowane buƙatar managed inference daga nan sai ya samar da control headers biyu:

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

Ana tabbatar da ainihin owner, generation, active connection, da authenticated API key nan take
kafin kowace yunƙurin upstream da aka tallafa. Sake amfani da owner da generation tare da wani key ya gaza ko da
wannan key ɗin yana ba da izinin haɗin ɗaya. Ba a adana ɗanyen owners, ba a rubuta su a log, ba a riƙe su
a cikin request snapshot, kuma ba a tura su upstream.

Rikicin ɗan lokaci yana mayar da HTTP `429` tare da `Retry-After` da:

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

Wannan amsar tana nufin ne kawai cewa jerin waɗanda suka cancanta na yau da kullum ba komai ba ne, kuma kowane ɗan takara
mai ’yanci yana hannun wani lease mai aiki na waje. Samfuran/masu samarwa da ba a tallafa ba, rashin daidaiton manufofi, cooldown, quota,
lafiya, da sauran gazawar cancanta ta yau da kullum suna riƙe amsoshin OmniRoute ɗinsu na yanzu.

### `x-omniroute-compression`

Sauya tsarin compression na kowace buƙata. Mafi girman fifiko — ya fi routing-combo
override, active profile, auto-trigger, da panel Default fifiko. Ƙimomi:

| Value         | Effect                                                                                                        |
| ------------- | ------------------------------------------------------------------------------------------------------------- |
| `off`         | Babu compression ga wannan buƙatar.                                                                           |
| `default`     | Profile na Default da aka samo daga panel (yana watsi da active profile). Ana barin injunan loss ɗin a kashe. |
| `safe`        | Dedup da folding na whitespace kawai.                                                                         |
| `allow-lossy` | A riƙe tsarin operator na wannan buƙatar, har da taƙaitawa da sake rubuta salo.                               |
| `engine:<id>` | Inji guda ɗaya idan an kunna shi, misali `engine:rtk`. Zaɓin wannan injin na kowace buƙata.                   |
| `<combo>`     | Combo mai suna, ana fara daidaita shi da suna (ba tare da la’akari da manya da ƙanana ba), sannan da id.      |

Bayanan kula:

- Ana yin watsi da ƙimomin da ba a sani ba (ba a taɓa ƙin buƙatar ba); warwarewa yana komawa ga fifikon operator na yau da kullum.
- Idan combos da yawa suna da suna ɗaya, aika combo **id** don samun daidaito tabbatacce.
- Combo wanda sunansa `off` ko `default` ba za a iya zaɓarsa da suna ba (ana fara fassara waɗannan kalmomin); a koma ga irin wannan combo ta id ɗinsa.
- Babban switch na compression ƙofa ce mai tsauri: idan an kashe compression gaba ɗaya, wannan header ba zai iya kunna shi ba.

Ana mayar da tsarin da aka aiwatar a cikin response header:

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

inda `<source>` yake ɗaya daga cikin `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, ko `off`.

---

## Embeddings

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

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

Masu samuwa: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.

Catalog ids su ne `provider/model` (misali: `jina-ai/jina-embeddings-v5-omni-small`). Bare Jina model ids da suka bayyana a registry (misali `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) su ma suna resolve. Jina embed/rerank/classify/segment suna fara amfani da bayanan shiga na `jina-ai` na dashboard; `JINA_AI_API_KEY` madadin ne kawai idan babu mabuɗin dashboard. Katin `jina-reader` na Reader / `r.jina.ai` ne kawai (`POST /v1/web/fetch`), kuma ba ya samar da embeddings ko rerank.

Registry models da ke sanar da goyon bayan multimodal suna kuma karɓar har zuwa abubuwa 32 masu tsari, marasa dogaro da provider. Nau’ikan abubuwan media su ne `text`, `image`, `audio`, `video`, da `document`. `source` na media ɗinsu ko dai `{"type":"url","url":"https://..."}` ne ko `{"type":"base64","data":"...","media_type":"..."}`.

Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`,
da family alias `jina-ai/jina-embeddings-v5-omni` → omni-small) yana kuma karɓar takardun Jina na asali
na EmbeddingsV5Request kuma yana **turawa ba tare da wani sauyi ba** zuwa `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,..." }] }
  ]
}
```

Ƙimomin asali na `{ image | audio | video | pdf }` na iya zama URL na HTTPS na jama’a, URI na `data:`, ko
base64 kai tsaye. OmniRoute ba ya mayar da waɗannan objects zuwa string ko kuma ɗauko native image URLs — Jina ce
ke karɓo public media ɗin da kanta. Ana tura ƙarin filayen Jina (`task`, `normalized`, `truncate`, `embedding_type`) yadda suke.

Jina SKUs masu text kawai har yanzu suna ƙin docs marasa text.

Iyakar tsaro da jigilar bayanai:

- Dole remote media URLs su kasance HTTPS na jama’a. Ana ɗauko canonical `{type,source:url}` items
  a gefen server (sake tabbatar da redirects, iyakar lokaci, iyakar girma, public DNS, da haɗa takamaiman adireshi) sannan a saka su a ciki kafin kiran provider. Ana tura Jina-native `{image:"https://..."}` items yadda suke bayan binciken HTTPS na jama’a iri ɗaya; Jina ce ke ɗauko URL ɗin.
- Media na base64 da aka saka a ciki yana da iyakar 8 MiB bayan decoding ga kowane item, da 16 MiB bayan decoding a dukkan request ɗin.

Fassarar provider (canonical items ba a taɓa tura su yadda suke ba):

- Jina multimodal models: kowane top-level item yana zama object guda mai maɓallin modality
  (`text` / `image` / `audio` / `video` / `pdf`) ta amfani da data URIs don media na cikin gida; vector guda ɗaya ga kowane top-level item.
- Gemini Embedding 2 family: array guda na top-level yana zama request na asali guda zuwa
  `models/{model}:embedContent`, tare da `content.parts` (`text` ko `inline_data`).
- llama.cpp (`llama-cpp/<model>`, ko wane model server na gida ya loda): canonical `text` items
  suna zama plain strings, yayin da `image` / `audio` / `video` suke zama object guda na
  `{"content": [part]}` kowannensu, ta amfani da chat content parts na llama-server (`image_url`,
  `input_audio` mai format `wav` / `mp3` / `flac`, `input_video`) tare da bayanan da aka saka a ciki; vector guda ɗaya ga kowane top-level item. Dole server ya yi aiki da `--embedding --mmproj …`; idan babu projector, shi kansa yana ƙin media. `document` ba ya samun goyon baya.
- Unknown/dynamic models da ba su da metadata na modality a sarari suna ƙin structured input tare da 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"
}
```

Haɗin model/modality da ba ya samun goyon baya yana mayar da HTTP 400 maimakon tilasta canza item ɗin. Filayen kari da ba na input ba a legacy string/token requests suna ci gaba da wucewa ba tare da sauyi ba.

```bash
# Jera dukkan embedding models
GET /v1/embeddings
```

---

## Samar da Hotuna

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

Masu samarwa da ake da su sun haɗa da OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, **ZenMux**, SD WebUI (na gida), da ComfyUI (na gida).

`n` yana mayar da hotuna `n` a cikin `data[]`. Masu samarwa waɗanda API ɗinsu na sama ke mayar da hoto guda ɗaya a kowace kira
(Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik,
NVIDIA NIM, Cloudflare Workers AI) ana yi musu kira daban-daban na sama `n`, tare da aƙalla kira 4 da ke gudana lokaci guda. `seed` da aka kayyade ana ƙara masa lambar kiran (`seed`, `seed + 1`, …), don haka hotunan suna bambanta amma suna ci gaba da kasancewa masu sake samarwa iri ɗaya. An taƙaita `n` zuwa 10. Buƙatar gaba ɗaya tana gazawa idan wani kira ya gaza. Jerin tsarin fan-out yana cikin `SINGLE_IMAGE_FANOUT_FORMATS` a
`open-sse/handlers/imageGeneration/fanOut.ts`.

ZenMux yana sake amfani da haɗin maɓallin API da ke akwai kuma yana karɓar prefix na `zenmux/` ko `zm/`:

- `zenmux/openai/gpt-image-2` yana amfani da OpenAI Images API na ZenMux. Zaɓuɓɓuka sun haɗa da `size`,
  `quality`, `n`, `output_format`, `output_compression`, `background`, da `response_format`.
- Sauran masu wallafawa, kamar `zm/meta/muse-image-1.0`, suna amfani da wurin ƙarshen Vertex AI `:predict` na ZenMux. `n` yana komawa zuwa `sampleCount`, `aspect_ratio` zuwa `aspectRatio`, sannan `image_size`
  (`1K`, `2K`, `4K`) zuwa `sampleImageSize`. `size` na pixel yana samar da yanayin faɗi da tsawo ne kawai,
  ba ya tabbatar da ainihin girman pixel ba. Matsakaicin faɗi da tsawo, ƙuduri, da adadin da ake tallafawa sun bambanta bisa ga samfurin.
- `zm/inclusionai/ming-image-0.1-design` yana zaɓar girmansa da kansa. A bar `size`,
  `aspect_ratio`, da `image_size` ba tare da bayar da su ba; ƙimomin da aka bayar kai tsaye suna mayar da HTTP 400. Ana iya neman PNG, JPEG, da WebP ta amfani da `output_format`.

Wannan haɗin yana tallafawa samar da hoto daga rubutu, ba gyaran hoto na tunani ba. Ana daidaita fitowar Vertex zuwa `data[].b64_json`; `response_format: "url"` yana mayar da URL na HTTPS daga sama ko URL ɗin bayanan base64 idan bytes ɗin hoto kawai ake da su. Fitowar da ba ta da komai ko wadda aka tace tana mayar da kuskure maimakon nasarar da ba ta da komai. Samun damar samfurin ya dogara da asusun ZenMux. Duba [Vertex API na ZenMux](https://docs.zenmux.ai/api/vertexai/generate-images) da
[OpenAI Images API](https://docs.zenmux.ai/api/openai/generate-an-image).

Haɗin shiga na Microsoft 365 Copilot yana samar da `copilot-m365-web/m365-copilot-image`
ta kayan aikin hoton da ke cikin Copilot: juya Copilot guda ɗaya a kowane hoto (`n` 1–4), `size` yana jagorantar yanayin tsayuwa ko kwance kawai, kuma ana mayar da hotuna kai tsaye (`b64_json`, ko URL ɗin bayanai ga
`response_format: "url"`). Duba [Microsoft 365 Copilot](../providers/COPILOT-M365.md#image-generation).

```bash
# Jera dukkan samfuran hotuna
GET /v1/images/generations
```

---

## OCR na Takardu

```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` yana zaɓar mai samar da OCR ta hanyar prefix na `provider/model`; ID na samfurin da ba shi da prefix (misali
`mistral-ocr-latest`) yana warwarewa zuwa mai samarwar da aka yi masa rajista, kuma idan ba a saka `model` ba, tsoho shi ne
Mistral (`mistral-ocr-latest`). Masu samarwa da aka yi wa rajista (`open-sse/config/ocrRegistry.ts`):

| ID na mai samarwa             | ID na samfurin       | Ƙimar `model`                                          | Bayanan kula                                                                                            |
| ----------------------------- | -------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `mistral`                     | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (ko `mistral-ocr-latest`) | Aiki kai tsaye — ana mayar da amsa kai tsaye daga kiran sama guda ɗaya.                                 |
| `azure-document-intelligence` | `prebuilt-read`      | `azure-document-intelligence/prebuilt-read`            | Kiran sama na asynchronous (`analyze` + poll) — duba ƙasa.                                              |
| `vertex-deepseek-ocr`         | `deepseek-ocr-maas`  | `vertex-deepseek-ocr/deepseek-ocr-maas`                | Aiki kai tsaye, ta ƙarshen abokin hulɗar Vertex AI `openapi/chat/completions` — duba ƙasa don auth/URL. |

Dukkan masu samarwa ukun suna amsawa da jiki mai tsarin Mistral iri ɗaya:

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

### Tsarin jiran amsa na Azure Document Intelligence

API na `analyze` na Azure Document Intelligence asynchronous ne: buƙatar farko tana mayar da taken
`Operation-Location` maimakon jiki, kuma dole ne a yi polling don samun sakamakon. Handler ɗin
(`open-sse/handlers/ocr.ts`) yana yin polling ga wannan URL kowane daƙiƙa na tsawon yunƙuri 30, yana dakatar da aiki nan take (ba ya ci gaba da polling)
idan amsar polling ba `ok` ba ce ko kuma matsayin ya kasance `"failed"`, sannan yana mayar da `504` idan aikin har yanzu yana gudana bayan an ƙare adadin yunƙurin. Ana daidaita amsar Azure ta ƙarshe
zuwa tsarin `pages`/`markdown` iri ɗaya da Mistral ke amfani da shi kafin a mayar da ita ga mai kira, don haka lambar abokin ciniki ba ta buƙatar keɓance mai samarwar.

### Tabbatarwa da warware ƙarshen Vertex AI DeepSeek OCR

`vertex-deepseek-ocr` yana sake amfani da tabbacin Vertex AI iri ɗaya da OmniRoute ta riga ta tallafa don
zirga-zirgar chat/hoto (`open-sse/executors/vertex.ts`): API key na haɗin yana kasancewa ko dai takardar shaidar Service Account JSON (ana musanya ta da OAuth access token mai ɗan gajeren lokaci ta hanyar JWT-bearer flow) ko kuma OAuth access token da aka riga aka samar wanda ake amfani da shi yadda yake. Ana gina URL na ƙarshen sama daga generic
`openapi/chat/completions` na Vertex a matsayin ƙarshen abokin hulɗa, bisa project da region na haɗin — `providerSpecificData.project`/`providerSpecificData.region` da aka bayar kai tsaye koyaushe suna da fifiko;
in ba haka ba ana samo project daga `project_id` na Service Account JSON, kuma region ɗin tsoho shi ne
`us-central1`. Ana yin warwarewar duka a cikin `open-sse/handlers/ocr.ts`
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`), sannan `src/app/api/v1/ocr/route.ts` ke amfani da su kafin aikawa zuwa `handleOcr`.

---

## Jerin Samfura

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

→ Yana mayar da dukkan samfuran hira, embedding, da hoto + haɗe-haɗe cikin tsarin OpenAI
```

### Farashin samfura (`pricing`)

Shigarwa tana ɗauke da wani abu na `pricing` lokacin da OmniRoute ya san farashin samfurin. Farashin yana
fitowa daga teburin farashin da lissafin kuɗi ke amfani da shi: tsoffin ƙimomin da aka gina a ciki,
farashin da aka daidaita, da gyare-gyaren da aka saita ta `/api/pricing`. Waɗannan farashin jerin farashi
ne, saboda haka masu ba da sabis na biyan kuɗi ma suna nuna farashi na kowane token.

```json
"pricing": {
  "prompt": "0.000005",
  "completion": "0.000025",
  "input_cache_read": "0.0000005",
  "input_cache_write": "0.00000625",
  "input": 5,
  "output": 25,
  "cached": 0.5,
  "cache_creation": 6.25
}
```

| Filayen                                                         | Ma'auni                             | Bayanan kula                                                                                                                                                       |
| --------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `prompt`, `completion`, `input_cache_read`, `input_cache_write` | USD a kowane token, igiyar goma     | Mai jituwa da OpenRouter, ba ya taɓa amfani da tsarin rubutun exponent. Filayen cache guda biyu suna bayyana ne kawai idan akwai farashin cache.                   |
| `input`, `output`, `cached`, `cache_creation`                   | USD a kowane token miliyan 1, lamba | Filayen daga tsofaffin sigogin kundin bayanai, an bar su don abokan ciniki na yanzu. `reasoning` da `long_context` ma suna bayyana idan layin farashin yana da su. |

- **Haɗe-haɗe** suna ɗauke da farashin target ɗinsu na farko da ake iya gani. Haɗe-haɗen `auto/*` da aka gina a ciki suna zaɓar
  target a lokacin buƙata, saboda haka ba su da `pricing`.
- **Samfuran kyauta** suna nuna `"0"` (da `0`) idan farashinsu sifili ne. Samfurin da ba shi da layin farashi
  ma yana nuna `"0"` lokacin da kundin bayanai ya nuna shi kyauta (`free: true`) ko kundin samfuran kyauta da aka gina a ciki ya jera shi.
- **Farashin da ba a sani ba:** shigarwar ba ta da mabuɗin `pricing`.
- **Masu ba da sabis masu auna kuɗi ta credit** (kamar Kiro) suna cajin kowane buƙata maimakon kowane token. Shigarwarsu
  tana riƙe da filayen lamba na kowane token miliyan 1 da suke da su a baya, kuma ba ta ɗauke da filayen kirtani na kowane token.
- **Bambance-bambance** (ids na reasoning-effort, laƙabin no-thinking, madubin discovery da gateway)
  suna kwafi farashin samfurin da suke tura buƙatu zuwa gare shi.
- Filayen suna ɗauke da ƙimomin tushe ne kawai. Matakan long-context (filin lamba na `long_context`) da
  masu ninkawa na service-tier (misali Codex fast ko flex) ba sa canza `prompt` ko
  `completion`.
- Abun yana ɗaya ga kowane salon tantancewa, har da buƙatar irin ta Anthropic mai ɗauke da `x-api-key` da `anthropic-version` (amsar tana nan `{ "object": "list",
"data": [...] }`). Aiwatarwa: `src/app/api/v1/models/catalogPricing.ts`.

### Gabatarwar id na samfura (`?prefix=`)

Yawancin samfura ana tallata su ƙarƙashin **gabatarwar mai ba da sabis**. Wane gabatarwa za ku samu yana ƙarƙashin ikon
tutar fasalin `MODELS_CATALOG_PREFIX_MODE`, kuma ana iya sauya shi **ga kowace buƙata** ta hanyar siga ta query — wannan yana da amfani
ga abokin ciniki da yake son jerin tsafta ba tare da canza saitin uwar garke na kowa ba:

```bash
GET /v1/models?prefix=alias        # id guda ɗaya ga kowane samfur — gajeriyar gabatarwar alias
GET /v1/models?prefix=dual         # siffofin biyu (tsoffin saitin uwar garke)
GET /v1/models?prefix=canonical    # gabatarwar cikakken provider-id kawai
```

| Yanayi      | Abin da yake fitarwa                                     | Bayanan kula                                                                                                                                                                                                                                |
| ----------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual`      | `cc/claude-sonnet-4-6` **da** `claude/claude-sonnet-4-6` | **Tsoho.** Duk ids ɗin suna tura buƙatu zuwa samfurin ɗaya; an bar su domin saitunan abokan ciniki da suka rubuta ɗaya daga cikin siffofin da hannu su ci gaba da aiki. Yawanci kundin bayanai ya ninka.                                    |
| `alias`     | `cc/claude-sonnet-4-6`                                   | Shigarwa guda ɗaya ga kowane samfur. Masu ba da sabis da ba su da alias na daban har yanzu suna fitar da shigarwarsu, don haka babu abin da ya ɓace.                                                                                        |
| `canonical` | `claude/claude-sonnet-4-6`                               | Shigarwa guda ɗaya ga kowane samfur ƙarƙashin cikakkiyar gabatarwar provider-id. Masu ba da sabis da ba su da alias na daban (misali `antigravity/…`, `agy/…`) su ma suna fitar da id ɗinsu guda ɗaya a nan, don haka babu abin da ya ɓace. |

Hakanan ana iya gane madubin yanayin `dual` ba tare da siga ta query ba: yana ɗauke da filin `parent`
da ke nuna id na farko.

Abokan ciniki da ke nuna mai zaɓar samfur ya kamata su nemi `?prefix=alias` — wannan shi ne abin da
[ƙarin OmniCopilot na VS Code](../guides/VSCODE-COPILOT.md) yake yi.

### Matatun ganowa (`?capability=`, `?min_context=`, `?kind=`, `?q=`)

`GET /v1/models` yana karɓar matatun ganowa na zaɓi. Idan ba a yi amfani da ko ɗaya daga cikinsu ba, amsar
ba ta canza. Suna rage kundin bayanan da mai kira ya riga ya gani (izinin API-key yana aiki da farko),
kuma suna gudana kafin shafin OpenAI-style na `limit` / `after`:

```bash
GET /v1/models?capability=vision&capability=tool_calling   # kowane capability da aka jera dole ya zama true
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding                              # `type` na kundin bayanai; layukan da ba su da shi su ne `chat`
GET /v1/models?q=sonnet&limit=10                           # daidaitawa ba tare da la’akari da manyan/ƙananan haruffa ba kan id ko suna
```

| Param         | Values                                                                                              |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `capability`  | `attachment`, `reasoning`, `structured_output`, `temperature`, `thinking`, `tool_calling`, `vision` |
| `min_context` | lamba mara mara mara mara mara mara mara mara, wanda aka kwatanta da `context_length`               |
| `kind`        | `chat`, `audio`, `embedding`, `image`, `moderation`, `music`, `rerank`, `video`                     |
| `q`           | haruffa 1–200                                                                                       |

Ƙimar da ba a sani ba, ko `min_context` da ba lamba cikakkiya ce mara mara ba (misali `1.5`),
na mayar da HTTP `400`, kuma saƙon yana jera ingantattun ƙimomi. Aiwatarwa:
`src/app/api/v1/models/catalogFilters.ts`.

### Jerin gajerun samfura (`POST /v1/models/query`)

`POST /v1/models/query` na mayar da gajeren jerin da ba ya canzawa daga kundin samfura ɗaya, tare da
ingantaccen izini da ganuwa ga kowane maɓalli kamar `GET /v1/models`:

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

{ "capabilities": ["vision", "tool_calling"], "min_context": 128000, "max_output": 16000,
  "kind": "chat", "q": "gpt", "owned_by": "openai", "exclude": ["openai/gpt-4o"], "limit": 5 }

→ { "object": "list", "data": [ ...models ] }
```

Dukkan filayen zaɓi ne. `capabilities` da `exclude` suna karɓar tsararru ko kirtani da aka raba da waƙafi;
`max_output` yana kwatanta da `max_output_tokens`. Ana jera sakamako bisa `owned_by`, sannan `id`.
`limit` yana da tsohuwar ƙima ta `20`, kuma ƙimomin da suka wuce `100` ana takaita su zuwa `100`. JSON mara inganci,
filin da ba a sani ba ko ƙima mara inganci na mayar da HTTP `400`.

### Samfuran tattaunawa da aka ɓoye ɗaiɗaiku

Samfurin da aka yi wa alamar **Boyayye** a shafin mai samar da shi ana cire shi daga kundin samfura kuma a ƙi
buƙatarsa kai tsaye da HTTP `404` / `model_not_found`. Binciken yana amfani da mai samarwa da samfurin da aka
warware, har da laƙabin masu samarwa, prefix na nodes na masu samarwa masu jituwa, da tsoffin saitunan haɗi.
Combo yana tsallake wuraren da aka ɓoye kuma yana iya amfani da ɗan'uwa da yake bayyane; idan babu sauran wurin
aiwatarwa, yana mayar da lambar kuskure ɗaya. Cire ɓoyewa yana aiki a buƙata ta gaba. Sauye-sauyen ganuwa
na hotuna kaɗai ba sa ɓoye samfurin tattaunawa mai ID ɗaya.

Wannan saitin samfurin na ɗaiɗaiku ya bambanta da
[jerin ba da izini/ƙin izini na fallasa samfura](../routing/MODEL_EXPOSURE_LIST.md), waɗanda ke tace tallan kundin
samfura da 'yan takarar sarrafa hanya ta atomatik yayin da suke riƙe da aika buƙata kai tsaye. Izinin samfurin
na maɓallin API yana ci gaba da aiki daban. Tsohon yanayin prefix na kundin samfura ya kasance `dual`.

### Bambance-bambancen samfura marasa tunani

Ga samfuran Claude masu iya tunani, `/v1/models` yana kuma tallata wani bambanci **marar tunani** wanda ID ɗinsa
ke da prefix `claude-3-omniroute-no-thinking/`:

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

Zaɓar wannan ID (misali a cikin saitin Claude Code da ke haɗa tubalin `thinking` koyaushe) yana warwarewa zuwa ainihin
`<provider>/<model>` tare da kashe reasoning — `thinking:{type:"disabled"}` a hanyar `/v1/messages`, ko kuma a cire filayen
`reasoning`/`reasoning_effort` a hanyar `/v1/chat/completions`. Ana jera wannan bambanci ne kawai ga samfuran dangin
Claude da ke goyan bayan tunani **kuma** suke mutunta `disabled` (saboda haka, misali, ana cire samfuran da suka dogara
kaɗai da adaptive waɗanda ke ƙin `disabled`). Masu gudanarwa na iya tilasta kunna ko kashe wannan laƙabi ga kowane samfur
ta hanyar `ModelSpec.noThinkingAlias`.

---

## Bayanin Plugin na Provider

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

Yana dawo da bayanin plugin na provider mai aminci ga JSON wanda Bifrost, CLIProxyAPI, da
masu tura buƙatu na sidecar na gaba ke amfani da shi. Ana samar da amsar ne daga rajistar
provider ta TypeScript, kuma da gangan ba ta ƙunshi sirrin abokan cinikin OAuth ba, warware
yanayin runtime, ayyukan executor, taken buƙata, ko bayanan asusu.

Yi amfani da wannan endpoint lokacin da sidecar ke aiki a matsayin wani tsari dabam kuma ba zai iya
shigo da `open-sse/config/providerPluginManifestRegistry.ts` kai tsaye ba.

---

## Samar da sautin ElevenLabs

Saita haɗin provider na `elevenlabs` a OmniRoute tare da maɓallin API na ElevenLabs.
Abokan ciniki suna tantancewa da maɓallin **OmniRoute** ɗinsu (`Authorization: Bearer $OMNIROUTE_API_KEY`);
gateway ɗin yana aika maɓallin provider da aka adana a matsayin `xi-api-key`. Kada a taɓa aika maɓallin ElevenLabs
a matsayin alamar bearer ta gateway.

| Hanya | Path                        | Amsa                                           | Rukunin endpoint na maɓallin API |
| ----- | --------------------------- | ---------------------------------------------- | -------------------------------- |
| POST  | `/v1/sound-generation`      | Bayt ɗin sauti na asali                        | `elevenlabs`                     |
| POST  | `/v1/music`                 | Bayt ɗin sauti na asali                        | `music`                          |
| POST  | `/v1/music/stream`          | Bayt ɗin sauti masu gudana                     | `music`                          |
| POST  | `/v1/music/detailed`        | Sautin multipart na asali da tsarin tsara      | `music`                          |
| POST  | `/v1/music/detailed/stream` | Metadata na SSE na asali da gutsattsarin sauti | `music`                          |
| POST  | `/v1/music/plan`            | Tsarin tsara a tsarin JSON                     | `music`                          |

Waɗannan endpoints suna ƙara wa hanyoyin `/v1/audio/speech`, `/v1/audio/transcriptions`,
`/v1/voices`, `/v1/text-to-speech/{voiceId}` da `/v1/speech-to-text` da ake da su. Ana adana filayen JSON
na asali da sigogin query kamar `output_format` da `enable_logging`.
Amsoshin `/v1/music/detailed` suna riƙe iyakokin multipart ɗinsu; yi fassarar su a matsayin multipart.
`/v1/music/detailed/stream` yana dawo da `text/event-stream` mai ɗauke da metadata na tsara da
gutsattsarin sauti na base64 a cikin abubuwan SSE. Dukkan hanyoyi shida suna goyon bayan CORS preflight.

```bash
export OMNIROUTE_BASE_URL="http://localhost:20128"
export OMNIROUTE_API_KEY="your-omniroute-api-key"

# Tasirin sauti gajere. Tsawon lokaci: daƙiƙa 0.5 zuwa 30.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/sound-generation?output_format=mp3_44100_128" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"A single soft bell chime","duration_seconds":1,"model_id":"eleven_text_to_sound_v2"}' \
  --output effect.mp3

# Ana bayyana tsawon kiɗa da milisakan: 3000 zuwa 600000.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music?output_format=mp3_44100_128" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Gentle instrumental piano","music_length_ms":10000,"force_instrumental":true,"model_id":"music_v1"}' \
  --output music.mp3
```

Yi amfani da `/v1/music/stream` tare da jikin JSON iri ɗaya domin isar da sauti a hankali.
Tsarawa tana karɓar ɗaya kawai daga cikin `prompt` ko `composition_plan`; `/v1/music/plan` yana buƙatar
`prompt` kuma bisa zaɓi yana karɓar `source_composition_plan`. Tsare-tsaren asali suna adana ƙarin
filayen provider domin nau’ikan tsarin tsara da zaɓuɓɓukan daidaita sauti su isa ElevenLabs.

Endpoint ɗin haɗin kai `/v1/music/generations` ma yana karɓar
`elevenlabs/music_v1`, `elevenlabs/music_v2` da `elevenlabs/music_v2_5`. Tare da haɗin ElevenLabs mai aiki,
ana nuna waɗannan samfura a cikin kundin kiɗa. Wannan endpoint yana dawo da
`{"created":...,"data":[{"b64_json":"...","format":"mp3"}]}`. Filinsa na `duration` yana cikin
daƙiƙu kuma yana taswira zuwa `music_length_ms`; `music_length_ms` da aka bayyana kai tsaye yana da fifiko.
`instrumental` yana taswira zuwa `force_instrumental`, tare da filin asali yana da fifiko.
Yi amfani da endpoints na yawo na asali don yawo, sannan endpoint na tsara na asali
don buƙatun da tsarin tsara kaɗai ke jagoranta.

```bash
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music/generations" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs/music_v1","prompt":"Gentle instrumental piano","duration":10,"instrumental":true}'
```

Ana aiwatar da ƙuntatawa na endpoint, samfuri, kasafi da haɗi kafin kiran upstream. Hanyoyin asali
suna dawo da lambobin matsayin upstream da jikin kurakurai ba tare da canji ba, har da `402`
don ƙuntatawar shiri da `429` don iyakar quota. Ana adana taken
`character-cost`, `song-id`, `request-id` da `retry-after` idan suna nan. Samun ragowar kyauta
ba ya tabbatar da damar amfani da kowane samfurin kiɗa, tsarin fitarwa ko fasalin API ba: ElevenLabs ne
ke yanke damar amfani ga kowace buƙata. Endpoint ɗin haɗin kai yana adana lambobin matsayin kurakurai
a cikin ambulan kurakurai da aka daidaita na OmniRoute.

Kwangilolin upstream: [tasirin sauti](https://elevenlabs.io/docs/api-reference/text-to-sound-effects/convert),
[tsarin kiɗa](https://elevenlabs.io/docs/api-reference/music/compose) da
[bayanan kiɗa masu gudana](https://elevenlabs.io/docs/api-reference/music/compose-detailed-stream).

---

## Ƙarshen Haɗin Kai

| Hanya | Hanya                                     | Tsari                                     |
| ----- | ----------------------------------------- | ----------------------------------------- |
| POST  | `/v1/chat/completions`                    | OpenAI                                    |
| POST  | `/v1/messages`                            | Anthropic                                 |
| POST  | `/v1/responses`                           | OpenAI Responses                          |
| POST  | `/v1/embeddings`                          | OpenAI                                    |
| POST  | `/v1/images/generations`                  | OpenAI Images                             |
| POST  | `/v1/images/edits`                        | OpenAI Images (gyara/cika gibi)           |
| POST  | `/v1/videos/generations`                  | Samar da bidiyo irin na OpenAI            |
| POST  | `/v1/music/generations`                   | Samar da kiɗa irin na OpenAI              |
| POST  | `/v1/audio/transcriptions`                | OpenAI Audio (STT)                        |
| POST  | `/v1/audio/speech`                        | OpenAI TTS (yana dawo da jikin sauti)     |
| POST  | `/v1/rerank`                              | Sake jera irin na Cohere/Voyage           |
| POST  | `/v1/classify`                            | Jina classify (`api.jina.ai`)             |
| POST  | `/v1/segment`                             | Jina segmenter (`segment.jina.ai`)        |
| POST  | `/v1/moderations`                         | OpenAI Moderations                        |
| GET   | `/v1/models`                              | OpenAI                                    |
| POST  | `/v1/models/query`                        | Jerin gajerun samfura da aka tace         |
| 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}/`                 | Laƙabin kundin OpenAI                     |
| GET   | `/api/v1/vscode/{token}/models`           | Laƙabin samfuran OpenAI                   |
| POST  | `/api/v1/vscode/{token}/chat/completions` | Laƙabin OpenAI mai alamar token           |
| POST  | `/api/v1/vscode/{token}/responses`        | Laƙabin OpenAI Responses mai alamar token |
| POST  | `/api/v1/vscode/{token}/api/chat`         | Laƙabin Ollama mai alamar token           |
| GET   | `/api/v1/vscode/{token}/api/tags`         | Laƙabin alamun Ollama mai alamar token    |

Dukkan hanyoyin POST suna bin tsari iri ɗaya: `Bearer your-api-key` + jikin JSON da Zod ya tabbatar da ingancinsa (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, da sauransu, duba `src/shared/validation/schemas.ts`). Ana dawo da 4xx idan tsarin bayanai bai yi nasara ba.

Ga abokan ciniki waɗanda ba za su iya haɗa `Authorization: Bearer ...` ba, OmniRoute yana kuma karɓar maɓallan API a cikin URL ta hanyar ko dai daidaitawar query string (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) ko kuma keɓaɓɓun hanyoyin `/api/v1/vscode/{token}/...` da aka bayyana a ƙasa.

```bash
# Sake jera (mai samarwa daga rajistar girgije, ko kumburin mai samarwa mai dacewa da OpenAI a matsayin "<prefix>/<model>")
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

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

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

# Binciken Jina (s.jina.ai; laƙaban masu samarwa: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

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

# TTS — yana dawo da jikin audio/mpeg (ko tsarin da aka nema)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Soniox TTS yana buƙatar harshe da murya: `language` yana da tsohowar "en"; idan babu
# murya ko aka yi amfani da sunan muryar OpenAI na asali (alloy, nova, …), ya zama "Adrian"
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }

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

# Samar da bidiyo / kiɗa (ID ɗin samfurin da aka riga aka sa sunan mai samarwa)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }
```

> **Nodes na provider don sake-rarrabawa:** `POST /v1/rerank` yana kuma tura buƙatu zuwa nodes na provider masu jituwa da OpenAI
> (oMLX, vLLM, Infinity, TEI a bayan gateway, …) waɗanda ake adireshinsu da `<node-prefix>/<model>`. Nodes na loopback
> (`localhost`, `127.0.0.1`, `172.16.0.0/12`) koyaushe sun cancanci amfani, haka ma sunayen runduna
> da mai gudanarwa ya jera a cikin `OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS` (misali sunan sabis na Docker/Compose kamar
> `http://reranker:8080/v1`; ana kiran waɗannan kai tsaye, ba ta `HTTP(S)_PROXY` ko wakilin da aka kulle wa haɗi ba).
> Nodes da ke kan kowace runduna
> dabam — kwamfuta a LAN ko abokin Tailscale — suna cancantar amfani ne kawai idan mai gudanarwa ya kunna
> tutar fasalin `RERANK_REMOTE_PROVIDER_NODES` **kuma** tushen URL na node ya wuce manufar URL na fita ta provider
> (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`).
> Matakin sake-rarrabawa na injin memory yana kiran wannan hanya ta
> loopback, saboda haka ƙa'ida ɗaya ce ke jagorantar `rerankProviderModel` a saitunan Memory.
>
> **Siffofin sabar ta gida:** ana kiran node a `<base>/v1/rerank` sannan, idan an sami 404, a `<base>/rerank`
> (Infinity, TEI). Jikin buƙatar zuwa upstream yana ɗauke da rubutun Cohere/OpenAI duka (`documents`,
> `return_documents`) da kuma rubutun TEI (`texts`, `return_text`), sannan ana daidaita amsar upstream
> zuwa ambulaf ɗin Cohere: `[{index, score, text}]` marar kunshin daga TEI, `{results: [{index, score}]}`
> daga ƙananan gateways, da `{data: [...]}` mai salo irin na Voyage duk suna dawowa ga abokin ciniki a matsayin
> `{results: [{index, relevance_score, document?}]}`, an jera su bisa maki kuma an taƙaita su zuwa `top_n`.

> **Gano nodes na provider:** samfura a kan node na provider mai jituwa da OpenAI suna bayyana a cikin `GET /v1/models`
> a ƙarƙashin prefix ɗin node. Layukan da ba su ɗauke da metadata na endpoint ba (abin da aka saba gani a jerin `/v1/models`
> na gida) suna gadon `apiType` na node, saboda haka samfuran node na `embeddings` suna da
> `type: "embedding"` kuma samfuran node na `rerank` suna da `type: "rerank"` maimakon su koma chat ta tsohuwa;
> `supportedEndpoints` da aka bayyana a sarari a kan layin da aka daidaita ko aka ƙara da hannu har yanzu yana da fifiko.

### Hanyoyin Provider na Musamman

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

Ana ƙara prefix ɗin provider ta atomatik idan babu shi. Samfuran da ba su dace ba suna dawo da `400`.

---

## API ɗin Fayiloli

Ƙarshen fayiloli mai dacewa da OpenAI don shigarwa/fitarwa na batch da loda fayiloli bisa manufa.

| Hanya  | Hanya                    | Bayani                                                                                                        |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/files`              | Loda fayil (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — iyakar 512 MiB |
| GET    | `/v1/files`              | Jera fayilolin maɓallin API da aka tabbatar da shi                                                            |
| GET    | `/v1/files/[id]`         | Dawo da bayanan fayil                                                                                         |
| DELETE | `/v1/files/[id]`         | Goge fayil                                                                                                    |
| GET    | `/v1/files/[id]/content` | Mayar da ɗanyen jikin fayil a matsayin rafi                                                                   |

**Tabbatarwa:** Maɓallin API na Bearer — ana keɓe fayiloli ga kowane maɓallin API ta hanyar `getApiKeyRequestScope`. Maɓalli yana ganin, sauke da goge fayilolinsa kawai; zaman dashboard ba tare da maɓalli ba yana karanta dukkan instans; fayil da ba shi da mai shi (loda ba tare da tantancewa ba ko ta zaman dashboard) ana hana kowane mai kira da ba na zaman ba shiga. `GET /v1/files` yana ƙin mai kira marar tantancewa — da kuma maɓallin da aka gabatar wanda ba a samu daidaitonsa ba — da `401` ko da `REQUIRE_API_KEY=false` ne, maimakon jera fayilolin dukkan masu haya (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

## API ɗin Batches

Ayyukan batch masu dacewa da OpenAI.

| Hanya  | Hanya                     | Bayani                                                                                                                  |
| ------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/batches`             | Ƙirƙiri batch — `v1BatchCreateSchema` yana tabbatar da jikin buƙatar (`input_file_id`, `endpoint`, `completion_window`) |
| GET    | `/v1/batches`             | Jera batches                                                                                                            |
| GET    | `/v1/batches/[id]`        | Dawo da matsayin batch + `request_counts`                                                                               |
| DELETE | `/v1/batches/[id]`        | Goge batch da ya kammala/ya gaza                                                                                        |
| POST   | `/v1/batches/[id]/cancel` | Soke batch da ke kan aiki                                                                                               |

**Tabbatarwa:** Maɓallin API na Bearer. Ana keɓe batches ga kowane maɓallin API bisa ƙa’idar rarrabuwa ta hanyoyi uku da ta shafi fayiloli: maɓallin kansa kawai, zaman dashboard yana da ikon ganin dukkan instans, kuma bayanan da ba su da mai su ana hana duk masu kira da ba na zaman ba shiga (dawo da bayanai, gogewa, sokewa, da binciken `input_file_id` yayin ƙirƙira). `GET /v1/batches` yana ƙin mai kira marar tantancewa da `401` ko da `REQUIRE_API_KEY=false` ne.

---

## API ɗin Bincike

Ƙyamar mai samar da binciken yanar gizo/bincike (Tavily, Brave, Exa, Serper, da sauransu).

| Method | Path                   | Description                                                                                                 |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------------------- |
| GET    | `/v1/search`           | Jera masu samar da binciken da aka saita + damar su                                                         |
| POST   | `/v1/search`           | Gudanar da tambayar bincike — `v1SearchSchema` ne ke tantance jiki, yana goyan bayan adanawa da haɗa buƙatu |
| GET    | `/v1/search/analytics` | Ƙididdigar sakamako/jinkiri/ma’ajiyar kowane mai samarwa                                                    |

**Auth:** Maɓallin API na Bearer (`extractApiKey` + `isValidApiKey`). Ana tilasta manufar bincike ta `enforceApiKeyPolicy`.

**Auto-select:** idan babu `provider`, mai samarwa mafi arha da ke da haɗin da aka saita shi ne ke fara aiki, sannan na gaba mafi arha shi ne na madadin idan na farko ya gaza. Ana amfani da masu samarwa kyauta na madadin ƙarshe (`duckduckgo-free`) ne kawai idan ba a saita wani abu dabam ba. Ana ɗaukar SearXNG mai karɓar kansa a matsayin wanda aka saita da zarar haɗinsa ya adana ainihin `baseUrl` (ba tsohon adireshin kundin `http://localhost:8888/search` ba): daga nan sai ya kasance mai samarwa na $0 a matsayi na gaba bayan masu maɓalli, yayin da mai samarwa mafi arha mai maɓalli yake zama na madadin, har ma idan SearXNG ya amsa da 400, 401, 403 ko 404. `baseUrl` da ba ingantaccen adireshin `http(s)` ba ne ko kuma ya nuna adireshin metadata na gajimare ba ya ƙirga. Haɗin SearXNG da ke adana alama yana matsayi haka ne kawai a kan `https://` ko `http://` na loopback. A kan `http://` na nesa mara kariya, ba ya taɓa zama na madadin kuma yana kasancewa na madadin ƙarshe, ana amfani da shi ne kawai idan ba a saita wani mai samarwa ba ko kuma an nema da suna; saboda haka yana aika alamar ba tare da ɓoyewa ba a waɗannan lokuta biyu.

### `provider_options` na Exa da Tavily

Exa da Tavily suna karanta filayen da suka kebanta da mai samarwa daga jaka mai suna:
`provider_options.exa` (ko `provider_options["exa-search"]`) da `provider_options.tavily`
(ko `provider_options["tavily-search"]`). Maɓallan da ke ƙasa kawai ake turawa. Ana bincika kowannensu
da nasa tsarin Zod a cikin `open-sse/handlers/search/providerOptionsPassthrough.ts`,
kuma ana cire maɓalli mai nau’in da bai dace ba. Ana watsi da duk wani maɓalli, har da na tantancewa, adireshin tushe,
`stream` da `outputSchema`. Maɓallan madaidaiciya da sauran masu samarwa ke amfani da su (`cx`, `depth`, ...) suna aiki
kamar da.

| Provider | Top-level fields                                                                                                                                                                                                                                                                                                                                                          | Nested                                                                                                                                   |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Exa      | `type`, `category`, `userLocation`, `moderation`, `additionalQueries`, `objective`, `systemPrompt`, `compliance` (ƙimomin asali madaidaiciya), `startPublishedDate`, `endPublishedDate`                                                                                                                                                                                   | `contents.{text, highlights, summary, extras, livecrawlTimeout, maxAgeHours}` ana haɗa su a kan tsoho `{ text: true, highlights: true }` |
| Tavily   | `search_depth`, `chunks_per_source`, `time_range`, `start_date`, `end_date`, `include_published_date`, `filter_by_published_date`, `include_answer`, `include_raw_content`, `include_images`, `include_image_descriptions`, `include_favicon`, `include_domains_mode`, `language`, `filter_by_language`, `auto_parameters`, `exact_match`, `include_usage`, `safe_search` | —                                                                                                                                        |

Filayen gabaɗaya koyaushe su ne ke da fifiko: `query`, `max_results`, `filters` (yankuna), `country` da
batun da aka samo daga `search_type`. A Exa, `search_type: "news"` yana riƙe `category: "news"`.
Tavily kuma yana karɓar `search_type: "finance"` (`topic: "finance"`).

Ana rubuta kuɗin binciken Firecrawl ga kowane tubali na sakamako 10 da aka fara dawowa, a $0.002 (ƙiredit 2)
ga kowane tubali, kuma aƙalla tubali guda ɗaya ga kowace kira
([Kudin Firecrawl](https://docs.firecrawl.dev/billing)): sakamako 11 yana kashe $0.004.

Filin gama-gari `time_range` yanzu yana isa ga masu samarwa duka: Exa yana samun `startPublishedDate` (tambarin lokaci na ISO)
kuma Tavily yana samun `start_date` (`YYYY-MM-DD`). Bayyanannen kwanan wata a cikin `provider_options`
yana rinjayar wanda aka tsara.

Sakamakon Exa yana riƙe `id`, `highlights` (dukkan abubuwan haskakawa, ba na farko kaɗai da aka yi amfani da shi a matsayin
`snippet` ba), `highlight_scores`, `summary`, `subpages`, `entities` da `extras` a cikin `provider_raw`. Sakamakon Tavily
yana riƙe `images` da `favicon`.

Ana rubuta kuɗin binciken Linkup a $0.005 ga `depth` `fast` da `standard`, sannan $0.05 ga
`deep` ([Farashin Linkup](https://docs.linkup.so/pages/documentation/development/pricing)),
ko da kuwa `depth` ya fito daga `provider_options` ko saitunan haɗin.

Exa `type: "lite"` (Exa 3.0) yana karɓar ƙaramin rukunin filaye kuma yana ƙin dukkan buƙatar
idan an saita wani filin daban. Ga lite, ana cire `additionalQueries`, `systemPrompt` da kowane maɓallin
`contents` ban da `text` da `highlights` kafin kira. Ba a ƙara tura tsofaffin
`subpages`, `subpageTarget`, `highlights.numSentences` da `highlights.highlightsPerUrl`.

Ana yin lissafin kuɗi ta amfani da rajistar lebur `costPerQuery`, sai dai Exa, wanda ke bin
farashin Exa na kansa: $0.007 kan kowane kira na `auto` (da `fast` na gado) ko $0.004 na
`lite` (da `instant` na gado), wanda ya ƙunshi sakamako 10; $0.001 kan kowane ƙarin
sakamako; da $0.001 kan kowane sakamakon da aka dawo da shi idan an saita
`contents.summary`. Ana rubuta Tavily da kiredit 1 ($0.008) don `search_depth` `basic`,
`fast` da `ultra-fast`, da kiredit 2 ($0.016) don `advanced`
([kiredit ɗin Tavily API](https://docs.tavily.com/documentation/api-credits)). Kira mai
`auto_parameters: true` wanda Tavily ya haɓaka zuwa advanced har yanzu ana rubuta shi da kiredit 1.

---

## API ɗin Web Fetch

Ciro abun ciki daga URL ta hanyar wani mai samar da web-fetch da aka tsara (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract).

Parallel Extract (`parallel-search`, yana amfani da API key iri ɗaya da Parallel Search) yana dawo da Markdown
kawai — duk wani `format` zai zama `400` — kuma yana iyakance abun ciki zuwa haruffa 100,000. Lokacin da ba za a iya ciro shafin da ake nema da kansa ba, upstream yana sanar da hakan a cikin HTTP 200;
OmniRoute yana bayyana hakan a matsayin `422` tare da saƙo tsayayye.

| Hanya | Hanya           | Bayani                                                                |
| ----- | --------------- | --------------------------------------------------------------------- |
| POST  | `/v1/web/fetch` | Ciro/scrape URL — jikin buƙatar ana inganta shi ta `v1WebFetchSchema` |

**Tabbatarwa:** Bearer API key (`extractApiKey` + `isValidApiKey`). Ana tilasta ƙa'ida ta hanyar `enforceApiKeyPolicy`.

**Madadin mai lura da quota (#8297):** idan ba a bayar da `provider` a sarari ba, ana zagayawa cikin pool
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search` →
`parallel-search`) cikin tsayayyen
tsarin fifiko (fill-first) — ana tsallake mai samarwa da aka saita amma aka iyakance masa yawan buƙatu
maimakon dakatar da buƙatar nan take, kuma gazawar upstream da za a iya sake gwadawa/ta quota
(HTTP 429 koyaushe; 402/403 ga Firecrawl/Tavily/TinyFish idan quota ta shafi matakan kyauta —
ba ga Jina Reader ba, kuma ba a taɓa amfani da wannan ga 400 na buƙatar da ba ta dace ba) tana wucewa zuwa
mai samarwa na gaba mai takardun shaida wanda ba a gwada ba a lokacin buƙatar. Idan kowane mai samarwa da ke cikin pool ya ƙare,
endpoint yana dawo da `429` guda ɗaya (tare da kanun `Retry-After`) maimakon `400` na gabaɗaya da ake samu a baya. Idan an buƙaci `provider` a sarari, **babu madadin ɓoye** — kuskure ko iyakancewar mai samarwa da aka zaɓa yana bayyana da kansa (`429` idan an iyakance shi, in ba haka ba matsayin upstream).

---

## Yawo ta WebSocket

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

Yana inganta handshake na WebSocket kuma yana dawo da saƙonnin misalin wire protocol (`request`, `cancel`). Uwar garken WS da aka haɗa ce ke sarrafa ainihin WS frames a wajen teburin hanyoyin Next.js.

**Tabbatarwa:** Bearer API key yayin handshake.

### Responses API ta WebSocket (codex kawai)

```bash
# Mai masauki:port iri ɗaya da HTTP API (tsoho 20128); haɓaka haɗin:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (ko: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Frame na farko DOLE ne ya zama response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```

An haɗa wakilin Responses-API-over-WebSocket **na musamman ga `codex`** (backend ɗin ChatGPT). Yana sauraro a tashar da API/dashboard ke amfani da ita a hanyoyin `/v1/responses`,
`/responses`, da `/api/v1/responses`. A farkon frame na `response.create`, yana tabbatarwa + shirya ta hanyar gadar cikin gida ta `codex-responses-ws`, ya zaɓi haɗin OAuth na codex, sannan ya ratsa zuwa `wss://chatgpt.com/backend-api/codex/responses`
ta hanyar jigilar `wreq-js`. Ana ƙin samfuran da ba na codex ba (`codex_ws_provider_required`).
Don amfani da rabon quota, yi amfani da `model: "qtSd/<group>/codex/<model>"`. An aiwatar da shi a
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.

**Tabbatarwa:** Bearer API key yayin handshake. Dole ne uwar garken HTTP da aka haɗa (`server-ws.mjs`)
ta zama entrypoint mai aiki (haka take ta tsohuwa idan `app/server-ws.mjs` yana akwai).

#### ID na model: yi amfani da ID ɗin ChatGPT kai tsaye (ba tare da prefix na `codex/` ba)

OpenAI **Codex CLI** yana inganta sunan model a gefen client idan
`supports_websockets = true` kuma yana ƙin ID masu prefix na provider
kamar `codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`). Aika ID ɗin kai tsaye (misali `gpt-5.5`). Gadar OmniRoute ta codex kawai ce, don haka tana sake warware ID kai tsaye a matsayin model na codex
(`resolveCodexWsModelInfo`) kafin ta ratsa upstream — duk da cewa `gpt-5.5` kai tsaye zai iya bi ta wani provider ta HTTP a wani yanayi.

#### Tsara OpenAI Codex CLI

Nuna Codex CLI zuwa OmniRoute ta ƙara wani mai samarwa na musamman mai goyon bayan WebSocket zuwa `~/.codex/config.toml` (yi amfani da `CODEX_HOME` na daban don guje wa taɓa wani config da ke akwai):

```toml
model = "gpt-5.5"                 # ID kai tsaye — BA "codex/gpt-5.5" BA
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # babu slash a ƙarshe; ana samo URL ɗin WS daga gare shi (yi amfani da https/wss a production)
wire_api = "responses"                    # ƙima kawai da ake tallafawa tun Fabrairu 2026
supports_websockets = true                # yana kunna jigilar Responses-over-WS
env_key = "OMNIROUTE_API_KEY"             # yana riƙe API key na OmniRoute (Bearer)
```

```bash
export OMNIROUTE_API_KEY=sk-...           # API key na OmniRoute (kowace key idan REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```

CLI yana haɓaka `base_url + /responses` zuwa WebSocket, kuma OmniRoute tana ratsa shi zuwa zaɓaɓɓen haɗin OAuth na codex. An tabbatar da shi daga farko har ƙarshe a kan uwar garken gida: ChatGPT yana dawo da `codex.rate_limits` + `response.created` kuma yana yawo da amsar.

---

## Rahoton Ƙayyadaddun Amfani da Matsaloli

| Hanya | Hanya               | Bayani                                                                                               |
| ----- | ------------------- | ---------------------------------------------------------------------------------------------------- |
| GET   | `/v1/quotas/check`  | Tabbatar da quota tun farko don `provider` + `accountId` kafin bayar da maɓallin da aka yi rajista   |
| POST  | `/v1/issues/report` | Ba da rahoton gazawar bayar da quota/maɓalli zuwa GitHub (yana buƙatar `GITHUB_ISSUES_REPO` + token) |

**Tabbatarwa:** Maɓallin API na Bearer (`isAuthenticated`).

### Maido da zaman quota (na zaɓi)

`POST /v1/chat/completions` ko `POST /v1/responses` wanda ba na streaming ba, idan ya gaza da
kuskuren quota na ƙarshe (`402`/`429`/`503` wanda jikin amsar ya ce quota ko credits sun ƙare),
ana iya ajiye shi a sake kunna shi daga baya maimakon mayar da kuskuren. Mai kira yana zaɓar wannan
a kowane request ta amfani da headers guda uku:

| Header                       | Ƙima                                                     |
| ---------------------------- | -------------------------------------------------------- |
| `x-omniroute-quota-recovery` | `auto`                                                   |
| `x-omniroute-session`        | ID na zaman, `[A-Za-z0-9._:-]{1,128}`                    |
| `x-omniroute-recovery-turn`  | ID na juyawa na musamman a cikin zaman (ƙa'ida iri ɗaya) |

Juyawar da ke da `stream: false` kawai, waɗanda ba su da tools, tarihin tool ko
`previous_response_id`, kuma ba su da pin na `x-omniroute-connection`, ne suka cancanta; dole ne a saita
`STORAGE_ENCRYPTION_KEY` (ana adana request ɗin cikin ɓoyayyen tsari na har zuwa awanni 24). Daga nan amsar
ta zama `202` mai ɗauke da `recovery.poll`; a yi polling da `GET /v1/quota-recoveries/{id}` (`202` yayin da ake jira,
`200` tare da jikin amsar da aka dawo da ita idan an kammala) ko a soke ta da `DELETE`. Tikiti ana iya ganin su ne kawai
ga maɓallin API da ya ƙirƙire su. Sake kunna request ɗin da ba a tabbatar da sakamakonsa ba yana ƙarewa da
`needs_confirmation` maimakon a aika shi sau biyu. Madogara: `src/lib/quota/quotaSessionRecovery.ts`.

---

## Amfani da sabis na kai (`/api/usage/om-usage`)

Kowane maɓalli API na iya karantawa** nata** amfani da ƙayyadaddun ƙididdiga — ba auth gudanarwa. Wannan shine ƙarshen ƙarshen abokin ciniki (CLI, kwamitin OmniCopilot ) yana amfani da shi don nuna mai maɓalli na abin da suke kashewa.

```bash
# Text form (the historical contract — plain text for a terminal)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Structured form — what a UI consumes
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"
```

Dole ne maɓalli ya kasance**`allowUsageCommand`** an kunna (kashe ta hanyar tsoho — mai sarrafa maɓallin API na dashboard yana jujjuya shi kowane maɓalli). Ba tare da shi ƙarshen yana amsa `403`.

`?format=json` yana dawo da sifar wariya don haka mai kira bai taɓa karanta filin bayanai ba daga ƙi. Kan nasara:

```jsonc
{
  "allowed": true,
  // present only when the key opted into per-key usage limits (daily/weekly/5-hour USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // the selected provider quota snapshot, or null when nothing is cached yet:
  "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */} },
  // every connection's snapshot, so a UI can render several providers side by side:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}
```

A kan ƙi (`401` bad maɓalli / `403` ba a yarda ba) hanya ɗaya ta dawo `{ "allowed": false, "error": { "message": "…" } }` — a halin yanzu amma mara komai `personal`/`provider` (maɓallin da aka yarda, babu abin da aka koya tukuna) yanayi ne daban da ƙi, kuma kawai nau'in JSON ne ke bambanta su.

**Gaskiya:** Maɓallin API ɗin mai kiran kansa, wanda aka inganta tare da `isValidApiKey` — wannan _ba_ filin gudanarwa ba ne (`/api/keys/…`), wanda ya tsaya a bayan `requireManagementAuth`.

### Raw vs. Cutoff-Madaidaitan Ƙimar Ƙimar Ƙimar

Lokacin cin `/api/usage/om-usage`, masu kira ya kamata su lura da bambanci tsakanin kaso da aka gabatar ta hanyar** fitowar rubutu a sarari** da kuma tsari**JSON fitarwa** :

| Al'amari              | Tsarin rubutu na fili (`/api/usage/om-usage` / `@@om-usage`)                                                  | tsarin JSON (`?format=json`)                                                                    |
| :-------------------- | :------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------- |
| **Filin fitarwa**     | `NN% left` (misali, `20% left`)                                                                               | `provider.quotas` / `providers[].quotas`                                                        |
| **Aunawa**            | **Cutoff-daidaitacce izini mai amfani** : ragowar ƙarfin sama da matakin yanke                                | **Ƙidaya mai raɗaɗi** : rashin daidaita ma'aunin mai bayarwa                                    |
| **Yanke sikelin**     | An ƙididdige ta hanyar `effectiveRemainingPercent()` don haka ajiyar da aka kiyaye ya karanta kamar `0% left` | Babu ko ɗaya (darajar hotunan hoto kamar yadda mai bayarwa ya ruwaito)                          |
| **Bayanan iyaka**     | Haɗa cikin adadin da aka nuna                                                                                 | An adana shi a cikin `quotaWindowThresholds` kowace haɗin haɗin gwiwa (ko tsohowar uwar garken) |
| **Mabukaci na farko** | CLIs mai mu'amala, tsokanar tasha, ma'aikatan ɗan adam                                                        | Haɗin kai na shirye-shirye, dashboards, nazari, masu biyan kuɗi                                 |

#### The Cutoff Daidaita Formula

OmniRoute tana goyan bayan ɓangarorin ƙididdiga masu aiki don hana gajiyawar sama (wanda aka saita ta hanyar haɗin `quotaWindowThresholds`, gazawar mai bada sabis, ko saitunan juriya na duniya). Lokacin da ƙofa mai yankewa (misali, `cutoff = 25%`) ke aiki akan taga keɓaɓɓu, mai yin rubutu yana ƙididdige ragowar alawus kamar:

- Idan `remaining <= cutoff`: ya dawo `0%`.
- Idan `remaining > cutoff`: ya dawo `((remaining - cutoff) / (100 - cutoff)) * 100`.

Fitowar rubutun da aka tsara yana zagaye wannan zuwa lamba mafi kusa (`Math.round(...)`).

#### Misalin Misali

Yi la'akari da taga mai bayarwa tare da** 60% rashin amfani** (don haka** 40% danye ragowar adadin** ) da kuma daidaitacce** 25% rage yawan kaso** bakin kofa:

| Wakilci                        | Lissafi                                            | Ya rage |                An Nuna Amfani                 |
| :----------------------------- | :------------------------------------------------- | :-----: | :-------------------------------------------: |
| **Raw JSON (`?format=json`)**  | Hoto na sama (`quotas[window]`)                    | **40%** |                    **60%**                    |
| **Tsarin rubutu (`NN% left`)** | `((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100` | **20%** | **80%** (idan ana lissafin `100 - remaining`) |

- **Me yasa rubutu ya nuna 20% hagu:** Daga cikin adadin kashi 40% na zahiri da aka bari akan asusun, 25% an tanadar ta hanyar manufar yankewa. Mai kiran yana da kashi 15% kawai cikin kashi 75 cikin 100 na ɗakin da ake amfani da shi kafin na'ura mai ba da hanya tsakanin hanyoyin sadarwa ta daina turawa zuwa wannan haɗin. Scaling yana tabbatar da ƙarewar siginar haɗin (`0% left`) daidai lokacin da za a daina tuƙi.
- **Me yasa JSON ke adana danye dabi'u:** Zazzagewar kuɗin JSON yana dawo da ainihin hoton mai bada (`UsageSnapshot`) don haka kayan aikin waje suna samun damar yin amfani da ƙasa-gaskiya na sama da `quotaWindowThresholds` -matakin haɗin kai ba tare da hasarar ɓarna ta gefen uwar garken ba.

#### Jagoran Hijira na Mabukaci

Idan haɗin waje (kamar plugin ɗin edita ko ƙarin wakili) a baya ya goge ƙarshen ƙarshen rubutu (`NN% left`) kuma an ƙididdige adadin da aka yi amfani da shi azaman `100 - NN`, ƙaura zuwa `?format=json` yana nufin:

- Karatun danyen darajar JSON za su yi tunani** ainihin amfani na sama** (60% ana amfani dashi a cikin misalin da ke sama).
- Idan haɗin kai yana son adana tarukan ba da izini mai amfani na ƙarshen rubutu, zai iya kimanta tasirin sauran dabarar-gefen abokin ciniki ta amfani da `quotaWindowThresholds` don tsallake matakin haɗin gwiwa.

---

## Ma'ajiyar Semantic

```bash
# Samo ƙididdigar ma'ajiya
GET /api/cache/stats

# Share dukkan ma'ajiyoyi
DELETE /api/cache/stats
```

Misalin amsa:

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

### Tasirin jinkiri

Semantic cache HIT yana bayar da amsar daga ma'ajiya **ba tare da kiran upstream
ba**, saboda haka `X-OmniRoute-Response-Latency` da aka bayar yana kusa da sifili
(ba tare da la'akari da ainihin jinkirin upstream ba). Abokan ciniki masu kula da
jinkiri (ma'aunin gwaji, sa ido kan p50/p99) ya kamata su duba taken amsar
`X-OmniRoute-Cache-Latency`:

| Value       | Ma'ana                                                                     |
| ----------- | -------------------------------------------------------------------------- |
| `synthetic` | An bayar da amsa daga ma'ajiya; jinkirin ba ainihin lokacin upstream ba ne |
| _(absent)_  | Amsa daga ainihin kiran upstream                                           |

### Ketare ma'ajiya ga kowane maɓalli

Maɓallan API na iya zaɓar fita daga karatun semantic cache ta hanyar `cacheDefaultMode`:

| Value    | Hali                                                         |
| -------- | ------------------------------------------------------------ |
| `legacy` | Halin ma'ajiya na yau da kullum (tsoho)                      |
| `bypass` | Tsallake binciken ma'ajiya gaba ɗaya; kullum a buga upstream |

Saita yayin ƙirƙirar maɓalli (`POST /api/keys`) ko sabuntawa (`PATCH /api/keys/[id]`):

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

### Ketare ma'ajiya ga kowace bukata

Duk wata bukata na iya ketare ma'ajiya ba tare da la'akari da saitunan maɓalli ba:

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

---

## Dacewar Gudanarwa da CLIProxyAPI

OmniRoute yana amsa ƙarshen hanyoyin gudanarwa guda uku na [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)
waɗanda dashboards na amfani ke kira don karanta iyakokin rajistar Claude da Codex
(misali tushen iyakar amfani na `cliproxy` na T3 Code). Nuna base URL na abokin ciniki zuwa
OmniRoute kuma yi amfani da maɓallin API mai ikon `manage` a matsayin maɓallin gudanarwarsa. Hanyoyin suna
a `/v0/management/*` da kuma `/api/v0/management/*`.

| Method | Path                         | Description                                                                                                                                                  |
| ------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/v0/management/auth-files`  | Haɗin OAuth na Claude da Codex a matsayin `{ files: [{ id, auth_index, provider, email, disabled, id_token }] }`. Babu alamun shiga                          |
| POST   | `/v0/management/api-call`    | Jiki `{ auth_index, method, url, header?, data? }`. Yana aika bukata guda da aka amince da ita tare da alamar asusun kuma ya dawo da `{ status_code, body }` |
| POST   | `/v0/management/reset-quota` | Jiki `{ auth_index }`. Yana share lokacin dakatarwar haɗi, kulle-kullen samfuri da lokutan dakatarwa na Codex na kowane iyaka na asusu guda                  |

- `auth_index` shi ne ID ɗin haɗin OmniRoute. `provider` shi ne `claude` ko `codex` (haɗin
  OAuth kawai; ba a jera mai samar da maɓallin API na `anthropic` ba). Ga Codex,
  `id_token.chatgpt_account_id` shi ne ID ɗin workspace da aka adana, sannan `plan_type` shi ne tsarin da aka adana.
- `api-call` ba wakili na gama-gari ba ne. Yana karɓar Claude `GET
https://api.anthropic.com/api/oauth/usage` kawai da Codex `GET
https://chatgpt.com/backend-api/wham/usage`, `GET .../wham/rate-limit-reset-credits` da
  `POST .../wham/rate-limit-reset-credits/consume` kawai, kuma kowanne sai don asusun mai samarwa da ya dace.
  Duk wani abu dabam yana dawo da `403` ba tare da tuntuɓar upstream ba. Ana yin watsi da taken
  `Authorization` na mai kira (har da madadin `$TOKEN$`): OmniRoute yana saka access token na haɗin,
  yana sabunta shi da farko idan yana kusa da ƙarewa, sannan yana tura taken da aka amince da su kawai
  (`anthropic-beta`; `OpenAI-Beta`, `Originator`, `Chatgpt-Account-Id`;
  `Accept`, `Content-Type`). Idan `Chatgpt-Account-Id` ya ɓace, ana amfani da ID ɗin workspace da aka adana.
  Bukatu suna ƙarewa bayan daƙiƙa 15 kuma suna amfani da wakilin haɗin.
- `reset-quota` yana barin yanayi na ƙarshe (`banned`, `expired`, `credits_exhausted`) yadda suke. Idan
  `auth_index` ba a sani ba ne, ana dawo da `404`.

**Tabbatarwa:** Zaman dashboard ko maɓallin API mai ikon `manage`, wanda ake buƙata ko da an kashe
shiga (hanyoyin suna cikin `ALWAYS_PROTECTED_API_PATHS`). Maɓallan da ke da ikon inference kawai suna samun `403`. Madogara:
`src/lib/cliproxyCompat/managementApi.ts`.

---

## Dashboard & Gudanarwa

Hanyoyin gudanarwa (`/api/*` banda jama'a auth/login) su ne** ba** izini ta hanyar maɓallan ƙima na yau da kullun API. Iyalai na shaida, iyakoki, da misalan misalan: [Tabbatar da Gudanarwa](../guides/MANAGEMENT-AUTH.md).

### Tabbatarwa

| Ƙarshen Ƙarshe                | Hanya    | Bayani                                                                                                                                                                                                                                                                                                   |
| ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/auth/login`             | POST     | Shiga                                                                                                                                                                                                                                                                                                    |
| `/api/auth/logout`            | POST     | Fita                                                                                                                                                                                                                                                                                                     |
| `/api/settings/require-login` | GET/POST | Matsayin shiga (GET, jama'a). POST yana saita kalmar sirri / toggles login: afareta- sau ɗaya kawai kalmar sirri ta wanzu (zaman dashboard, CLI na gida, ko shiga an kashe maɓallan — API kuma alamun `oma_` suna samun `403`); zaman dashboard yana aika `currentPassword` don maye gurbin kalmar sirri |

### Gudanar da Mai bayarwa

| Ƙarshen Ƙarshe                          | Hanya                     | Bayani                                                                                                                                                 |
| --------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/providers`                        | GET/POST                  | Jerin / ƙirƙirar masu samarwa                                                                                                                          |
| `/api/providers/[id]`                   | GET/PUT/DELETE            | Sarrafa mai bayarwa                                                                                                                                    |
| `/api/providers/[id]/test`              | POST                      | Gwajin haɗin mai bada sabis                                                                                                                            |
| `/api/providers/[id]/models`            | GET                       | Samfuran masu ba da lissafi                                                                                                                            |
| `/api/providers/validate`               | POST                      | Tabbatar da saitin mai bada sabis                                                                                                                      |
| `/api/providers/bulk`                   | POST                      | Babban-ƙara maɓallan API don mai bada ONE                                                                                                              |
| `/api/providers/import`                 | POST                      | Shigo da mai bada LIST iri-iri daga fayil ɗin CSV/JSON (#6836); Sakamakon rashin gazawar kowane jere                                                   |
| `/api/provider-nodes*`                  | Daban-daban               | Gudanar da kumburin mai bayarwa                                                                                                                        |
| `/api/provider-models`                  | GET/POST/PUT/PATCH/DELETE | Samfuran al'ada da soke-soken kowane samfuri (ƙara, sabuntawa, hide/show, share)                                                                       |
| `/api/provider-models/validate-and-add` | POST                      | Gudanarwa-tabbataccen, ficewa cikin ingantaccen haɗin kai da rajista na al'ada ta atomatik; duba [ingantaccen samfurin](../guides/MODEL-VALIDATION.md) |

Don ƙirar synced/imported, `PUT /api/provider-models` yana karɓar `provider`, `modelId`, da `maxOutputTokenOverride`: integer tabbatacce yana saita hular fitarwa ta hannu, kuma `null` yana share ta don dawo da tsoho. `GET /api/provider-models?provider=<provider>` yana dawo da waɗannan ƙimar a cikin `modelOutputOverrides`, gami da ƙira ba tare da jeri na al'ada ba. Ƙarfafawa yana amfani da damar `max_output_tokens` na lokacin gudu kuma ya tsira daga sake daidaitawa samfurin. Shafin mai dacewa na OpenAI yana ba da sarrafawar edit/clear iri ɗaya da alamar samfuri tare da bayyanannen tallafin hangen nesa.

A kan kullin mai ba da aiki mai jituwa, hanyoyin rubuta (`POST`, `PUT`, `PATCH`, `DELETE` da `/api/provider-models/validate-and-add`) suna adana ƙirar ƙira a matsayin id na sama mara kyau: id ɗin da aka liƙa daga jeri da aka riga aka yi yana da duk wani babban jigon jigon kumburin kansa ya ruguje, kuma amsoshi suna maimaita id ɗin da aka adana. Ana adana ids ɗin masu ba da izini (misali `nvidia/nemotron-…`) a zahiri. `/v1/models` baya fitar da madaidaicin `<prefix>/<prefix>/<model>` id.

Ƙididdigar Ƙirar Ƙirar Taɗi ta al'ada suna daidaita fitattun dalilai ficewa daga baya zuwa sama. Gwajin haɗin gwiwa mai nasara yana zaɓar sarrafawa ta atomatik-samfurin taɗi don kowane ainihin samfurin ID wanda shigarwar `/models` ya tabbatar da ƙimar `owned_by` : `vllm`, `sglang`, ko `llamacpp`. Fassarar buɗe AI mai jituwa masu dacewa na iya adana ainihin shigarwar samfurin cikin wani abu `openai` gida; ganowa ya biyo baya har zuwa irin waɗannan ambulaf guda uku. Samfuran da suka ɓace, waɗanda ba a sani ba, ko masu cin karo da juna suna kiyaye halayen OpenAI na yau da kullun. Gano yana sake yin amfani da buƙatun katalogin da ke akwai, baya haifar da alamun kammalawa, kuma ba shi da inganci lokacin da ƙarshen haɗin haɗin ya canza.

Don daidaita ɗabi'a don abin baya wanda baya fallasa waɗannan metadata, yi amfani da sabunta sashin mai ba da sabis API:

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

Aika wannan jikin da `PUT /api/providers/<connection-id>`. A kan wannan haɗin, ana aika ƙoƙarin dalili na `none` a matsayin `chat_template_kwargs.thinking=false` da `chat_template_kwargs.enable_thinking=false`. Bayyanan dabi'un samfuri na asali sun kasance masu iko sai dai idan tsarin tunani na gefen uwar garke ya tilasta ƙoƙari. Saitin yana aiki ne kawai lokacin da haɗin budewa na al'ada mai dacewa da OpenAI ya aika jikin Kammala Taɗi; Buƙatun amsoshi da masu samarwa talakawa suna kiyaye sifar buƙatun su na asali. Saita `reasoningControl` zuwa `openai` don tilastawa talakawa wucewar OpenAI `reasoning_effort`, ko bar it/set zuwa `null` don amfani da ganowa ta atomatik.

Claude Code classifier yanayin atomatik yana buƙatar tsoho tunani na asali don kashewa lokacin da basu ƙunshi takamaiman sarrafa hankali ba. Ganewa yana amfani da alamar tsarin ƙira a cikin buƙatun tsarin Claude, ba sunaye na ƙira ba ko iyakar ƙarewa. Filayen sarrafa jiki, masu goyan baya effort/thinking, ƙa'idodin kewayawa, da yunƙurin ƙirar ƙira suna kiyaye fifikonsu na yanzu. Duk matakan rarrabuwa biyu suna riƙe da faɗakarwa, iyakokin ƙarewa, jerin dakatarwa, da hukunce-hukuncen izini na ainihi; mataki na biyu har yanzu yana iya samar da hujjar da ake nema a matsayin rubutu na yau da kullun.

### OAuth yawo

| Ƙarshen Ƙarshe                   | Hanya       | Bayani           |
| -------------------------------- | ----------- | ---------------- |
| `/api/oauth/[provider]/[action]` | Daban-daban | takamaiman OAuth |

### Gudanarwa & Gyara

| Ƙarshen Ƙarshe        | Hanya       | Bayani                           |
| --------------------- | ----------- | -------------------------------- |
| `/api/models`         | GET/PUT     | Lissafin samfuri / sabuntawa     |
| `/api/models/alias`   | GET/POST    | Laƙabin ƙira                     |
| `/api/models/catalog` | GET         | Duk samfura ta mai bada nau'in + |
| `/api/combos*`        | Daban-daban | Gudanar da haɗakarwa             |
| `/api/keys*`          | Daban-daban | API key management               |
| `/api/pricing`        | GET         | Farashin samfurin                |

#### Model iyaka tabbatarwa

`GET /api/models?withLimits=1` (kuma `true`; `0`/`false` ko tsallake shi yana kiyaye tsohowar kayan aiki baya canzawa) yana ƙara `contextWindow`, `maxInputTokens`, `maxOutputTokens` da `capsSource` abu zuwa kowane jeri na ƙira. `capsSource` suna suna dokar da ta ba da kowane iyaka, don haka iyakar abin mamaki (misali 128k akan ƙirar 1M) ana iya gano asalinsa. Ƙimar da aka warware su iri ɗaya ne da ake amfani dasu; Tutar tana ƙara filayen kawai kuma baya canza ƙima. Ana ƙi duk wani darajar `withLimits` tare da `400`.

| darajar `capsSource`                         | Asalin                                                                  |
| -------------------------------------------- | ----------------------------------------------------------------------- |
| `override:context`                           | Dagewar mahallin-taga ta soke (`model_context_overrides`)               |
| `override:max_input` / `override:max_output` | Ƙarfin ƙarfin `max_input_tokens` / `max_output_tokens` ya ƙetare        |
| `static-authoritative:<provider>/<model>`    | A tsaye mai iko mahallin-taga tebur                                     |
| `synced:<provider>/<model>`                  | model.dev synced iya aiki jere                                          |
| `registry:<provider>/<model>`                | Shigar mai bayarwa                                                      |
| `spec:<model>`                               | Static model spec                                                       |
| `effort-base:` prefix                        | Layi da aka aro daga ƙirar tushe na bambance-bambancen maƙasudin ƙoƙari |
| `none`                                       | Babu wata hanyar da ta bayyana iyaka (darajar `null`)                   |

Aiwatar da: `getResolvedModelCapabilitiesWithLimitSources()` a cikin `src/lib/modelCapabilities.ts` da fifikon sarƙoƙi a cikin `src/lib/modelCapabilityLimits.ts`.

### Amfani & Bincike

| Ƙarshen Ƙarshe                   | Hanya           | Bayani                                                                                                                                                                                                                                                                                                     |
| -------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history`             | GET             | Tarihin amfani                                                                                                                                                                                                                                                                                             |
| `/api/usage/logs`                | GET             | Lokutan amfani                                                                                                                                                                                                                                                                                             |
| `/api/usage/request-logs`        | GET             | Rajistar matakin buƙatu                                                                                                                                                                                                                                                                                    |
| `/api/usage/[connectionId]`      | GET             | Amfani da haɗin kai                                                                                                                                                                                                                                                                                        |
| `/api/usage/token-limits`        | GET/POST/DELETE | Kudiddigar maɓalli na-Pi-key-iyakance                                                                                                                                                                                                                                                                      |
| `/api/usage/model-latency-stats` | GET             | Rolling per-provider/model tara latency (avg/p50/p95/p99, ƙimar nasara); tacewa: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873)                                                                                                                                                           |
| `/api/usage/cache-health`        | GET             | Takaitaccen bayanin lafiya na cache akan rabon `call_logs` — write/read, rarraba girman p50/p90/p99, babban rubutu mai nauyi, rarrabuwar kowane samfuri, da hukunci `healthy`/`degraded`/`thrash`/`no-data` ; tambaya params `range` (`1h`\| `24h`\| `7d`\| `30d`, tsoho `24h`) da `model` na zaɓi (#8827) |

### iznin makullin API

`PATCH /api/keys/{id}` tana sabunta izini na maɓallin da ke akwai. Kamar kowace hanyar `/api/keys*` tana buƙatar izinin gudanarwa (duba [Tabbatar da Gudanarwa](../guides/MANAGEMENT-AUTH.md) ), ba maɓalli ba. Aika kawai filayen da kake son canzawa; buqata tare da ɗayansu ba a ƙi su tare da `No valid fields to update`. An bayyana filayen da aka karɓa ta `updateKeyPermissionsSchema` a cikin `src/shared/validation/schemas/keys.ts`.

| Filin                                       | Nau'in                                                                     | Bayanan kula                                                                                                                                                                                                                                                                                            |
| ------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                                      | kirtani, 1-200 chars                                                       |                                                                                                                                                                                                                                                                                                         |
| `isActive`                                  | boolean                                                                    |                                                                                                                                                                                                                                                                                                         |
| `isBanned`                                  | boolean                                                                    |                                                                                                                                                                                                                                                                                                         |
| `expiresAt`                                 | ISO 8601 kwanan wata ko `null`                                             | `null` share fage                                                                                                                                                                                                                                                                                       |
| `modelAccessMode`                           | `all` \| `restricted`                                                      | `allowedModels` dole ne ya zama fanko lokacin da yanayin ya kasance `all`                                                                                                                                                                                                                               |
| `allowedModels`, `blockedModels`            | tsararrun igiyoyi, har zuwa 1000                                           |                                                                                                                                                                                                                                                                                                         |
| `allowedCombos`                             | tsararrun igiyoyi, har zuwa 500                                            | Ƙofofin da ke haɗa maɓalli na iya kira; samfuran kai tsaye ana sarrafa su ta `modelAccessMode` / `allowedModels`                                                                                                                                                                                        |
| `connectionAccessMode`                      | `all` \| `restricted`                                                      | `allowedConnections` dole ne ya zama mara komai lokacin `restricted` kuma babu komai lokacin `all`                                                                                                                                                                                                      |
| `allowedConnections`                        | tsararru na UUIDs, har zuwa 100                                            |                                                                                                                                                                                                                                                                                                         |
| `allowAutoCombos`                           | boolean                                                                    | `false` ya ƙi buƙatun samfuran `auto/*` tare da wannan maɓalli; maɓallan da ba su taɓa saita shi ba an yarda                                                                                                                                                                                            |
| `catalogScope`                              | `all` \| `combos` \| `models`                                              | Abin da `GET /v1/models` ya lissafa na wannan maɓalli (combos kawai, samfuri kawai, ko duka biyu); ba ya canza abin da maɓalli zai iya kira                                                                                                                                                             |
| `forcedModel`                               | kirtani har zuwa 300 chars, ko `null`                                      | Hanyoyin tattaunawa da buƙatun zuwa wannan model/combo, akan `X-Route-Model` da `body.model`; iyakokin maɓalli har yanzu suna aiki                                                                                                                                                                      |
| `noLog`, `autoResolve`                      | boolean                                                                    |                                                                                                                                                                                                                                                                                                         |
| `throttleDelayMs`                           | lamba, 0-300000                                                            |                                                                                                                                                                                                                                                                                                         |
| `maxSessions`                               | lamba, 0-10000                                                             |                                                                                                                                                                                                                                                                                                         |
| `rateLimits`                                | tsararrun `{ limit, window }` (tabbatattun lambobi, har zuwa 50) ko `null` | `null` tana share iyaka                                                                                                                                                                                                                                                                                 |
| `accessSchedule`                            | tsara abu ko `null`                                                        | `null` share jadawali                                                                                                                                                                                                                                                                                   |
| `scopes`                                    | tsararrun igiyoyi, har zuwa 32                                             |                                                                                                                                                                                                                                                                                                         |
| `allowedEndpoints`                          | tsararrun igiyoyi, har zuwa 20                                             |                                                                                                                                                                                                                                                                                                         |
| `streamDefaultMode`                         | `legacy` \| `json`                                                         |                                                                                                                                                                                                                                                                                                         |
| `cacheDefaultMode`                          | `legacy` \| `bypass`                                                       | Dubi [hanyar maɓalli na Per-key](#per-key-cache-bypass)                                                                                                                                                                                                                                                 |
| `compressionEnabled`                        | boolean                                                                    |                                                                                                                                                                                                                                                                                                         |
| `codexServiceMode`                          | ɗaya daga cikin hanyoyin sabis na Codex                                    |                                                                                                                                                                                                                                                                                                         |
| `disableNonPublicModels`                    | boolean                                                                    |                                                                                                                                                                                                                                                                                                         |
| `allowUsageCommand`                         | boolean                                                                    |                                                                                                                                                                                                                                                                                                         |
| `usageLimitEnabled`                         | boolean                                                                    |                                                                                                                                                                                                                                                                                                         |
| `dailyUsageLimitUsd`, `weeklyUsageLimitUsd` | lamba >= 0 ko `null`                                                       |                                                                                                                                                                                                                                                                                                         |
| `fiveHourUsageLimitUsd`                     | lamba >= 0 ko `null`                                                       | Mirgine kasafin USD na awa 5, ana aiwatar da shi kamar iyakokin yau da kullun da na mako-mako (`usageLimitEnabled`, `UNPRICED_USAGE_BUDGET_POLICY`). `retry-after` shine lokacin da mafi tsufan kashewa a cikin taga ya ƙare, wanda zai iya barin maɓalli mai nisa akan iyakar sa har yanzu yana toshe. |
| `chaosModeEnabled`                          | boolean                                                                    |                                                                                                                                                                                                                                                                                                         |

```bash
curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \
  -H "Authorization: Bearer <management-credential>" \
  -H "Content-Type: application/json" \
  -d '{ "allowAutoCombos": false, "catalogScope": "combos" }'
```

### Saituna

| Ƙarshen Ƙarshe                        | Hanya         | Bayani                                                                                                                                                                                                                                                                                 |
| ------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings`                       | GET/PUT/PATCH | Gabaɗaya saituna. Maɓallan tsare-tsaren tsaro (`requireLogin`, `newPassword`, `oidc*`, `corsOrigins`, `bruteForceProtection`) suna buƙatar `currentPassword` da maɓallan ma'aikacin — API da alamun `oma_` suna samun `403`; kowane maye gurbi yana buƙatar iyakar ikon isa ga `admin` |
| `/api/settings/proxy`                 | GET/PUT       | Saitin wakili na hanyar sadarwa                                                                                                                                                                                                                                                        |
| `/api/settings/proxy/test`            | POST          | Gwada haɗin wakili                                                                                                                                                                                                                                                                     |
| `/api/settings/ip-filter`             | GET/PUT       | IP allowlist/blocklist                                                                                                                                                                                                                                                                 |
| `/api/settings/thinking-budget`       | GET/PUT       | Thinking/reasoning** nema** Yanayin sake rubutawa (wucewa / auto-strip / custom / adaptive). Mai zaman kansa na matsawa. Duba [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md).                                                                                                      |
| `/api/settings/system-prompt`         | GET/PUT       | Tsarin tsarin duniya                                                                                                                                                                                                                                                                   |
| `/api/settings/compression`           | GET/PUT       | Tsarin matsi na duniya                                                                                                                                                                                                                                                                 |
| `/api/settings/purge-request-history` | POST          | Share layukan rajistar buƙatun da kayan tarihin kira na gida                                                                                                                                                                                                                           |

### Magana & Matsawa

| Ƙarshen Ƙarshe                         | Hanya          | Bayani                                                                           |
| -------------------------------------- | -------------- | -------------------------------------------------------------------------------- |
| `/api/compression/preview`             | POST           | Duban matsawar off/lite/standard/aggressive/ultra/RTK/stacked                    |
| `/api/compression/language-packs`      | GET            | Jerin akwai fakitin yaren Caveman                                                |
| `/api/compression/rules`               | GET            | Lissafin metadata na dokar Caveman                                               |
| `/api/context/caveman/config`          | GET/PUT        | Saitunan ƙayyadaddun ƙayyadaddun laƙabi                                          |
| `/api/context/rtk/config`              | GET/PUT        | Saitunan takamaiman RTK, gami da masu tacewa na al'ada da riƙe da ɗanyen fitarwa |
| `/api/context/rtk/filters`             | GET            | RTK tace katalogi da na'urar tantancewa ta al'ada                                |
| `/api/context/rtk/test`                | POST           | Gudu RTK preview/test akan nauyin rubutu                                         |
| `/api/context/rtk/raw-output/[id]`     | GET            | Karanta abin da aka ci gaba da sake gyarawa ta hanyar mai nuna alama             |
| `/api/context/combos`                  | GET/POST       | Compression combo list/create                                                    |
| `/api/context/combos/[id]`             | GET/PUT/DELETE | Compression combo detail/update/delete                                           |
| `/api/context/combos/[id]/assignments` | GET/PUT        | Sanya combos masu matsawa zuwa haɗakarwa                                         |
| `/api/context/analytics`               | GET            | Matsa lamba analytics                                                            |

### Saka idanu

| Ƙarshen Ƙarshe                       | Hanya      | Bayani                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions`                      | GET        | Bin sawun zaman aiki                                                                                                                                                                                                                                                                                                                                                                                           |
| `/api/rate-limits`                   | GET        | Iyakance ƙimar kowane-asusu                                                                                                                                                                                                                                                                                                                                                                                    |
| `/api/monitoring/health`             | GET        | Takaitaccen bayanin mai bada lafiyar + (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Duban gudanarwa ya haɗa da `credentialHealth`: binciken cache scalars, `failedConnections` lokacin da `failed>0`, da `staleDbNonOkCount` (SQLite sticky `test_status`, ba ma'auni ba). Duba [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). |
| `/api/cache/stats`                   | GET/DELETE | Cache stats / share                                                                                                                                                                                                                                                                                                                                                                                            |
| `/api/modality-bridge/stats`         | GET        | In-memory `attempts`, nasarori/`bridged`, kasawa, cache hits, `totalLatencyMs`, `latencySamples`, samfurin-denominated `averageLatencyMs`, da na ƙarshe-amfani lokaci (sake saitin a sake kunnawa; Gudanarwa auth)                                                                                                                                                                                             |
| `/api/modality-bridge/video/runtime` | GET        | Tsananin amintacce-loopback duba kafin gudanarwa auth/probe; samuwan FFmpeg/ffprobe mai tsafta da sigogin (babu kantin sayar da kaya)                                                                                                                                                                                                                                                                          |
| `/api/modality-bridge/video/extract` | POST       | Dillali mai amintaccen madauki na ciki; shigarwar MiB 50, fitarwar MiB queue/32 iyaka, ƙarfin `503`, cire haɗin `499`, ranar ƙarshe `504` ; ba jama'a upload API                                                                                                                                                                                                                                               |

### Bidiyon firam ɗin rawar jiki

`GET /api/v1/video-bridge/drilldown` ta karanta madaidaicin hannun mai ɗaure da aka dawo cikin `x-omniroute-video-drilldown` bayan buƙatar gadar Bidiyo a sarari. Duk karantawa da `DELETE` koyaushe suna buƙatar ingantaccen maɓallin API da izinin `modalityBridgeVideoDrilldownRemoteEnabled` mai zaman kansa na mai aiki. Riƙewar samarwa yana buƙatar `modalityBridgeVideoDrilldownEnabled` da tsauraran kowane sashi `drilldown: true`. Idan maɓalli yana da jerin izinin ƙare mara komai, dole ne ya haɗa da `video` na duka GET da DELETE, ko mai kiran yana amfani da `/v1` ko `/api/v1`.

tambaya GET : buqatar `handle`; `variant` na zaɓi (`preview`, `standard`, `detail`), `limit` (1-8; gadon `frames` ana karɓa amma ba za a iya haɗa shi da `limit` ba), tushen `page`, da daƙiƙan `start`/`end`. Lokacin da aka kawo iyakokin mayar da hankali biyu, `end` dole ne ya fi `start` girma. An ƙi maɓallan tambaya Duplicate/unknown. Amsoshin da suka yi nasara sun ƙunshi `derivation`, `durationSeconds`, `frames`, `hasMore`, `page`, `variant`, da `focusWindow` na zaɓi ; babu kantin sayar JSON an rufe shi a 32 MiB gami da Base64. Yawan fitarwa ya dawo 413; nemi ƴan firam.

`DELETE /api/v1/video-bridge/drilldown?handle=...` dawo `{ "removed": 0|1 }`. Ba a sani ba, ƙarewa da maɓalli na giciye GETs ba a iya bambanta martani 404; giciye-key DELETE zai iya cire shigarwar mai shi ba. An hana samun damar dawowa 403, tantancewar missing/invalid 401, tambayoyin mara inganci 400, sokewa 499 da kurakurai na wucin gadi 503. Hannun hannu na tsari-na gida ne, suna ƙarewa bayan mintuna goma, kuma ba za su tsira daga sake farawa ba. Sabbin hannaye suna amfani da `v1.` da alamar Base64URL bazuwar 32-byte; Hashes token kawai ake riƙe. Legacy 64-hex tokens sun kasance ana iya karanta su ta zahiri don dacewa. Dubi [hanyoyin gadar Bidiyo](../security/GUARDRAILS.md#video-bridge-videobridgets-videobridgepipelinets) don izini, ƙididdiga da cikakkun bayanan samu.

### Ajiyayyen & Export/Import

| Ƙarshen Ƙarshe              | Hanya  | Bayani                                                                           |
| --------------------------- | ------ | -------------------------------------------------------------------------------- |
| `/api/db-backups`           | GET    | Jerin abubuwan ajiyar da ake samu                                                |
| `/api/db-backups`           | PUT    | Ƙirƙiri madadin da hannu                                                         |
| `/api/db-backups`           | POST   | Dawo daga takamaiman madadin                                                     |
| `/api/db-backups`           | PATCH  | Ajiye saitunan riƙewa (mai gudanarwa-kawai)                                      |
| `/api/db-backups`           | DELETE | Gyara madogaran da aka adana zuwa saitunan riƙewa (mai gudanarwa-kawai)          |
| `/api/db-backups/export`    | GET    | Zazzage bayanan bayanai azaman fayil .sqlite                                     |
| `/api/db-backups/import`    | POST   | Loda fayil ɗin .sqlite don maye gurbin bayanai (`?dryRun=true` ya inganta kawai) |
| `/api/db-backups/exportAll` | GET    | Zazzage cikakken madadin azaman tarihin .tar.gz                                  |

`/api/db-backups/export`, `/api/db-backups/exportAll` da `/api/settings/export-json` suna ba da kowane takaddun shaida da aka adana, don haka suna buƙatar zaman dashboard ko CLI na gida (ko shiga ya lalace). maɓallan API na kowane yanki da alamun samun damar `oma_` suna samun `403`. Maidowa suna riƙe da iyaka iri ɗaya: `POST /api/db-backups/import` ( haɗaɗɗen `dryRun=true` ), `POST /api/db-backups` (maidowa ta id) da `POST /api/settings/import-json` suna maye gurbin rayayyun bayanan bayanai ko saitunan, don haka shaidar shaidar injin ta sami `403` a can ma; `omniroute sync import` yana aika takardar shaidar CLI na gida. Don haka yi `DELETE /api/db-backups` (datsa abubuwan adanawa) da `PATCH /api/db-backups` (saitunan riƙewa: ƙimar da aka dage tana fitar da pruning ta atomatik bayan kowane madadin). Jeri (`GET`) da ƙirƙirar madaidaicin hannu (`PUT`) suna kiyaye amincin gudanarwa na yau da kullun.

### Cloud Sync

| Ƙarshen Ƙarshe         | Hanya       | Bayani                      |
| ---------------------- | ----------- | --------------------------- |
| `/api/sync/cloud`      | Daban-daban | Ayyukan daidaitawa na Cloud |
| `/api/sync/initialize` | POST        | Fara aiki tare              |
| `/api/cloud/*`         | Daban-daban | Gudanar da girgije          |

### Tunnels

| Ƙarshen Ƙarshe             | Hanya | Bayani                                                                 |
| -------------------------- | ----- | ---------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET   | Karanta Cloudflare Saurin Tunnel install/runtime matsayi don dashboard |
| `/api/tunnels/cloudflared` | POST  | Kunna ko kashe Cloudflare Quick Tunnel (`action=enable/disable`)       |
| `/api/tunnels/ngrok`       | GET   | Karanta halin lokacin gudu ngrok Tunnel don dashboard                  |
| `/api/tunnels/ngrok`       | POST  | Kunna ko kashe Ramin ngrok (`action=enable/disable`)                   |

### CLI Tools

| Ƙarshen Ƙarshe                     | Hanya | Bayani              |
| ---------------------------------- | ----- | ------------------- |
| `/api/cli-tools/claude-settings`   | GET   | Claude CLI          |
| `/api/cli-tools/codex-settings`    | GET   | Codex CLI           |
| `/api/cli-tools/droid-settings`    | GET   | Droid CLI status    |
| `/api/cli-tools/openclaw-settings` | GET   | OpenClaw CLI        |
| `/api/cli-tools/runtime/[toolId]`  | GET   | Generic CLI runtime |

Amsoshin CLI sun haɗa da: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.

### ACP Agents

| Ƙarshen Ƙarshe    | Hanya  | Bayani                                                              |
| ----------------- | ------ | ------------------------------------------------------------------- |
| `/api/acp/agents` | GET    | Lissafin duk wakilan da aka gano (ginayen + al'ada) tare da matsayi |
| `/api/acp/agents` | POST   | Ƙara wakili na al'ada ko sabunta cache ganowa                       |
| `/api/acp/agents` | DELETE | Cire wakili na al'ada ta hanyar tambayar `id` param                 |

Amsar GET ta haɗa da `agents[]` (id, suna, binary, sigar, shigar, yarjejeniya, isCustom) da `summary` (jimillan, shigar, notFound, builtIn, al'ada).

### Juriya & Ƙimar Ƙimar

| Ƙarshen Ƙarshe                    | Hanya     | Bayani                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/resilience`                 | GET/PATCH | layin buƙatun Get/update, sanyin haɗi, mai warwarewar mai badawa, da saitunan jira                                                                                                                                                                                                                                                                                                              |
| `/api/resilience/reset`           | POST      | Sake saita na'urori masu kawowa                                                                                                                                                                                                                                                                                                                                                                 |
| `/api/resilience/model-cooldowns` | GET       | Lissafa masu aiki da----- (mai bayarwa, haɗi, ƙirar ƙira) makulli, ana jerawa ta ragowar lokacin                                                                                                                                                                                                                                                                                                |
| `/api/resilience/model-cooldowns` | DELETE    | Share samfurin kulle — jiki `{provider, model}` ko `{all: true}` don goge komai                                                                                                                                                                                                                                                                                                                 |
| `/api/rate-limits`                | GET/POST  | Per-account rate limit status (GET) or toggle rate-limit protection for a connection (POST `{connectionId, enabled}`). Supported write path for `rateLimitProtection` (never modified via `PUT /api/providers/[id]`). Note: `enabled: false` disables explicit protection but does not opt an active API-key connection out of the global auto-enable safety net (`autoEnableApiKeyProviders`). |
| `/api/rate-limit`                 | GET       | Ƙayyadaddun ƙayyadaddun ƙayyadaddun ƙima na duniya (wanda aka lakafta shi zuwa `/api/rate-limits`)                                                                                                                                                                                                                                                                                              |

> Duk hanyoyin `/api/resilience/*` guda huɗu suna buƙata** sarrafa kansa** (`requireManagementAuth`). Dubi [Resilience (tsara)](#resilience-extended) don cikakken rugujewar mai warwarewar mai badawa vs sanyin haɗi vs kulle ƙirar ƙira.

### Evals

| Ƙarshen Ƙarshe | Hanya    | Bayani                                   |
| -------------- | -------- | ---------------------------------------- |
| `/api/evals`   | GET/POST | Jerin eval suites / gudanar da kimantawa |

### Manufofi

| Ƙarshen Ƙarshe  | Hanya           | Bayani                 |
| --------------- | --------------- | ---------------------- |
| `/api/policies` | GET/POST/DELETE | Sarrafa manufofin tuƙi |

### Biyayya

| Ƙarshen Ƙarshe              | Hanya | Bayani                                    |
| --------------------------- | ----- | ----------------------------------------- |
| `/api/compliance/audit-log` | GET   | Login bin diddigin bin doka (N na ƙarshe) |

### v1beta (Masu jituwa na Gemini)

| Ƙarshen Ƙarshe             | Hanya | Bayani                               |
| -------------------------- | ----- | ------------------------------------ |
| `/v1beta/models`           | GET   | Jerin samfuran a cikin tsarin Gemini |
| `/v1beta/models/{...path}` | POST  | Gemini `generateContent` karshen     |

Waɗannan wuraren ƙarshen suna madubi tsarin Gemini's API don abokan ciniki waɗanda ke tsammanin dacewar Gemini SDK na asali.

### Internal / System APIs

| Ƙarshen Ƙarshe           | Hanya | Bayani                                                           |
| ------------------------ | ----- | ---------------------------------------------------------------- |
| `/api/init`              | GET   | Fara ayyukan daidaitawa na baya (auth gudanarwa)                 |
| `/api/tags`              | GET   | Alamomin samfurin Ollama masu jituwa (na abokan cinikin Ollama ) |
| `/api/restart`           | POST  | Sake kunna uwar garken alheri sake kunnawa                       |
| `/api/shutdown`          | POST  | Ya haifar da rufewar uwar garken alheri                          |
| `/api/system/env/repair` | POST  | Gyara sauye-sauyen yanayi mai bada OAuth                         |
| `/api/system/version`    | GET   | Current/latest version, sabunta hali, tashar saki                |
| `/api/system/version`    | POST  | Fara sabuntawa-sane da sabuntawa zuwa sabon sigar                |

> **Lura:** Ana amfani da waɗannan wuraren ƙarshen a ciki ta tsarin ko don dacewa da abokin ciniki Ollama. Ba yawanci masu amfani da ƙarshen ke kiran su ba.

### Gyara Muhalli OAuth _(v3.6.1 +)_

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

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

Yana gyara abubuwan da suka ɓace ko gurɓatattun ma'auni OAuth don takamaiman mai bayarwa. Yana dawowa:

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

### Siga da Tashar Saki

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

Hanyar gudanar da dawo da baya-kawai (auth admin). Yana dawo da sigar da ke gudana, sabon sigar da aka buga da matsayin sabuntawa ta atomatik. `releaseChannel` da `channels` filayen ƙari ne (dogo 3.8.54); `channel` yana kiyaye ma'anarsa — yanayin turawa mai sabunta dashboard yana amfani da shi (`npm`, `source` ko `docker-compose`).

```json
{
  "current": "3.8.52",
  "latest": "3.8.52",
  "updateAvailable": false,
  "channel": "npm",
  "autoUpdateSupported": true,
  "autoUpdateError": null,
  "news": null,
  "releaseChannel": "latest",
  "channels": { "latest": "3.8.52", "next": "3.8.53-rc.1" }
}
```

- tashar `releaseChannel` — npm na ginawa mai gudana: `nightly` don nau'ikan `-nightly.*`, `next` don sauran abubuwan da aka riga aka gabatar (`-rc.*`, `-beta.*`, `-alpha.*`), `lts` don ingantaccen sigar babban tsoho fiye da `channels.latest`, in ba haka ba `latest`. Dokoki iri ɗaya kamar `scripts/release/dist-tag.mjs`, wanda ke ɗaukar alamar dist-npm a lokacin bugawa.
- `channels` — da aka buga shugaban kowane dist-tag, daga `npm view omniroute dist-tags` (rejista HTTP fallback), cache tare da TTL na mintuna 10 iri ɗaya kamar `latest`. kullum `latest` yana nan (ya koma filin `latest`, sannan `"unavailable"`); `next`, `nightly` da `lts` suna bayyana ne kawai lokacin da wannan alamar ta kasance. Buƙatun `Cache-Control: no-cache` yana sabunta duban biyun.

Samfurin tashar (`latest` = v3 har zuwa 4.0 GA, `next` = rc, `nightly` = `develop` yana ginawa, `lts` = v3 faci bayan 4.0 GA) an kwatanta shi a cikin `docs/ops/RELEASE_STRATEGY.md`.

---

## Canza Sauti zuwa Rubutu

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

Canza fayilolin sauti zuwa rubutu ta amfani da duk wani mai samar da STT da aka tsara. Sashen farko na hanyar URL yana zaɓar mai samarwa na asali (`openai/…`, `deepgram/…`). Ƙofofin da suke sake fitar da samfurin wani mai samarwa suna amfani da ƙayyadadden ID
(`openrouter/deepgram/nova-3`).

**Buƙata:**

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

**Amsa:**

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

**Misalan ID na samfurai:** `openai/whisper-1` (yana buƙatar maɓallin OpenAI),
`openrouter/deepgram/nova-3` (yana buƙatar maɓallin OpenRouter),
`deepgram/nova-3` (yana buƙatar maɓallin Deepgram na asali). Buƙatar
`deepgram/nova-3` kai tsaye **ba** ta amfani da OpenRouter.

**Tsarukan da ake tallafawa:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.

**Gemini Live (`gemini/gemini-3.5-transcribe-live`):** canza sauti zuwa rubutu cikin yanayin fayil ta hanyar
WebSocket na Gemini Live (yana buƙatar maɓallin Gemini API). Ana canza abin da aka ɗora zuwa PCM mono mai 16 kHz ta amfani da `ffmpeg`
(`ffmpeg` dole ne ya kasance a kan `PATH`, sai dai idan fayil ɗin ya riga ya kasance WAV PCM mono mai 16 kHz), sannan a
watsa shi zuwa zaman kuma a dawo da rubutun da aka kammala a matsayin `{ "text": "..." }`. Ana tura filayen fom na `language` da `prompt` na zaɓi. Iyakoki: idan abubuwan da aka ɗora sun wuce 25 MiB ko tsawon sautin da aka warware ya wuce mintuna 10, ana amsa da
`413`; idan juyawar ta ɗauki fiye da daƙiƙu 60, ana dakatar da ita kuma a amsa da
`504`. Ana aika maɓallin API a cikin taken `x-goog-api-key` kawai, ba a cikin URL ɗin WebSocket ba.

## Daidaituwar Ollama

Ga abokan ciniki da ke amfani da tsarin API na Ollama:

```bash
# Ƙarshen magana ta tattaunawa (tsarin Ollama)
POST /v1/api/chat

# Jerin samfurai (tsarin Ollama)
GET /api/tags
```

Ana fassara buƙatu kai tsaye tsakanin tsarin Ollama da tsarin ciki.

## VS Code Mai Alamar Token / Sunayen Madadin Marasa Taken Kai

Yi amfani da waɗannan sunayen madadin idan haɗin kai ba zai iya saka taken `Authorization` ba kuma yana buƙatar saka mabuɗin API a cikin URL na tushe.

```bash
# Sunan madadin kundin OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Sunayen madadin tattaunawa irin na OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Sunayen madadin irin na Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```

Misali:

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

Bayanan kula:

- Sunayen madadin masu alamar token suna sake amfani da masu sarrafa buƙatu iri ɗaya da `/v1/*` da `/api/tags`; tsarin amsoshi yana nan iri ɗaya.
- Fi son `Authorization: Bearer ...` a duk lokacin da abokin ciniki ke tallafa wa taken da aka keɓance.
- Token na URL na iya bayyana a rajistan ayyukan reverse-proxy, tarihin burauza, da bayanan telemetry a wajen OmniRoute. Mu ɗauke su a matsayin zaɓin daidaituwa, ba yanayin tantancewa na asali ba.

---

## Telemetry

```bash
# Samu taƙaitaccen bayanin telemetry na jinkiri (p50/p95/p99 ga kowane mai samarwa)
GET /api/telemetry/summary
```

**Amsa:**

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

---

## Kasafin Kuɗi

```bash
# Samu matsayin kasafin kuɗi na dukkan mabuɗan API
GET /api/usage/budget

# Saita ko sabunta kasafin kuɗi
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"
}
```

> **Bayanan kula na tsarin** (`setBudgetSchema`): `apiKeyId` wajibi ne; aƙalla ɗaya daga cikin `dailyLimitUsd`, `weeklyLimitUsd`, ko `monthlyLimitUsd` dole ya fi sifili. Filayen zaɓi: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Tsarin gado `{keyId, limit, period}` yana mayar da `400 Bad Request`.

## Iyakokin Token

Kasafin **token** na kowane API key (dabam da Kasafin da ya dogara da USD da aka ambata a sama). Ana aiwatar da su kai tsaye a hanyar buƙata: idan amfani da taga na yanzu na key ya kai iyakarsa, ana ƙin buƙatun da `429 Too Many Requests`. Ana iya keɓance iyakokin ga takamaiman `model`, `provider`, ko a yi amfani da su `global`ly a faɗin key ɗin; idan iyakoki da yawa sun dace da buƙata, mafi tsaurin iyaka ce ke aiki.

```bash
# Jerin iyakokin token na key (ya haɗa da amfani da taga kai tsaye)
GET /api/usage/token-limits?apiKeyId=key-123

# Ƙirƙira ko sabunta iyakar token
POST /api/usage/token-limits
Content-Type: application/json

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

# Goge iyakar token ta id
DELETE /api/usage/token-limits?id=tl-abc
```

> **Bayanan tsarin** (`setTokenLimitSchema`): `apiKeyId` da `scopeType` (`model` | `provider` | `global`) dole ne su kasance. `scopeValue` dole ne ya kasance sai dai idan `scopeType` ɗin `global` ne (misali, model id don iyakar `model`, ko provider id don iyakar `provider`). `tokenLimit` dole ne ya zama cikakkiyar lamba mai kyau (ana juya shi daga string). Na zaɓi: `id` (a bar shi don ƙirƙira, a samar da shi don sabuntawa), `resetInterval` (`daily` | `weekly` | `monthly`, tsoho `monthly`), `resetTime` (`HH:MM`), `enabled` (tsoho `true`). Amsoshin `GET` suna ƙara wa kowace iyaka `tokensUsed`, `remaining`, `windowStart`, `periodStartAt`, da `nextResetAt`. Wannan ƙarshen hanya na ajin gudanarwa ne (ana tilasta tantancewa ta tsakiya ta hanyar bututun authz).

## Sarrafa Buƙatu

1. Abokin ciniki yana aika buƙata zuwa `/v1/*`
2. Mai sarrafa hanya yana kiran `handleChat`, `handleEmbedding`, `handleAudioTranscription`, ko `handleImageGeneration`
3. Ana warware model (provider/model kai tsaye ko alias/combo)
4. Ana zaɓar bayanan tantancewa daga DB na cikin gida tare da tace samuwar account
5. Don chat: `handleChatCore` yana duba semantic/signature cache kuma yana warware saitunan matsawa na combo
6. Matsawa ta gaba tana gudana kafin fassarar provider idan an kunna ta (`lite`, Caveman, RTK, ko stacked)
7. Mai aiwatar da provider yana aika buƙatar zuwa upstream
8. Ana mayar da amsa zuwa tsarin abokin ciniki (chat), ko a mayar da ita yadda take (embeddings/images/audio)
9. Ana yin rikodin amfani, nazarin matsawa, da rajistan buƙatu
10. Ana amfani da fallback idan an samu kurakurai bisa ga dokokin combo

Cikakken bayanin gine-gine: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)

---

## Sarrafa Combo

Hanyoyin routing na mataki mafi girma (waɗanda aka riga aka taƙaita ƙarƙashin `/api/combos*`) za a iya tsara su 1:1 daga tsarin model id, wanda ke ba da damar karkatar da model id mai salon OpenAI a bayyane zuwa combo.

| Hanya  | Path                             | Bayani                                                                          |
| ------ | -------------------------------- | ------------------------------------------------------------------------------- |
| GET    | `/api/model-combo-mappings`      | Jera duk taswirar model→combo                                                   |
| POST   | `/api/model-combo-mappings`      | Ƙirƙiri taswira — jiki: `{pattern, comboId, priority?, enabled?, description?}` |
| GET    | `/api/model-combo-mappings/[id]` | Dawo da taswira guda ɗaya                                                       |
| PUT    | `/api/model-combo-mappings/[id]` | Sabunta filayen taswirar da take akwai                                          |
| DELETE | `/api/model-combo-mappings/[id]` | Cire taswira                                                                    |

**Tantancewa:** zaman gudanarwa/API key (`requireManagementAuth`).

---

## Webhooks

Biyan kuɗin webhook na waje don abubuwan OmniRoute (kammala buƙata, ƙarewar kaso, jujjuyawar maɓalli, da sauransu).

| Hanya  | Hanya                     | Bayani                                                                 |
| ------ | ------------------------- | ---------------------------------------------------------------------- |
| GET    | `/api/webhooks`           | Jera webhooks (ana ɓoye sirrika zuwa `<prefix>...`)                    |
| POST   | `/api/webhooks`           | Ƙirƙiri webhook — jiki: `{url, events?: ["*"], secret?, description?}` |
| GET    | `/api/webhooks/[id]`      | Dawo da webhook                                                        |
| PUT    | `/api/webhooks/[id]`      | Sabunta url/events/secret/description                                  |
| DELETE | `/api/webhooks/[id]`      | Cire webhook                                                           |
| POST   | `/api/webhooks/[id]/test` | Aika bayanan gwaji zuwa URL ɗin webhook kuma dawo da matsayin isarwa   |

**Tabbatarwa:** zaman gudanarwa/maɓallin API (`requireManagementAuth`).

---

## Maɓallan da Aka Yi Rajista (Gudanarwa ta atomatik)

Ana amfani da su ta tsarin gudanar da maɓallai ta atomatik don fitarwa da jujjuya maɓallan API a kan mai samarwa/asusu na baya, tare da kaso na yau da kullum/na awa.

| Hanya  | Hanya                                 | Bayani                                                                                                                                                                                                                                  |
| ------ | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/registered-keys`             | Jera maɓallan da aka yi rajista (gabatarwar da aka ɓoye kawai)                                                                                                                                                                          |
| POST   | `/api/v1/registered-keys`             | Fitar da sabon maɓallin da aka yi rajista — jiki: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Yana dawo da maɓallin danye **sau ɗaya kawai**. Yana dawo da `429` idan an ƙi saboda kaso. |
| GET    | `/api/v1/registered-keys/[id]`        | Dawo da bayanan maɓallin da aka yi rajista (babu ainihin abin da ke cikin maɓallin)                                                                                                                                                     |
| DELETE | `/api/v1/registered-keys/[id]`        | Soke maɓallin da aka yi rajista                                                                                                                                                                                                         |
| POST   | `/api/v1/registered-keys/[id]/revoke` | Ƙarshen API na soke maɓalli a sarari (sakamako iri ɗaya da DELETE)                                                                                                                                                                      |

**Tabbatarwa:** zaman gudanarwa/maɓallin API (`requireManagementAuth`) — mai gadi iri ɗaya da `/api/keys`: zaman dashboard, alamar CLI ta cikin gida, ko maɓallin API mai ikon `manage`/`admin`; maɓallan API na inference-kawai suna samun `403`. Duba kuma `/v1/quotas/check` da `/v1/issues/report`.

---

## Yarjejeniyar Agents

Ayyukan wakilin girgije (Claude Code, Codex Cloud, OpenHands, da sauransu) da ake aiwatarwa daga nesa a madadin masu amfani da OmniRoute.

| Method | Path                          | Description                                                                                                                                                       |
| ------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/agents/tasks`        | Jerin ayyuka — zaɓi na `?provider=`, `?status=`, `?limit=` (1–500, tsoho 50)                                                                                      |
| POST   | `/api/v1/agents/tasks`        | Ƙirƙiri aiki — `CreateCloudAgentTaskSchema` ne ke tantance jikin buƙatar (`providerId`, `prompt`, `source`, `options?`). Yana dawo da `201` tare da kunshin aikin |
| DELETE | `/api/v1/agents/tasks?id=...` | Goge aiki                                                                                                                                                         |
| GET    | `/api/v1/agents/tasks/[id]`   | Karanta aiki — yana sabunta matsayi a aiki tare daga wakilin girgije na sama idan an saita `external_id`                                                          |
| POST   | `/api/v1/agents/tasks/[id]`   | Aiki bisa nau'in buƙata: `{action: "approve"}`, `{action: "message", message}`, ko `{action: "cancel"}`                                                           |
| DELETE | `/api/v1/agents/tasks/[id]`   | Goge takamaiman aiki ta id                                                                                                                                        |

> **Auth:** Ana buƙatar izinin gudanarwa a kowace hanya (`requireCloudAgentManagementAuth`). Kafin v3.8.0, waɗannan hanyoyin ba su da tantancewa — duba commit `588a0333` don canjin da ya karya daidaito.

```bash
# Ƙirƙiri aikin girgije na 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":"..."}}'
```

---

## Wakilan Gudanarwa

Wakilan HTTP(S)/SOCKS masu fita waɗanda za a iya sanya wa masu samar da sabis, asusu, ko a duk duniya.

| Method | Path                                         | Description                                                                                                                                           |
| ------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/management/proxies`                 | Jera wakilai (tare da `?id=` yana dawo da guda ɗaya; tare da `?id=&where_used=1` yana dawo da jadawalin sanya su)                                     |
| POST   | `/api/v1/management/proxies`                 | Ƙirƙiri wakili — `createProxyRegistrySchema` ne ke tantance jikin buƙatar                                                                             |
| PATCH  | `/api/v1/management/proxies`                 | Sabunta wakili — `updateProxyRegistrySchema` ne ke tantance jikin buƙatar (ana buƙatar `id`)                                                          |
| DELETE | `/api/v1/management/proxies?id=...&force=1`  | Goge wakili (yi amfani da `force=1` don cire abubuwan da aka sanya)                                                                                   |
| GET    | `/api/v1/management/proxies/assignments`     | Jera abubuwan da aka sanya — ana iya tacewa ta `proxy_id`, `scope`, `scope_id`; aika `resolve_connection_id=<id>` don warware wakili mai aiki na haɗi |
| PUT    | `/api/v1/management/proxies/assignments`     | Sanya — `proxyAssignmentSchema` ne ke tantance jikin buƙatar (`{scope, scopeId?, proxyId?}`). Yana share ma'ajiyar dispatcher                         |
| PUT    | `/api/v1/management/proxies/bulk-assign`     | Sanya da yawa — `bulkProxyAssignmentSchema` ne ke tantance jikin buƙatar (`{scope, scopeIds[], proxyId?}`)                                            |
| GET    | `/api/v1/management/proxies/health?hours=24` | Tara lafiyar wakilai (adadin nasara/rashin nasara, jinkiri) a cikin wani tazarar lokaci                                                               |

**Auth:** Ana buƙatar zaman gudanarwa/maɓallin API a kowace hanya (`requireManagementAuth`).

> Bayanin aikin `POST /api/v1/management/proxies/[id]/assignments` da `POST /api/v1/management/proxies/[id]/health` ana hidimta musu ta hanyoyin `/assignments` da `/health` marasa rassa da aka nuna a sama — babu hanyoyin ƙasa na kowane id a cikin kundin lambar.

---

## Juriya (ƙarin bayani)

OmniRoute yana samar da hanyoyi uku masu zaman kansu na ɗan gajeren gazawa; endpoints na gudanarwa da ke ƙasa suna ba masu aiki damar karantawa da kuma gyara su:

| Iyakar aiki           | Adana yanayi                                | Karantawa                                 | Sake saita / sharewa                                          |
| --------------------- | ------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------- |
| Mai katse mai samarwa | `domain_circuit_breakers` + cikin ƙwaƙwalwa | `/api/monitoring/health`                  | `POST /api/resilience/reset`                                  |
| Jinkirin haɗi         | `rateLimitedUntil` a kan haɗin masu samarwa | `/api/rate-limits`, `/api/providers/[id]` | (yana sake kunnawa a hankali; sharewa ta hanyar provider PUT) |
| Kulle samfur          | Rijistar samuwar samfur a cikin ƙwaƙwalwa   | `GET /api/resilience/model-cooldowns`     | `DELETE /api/resilience/model-cooldowns`                      |

`PATCH /api/resilience` yana karɓar gyare-gyaren mai katse mai samarwa a ƙarƙashin `providerBreaker.oauth` da `providerBreaker.apikey`. Kowane bayanin saituna yana tallafa wa `degradationThreshold`, `failureThreshold`, da `resetTimeoutMs`; ana kuma nuna filayen iri ɗaya a Dashboard → Saituna → Juriya.

```bash
# Share kullen samfur guda ɗaya
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"}'

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

Don cikakken bayanin ra’ayi da tsoffin saitunan mai katsewa: duba [`CLAUDE.md`](../../CLAUDE.md) → "Resilience Runtime State" da [`docs/architecture/RESILIENCE_GUIDE.md`](../architecture/RESILIENCE_GUIDE.md).

### Layin Jerin Rate-Limit da Kariyar Auto-Enable

- **Hanyar rubutu da ake tallafawa**: `POST /api/rate-limits` tare da jikin `{"connectionId": "<id>", "enabled": true|false}` shi ne endpoint ɗin gudanarwa da ake tallafawa don kunna ko kashe kariyar rate-limit ga haɗi. `PUT /api/providers/[id]` da gangan ba ya gyara ko sauya `rateLimitProtection` (#11278).
- **Ma’anar `enabled: false`**: Saita `enabled: false` yana cire kariya ta musamman ga haɗin, amma **ba ya fitar da** haɗin API-key mai aiki daga tsarin kariyar auto-enable na duniya (`autoEnableApiKeyProviders = true`). A cikin `reconcileEnabledConnections` (`open-sse/services/rateLimitManager.ts`), `false` da `undefined` suna da ma’ana iri ɗaya; haɗin API-key mai aiki ba tare da kariya ta musamman ba zai ci gaba da samun kariya ƙarƙashin tsarin auto-enable.
- **Kashewa a duniya**: Don gudanar da haɗin API-key ba tare da layukan jerin rate-limit ba, kashe tsarin kariyar a duniya ta hanyar `RATE_LIMIT_AUTO_ENABLE=false` (env) ko `resilienceSettings.requestQueue.autoEnableApiKeyProviders = false` (Saituna → Juriya / `PATCH /api/resilience`).

---

## Ƙwarewa

Tsarin ƙwarewa don faɗaɗa OmniRoute da masu sarrafa aiwatarwa na musamman, tare da haɗin gwiwar kasuwar kayayyaki.

| Hanya  | Tafarki                           | Bayani                                                                                                                                    |
| ------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`                     | Jera ƙwarewar da aka girka — ana iya tacewa ta `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, tare da rarraba shafuka |
| GET    | `/api/skills/[id]`                | Dawo da ƙwarewa guda ɗaya                                                                                                                 |
| PUT    | `/api/skills/[id]`                | Sabunta ƙwarewa (suna, bayani, yanayi, tsari, mai sarrafawa, alamomi)                                                                     |
| DELETE | `/api/skills/[id]`                | Cire ƙwarewa                                                                                                                              |
| POST   | `/api/skills/install`             | Girka ƙwarewa daga bayyanannen bayani kai tsaye — jiki: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}`    |
| GET    | `/api/skills/executions`          | Jera aiwatar da ƙwarewa na baya-bayan nan (tarihin bincike tare da shigarwa/fitarwa/lokacin aiwatarwa)                                    |
| GET    | `/api/skills/marketplace?q=...`   | Bincika/jera mashahurai daga kasuwar SkillsMP (yana buƙatar saitin `skillsmpApiKey`)                                                      |
| POST   | `/api/skills/marketplace/install` | Girka ƙwarewa ta ID daga SkillsMP                                                                                                         |
| GET    | `/api/skills/skillssh?q=&limit=`  | Bincika rajistar skills.sh                                                                                                                |
| POST   | `/api/skills/skillssh/install`    | Girka ƙwarewa ta ID daga skills.sh                                                                                                        |

**Tabbatarwa:** zaman gudanarwa/mabuɗin API. Hanyoyin binciken kasuwa suna karɓar ko dai tabbacin gudanarwa ko mabuɗin API na Bearer (`isAuthenticated`).

---

## Ƙwaƙwalwa

Ma’ajiyar bayanan tattaunawa/haƙiƙa ta dindindin, wadda ta keɓanta ga kowane maɓallin API / zaman.

| Hanya  | Hanya                | Bayani                                                                                                                     |
| ------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/memory`        | Jera ƙwaƙwalwa — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, tare da rarrabawa ta `offset/limit` ko `page/limit`         |
| POST   | `/api/memory`        | Ƙirƙiri ƙwaƙwalwa — jikin buƙatar da Zod ya inganta: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET    | `/api/memory/[id]`   | Dawo da ƙwaƙwalwa guda ɗaya                                                                                                |
| DELETE | `/api/memory/[id]`   | Goge ƙwaƙwalwa                                                                                                             |
| GET    | `/api/memory/health` | Lafiyar tsarin ƙwaƙwalwa (haɗin DB, backend na embeddings, matsayin vector index)                                          |

**Tabbatar da izini:** zaman gudanarwa/maɓallin API (`requireManagementAuth`). Enum na `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (duba `MemoryType` a cikin `src/lib/memory/types.ts`).

---

## Sabar MCP

OmniRoute na zuwa da ginanniyar sabar Model Context Protocol mai jigilar bayanai 3 (stdio, SSE, streamable-http) da kayan aiki masu iyakantaccen yanki. Ƙarshen dashboard da ke ƙasa suna karanta bayanan matsayi/audit kuma suna tura jigilar HTTP.

| Hanya | Hanya | Bayani |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Bugun zuciya, jigilar bayanai, matsayin kan layi, kiran ƙarshe, manyan kayan aiki, ƙimar nasara ta awanni 24 |
| GET | `/api/mcp/tools` | Jerin kayan aikin MCP tare da `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
| GET | `/api/mcp/sse` | Buɗe rafin SSE don jigilar SSE (yana dawo da `503` idan MCP a kashe yake ko jigilar ba ta dace ba) |
| POST | `/api/mcp/sse` | Aika firam ɗin JSON-RPC ta jigilar SSE |
| GET | `/api/mcp/stream` | Buɗe ɓangaren SSE na jigilar Streamable HTTP (saƙonnin da sabar ta fara) |
| POST | `/api/mcp/stream` | Aika firam ɗin JSON-RPC ta jigilar Streamable HTTP |
| DELETE | `/api/mcp/stream` | Ƙare zaman Streamable HTTP |
| GET | `/api/mcp/audit` | Yi tambaya ga log ɗin audit — `?limit=`, `?offset=`, `?tool=`, `?success=true                                | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | Ƙididdigar audit da aka tattara (jimilloli, ƙimar nasara, matsakaicin tsawon lokaci, manyan kayan aiki) |

**Tabbatar da izini:** jigilar `sse`/`stream` suna bin tsarin izini na musamman na MCP (maɓallin API na Bearer mai `mcp` scope); ana iya karanta hanyoyin `status`/`tools`/`audit*` daga dashboard (babu ƙarin izini da ake buƙata bayan isa ga masaukin dashboard).

> Ana sarrafa jigilar HTTP ɗin biyu ta `settings.mcpEnabled` da `settings.mcpTransport` — rashin dacewar jigila yana dawo da `400`, yayin da MCP da aka kashe yake dawo da `503`.

---

## Sabar A2A

OmniRoute yana fallasa ƙarshen JSON-RPC 2.0 na A2A (Agent-to-Agent), tare da kunshin REST don dubawa da amfani da dashboard.

### JSON-RPC

```bash
POST /a2a
Authorization: Bearer your-api-key   # na zaɓi ne sai idan an saita OMNIROUTE_API_KEY
Content-Type: application/json

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

Hanyoyin da ake tallafawa (duk suna buƙatar `settings.a2aEnabled`):

| Hanya            | Bayani                                                                     |
| ---------------- | -------------------------------------------------------------------------- |
| `message/send`   | Aiwatar da skill cikin jituwa; yana mayar da `{task, artifacts, metadata}` |
| `message/stream` | Aiwatar da skill iri ɗaya ta hanyar SSE mai gudana                         |
| `tasks/get`      | Dawo da task ta `taskId`                                                   |
| `tasks/cancel`   | Soke task ta `taskId`                                                      |

Skills da aka gina a ciki: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.

### Katin Agent

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

Yana mayar da katin agent na A2A na jama'a (suna, bayani, damar aiki, kundin skills, tsarin tantancewa) — ana adana shi a cache ga jama'a na awa 1. Ba a buƙatar tantancewa.

### Masu taimakon REST

| Hanya | Hanya                        | Bayani                                                                                                          |
| ----- | ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/a2a/status`            | Bayanin ko an kunna A2A + ƙididdigar tasks + taƙaitaccen katin agent da ke cikin cache                          |
| GET   | `/api/a2a/tasks`             | Jera tasks — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST  | `/api/a2a/tasks`             | (Ba a aiwatar da shi a matsayin mai taimakon REST ba — ƙirƙira ta JSON-RPC `message/send`)                      |
| GET   | `/api/a2a/tasks/[id]`        | Dawo da task guda                                                                                               |
| POST  | `/api/a2a/tasks/[id]/cancel` | Soke task                                                                                                       |

**Tantancewa:** masu taimakon REST suna aiki ba tare da tantancewar gudanarwa ba (ana iya karanta su daga dashboard); hanyar JSON-RPC `/a2a` tana amfani da Bearer `OMNIROUTE_API_KEY` idan an saita shi.

---

## Gajimare, Evals da Assess

| Hanya | Hanya | Bayani |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Tabbatar da maɓallin Bearer sannan ya mayar da haɗin masu samarwa da aka ɓoye + laƙabban samfura don abokan cinikin da ke daidaitawa da gajimare |
| POST | `/api/cloud/credentials/update` | Sabunta bayanan tantancewa da aka ɓoye na mai samarwa da aka daidaita da gajimare |
| POST | `/api/cloud/model/resolve` | Warware ID na samfurin ma'ana zuwa takamaiman mai samarwa/samfurin ta amfani da teburin kewayawa na gida |
| GET | `/api/cloud/models/alias` | Jera laƙabban samfura kamar yadda ake fallasa su ga daidaitawar gajimare |
| GET | `/api/assess` | Karanta sabbin rarrabuwar assessment (na kowane mai samarwa/samfuri) |
| POST | `/api/assess` | Gudanar da assessment — jiki: `{scope: {type:"all"}                                                   | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Jera rukunin evals da aka gina a ciki + gudanarwar baya-bayan nan |
| POST | `/api/evals` | Fara gudanar da eval |
| POST | `/api/evals/suites` | Ƙirƙiri rukunin eval na musamman — ana tabbatar da jiki ta `evalSuiteSaveSchema` |
| GET | `/api/evals/suites/[id]` | Dawo da rukunin eval na musamman |

**Tantancewa:** `/api/cloud/auth` yana tabbatar da maɓallin Bearer kai tsaye kuma yana mayar da maɓallin da aka ɓoye da `projectId` na kowace haɗi ne kawai ga maɓallin da ke da ikon `manage` / `admin`; sauran hanyoyin `/api/cloud/*`, `/api/evals/*`, da `/api/assess` suna buƙatar zaman/API key na gudanarwa. POST na `/api/assess` yana amfani da `validateBody` tare da tsarin scope na discriminated-union.

---

## Gudanar da ACP (Agent Client Protocol)

a matsayin hanyoyin `child processes`. Waɗannan wuraren shiga suna sarrafa gano wakilan ACP da
rajistar wakilai na musamman.

| Hanya  | Wuri              | Bayani                                                                                                                                                            |
| ------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/acp/agents` | Jera duk sanannun wakilan CLI (na ciki + na musamman) tare da matsayin girkawa, sigar, da binary                                                                  |
| POST   | `/api/acp/agents` | Yi rajistar wakilin ACP na musamman ko sabunta ma’ajiya — jiki: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` ko `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Cire wakilin ACP na musamman — sigar tambaya: `?id=<agentId>`                                                                                                     |

**Misalin amsa** (`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
}
```

**Tabbatarwa:** Yana buƙatar zaman gudanarwa (kuk ɗin `auth_token` na dashboard) ko
maɓallin API mai iyakar gudanarwa.

Duba [Tsarin ACP](../frameworks/ACP.md) don cikakkun bayanai.

---

## Nazarin Bayanai da Sa-ido

Wuraren shiga na nazarin bayanai na ainihin lokaci don sa ido kan turawa, matsewa, da
bambancin masu samarwa. Waɗannan su ne ke ƙarfafa shafukan `/dashboard/analytics/*`.

### Nazarin bayanan turawa ta atomatik

| Hanya | Wuri                                 | Bayani                                                                                                  |
| ----- | ------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| GET   | `/api/analytics/auto-routing`        | Tara ƙididdigar turawa ta atomatik: jimillar kira, rarraba dabaru, rarraba matakai, manyan masu samarwa |
| GET   | `/api/analytics/auto-routing?days=7` | Ƙididdiga bisa tazarar lokaci (tsoho 24h)                                                               |

**Misalin amsa**:

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

### Nazarin matsewa

| Hanya | Wuri                         | Bayani                                                                                           |
| ----- | ---------------------------- | ------------------------------------------------------------------------------------------------ |
| GET   | `/api/analytics/compression` | Tara ƙididdigar matsewa: alamomin da aka adana, kaso na tanadi, rarraba yanayi, amfani da injuna |

**Misalin amsa**:

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

### Bibiyar bambancin masu samarwa

| Hanya | Wuri                       | Bayani                                                                                                                |
| ----- | -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/analytics/diversity` | Bibiyar bambanci bisa entropy na Shannon: tana hana dogaro da wuri guda na gazawa ta hanyar auna yaɗuwar masu samarwa |

**Misalin amsa**:

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

**Tabbatarwa:** Yana buƙatar zaman gudanarwa ko maɓallin API mai iyakar gudanarwa.

---

## Ayyukan Gudanarwa

Ƙarshen hanyoyin da masu gudanarwa kawai za su iya amfani da su don sarrafa ayyukan aiki.

| Method | Path                     | Description                                                                                    |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------------- |
| GET    | `/api/admin/concurrency` | Karanta iyakokin concurrency na yanzu (na gaba ɗaya + na kowane mai samarwa)                   |
| POST   | `/api/admin/concurrency` | Sabunta iyakokin concurrency — jiki: `{global?: number, perProvider?: Record<string, number>}` |

**Auth:** Yana buƙatar zaman gudanarwa mai ikon admin.

---

## Gudanar da Kayan Aikin CLI

Sarrafa kayan aikin CLI da ke haɗuwa da OmniRoute (antigravity, commandCode,
devin-cli, da sauransu). Duba [Maganar Mai Samarwa](./PROVIDER_REFERENCE.md) don cikakken jerin.

| Method | Path                                    | Description                                                                                                                                                                                     |
| ------ | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cli-tools/all-statuses`           | Matsayin duk kayan aikin CLI (an girka, sigar, lokacin gani na ƙarshe)                                                                                                                          |
| GET    | `/api/cli-tools/status`                 | Cikakken matsayin kayan aikin CLI guda ɗaya (`?tool=` query)                                                                                                                                    |
| POST   | `/api/cli-tools/apply`                  | Rubuta saitin kayan aiki da aka samar (`dryRun` yana nuna samfoti; `422` + `containerEphemeralTarget` lokacin da aka saka shi cikin akwati; `migration` yana rubuta bayanin Codex YAML na gado) |
| GET    | `/api/cli-tools/backups`                | Jera madadin saitunan kayan aikin CLI                                                                                                                                                           |
| POST   | `/api/cli-tools/backups`                | Ƙirƙiri madadin duk saitunan kayan aikin CLI                                                                                                                                                    |
| POST   | `/api/cli-tools/backups`                | Mayarwa: amfani da wannan hanyar tare da `{tool, backupId}` a jiki yana mayar da wannan madadin                                                                                                 |
| GET    | `/api/cli-tools/antigravity-mitm`       | Matsayin wakilin MITM na Antigravity (kayan aikin CLI na "antigravity-mitm")                                                                                                                    |
| POST   | `/api/cli-tools/antigravity-mitm/alias` | Saita laƙabin antigravity-mitm                                                                                                                                                                  |

**Auth:** Yana buƙatar zaman gudanarwa.

---

## Ƙwarewar Wakili

Sarrafa ƙwarewar wakilan AI (mai kama da GPTs na al'ada na OpenAI, amma don wakilai).

| Method | Path                         | Description                                                                                   |
| ------ | ---------------------------- | --------------------------------------------------------------------------------------------- |
| GET    | `/api/agent-skills`          | Jera duk ƙwarewar wakilai (ginannu + na al'ada)                                               |
| GET    | `/api/agent-skills/[id]`     | Samu takamaiman ƙwarewar wakili                                                               |
| POST   | `/api/agent-skills`          | Ƙirƙiri ƙwarewar wakili ta al'ada — jiki: `{name, description, prompt, model?, temperature?}` |
| PUT    | `/api/agent-skills/[id]`     | Sabunta ƙwarewar wakili ta al'ada                                                             |
| DELETE | `/api/agent-skills/[id]`     | Goge ƙwarewar wakili ta al'ada                                                                |
| GET    | `/api/agent-skills/[id]/raw` | Samu prompt + metadata ɗanye (ba tare da aiwatarwa ba)                                        |
| POST   | `/api/agent-skills/generate` | Samar da sabuwar ƙwarewa ta AI daga bayanin cikin harshen dabi'a                              |

**Auth:** Yana buƙatar zaman gudanarwa ko maɓallin API mai ikon gudanarwa.

---

## Gudanar da Cache

Sarrafa semantic cache da reasoning cache.

| Method | Path                   | Description                                                                                                 |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cache`           | Bayanin cache: jimillar shigarwa, ƙimar amfani, girman da ke kan faifai                                     |
| GET    | `/api/cache/entries`   | Jera shigarwar cache (tare da pagination)                                                                   |
| DELETE | `/api/cache/entries`   | Goge shigarwar cache (tacewa ta sigogin tambaya)                                                            |
| GET    | `/api/cache/stats`     | Cikakkun ƙididdigar cache (ta kowane mai samarwa, ta kowane samfurin)                                       |
| GET    | `/api/cache/reasoning` | Matsayin reasoning cache (don sake kunna reasoning)                                                         |
| DELETE | `/api/cache/reasoning` | Share reasoning cache — sigogin tambaya: `?toolCallId=<id>` (ɗaya) ko `?provider=<p>` ko babu sigogi (duka) |

**Auth:** Yana buƙatar zaman gudanarwa.

---

## Tsarin Memory

Sarrafa memory mai ɗorewa (FTS5 + vector embeddings).

| Method | Path               | Description                                                                  |
| ------ | ------------------ | ---------------------------------------------------------------------------- |
| GET    | `/api/memory`      | Jera shigarwar memory (tacewa ta scope, type, search query)                  |
| POST   | `/api/memory`      | Ƙirƙiri sabuwar shigarwar memory — body: `{scope, type, content, metadata?}` |
| GET    | `/api/memory/[id]` | Samu takamaiman shigarwar memory                                             |
| PUT    | `/api/memory/[id]` | Sabunta shigarwar memory                                                     |
| DELETE | `/api/memory/[id]` | Goge shigarwar memory                                                        |
| GET    | `/api/memory?q=`   | Bincika memory (FTS5 + vector) — ana haɗa ƙididdiga a cikin amsa ɗaya        |

**Auth:** Yana buƙatar zaman gudanarwa ko maɓallin API mai iyakar gudanarwa.

---

## Webhooks

Sarrafa rajistar webhook don abubuwan da ke faruwa.

| Method | Path                            | Description                                                          |
| ------ | ------------------------------- | -------------------------------------------------------------------- |
| GET    | `/api/webhooks`                 | Jera dukkan rajistar webhook                                         |
| POST   | `/api/webhooks`                 | Ƙirƙiri rajistar webhook — body: `{url, events[], secret?, active?}` |
| GET    | `/api/webhooks/[id]`            | Samu takamaiman rajistar webhook                                     |
| PUT    | `/api/webhooks/[id]`            | Sabunta rajistar webhook                                             |
| DELETE | `/api/webhooks/[id]`            | Goge rajistar webhook                                                |
| GET    | `/api/webhooks/[id]/deliveries` | Jera tarihin isarwa na webhook (rahoton nasara/rashin nasara)        |
| POST   | `/api/webhooks/[id]/test`       | Aika abin da ya faru na gwaji zuwa webhook                           |

**Auth:** Yana buƙatar zaman gudanarwa.

Duba [Tsarin Webhooks](../frameworks/WEBHOOKS.md) don cikakkun nau’ikan abubuwan da ke faruwa.

---

## Tsarin Ƙwarewa

Sarrafa Ƙwarewa (tsarin faɗaɗa ayyukan wakili).

| Hanya  | Hanya                    | Bayani                                                                               |
| ------ | ------------------------ | ------------------------------------------------------------------------------------ |
| GET    | `/api/skills`            | Jera duk ƙwarewar da aka girka (na cikin tsari + na musamman)                        |
| POST   | `/api/skills/install`    | Girka ƙwarewa daga hanyar gida ko URL                                                |
| DELETE | `/api/skills/[id]`       | Cire ƙwarewa                                                                         |
| PUT    | `/api/skills/[id]`       | Kunna ko kashe ƙwarewa — jiki: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST   | `/api/skills/executions` | Aiwatar da ƙwarewa — jiki: `{skillName, apiKeyId, input?, sessionId?}`               |
| GET    | `/api/skills/executions` | Jera tarihin aiwatarwa na duk ƙwarewa (tace ta `?apiKeyId=`)                         |

**Tabbatarwa:** Ana buƙatar zaman gudanarwa ko maɓallin API mai iyakar gudanarwa.

Duba [Tsarin Ƙwarewa](../frameworks/SKILLS.md) don cikakkun bayanai.

---

## Ƙarin Manhajoji

Sarrafa ƙarin manhajojin OmniRoute (faɗaɗawa daga wasu ɓangarori).

| Hanya  | Hanya                              | Bayani                                     |
| ------ | ---------------------------------- | ------------------------------------------ |
| GET    | `/api/plugins`                     | Jera ƙarin manhajojin da aka girka         |
| POST   | `/api/plugins/marketplace/install` | Girka ƙarin manhaja daga kasuwar manhajoji |
| DELETE | `/api/plugins/[name]`              | Cire ƙarin manhaja                         |
| POST   | `/api/plugins/[name]/activate`     | Kunna ƙarin manhaja                        |
| POST   | `/api/plugins/[name]/deactivate`   | Kashe ƙarin manhaja                        |
| GET    | `/api/plugins/[name]/config`       | Samo saitin ƙarin manhaja                  |
| PUT    | `/api/plugins/[name]/config`       | Sabunta saitin ƙarin manhaja               |

**Tabbatarwa:** Ana buƙatar zaman gudanarwa.

Duba [Tsarin Ƙarin Manhajoji](../frameworks/PLUGIN_SDK.md) don cikakkun bayanai.

---

## Karkatar da Inuya

Kwatanta masu samarwa ta hanyar inuwa / A-B **ba wani keɓaɓɓen REST surface ba** — ana tsara shi ta hanyar haɗa hanyoyin kewayawa (duba [Haɗa Kai Tsaye](../routing/AUTO-COMBO.md)). Ana samar da ma’aunan kwatanta na kowane haɗin hanya ta `GET /api/combos/metrics`.

---

## Ka’idojin Kariya

Duba ka’idojin kariya na lokacin aiki (gano PII, gano allurar umarni, haɗa hangen nesa). Ka’idojin kariya suna aiki a kowace buƙata; cire su ga kira guda ana yin sa ta kanun buƙatar `x-omniroute-disabled-guardrails` — babu wani wuri na dindindin na kunnawa/kashewa.

| Hanya | Hanya                  | Bayani                                                                                                         |
| ----- | ---------------------- | -------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/guardrails`      | Jera ka’idojin kariyar da aka yi rajista da matsayinsu (suna / an kunna / fifiko)                              |
| POST  | `/api/guardrails/test` | Gudanar da butaccen gwaji na bututun kafin kira a kan samfurin shigarwa — jiki: `{input, disabledGuardrails?}` |

**Tabbatarwa:** Ana buƙatar zaman gudanarwa.

Duba [Tsaro > Ka’idojin Kariya](../security/GUARDRAILS.md) don cikakkun bayanai.

---

---

## Tabbatarwa

Duba [Tabbatarwar Sarrafawa](../guides/MANAGEMENT-AUTH.md) don iyalan takardun shaidar guda huɗu (zaman dashboard, alamar CLI ta gida, `oma_live_…` Access Token, da maɓallin API mai iyakar manage) da yadda suka bambanta da maɓallan inference.

- Hanyoyin dashboard (`/dashboard/*`) suna amfani da kukin `auth_token`
- Shiga yana amfani da hash ɗin kalmar sirri da aka ajiye; madadin shi ne `INITIAL_PASSWORD`
- Ana iya kunnawa ko kashe zaɓin `requireLogin` ta `/api/settings/require-login`
- Hanyoyin `/v1/*` na iya buƙatar maɓallin API na Bearer idan `REQUIRE_API_KEY=true`
- “alamar sarrafawa” / “maɓallin API mai iyakar sarrafawa” a cikin wannan bayanin yana nufin ɗaya daga cikin iyalan da ke cikin wannan jagorar — ba wani ƙarin nau'in sirri da ba a fayyace ba

> **Sauyin da ke karya jituwa (v3.8.0)** — `/api/v1/agents/tasks/*` da wuraren sarrafa lokacin dakatawa yanzu suna buƙatar **tabbatarwar sarrafawa** (kukin `auth_token` na dashboard ko maɓallin API mai iyakar sarrafawa). Abokan ciniki da a baya suke kiran waɗannan hanyoyi ba tare da tabbatarwa ba za su karɓi `401 Unauthorized`. Duba commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).