pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-18 12:52:25 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
2f0a01d75cedb3b04c8b880cbb9d778f46155e49
OmniRoute/docs/i18n/ha/docs/reference/API_REFERENCE.md
Diego Rodrigues de Sa e Souza 58f88a83e4 feat(i18n): 7 new locales — Hausa, Yoruba, Igbo, Amharic, Uzbek, Georgian, Armenian (66 locales) (#13727) 
Batch 3 (last) of the locale-expansion plan: ha, yo, ig, am, uz, ka, hy on every surface — dashboard catalog, docs mirror (22-file core + llm.txt + CHANGELOG), CLI catalog, README flag block, locale tables and 🌐 language bars. Also closes the key gap the batch-1 (43 keys) and batch-2 (10 keys) catalogs carried since their base merges, fixes the Igbo "Model" copy and allowlists the Uzbek cognate. Translation-ratio baseline covers 65 locales.

⚠️ base-red inherited: #12732
2026-09-15 09:50:01 -03:00

1780 lines
122 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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) · 🇨🇿 [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)
---
---
title: "Manazartar API"
version: 3.8.51
lastUpdated: 2026-08-31
---
# Manazartar API
🌐 **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) · 🇨🇿 [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)
Babban manazarta na OmniRoute API. Ya ƙunshi ɓangaren `/v1` na jama'a da kuma wuraren ƙarshen gudanarwa da aka fi amfani da su; [`docs/openapi.yaml`](../openapi.yaml) mai iya karantawa ta na'ura da bishiyar hanyoyi da ke ƙarƙashin `src/app/api/` su ne cikakkun tushe.
---
## Jerin Abubuwan Ciki
- [Kammalawar Taɗi](#chat-completions)
- [Hayar Zama Mai Sarrafawa ta Keɓance](#exclusive-managed-session-leases)
- [Embeddings](#embeddings)
- [Samar da Hoto](#image-generation)
- [OCR na Takardu](#document-ocr)
- [Jerin Samfura](#list-models)
- [Manifest ɗin Plugin na Mai Bayarwa](#provider-plugin-manifest)
- [Endpoints na Daidaituwa](#compatibility-endpoints)
- [API na Fayiloli](#files-api)
- [API na Batches](#batches-api)
- [API na Bincike](#search-api)
- [Yawo ta WebSocket](#websocket-streaming)
- [Rahoton Ƙayyadaddun Amfani da Matsaloli](#quotas--issues-reporting)
- [Ma'ajiyar Wucin Gadi ta Ma'ana](#semantic-cache)
- [Dashboard da Gudanarwa](#dashboard--management)
- [Gudanar da Combo](#combo-management)
- [Webhooks](#webhooks)
- [Maɓallan da Aka Yi Rajista (Gudanarwa ta Atomatik)](#registered-keys-auto-management)
- [Ka'idar Agents](#agents-protocol)
- [Proxies na Gudanarwa](#management-proxies)
- [Juriya (faɗaɗaɗɗe)](#resilience-extended)
- [Ƙwarewa](#skills)
- [Ƙwaƙwalwa](#memory)
- [Sabar MCP](#mcp-server)
- [Sabar A2A](#a2a-server)
- [Cloud, Evals da Assess](#cloud-evals--assess)
- [Sarrafa Buƙata](#request-processing)
- [Tabbatar da Shaida](#authentication)
---
## Kammalawar Taɗi
```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
}
```
### Keɓaɓɓun Headers
| Header | Alkibla | Bayani |
| ------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache` | Buƙata | Saita zuwa `true` don ƙetare ma'ajiyar wucin gadi |
| `x-omniroute-no-memory` | Buƙata | Saita zuwa `true` don tsallake saka ƙwaƙwalwa + ƙwarewa cikin wannan buƙatar (yana kwaikwayon no-cache; yana kauce wa ƙarin nauyin token/kuɗin kowane kira) |
| `X-OmniRoute-Progress` | Buƙata | Saita zuwa `true` don samun al'amuran ci gaba |
| `X-Session-Id` | Buƙata | Maɓallin zama mai ɗorewa don dangantakar zama ta waje |
| `x_session_id` | Buƙata | Ana kuma karɓar nau'in da ke amfani da alamar ƙasa (HTTP kai tsaye) |
| `X-OmniRoute-Session-Id` | Buƙata | Alamar zama/tattaunawa da mai kira ya bayar (kuma tana ciyar da ƙwaƙwalwa). Idan tana nan, ana adana ta yadda take a `call_logs.session_tag` don danganta kuɗi ga kowane zama (#8249) — ba a taɓa ƙirƙirar ta idan babu |
| `Idempotency-Key` | Buƙata | Maɓallin kawar da maimaitawa (tazarar 5s) |
| `X-Request-Id` | Buƙata | Madadin maɓallin kawar da maimaitawa |
| `X-OmniRoute-Cache` | Amsa | `HIT` ko `MISS` (ba mai yawo ba) |
| `X-OmniRoute-Idempotent` | Amsa | `true` idan an kawar da maimaitawa |
| `X-OmniRoute-Progress` | Amsa | `enabled` idan bin diddigin ci gaba yana kunne |
| `X-OmniRoute-Session-Id` | Amsa | ID ɗin zama mai aiki da OmniRoute ya yi amfani da shi |
| `X-OmniRoute-Request-Id` | Amsa | ID na alaƙanta buƙata (idan an san shi) |
| `X-OmniRoute-Version` | Amsa | Nau'in ginin OmniRoute (yana nan koyaushe) |
| `X-OmniRoute-Cost-Saved` | Amsa | Adadin USD da ma'ajiyar wucin gadi ta hana kashewa a kan HIT (bugun ma'ajiyar wucin gadi kawai) |
| `X-OmniRoute-Decision` | Amsa | Sawun zaɓin hanya: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` shi ne dabarar combo, ko `single` ga buƙatar da ba ta combo ba) — yana nan koyaushe a amsoshin kammalawa |
> Bayanin Nginx: idan kuna dogaro da headers masu alamar ƙasa (misali `x_session_id`), kunna `underscores_in_headers on;`.
> **Kanun bayanan kuɗi:** amsoshin nasara marasa gudana su ma suna ɗauke da saitin kanun bayanan kuɗi na `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, tabbatattun lambobi 10 bayan alamar goma; `0.0000000000` ga abin da yake kyauta/ba a sanya masa 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 ta kammalawar taɗi, `/v1/responses`, `/v1/messages`, **da maƙurar 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` (kullum kuɗinsa `0` ne). Ana ƙididdige kuɗin kafofin watsa labarai bisa kowane nau'i (kowanne hoto, kowace daƙiƙa, kowane harafi, kowace naúrar bincike) idan akwai farashi, in ba haka ba `0` (a bar aiki ya ci gaba).
> **Ma'anar kuɗin samun bayanai daga ma'ajiyar wucin gadi:** idan an sami HIT daga ma'ajiyar wucin gadi ta ma'ana (`X-OmniRoute-Cache-Hit: true`) ba a yin kiran uwar garken sama, saboda haka `X-OmniRoute-Response-Cost` zai zama `0.0000000000` (**ƙarin** kuɗin samar da abin da aka samu). Ana bayar da rahoton kuɗin asali/da-da-an-ci a keɓance a cikin `X-OmniRoute-Cost-Saved`. Ya kamata masu amfani da bayanan lissafin kuɗi su tara `X-OmniRoute-Response-Cost` (abubuwan da aka samu daga ma'ajiyar ba su da kuɗi); nazarin ma'ajiyar wucin gadi na iya tara `X-OmniRoute-Cost-Saved`.
## Hayar Zama Mai Gudanarwa Ta Keɓantacce
Hayar zama mai gudanarwa ta keɓantacce yarjejeniya ce ta zaɓin shiga, wadda ba ta taƙaita ga wani abokin ciniki ba, don tsara turawa: mai mallaka guda ɗaya mai aiki
yana riƙe da haɗin OmniRoute guda ɗaya da ya cancanta. Ba ta bayar da hayar wani samfuri, ba ta buƙatar OAuth, ba ta tantance wani
takamaiman abokin ciniki, kuma ba ta buƙatar wani takamaiman mai samarwa.
Maɓallin API da ake amfani da shi wajen tantancewa dole ne ya kasance da izinin `lease:exclusive` da kuma jerin
`allowedConnections` bayyananne wanda ba komai ba ne. Iyakar sauyin bayanai ta rumbun bayanai tana tilasta kasancewar 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 da suka yi nasara suna bayyana tambarin lokaci, `state`, da takamaiman
`generation` mai ƙima tabbatacciya, amma ba sa taɓa bayyana haɗin da aka zaɓa ko bayanan sirri. Renew da release suna bayar da
generation a jikin JSON:
```json
{ "action": "renew", "generation": 1 }
```
```json
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
```
Mai mallakar haya mai aiki zai iya neman bayanan nunawa masu kiyaye sirri a sarari don ɗaurinsa 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ɓin shiga yana da shinge ta mai mallaka marar bayyananniyar ma'ana, ingantaccen maɓallin API mai gudanarwa, da takamaiman
generation mai aiki a cikin ma'amalar rumbun bayanai guda ɗaya. `displayName` shi ne kawai sunan haɗin da aka saita bayan an cire sararin gefuna;
yana zama `null` idan babu amintaccen suna da aka saita. OmniRoute ba ya taɓa maye gurbinsa da
imel ko ƙirƙirarren bayanin asusun mai amfani. Ƙimar provider lakabin nuni ce marar muhimmancin sirri, kuma ba ta taɓa zama
ƙirƙirarren mai ganowa na mai samarwa mai dacewa ba. An cire bayanan sirri, tokens, cookies, ɗanyen haɗi ko
ids na maɓallan API, hashes na masu mallaka, sirrin shinge, da bayanan turawa na ciki.
Binciken da ya ƙunshi maɓalli mara daidai, mai mallaka mara daidai, generation da ya tsufa, wanda ya ɓace, ya ƙare, aka saki, ko aka soke duk suna
mayar da kuskuren `409 LEASE_FENCE_STALE` iri ɗaya ba tare da metadata na haɗi ba. Abokin ciniki da ya karɓi amsar jiran samuwar ƙarfin aiki ba shi da ɗauri mai aiki da zai bincika. Lokacin da tsarin turawa ya sauya wata haya mai aiki,
generation ɗin nan ɗin yana ci gaba da aiki, kuma status yana mayar da sabon ɗaurin a lokaci guda, ba tsohon ba.
Abokan ciniki da ake da su ba sa canzawa saboda amsoshin acquire, renew, release, da waiting suna riƙe
tsarinsu na baya.
Wannan yarjejeniyar uwar garke ba ta canza daidaitaccen OpenAI Codex `/status` ba. A halin yanzu, daidaitaccen Codex yana bayar da rahoton
mai samar da samfurinsa da ginanniyar yanayin tantancewa/asusu, amma ba ya nuna metadata na asusun
mai samarwa na musamman yadda ake so; haɗawar abokin ciniki a nan gaba dole ne ta kira wannan aikin sannan ta yanke shawarar yadda za ta
nuna `connection.displayName`.
Daga nan, kowace buƙatar inference mai gudanarwa tana bayar da duka control headers biyun:
```http
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
```
Ana killace takamaiman mai mallaka, generation, haɗi mai aiki, da ingantaccen maɓallin API nan take
kafin kowane yunƙurin upstream da ake goyon baya. Sake amfani da mai mallaka da generation tare da wani maɓalli yana gaza ko da
wannan maɓallin yana ba da izinin haɗin iri ɗaya. Ba a adana ɗanyen bayanan masu mallaka, rubuta su a log, riƙe su a cikin
hoton buƙata, ko tura su zuwa upstream.
Cunkoso na ɗ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 kawai cewa jerin waɗanda suka cancanta na yau da kullum bai kasance fanko ba, kuma kowane ɗan takara da yake a sake yana
hannun wata haya mai aiki ta wani. Samfura/masu samarwa marasa tallafi, rashin dacewar manufa, cooldown, quota,
health, da sauran gazawar cancanta ta yau da kullum suna riƙe amsoshin OmniRoute da suke da su.
### `x-omniroute-compression`
Sauya tsarin compression na kowace buƙata. Shi ne mafi fifiko — yana rinjayar sauyin routing-combo,
active profile, auto-trigger, da Default na panel. Ƙimomi:
| Ƙima | Tasiri |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `off` | Babu compression ga wannan buƙatar. |
| `default` | Default profile da panel ya samar (yana yin watsi da active profile). |
| `engine:<id>` | Engine guda ɗaya idan an kunna shi, misali `engine:rtk`. |
| `<combo>` | Combo mai suna, ana fara daidaita shi ta suna (ba tare da kula da girman haruffa ba), sannan ta id. |
Bayanan kula:
- Ana yin watsi da ƙimomin da ba a sani ba (ba a taɓa ƙin buƙatar ba); warwarewar tana komawa ga tsarin fifikon ma'aikata na yau da kullum.
- Idan combos da yawa suna da suna iri ɗaya, aika **id** na combo don samun daidaitaccen sakamako.
- Ba za a iya zaɓar combo mai suna `off` ko `default` ta hanyar suna ba (ana fara fassara waɗannan keywords); yi nuni da irin wannan combo ta amfani da id ɗinsa.
- Babban maɓallin compression ƙaƙƙarfan shinge ne: idan an kashe compression gaba ɗaya, wannan header ba zai iya kunna shi ba.
Ana maimaita shirin da aka yi amfani da shi 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 samarwa da ake da su: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.
ID na kundin suna da tsarin `provider/model` (misali: `jina-ai/jina-embeddings-v5-omni-small`). ID na samfurin Jina marasa prefix da suka bayyana a rajista (misali `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) su ma suna aiki. Ayyukan embed/rerank/classify/segment na Jina suna fara amfani da bayanan shiga na `jina-ai` daga dashboard; ana amfani da `JINA_AI_API_KEY` a matsayin madadin ne kawai idan babu maɓalli a dashboard. Katin `jina-reader` na Reader / `r.jina.ai` ne kawai (`POST /v1/web/fetch`) kuma ba ya taɓa samar da embeddings ko rerank.
Samfuran rajista da suka nuna goyon bayan multimodal suna kuma karɓar abubuwa tsararru masu zaman kansu daga mai samarwa har zuwa 32.
Nau'ikan abubuwan kafofin watsa labarai su ne `text`, `image`, `audio`, `video`, da `document`. `source`
na kafofin watsa labaransu 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 laƙabin iyali `jina-ai/jina-embeddings-v5-omni` → omni-small) yana kuma karɓar takardun
EmbeddingsV5Request na asali na Jina kuma yana **tura su yadda suke ba tare da canji 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 ɗanyen
base64. OmniRoute ba ya mayar da waɗannan abubuwa zuwa string ko ɗauko URL na hotuna na asali — Jina da kansa ne yake ɗauko
kafofin watsa labarai na jama'a. Ana tura ƙarin filayen Jina (`task`, `normalized`, `truncate`, `embedding_type`).
SKU na Jina masu rubutu kaɗai har yanzu suna ƙin takardun da ba rubutu ba.
Iyakokin tsaro da jigilar bayanai:
- Dole ne URL na kafofin watsa labarai na nesa su kasance HTTPS na jama'a. Ana ɗauko abubuwan canonical na `{type,source:url}`
a gefen uwar garke (sake tabbatar da turawa, wa'adin lokaci, iyakokin girma, DNS na jama'a, da kulle haɗi), sannan a
saka su kai tsaye kafin kiran mai samarwa. Ana tura abubuwan Jina na asali `{image:"https://..."}` yadda suke
bayan an yi musu wannan binciken HTTPS na jama'a; Jina ne yake ɗauko URL ɗin.
- An iyakance kafofin watsa labarai na base64 da aka saka kai tsaye zuwa 8 MiB bayan warwarewa ga kowane abu, da 16 MiB bayan warwarewa ga dukkan buƙatar.
Fassarar tsarin mai samarwa (ba a taɓa tura abubuwan canonical yadda suke ba):
- Samfuran multimodal na Jina: kowane abu na matakin sama yana zama abu guda mai maɓallin nau'in bayanai
(`text` / `image` / `audio` / `video` / `pdf`), tare da amfani da URI na data don kafofin watsa labarai da aka saka kai tsaye; vector guda ga kowane
abu na matakin sama.
- Iyalan Gemini Embedding 2: array guda na matakin sama yana zama buƙatar asali guda ta
`models/{model}:embedContent` mai `content.parts` (`text` ko `inline_data`).
- Samfuran da ba a sani ba/masu canzawa waɗanda ba su da metadata na nau'in bayanai a bayyane suna ƙin shigarwar tsararru 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 samfur/nau'in bayanai da ba a goyon baya yana mayar da HTTP 400 maimakon tilasta canza abin. Filayen
faɗaɗawa da ba na input ba a tsofaffin buƙatun string/token suna ci gaba da wucewa yadda suke ba tare da canji ba.
```bash
# Jera dukkan samfuran embedding
GET /v1/embeddings
```
---
## Samar da Hoto
```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: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (na gida), ComfyUI (na gida).
```bash
# Jera duk samfuran hoto
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 amfani da g prefix na `provider/model`; id na samfuri kaɗai (misali,
`mistral-ocr-latest`) yana komawa ga mai samarwarsa da aka yi wa rajista, kuma idan ba a saka `model` ba, tsoffin saituna sukan koma ga
Mistral (`mistral-ocr-latest`). Masu samarwa da aka yi wa rajista (`open-sse/config/ocrRegistry.ts`):
| Id na mai samarwa | Id na samfuri | Ƙimar `model` | Bayanan kula |
| ----------------------------- | -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (ko `mistral-ocr-latest` kaɗai) | Mai aiki tare — ana mayar da amsar kai tsaye daga kiran upstream guda ɗaya. |
| `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Upstream mara aiki tare (`analyze` + binciken lokaci-lokaci) — duba ƙasa. |
| `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Mai aiki tare, ta endpoint na abokin haɗin gwiwar Vertex AI na `openapi/chat/completions` — duba ƙasa don tantancewa/URL. |
Dukkan masu samarwar uku suna bayar da amsa cikin tsari iri ɗaya na Mistral:
```json
{
"pages": [{ "index": 0, "markdown": "# Extracted text..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
```
### Tsarin binciken lokaci-lokaci na Azure Document Intelligence
API na `analyze` na Azure Document Intelligence mara aiki tare ne: buƙatar farko tana mayar da
header na `Operation-Location` maimakon body, kuma dole ne a riƙa bincika sakamakon lokaci-lokaci. Handler ɗin
(`open-sse/handlers/ocr.ts`) yana bincika wannan URL a kowane daƙiƙa ɗaya har zuwa yunƙuri 30, yana gaza nan take (ba ya
ci gaba da bincike) idan amsar binciken ba `ok` ba ce ko idan matsayin ya kasance `"failed"`, sannan yana mayar da `504` idan
har yanzu aikin yana gudana bayan an ƙare adadin yunƙuran da aka ware. 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 hulɗa ba ta buƙatar yin kulawa ta musamman ga kowane mai samarwa.
### Tantancewar Vertex AI DeepSeek OCR da warware endpoint
`vertex-deepseek-ocr` yana sake amfani da irin tantancewar Vertex AI da OmniRoute ya riga ya goyi baya don
zirga-zirgar chat/hoto (`open-sse/executors/vertex.ts`): API key na haɗin ko dai
shaidar Service Account JSON ce (wadda ake musanyawa da OAuth access token mai ɗan gajeren wa'adin aiki ta hanyar tsarin JWT-bearer)
ko kuma OAuth access token da aka riga aka samar wanda ake amfani da shi yadda yake. URL na upstream endpoint shi ne
babban endpoint na abokin haɗin gwiwar Vertex na `openapi/chat/completions`, wanda aka gina daga project da
region na haɗin — ƙayyadadden `providerSpecificData.project`/`providerSpecificData.region` shi ne koyaushe ake fifitawa;
in ba haka ba, ana samo project daga `project_id` na Service Account JSON, sannan region
yana komawa ga tsohon saiti na `us-central1`. Ana yin waɗannan warwarewar biyu a `open-sse/handlers/ocr.ts`
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`), kuma
`src/app/api/v1/ocr/route.ts` yana amfani da su kafin aika aikin zuwa `handleOcr`.
---
## Jerin Samfura
```bash
GET /v1/models
Authorization: Bearer your-api-key
→ Yana dawo da duk samfuran tattaunawa, embedding, da hotuna + haɗaɗɗun samfura a tsarin OpenAI
```
### Prefix na id na samfura (`?prefix=`)
Yawancin samfura ana tallata su ƙarƙashin **prefix na mai samarwa**. Prefix ɗin da za ka samu yana ƙarƙashin ikon
tutar fasalin `MODELS_CATALOG_PREFIX_MODE`, kuma ana iya maye gurbinsa **ga kowace buƙata** ta amfani da
query parameter — yana da amfani ga client da ke son tsaftatacciyar jeri ba tare da canza saitin dukkan
server ga kowa ba:
```bash
GET /v1/models?prefix=alias # id ɗaya ga kowace samfura — gajeren prefix na alias
GET /v1/models?prefix=dual # dukkan nau'ikan biyu (tsohon saitin server)
GET /v1/models?prefix=canonical # cikakken prefix na provider-id kawai
```
| Yanayi | Abin da yake fitarwa | Bayani |
| ----------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual` | `cc/claude-sonnet-4-6` **da** `claude/claude-sonnet-4-6` | **Tsohon saiti.** Duk id biyun suna kaiwa ga samfura ɗaya; an riƙe su domin saitunan client da suka hardcode kowane ɗayan nau'in su ci gaba da aiki. Yana kusan ninka girman katalog. |
| `alias` | `cc/claude-sonnet-4-6` | Shigarwa ɗaya ga kowace samfura. Masu samarwa 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 ɗaya ga kowace samfura ƙarƙashin cikakken prefix na provider-id. Masu samarwa 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 query parameter ba: yana ɗauke da filin `parent`
da ke nuni zuwa id na farko.
Clients da ke nuna mai zaɓen samfura ya kamata su nemi `?prefix=alias` — wannan ne abin da
[ƙarin OmniCopilot na VS Code](../guides/VSCODE-COPILOT.md) yake yi.
### Nau'ikan samfura marasa tunani
Ga samfuran Claude masu iya tunani, `/v1/models` yana kuma tallata nau'in **mara tunani** wanda aka fara id ɗinsa da `claude-3-omniroute-no-thinking/`:
```
claude-3-omniroute-no-thinking/<provider>/<model>
```
Zaɓar wannan id (misali, a cikin saitin Claude Code da koyaushe yake haɗa block na `thinking`) yana mayar da shi zuwa ainihin `<provider>/<model>` tare da dakatar da reasoning — `thinking:{type:"disabled"}` a kan hanyar `/v1/messages`, ko kuma a cire filayen `reasoning`/`reasoning_effort` a kan hanyar `/v1/chat/completions`. Ana jera wannan nau'in ne kawai ga samfuran dangin Claude waɗanda ke goyon bayan tunani **kuma** suke mutunta `disabled` (don haka, misali, ana cire samfuran adaptive-only waɗanda ke ƙin `disabled`). Masu gudanarwa za su iya tilasta kunna ko kashe wannan nau'in ga kowace samfura ta hanyar `ModelSpec.noThinkingAlias`.
---
## Bayanin Plugin na Mai Bayarwa
```bash
GET /api/v1/provider-plugin-manifest
```
Yana mayar da bayanin plugin na mai bayarwa mai aminci ga JSON wanda Bifrost, CLIProxyAPI, da
na'urorin sidecar router na gaba suke amfani da shi. Ana samar da amsar daga registry na mai bayarwa na TypeScript
kuma da gangan ba ta haɗa da sirrin abokin cinikin OAuth, warware muhallin lokacin aiki,
ayyukan executor, headers na buƙata, da bayanan asusu.
Yi amfani da wannan endpoint lokacin da sidecar ke aiki a wajen tsari kuma ba zai iya import
`open-sse/config/providerPluginManifestRegistry.ts` kai tsaye ba.
---
## Endpoints na Daidaituwa
| Hanya | Path | 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/inpaint) |
| 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 mayar da audio body) |
| POST | `/v1/rerank` | Sake jere irin na Cohere/Voyage |
| POST | `/v1/classify` | Rarrabawar Jina (`api.jina.ai`) |
| POST | `/v1/segment` | Mai rarraba Jina (`segment.jina.ai`) |
| POST | `/v1/moderations` | OpenAI Moderations |
| GET | `/v1/models` | OpenAI |
| POST | `/v1/messages/count_tokens` | Anthropic |
| GET | `/v1beta/models` | Gemini |
| POST | `/v1beta/models/{...path}` | Gemini generateContent |
| POST | `/v1/api/chat` | Ollama |
| GET | `/api/v1/vscode/{token}/` | Laƙabin kundin OpenAI |
| GET | `/api/v1/vscode/{token}/models` | Laƙabin models na OpenAI |
| POST | `/api/v1/vscode/{token}/chat/completions` | Laƙabin OpenAI mai token |
| POST | `/api/v1/vscode/{token}/responses` | Laƙabin OpenAI Responses mai token |
| POST | `/api/v1/vscode/{token}/api/chat` | Laƙabin Ollama mai token |
| GET | `/api/v1/vscode/{token}/api/tags` | Laƙabin tags na Ollama mai token |
Duk hanyoyin POST suna bin tsari iri ɗaya: `Bearer your-api-key` + JSON body da Zod ya inganta (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, da sauransu, duba `src/shared/validation/schemas.ts`). Ana mayar da 4xx idan schema ya gaza.
Ga clients waɗanda ba za su iya haɗa `Authorization: Bearer ...` ba, OmniRoute kuma yana karɓar API keys a cikin URL ta hanyar daidaituwar query-string (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) ko kuma keɓaɓɓun endpoints na `/api/v1/vscode/{token}/...` da aka bayyana a ƙasa.
```bash
# Sake jere
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
# Rarrabawar Jina (takardun shaidar Foundation API)
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
# Mai rarraba Jina
POST /v1/segment { "content": "...", "return_chunks": true }
# Binciken Jina (s.jina.ai; laƙuban mai bayarwa: jina-search, jina-ai, jina)
POST /v1/search { "query": "...", "provider": "jina-search" }
# Daidaita abun ciki
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
# TTS — yana mayar da audio/mpeg (ko tsarin da aka nema) a matsayin body
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
# Gyaran hoto (multipart)
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
# Samar da bidiyo / kiɗa (model id mai prefix na mai bayarwa)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." }
```
### Keɓaɓɓun Hanyoyin Mai Bayarwa
```bash
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
```
Ana ƙara prefix na mai bayarwa kai tsaye idan babu shi. Models marasa daidaituwa suna mayar da `400`.
---
## API na Fayiloli
Wurin ƙarshen fayiloli mai dacewa da OpenAI don shigarwa/fitarwa ta rukuni da lodin fayiloli bisa manufa.
| Hanya | Tafarki | Bayani |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| POST | `/v1/files` | Loda fayil (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — iyakar 512 MiB |
| GET | `/v1/files` | Jera fayiloli na maɓallin API da aka tantance |
| GET | `/v1/files/[id]` | Karɓo metadata na fayil |
| DELETE | `/v1/files/[id]` | Share fayil |
| GET | `/v1/files/[id]/content` | Yaɗa ainihin jikin fayil ɗin kai tsaye |
**Tantancewa:** Maɓallin API na Bearer — ana ware fayiloli ga kowane maɓallin API ta hanyar `getApiKeyRequestScope`.
---
## API na Rukunonin Aiki
Sarrafa ayyuka a rukuni mai dacewa da OpenAI.
| Hanya | Tafarki | Bayani |
| ------ | ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| POST | `/v1/batches` | Ƙirƙiri rukuni — ana tantance body ta `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) |
| GET | `/v1/batches` | Jera rukunonin aiki |
| GET | `/v1/batches/[id]` | Karɓo matsayin rukuni + `request_counts` |
| DELETE | `/v1/batches/[id]` | Share rukuni da ya kammala/ya gaza |
| POST | `/v1/batches/[id]/cancel` | Soke rukuni da ake kan aiwatarwa |
**Tantancewa:** Maɓallin API na Bearer. Ana ware rukunonin aiki ga kowane maɓallin API.
---
## API na Bincike
Tsarin haɗin gwiwa na masu samar da binciken yanar gizo (Tavily, Brave, Exa, Serper, da sauransu).
| Hanya | Tafarki | Bayani |
| ----- | ---------------------- | -------------------------------------------------------------------------------------------------------- |
| GET | `/v1/search` | Jera masu samar da bincike da aka saita + ƙarfinsu |
| POST | `/v1/search` | Gudanar da tambayar bincike — ana tantance body ta `v1SearchSchema`, yana goyon bayan caching/coalescing |
| GET | `/v1/search/analytics` | Ƙididdigar hit/latency/cache ta kowane mai samarwa |
**Tantancewa:** Maɓallin API na Bearer (`extractApiKey` + `isValidApiKey`). Ana tilasta manufofin bincike ta hanyar `enforceApiKeyPolicy`.
---
## Web Fetch API
Ciro abun ciki daga URL ta hanyar mai samar da web-fetch da aka saita (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).
| Hanya | Path | Bayani |
| ----- | --------------- | --------------------------------------------------------------------- |
| POST | `/v1/web/fetch` | Ɗauko/cire bayanai daga URL — ana tantance body ta `v1WebFetchSchema` |
**Tabbatarwa:** Maɓallin Bearer API (`extractApiKey` + `isValidApiKey`). Ana aiwatar da manufar ta hanyar `enforceApiKeyPolicy`.
**Komawa madadin mai la’akari da ƙayyadadden amfani (#8297):** idan ba a bayar da takamaiman `provider` ba, ana bi ta cikin rukunin
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) bisa tsayayyen
tsarin fifiko (cika-na-farko) — ana tsallake mai samarwa da aka saita amma aka taƙaita saurin amfani da shi
maimakon katse buƙatar nan take, kuma gazawar sabis na sama da za a iya sake gwadawa/mai alaƙa da ƙayyadadden amfani
(HTTP 429 a koyaushe; 402/403 ga matakan kyauta masu salon ƙayyadadden amfani na Firecrawl/Tavily/TinyFish —
ba ga Jina Reader ba, kuma ba a taɓa yin haka ga buƙatar 400 mara inganci ta yau da kullum ba) tana wucewa zuwa
mai samarwa na gaba da ba a gwada ba, mai bayanan shiga, a lokacin buƙatar. Idan duk masu samarwa da ke cikin
rukunin sun ƙare, endpoint ɗin yana mayar da `429` guda ɗaya (tare da header na `Retry-After`)
maimakon tsohon `400` na gama-gari. Idan an nemi takamaiman `provider`, **babu** komawa madadin a ɓoye — takamaiman
mai samarwa da aka taƙaita saurin amfani da shi ko ya gaza zai nuna kuskurensa kai tsaye (`429` idan an taƙaita saurin amfani, in ba haka ba status na sabis na sama).
---
## Watsawar WebSocket
```bash
GET /v1/ws?handshake=1
```
Yana tantance WebSocket upgrade handshake kuma yana mayar da misalan saƙonnin wire protocol (`request`, `cancel`). Sabar WS da aka haɗa ce ke sarrafa ainihin WS frames a wajen jadawalin route na Next.js.
**Tabbatarwa:** Maɓallin Bearer API yayin handshake.
### Responses API ta WebSocket (codex kawai)
```bash
# Host:port ɗaya da HTTP API (tsoho 20128); ɗaukaka 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 kasance response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```
An haɗa proxy na Responses-API-over-WebSocket **ga `codex` kaɗai** (backend na ChatGPT).
Yana sauraro a port ɗaya da API/dashboard a paths `/v1/responses`,
`/responses`, da `/api/v1/responses`. A frame na farko na `response.create`, yana
tabbatar da izini + shirya ta hanyar bridge na ciki na `codex-responses-ws`, yana zaɓar
haɗin codex OAuth, sannan yana yin tunnel zuwa `wss://chatgpt.com/backend-api/codex/responses`
ta hanyar transport na `wreq-js`. **Ana ƙin samfuran da ba codex ba** (`codex_ws_provider_required`).
Don routing na rabon ƙayyadadden amfani, 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:** Maɓallin Bearer API yayin handshake. Dole ne sabar HTTP da aka haɗa (`server-ws.mjs`)
ta kasance entrypoint mai aiki (kuma haka take, ta tsohuwa, idan `app/server-ws.mjs` yana nan).
#### Model id: yi amfani da ainihin ChatGPT id (ba tare da prefix na `codex/` ba)
OpenAI **Codex CLI** yana tantance sunan model a bangaren client idan
`supports_websockets = true` kuma yana **ƙin ids 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 **ainihin** id (misali `gpt-5.5`). Bridge na OmniRoute
na codex ne kawai, don haka yana sake tantance ainihin id a matsayin model na codex
(`resolveCodexWsModelInfo`) kafin yin tunnel zuwa sabis na sama — ko da yake ainihin
`gpt-5.5` zai iya routing zuwa wani provider ta HTTP idan ba haka ba.
#### Saita OpenAI Codex CLI
Nuna Codex CLI zuwa OmniRoute ta hanyar ƙara custom provider mai goyon bayan WebSocket
a `~/.codex/config.toml` (yi amfani da `CODEX_HOME` na daban don kauce wa taɓa
saitin da yake akwai):
```toml
model = "gpt-5.5" # ainihin id — 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 samar da WS URL daga gare shi (yi amfani da https/wss a production)
wire_api = "responses" # ƙima ɗaya tilo da ake goyon baya tun Feb 2026
supports_websockets = true # yana kunna transport na Responses-over-WS
env_key = "OMNIROUTE_API_KEY" # yana riƙe da maɓallin OmniRoute API (Bearer)
```
```bash
export OMNIROUTE_API_KEY=sk-... # maɓallin OmniRoute API (kowane maɓalli idan REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```
CLI yana ɗaukaka `base_url + /responses` zuwa WebSocket, sannan OmniRoute yana yin tunnel ɗinsa
zuwa haɗin codex OAuth da aka zaɓa. An tantance shi daga farko zuwa ƙarshe a kan sabar
gida: ChatGPT yana mayar da `codex.rate_limits` + `response.created` kuma yana watsa
cikawar a hankali.
---
## Ƙayyadaddun Amfani & Bayar da Rahoton Matsaloli
| Hanya | Path | Bayani |
| ----- | ------------------- | --------------------------------------------------------------------------------------------------------------- |
| GET | `/v1/quotas/check` | Tabbatar da ƙayyadadden amfani tun da wuri don `provider` + `accountId` kafin bayar da maɓalli mai rajista |
| POST | `/v1/issues/report` | Kai rahoton gazawar ƙayyadadden amfani/bayar da maɓalli zuwa GitHub (yana buƙatar `GITHUB_ISSUES_REPO` + token) |
**Tabbatarwa:** Maɓallin API na Bearer (`isAuthenticated`).
---
## Amfani na kai-tsaye (`/api/usage/om-usage`)
Kowane maɓallin API zai iya karanta bayanan amfaninsa da ƙayyadaddun amfaninsa **na kansa** — ba a buƙatar izinin gudanarwa. Wannan shi ne endpoint ɗin da
client (CLI, panel ɗin OmniCopilot) yake amfani da shi don nuna wa mai riƙe da maɓalli kuɗin da ya kashe.
```bash
# Tsarin rubutu (yarjejeniyar tarihi — rubutu kai tsaye don terminal)
curl -H "Authorization: Bearer <your-api-key>" \
http://localhost:20128/api/usage/om-usage
# Tsari mai tsararrun bayanai — wanda UI ke amfani da shi
curl -H "Authorization: Bearer <your-api-key>" \
"http://localhost:20128/api/usage/om-usage?format=json"
```
Dole ne maɓallin ya kasance da **`allowUsageCommand`** a kunne (a kashe yake ta tsohuwa — manajan maɓallin API na dashboard
yana kunna ko kashe shi ga kowane maɓalli). Idan babu shi, endpoint ɗin zai mayar da `403`.
`?format=json` yana mayar da tsari mai bambance yanayi domin mai kira kada ya taɓa karanta filin bayanai daga
amsar ƙin izini. Idan an yi nasara:
```jsonc
{
"allowed": true,
// yana nan ne kawai idan maɓallin ya zaɓi ƙayyadaddun amfani na kowane maɓalli (USD na kullum/mako-mako):
"personal": {
"dailySpentUsd": 1.25,
"dailyLimitUsd": 5,
"dailyResetAtIso": "…",
"weeklySpentUsd": 8,
"weeklyLimitUsd": 20,
"weeklyResetAtIso": "…" /* … */,
},
// hoton ƙayyadadden amfani na provider da aka zaɓa, ko null idan ba a ajiye komai a cache ba tukuna:
"provider": {
"connectionId": "…",
"provider": "claude",
"plan": "…",
"quotas": {/* … */},
},
// hoton kowace connection, domin UI ya iya nuna providers da yawa gefe da gefe:
"providers": [
{ "connectionId": "…", "provider": "claude" /* … */ },
{ "provider": "codex" /* … */ },
],
}
```
Idan an ƙi izini (`401` maɓalli mara inganci / `403` ba a ba da izini ba), wannan route ɗin zai mayar da
`{ "allowed": false, "error": { "message": "…" } }` — kasancewar `personal`/`provider` amma babu komai a ciki
(an ba maɓallin izini, amma har yanzu ba a samu wani bayani ba) wani yanayi ne daban da ƙin izini, kuma tsarin JSON ne kawai
ke bambance su.
**Tabbatarwa:** maɓallin API na Bearer na mai kiran da kansa, wanda aka tabbatar da shi ta `isValidApiKey` — wannan _ba_ wurin
gudanarwa ba ne (`/api/keys/…`), wanda yake ci gaba da kasancewa a bayan `requireManagementAuth`.
---
## Cache na Ma’ana
```bash
# Samo ƙididdigar cache
GET /api/cache/stats
# Share dukkan caches
DELETE /api/cache/stats
```
Misalin amsa:
```json
{
"semanticCache": {
"memorySize": 42,
"memoryMaxSize": 500,
"dbSize": 128,
"hitRate": 0.65
},
"idempotency": {
"activeKeys": 3,
"windowMs": 5000
}
}
```
### Tasiri kan jinkiri
HIT na cache na ma’ana yana bayar da amsar daga cache **ba tare da yin kiran upstream
ba**, saboda haka `X-OmniRoute-Response-Latency` da aka bayar da rahoto yana kusa da sifili
(ba tare da la’akari da ainihin jinkirin upstream ba). Ya kamata clients masu kula da jinkiri
(gwajin aiki, sa ido kan p50/p99) su duba response header na
`X-OmniRoute-Cache-Latency`:
| Ƙima | Ma’ana |
| ----------- | ----------------------------------------------------------------------- |
| `synthetic` | An bayar da amsa daga cache; jinkirin ba ainihin lokacin upstream ba ne |
| _(babu)_ | Amsa daga ainihin kiran upstream |
### Tsallake cache ga kowane maɓalli
Maɓallan API za su iya ƙin karantawa daga cache na ma’ana ta hanyar `cacheDefaultMode`:
| Ƙima | Halayya |
| -------- | ------------------------------------------------------- |
| `legacy` | Halayyar cache ta yau da kullum (ta tsohuwa) |
| `bypass` | Tsallake binciken cache gaba ɗaya; koyaushe je upstream |
Saita lokacin ƙirƙirar maɓalli (`POST /api/keys`) ko sabuntawa (`PATCH /api/keys/[id]`):
```json
{ "cacheDefaultMode": "bypass" }
```
### Tsallake cache ga kowace request
Kowace request za ta iya tsallake cache ba tare da la’akari da saitunan maɓalli ba:
```
X-OmniRoute-No-Cache: true
```
---
## Dashboard & Gudanarwa
Hanyoyin gudanarwa (`/api/*` ban da tantancewar jama'a/shiga) **ba a** ba su izini ta hanyar maɓallan API na inference na yau da kullum. Nau'ikan bayanan shaida, scopes, da misalan curl:
[Tantancewar Gudanarwa](../guides/MANAGEMENT-AUTH.md).
### Tantancewa
| Endpoint | Method | Bayani |
| ----------------------------- | ------- | -------------------------- |
| `/api/auth/login` | POST | Shiga |
| `/api/auth/logout` | POST | Fita |
| `/api/settings/require-login` | GET/PUT | Kunna/kashe wajibcin shiga |
### Gudanar da Provider
| Endpoint | Method | Bayani |
| ---------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `/api/providers` | GET/POST | Jera / ƙirƙiri providers |
| `/api/providers/[id]` | GET/PUT/DELETE | Gudanar da provider |
| `/api/providers/[id]/test` | POST | Gwada haɗin provider |
| `/api/providers/[id]/models` | GET | Jera models na provider |
| `/api/providers/validate` | POST | Tabbatar da config na provider |
| `/api/providers/bulk` | POST | Ƙara maɓallan API da yawa ga provider GUDA |
| `/api/providers/import` | POST | Shigo da JERIN providers iri-iri daga fayil ɗin CSV/JSON da aka parse (#6836); sakamakon gazawar wani ɓangare na kowane layi |
| `/api/provider-nodes*` | Various | Gudanar da nodes na provider |
| `/api/provider-models` | GET/POST/PATCH/DELETE | Models na musamman (ƙara, sabunta, ɓoye/nunawa, sharewa) |
### Hanyoyin OAuth
| Endpoint | Method | Bayani |
| -------------------------------- | ------- | ----------------------------- |
| `/api/oauth/[provider]/[action]` | Various | OAuth na musamman ga provider |
### Routing & Config
| Endpoint | Method | Bayani |
| --------------------- | -------- | -------------------------------- |
| `/api/models/alias` | GET/POST | Laƙaban model |
| `/api/models/catalog` | GET | Duk models bisa provider + nau'i |
| `/api/combos*` | Various | Gudanar da combo |
| `/api/keys*` | Various | Gudanar da maɓallin API |
| `/api/pricing` | GET | Farashin model |
### Amfani & Nazari
| Endpoint | Method | Bayani |
| -------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history` | GET | Tarihin amfani |
| `/api/usage/logs` | GET | Rajistan amfani |
| `/api/usage/request-logs` | GET | Rajista na matakin buƙata |
| `/api/usage/[connectionId]` | GET | Amfani na kowace haɗi |
| `/api/usage/token-limits` | GET/POST/DELETE | Kasafin iyakar token na kowane maɓallin API |
| `/api/usage/model-latency-stats` | GET | Tarin ƙididdigar jinkiri mai sabuntawa na kowane mai samarwa/samfuri (avg/p50/p95/p99, adadin nasara); matatu: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) |
| `/api/usage/cache-health` | GET | Taƙaitaccen bayanin lafiyar ma'ajiyar prompt a kan `call_logs` — rabon rubutawa/karantawa, rarraba girman rubutawa na p50/p90/p99, tattaruwar rubutawa mai yawa, rabewa bisa samfurori, da hukuncin `healthy`/`degraded`/`thrash`/`no-data`; sigogin tambaya `range` (`1h`\|`24h`\|`7d`\|`30d`, tsoho `24h`) da `model` na zaɓi (#8827) |
### Saituna
| Endpoint | Method | Bayani |
| ------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings` | GET/PUT/PATCH | Saitunan gama-gari |
| `/api/settings/proxy` | GET/PUT | Saitin wakilin hanyar sadarwa |
| `/api/settings/proxy/test` | POST | Gwada haɗin wakili |
| `/api/settings/ip-filter` | GET/PUT | Jerin IP da aka yarda/aka toshe |
| `/api/settings/thinking-budget` | GET/PUT | Yanayin sake rubuta **buƙatar** kasafin tunani/fahimta (wucewa kai tsaye / cirewa ta atomatik / na musamman / mai daidaitawa). Ba ya dogara da matsawa. Duba [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). |
| `/api/settings/system-prompt` | GET/PUT | Prompt na tsarin duniya baki ɗaya |
| `/api/settings/compression` | GET/PUT | Saitin matsawa na duniya baki ɗaya |
| `/api/settings/purge-request-history` | POST | Share layukan rajistan buƙata da kayayyakin rajistan kira na gida |
### Mahalli & Matsawa
| Ƙarshen hanya | Hanya | Bayani |
| -------------------------------------- | -------------- | ---------------------------------------------------------------------------------- |
| `/api/compression/preview` | POST | Samfotin matsewa na off/lite/standard/aggressive/ultra/RTK/stacked |
| `/api/compression/language-packs` | GET | Jera fakitin harsunan Caveman da suke samuwa |
| `/api/compression/rules` | GET | Jera metadata na ƙa'idodin Caveman |
| `/api/context/caveman/config` | GET/PUT | Laƙabin saitunan da suka keɓanta ga Caveman |
| `/api/context/rtk/config` | GET/PUT | Saitunan da suka keɓanta ga RTK, ciki har da matatan al'ada da riƙe ɗanyen fitarwa |
| `/api/context/rtk/filters` | GET | Katalojin matatan RTK da binciken matsalolin matatan al'ada |
| `/api/context/rtk/test` | POST | Gudanar da samfoti/gwajin RTK a kan bayanan rubutu |
| `/api/context/rtk/raw-output/[id]` | GET | Karanta ɗanyen fitarwa da aka ɓoye bayanansa kuma aka riƙe ta hanyar id na manuni |
| `/api/context/combos` | GET/POST | Jera/ƙirƙiri haɗin matsewa |
| `/api/context/combos/[id]` | GET/PUT/DELETE | Cikakkun bayanai/sabuntawa/share haɗin matsewa |
| `/api/context/combos/[id]/assignments` | GET/PUT | Sanya haɗin matsewa ga haɗin zaɓin hanya |
| `/api/context/analytics` | GET | Laƙabin nazarin matsewa |
### Sa-ido
| Ƙarshen hanya | Hanya | Bayani |
| ------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions` | GET | Bibiyar zaman da ke aiki |
| `/api/rate-limits` | GET | Iyakokin ƙima na kowane asusu |
| `/api/monitoring/health` | GET | Binciken lafiya + taƙaitaccen bayanin mai samarwa (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Duban gudanarwa ya haɗa da `credentialHealth`: ma'aunai guda-guda na ma'ajiyar bincike, `failedConnections` idan `failed>0`, da `staleDbNonOkCount` (`test_status` mai ɗorewa na SQLite, ba ma'aunin nan-take ba). Duba [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). |
| `/api/cache/stats` | GET/DELETE | Ƙididdigar ma'ajiya / sharewa |
| `/api/modality-bridge/stats` | GET | `attempts` na cikin-ƙwaƙwalwa, nasarori/`bridged`, gazawa, samun bayanai daga ma'ajiya, `totalLatencyMs`, `latencySamples`, `averageLatencyMs` mai amfani da yawan samfura a matsayin maƙasudi, da lokacin amfani na ƙarshe (yana sake farawa bayan sake kunna tsarin; tantancewar gudanarwa) |
| `/api/modality-bridge/video/runtime` | GET | Tsauraran binciken amintaccen loopback kafin tantancewar gudanarwa/bincike; samuwa da nau'ikan FFmpeg/ffprobe da aka tsabtace (ba a adanawa) |
| `/api/modality-bridge/video/extract` | POST | Dillalin bytes na cikin gida mai tantancewa da amintaccen loopback; shigarwar 50 MiB, jerin jiran aiki mai iyaka/fitarwar 32 MiB, ƙarfin `503`, yankewar haɗi `499`, wa'adin `504`; ba API ɗin loda fayil na jama'a ba ne |
### Ajiyar Bayanai & Fitarwa/Shigowa
| Endpoint | Hanya | Bayani |
| --------------------------- | ----- | ---------------------------------------------------------- |
| `/api/db-backups` | GET | Jera ajiyayyun bayanai da ake da su |
| `/api/db-backups` | PUT | Ƙirƙiri ajiyayyen bayanai da hannu |
| `/api/db-backups` | POST | Maido daga takamaiman ajiyayyen bayanai |
| `/api/db-backups/export` | GET | Sauke rumbun bayanai a matsayin fayil ɗin .sqlite |
| `/api/db-backups/import` | POST | Loda fayil ɗin .sqlite don maye gurbin rumbun bayanai |
| `/api/db-backups/exportAll` | GET | Sauke cikakken ajiyayyen bayanai a matsayin kundin .tar.gz |
### Aiki Tare da Gajimare
| Endpoint | Hanya | Bayani |
| ---------------------- | ----------- | ----------------------------- |
| `/api/sync/cloud` | Daban-daban | Ayyukan aiki tare da gajimare |
| `/api/sync/initialize` | POST | Fara aiki tare |
| `/api/cloud/*` | Daban-daban | Gudanar da gajimare |
### Tunnels
| Endpoint | Hanya | Bayani |
| -------------------------- | ----- | ---------------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET | Karanta matsayin shigarwa/gudanarwa na Cloudflare Quick Tunnel don dashboard |
| `/api/tunnels/cloudflared` | POST | Kunna ko kashe Cloudflare Quick Tunnel (`action=enable/disable`) |
| `/api/tunnels/ngrok` | GET | Karanta matsayin gudanarwa na ngrok Tunnel don dashboard |
| `/api/tunnels/ngrok` | POST | Kunna ko kashe ngrok Tunnel (`action=enable/disable`) |
### Kayan Aikin CLI
| Endpoint | Hanya | Bayani |
| ---------------------------------- | ----- | --------------------------- |
| `/api/cli-tools/claude-settings` | GET | Matsayin Claude CLI |
| `/api/cli-tools/codex-settings` | GET | Matsayin Codex CLI |
| `/api/cli-tools/droid-settings` | GET | Matsayin Droid CLI |
| `/api/cli-tools/openclaw-settings` | GET | Matsayin OpenClaw CLI |
| `/api/cli-tools/runtime/[toolId]` | GET | Gudanarwar CLI ta gama-gari |
Amsoshin CLI sun haɗa da: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
### Wakilan ACP
| Endpoint | Hanya | Bayani |
| ----------------- | ------ | ----------------------------------------------------------------------- |
| `/api/acp/agents` | GET | Jera duk wakilan da aka gano (ginannu + na musamman) tare da matsayinsu |
| `/api/acp/agents` | POST | Ƙara wakili na musamman ko sabunta ma'ajiyar gano wakilai |
| `/api/acp/agents` | DELETE | Cire wakili na musamman ta amfani da sigar tambaya ta `id` |
Amsar GET ta ƙunshi `agents[]` (id, name, binary, version, installed, protocol, isCustom) da `summary` (total, installed, notFound, builtIn, custom).
### Juriyar Matsala da Iyakokin Buƙata
| Endpoint | Hanya | Bayani |
| --------------------------------- | --------- | ---------------------------------------------------------------------------------------------------- |
| `/api/resilience` | GET/PATCH | Samo/sabunta layin jiran buƙatu, lokacin dakatar da haɗi, katsewar mai samarwa, da saitunan jira |
| `/api/resilience/reset` | POST | Sake saita masu katse da'irar masu samarwa |
| `/api/resilience/model-cooldowns` | GET | Jera duk kulle-kullen kowane-(provider, connection, model) masu aiki, an tsara su bisa sauran lokaci |
| `/api/resilience/model-cooldowns` | DELETE | Share kullewar model — jiki `{provider, model}` ko `{all: true}` don share komai |
| `/api/rate-limits` | GET | Matsayin iyakar buƙata na kowane asusu |
| `/api/rate-limit` | GET | Tsarin iyakar buƙata na duniya |
> Dukkan hanyoyin `/api/resilience/*` guda huɗu suna buƙatar **tabbatar da izinin gudanarwa** (`requireManagementAuth`). Duba [Juriyar Matsala (cikakke)](#resilience-extended) don cikakken bayani kan katsewar mai samarwa da lokacin dakatar da haɗi da kuma kullewar model.
### Evals
| Endpoint | Hanya | Bayani |
| ------------ | -------- | --------------------------------------------- |
| `/api/evals` | GET/POST | Jera tarin gwaje-gwaje / gudanar da kimantawa |
### Manufofi
| Endpoint | Hanya | Bayani |
| --------------- | --------------- | --------------------------- |
| `/api/policies` | GET/POST/DELETE | Gudanar da manufofin turawa |
### Bin Ƙa'idoji
| Endpoint | Hanya | Bayani |
| --------------------------- | ----- | -------------------------------------------- |
| `/api/compliance/audit-log` | GET | Rajistar binciken bin ƙa'idoji (N na ƙarshe) |
### v1beta (Mai Jituwa da Gemini)
| Endpoint | Hanya | Bayani |
| -------------------------- | ----- | ------------------------------------ |
| `/v1beta/models` | GET | Jera models a tsarin Gemini |
| `/v1beta/models/{...path}` | POST | Endpoint na Gemini `generateContent` |
Waɗannan endpoints suna kwaikwayon tsarin API na Gemini ga clients waɗanda ke tsammanin jituwar Gemini SDK ta asali.
### APIs na Ciki / Tsari
| Endpoint | Method | Bayani |
| ------------------------ | ------ | ------------------------------------------------------------------- |
| `/api/init` | GET | Duba farawar manhaja (ana amfani da shi a fara amfani) |
| `/api/tags` | GET | Alamomin samfurori masu dacewa da Ollama (don abokan hulɗar Ollama) |
| `/api/restart` | POST | Jawo sake kunna sabar cikin tsari |
| `/api/shutdown` | POST | Jawo kashe sabar cikin tsari |
| `/api/system/env/repair` | POST | Gyara masu canjin muhalli na mai samar da OAuth |
> **Lura:** Tsarin yana amfani da waɗannan endpoints ne a ciki ko kuma don dacewa da abokan hulɗar Ollama. Yawanci masu amfani na ƙarshe ba sa kiran su.
### Gyaran Muhallin OAuth _(v3.6.1+)_
```bash
POST /api/system/env/repair
Content-Type: application/json
{
"provider": "claude-code"
}
```
Yana gyara masu canjin muhalli na OAuth da suka ɓace ko suka lalace ga takamaiman mai samarwa. Yana mayar da:
```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"
}
```
---
## Mayar da Sauti Zuwa Rubutu
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
```
Mayar da fayilolin sauti zuwa rubutu ta amfani da duk wani mai samar da STT da aka saita. Sashen farko na hanyar yana zaɓar mai samarwa na asali (`openai/…`, `deepgram/…`). Ƙofofin da ke sake fitar da samfurin wani mai samarwa suna amfani da cikakken 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 model ids:** `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.
**Tsare-tsaren da ake goyon baya:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
---
## Daidaituwa da Ollama
Ga abokan hulɗa da ke amfani da tsarin API na Ollama:
```bash
# Wurin ƙarshen taɗi (tsarin Ollama)
POST /v1/api/chat
# Jerin samfura (tsarin Ollama)
GET /api/tags
```
Ana fassara buƙatu ta atomatik tsakanin tsarin Ollama da tsare-tsaren ciki.
## Laƙabban VS Code Masu Token / Marasa Header
Yi amfani da waɗannan laƙabban lokacin da haɗin kai ba zai iya saka header na `Authorization` ba kuma yana buƙatar a saka maɓallin API a cikin URL na tushe.
```bash
# Laƙabin kundin bayanai irin na OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models
# Laƙabban taɗi irin na OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses
# Laƙabban 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:
- Laƙabban masu token suna sake amfani da masu sarrafa buƙatu iri ɗaya da `/v1/*` da `/api/tags`; tsarin amsoshin yana kasancewa iri ɗaya.
- Fi son amfani da `Authorization: Bearer ...` a duk lokacin da abokin hulɗa ke goyon bayan headers na musamman.
- Tokens da ke cikin URL na iya bayyana a cikin rajistan ayyukan reverse-proxy, tarihin burauza, da telemetry a wajen OmniRoute. Ɗauke su a matsayin zaɓin daidaituwa, ba hanyar tantancewa ta asali ba.
---
## Telemetry
```bash
# Samu taƙaitaccen 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 maɓallan 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 schema** (`setBudgetSchema`): Ana buƙatar `apiKeyId`; aƙalla ɗaya daga cikin `dailyLimitUsd`, `weeklyLimitUsd`, ko `monthlyLimitUsd` dole ne ya fi sifili. Filayen zaɓi: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Tsohon tsarin `{keyId, limit, period}` yana mayar da `400 Bad Request`.
## Iyakokin Token
Kasafin **token** na kowace maɓallin API (wanda ya bambanta da Kasafin kuɗi na USD da ke sama). Ana tilasta su kai tsaye a hanyar buƙata: idan amfanin maɓalli a taga na yanzu ya kai iyakarsa, ana ƙin buƙatun da `429 Too Many Requests`. Ana iya iyakance iyakoki ga takamaiman `model`, `provider`, ko a yi amfani da su a matakin `global` a duk faɗin maɓallin; idan iyakoki da yawa sun dace da wata buƙata, mafi tsananinsu ne zai yi aiki.
```bash
# Jera iyakokin token na maɓalli (ya haɗa da amfanin taga na yanzu)
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
}
# Share iyakar token ta amfani da id
DELETE /api/usage/token-limits?id=tl-abc
```
> **Bayanan schema** (`setTokenLimitSchema`): Ana buƙatar `apiKeyId` da `scopeType` (`model` | `provider` | `global`). Ana buƙatar `scopeValue` sai dai idan `scopeType` ya kasance `global` (misali, id na model don iyakar `model`, ko id na provider don iyakar `provider`). Dole ne `tokenLimit` ya kasance cikakkiyar lamba mai kyau (ana sauya ta daga string). Na zaɓi: `id` (a bar shi don ƙirƙirawa, a bayar da shi don sabuntawa), `resetInterval` (`daily` | `weekly` | `monthly`, tsoho shi ne `monthly`), `resetTime` (`HH:MM`), `enabled` (tsoho shi ne `true`). Amsoshin `GET` suna ƙara wa kowace iyaka `tokensUsed`, `remaining`, `windowStart`, `periodStartAt`, da `nextResetAt`. Wannan endpoint ne na ajin gudanarwa (ana tilasta auth daga tsakiya ta hanyar authz pipeline).
## Sarrafa Buƙata
1. Client yana aika buƙata zuwa `/v1/*`
2. Route handler yana kiran `handleChat`, `handleEmbedding`, `handleAudioTranscription`, ko `handleImageGeneration`
3. Ana tantance model (provider/model kai tsaye ko alias/combo)
4. Ana zaɓar credentials daga DB na gida tare da tace samuwar account
5. Don chat: `handleChatCore` yana duba semantic/signature cache kuma yana tantance saitunan compression na combo
6. Proactive compression yana gudana kafin fassarar provider idan an kunna shi (`lite`, Caveman, RTK, ko waɗanda aka jera tare)
7. Provider executor yana aika buƙatar upstream
8. Ana fassara amsa zuwa tsarin client (chat) ko a mayar da ita yadda take (embeddings/images/audio)
9. Ana adana usage, bayanan nazarin compression, da request logs
10. Ana amfani da fallback idan an samu kurakurai bisa ga dokokin combo
Cikakken bayanin architecture: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)
---
## Gudanar da Combo
Hakanan ana iya haɗa routing combos na babban mataki (waɗanda aka riga aka taƙaita ƙarƙashin `/api/combos*`) 1:1 daga model id pattern, wanda ke ba da damar karkatar da OpenAI-style model id zuwa combo ba tare da bayyanawa ba.
| Hanya | Path | Bayani |
| ------ | -------------------------------- | ------------------------------------------------------------------------------- |
| GET | `/api/model-combo-mappings` | Jera duk mappings na model→combo |
| POST | `/api/model-combo-mappings` | Ƙirƙiri mapping — body: `{pattern, comboId, priority?, enabled?, description?}` |
| GET | `/api/model-combo-mappings/[id]` | Dawo da mapping guda ɗaya |
| PUT | `/api/model-combo-mappings/[id]` | Sabunta fields na mapping da ke akwai |
| DELETE | `/api/model-combo-mappings/[id]` | Cire mapping |
**Auth:** management session/API key (`requireManagementAuth`).
---
## Webhooks
Biyan kuɗin shiga na webhook masu fita don abubuwan da suka faru na OmniRoute (kammala buƙata, ƙarewar ƙayyadadden amfani, sauya maɓalli, da sauransu).
| Hanya | Path | Bayani |
| ------ | ------------------------- | --------------------------------------------------------------------------- |
| GET | `/api/webhooks` | Jera webhooks (an ɓoye sirrika zuwa `<prefix>...`) |
| POST | `/api/webhooks` | Ƙirƙiri webhook — body: `{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 payload na gwaji zuwa URL ɗin webhook sannan a dawo da matsayin isarwa |
**Tabbatarwa:** zaman gudanarwa/maɓallin API (`requireManagementAuth`).
---
## Maɓallan da Aka Yi Rajista (Gudanarwa ta Atomatik)
Ƙaramin tsarin gudanar da maɓalli ta atomatik ne ke amfani da su don bayarwa da sauya maɓallan API ta hanyar mai samarwa/asusun da ke goyon baya, tare da ƙayyadaddun amfani na kullum/sa'a-sa'a.
| Hanya | Path | Bayani |
| ------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/v1/registered-keys` | Jera maɓallan da aka yi rajista (prefix da aka ɓoye kawai) |
| POST | `/api/v1/registered-keys` | Bayar da sabon maɓalli da aka yi rajista — body: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Yana dawo da ainihin maɓallin **sau ɗaya**. Yana dawo da `429` idan an ƙi saboda ƙayyadadden amfani. |
| GET | `/api/v1/registered-keys/[id]` | Dawo da metadata na maɓallin da aka yi rajista (ba tare da ainihin maɓallin ba) |
| DELETE | `/api/v1/registered-keys/[id]` | Soke maɓallin da aka yi rajista |
| POST | `/api/v1/registered-keys/[id]/revoke` | Takamaiman endpoint na sokewa (tasirinsa iri ɗaya ne da DELETE) |
**Tabbatarwa:** maɓallin Bearer API (`isAuthenticated`). Duba kuma `/v1/quotas/check` da `/v1/issues/report`.
---
## Ka'idar Agents
Ayyukan wakilan cloud (Claude Code, Codex Cloud, OpenHands, da sauransu) waɗanda ake aiwatarwa daga nesa a madadin masu amfani da OmniRoute.
| Hanya | Path | Bayani |
| ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/v1/agents/tasks` | Jera ayyuka — `?provider=`, `?status=`, `?limit=` na zaɓi ne (1–500, tsoho 50) |
| POST | `/api/v1/agents/tasks` | Ƙirƙiri aiki — `CreateCloudAgentTaskSchema` na tantance body (`providerId`, `prompt`, `source`, `options?`). Yana mayar da `201` tare da task envelope |
| DELETE | `/api/v1/agents/tasks?id=...` | Share aiki |
| GET | `/api/v1/agents/tasks/[id]` | Karanta aiki — yana sabunta status kai-tsaye daga wakilin cloud na upstream idan an saita `external_id` |
| POST | `/api/v1/agents/tasks/[id]` | Aiki mai bambance nau'i: `{action: "approve"}`, `{action: "message", message}`, ko `{action: "cancel"}` |
| DELETE | `/api/v1/agents/tasks/[id]` | Share takamaiman aiki ta id |
> **Auth:** ana buƙatar auth na gudanarwa a kowace hanya (`requireCloudAgentManagementAuth`). Kafin v3.8.0 waɗannan ba sa buƙatar tantancewa — duba commit `588a0333` don canjin da ya karya dacewa.
```bash
# Ƙirƙiri aikin cloud 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":"..."}}'
```
---
## Proxies na Gudanarwa
Proxies na HTTP(S)/SOCKS masu fita waɗanda za a iya warewa ga providers, accounts, ko kuma a duniya baki ɗaya.
| Hanya | Path | Bayani |
| ------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/management/proxies` | Jera proxies (tare da `?id=` yana mayar da guda ɗaya; tare da `?id=&where_used=1` yana mayar da jadawalin warewa) |
| POST | `/api/v1/management/proxies` | Ƙirƙiri proxy — `createProxyRegistrySchema` na tantance body |
| PATCH | `/api/v1/management/proxies` | Sabunta proxy — `updateProxyRegistrySchema` na tantance body (yana buƙatar `id`) |
| DELETE | `/api/v1/management/proxies?id=...&force=1` | Share proxy (yi amfani da `force=1` don cire warewar da aka yi) |
| GET | `/api/v1/management/proxies/assignments` | Jera warewa — ana iya tacewa ta `proxy_id`, `scope`, `scope_id`; aika `resolve_connection_id=<id>` don gano proxy mai aiki na wata connection |
| PUT | `/api/v1/management/proxies/assignments` | Ware — `proxyAssignmentSchema` na tantance body (`{scope, scopeId?, proxyId?}`). Yana share dispatcher cache |
| PUT | `/api/v1/management/proxies/bulk-assign` | Ware da yawa — `bulkProxyAssignmentSchema` na tantance body (`{scope, scopeIds[], proxyId?}`) |
| GET | `/api/v1/management/proxies/health?hours=24` | Haɗa bayanan lafiyar proxy (ƙididdigar nasara/rashin nasara, latency) cikin wani wa'adin lokaci |
**Auth:** management session/API key a kowace route (`requireManagementAuth`).
> `POST /api/v1/management/proxies/[id]/assignments` da `POST /api/v1/management/proxies/[id]/health` da ke cikin bayanin aikin ana samar da su ta hanyar routes marasa zurfi na `/assignments` da `/health` da aka nuna a sama — babu subroutes na kowane id a cikin codebase.
---
## Juriya (faɗaɗɗe)
OmniRoute yana samar da hanyoyi masu zaman kansu guda uku don magance gazawar wucin gadi; wuraren sarrafawa da ke ƙasa suna ba masu gudanarwa damar karantawa da sauya saitunansu:
| Iyaka | Ma'ajiyar hali | Karantawa | Sake saiti / gogewa |
| ------------------------ | -------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------- |
| Mai katsewar mai samarwa | `domain_circuit_breakers` + cikin ƙwaƙwalwar ajiya | `/api/monitoring/health` | `POST /api/resilience/reset` |
| Lokacin jiran haɗi | `rateLimitedUntil` a kan haɗin mai samarwa | `/api/rate-limits`, `/api/providers/[id]` | (yana sake kunnawa a hankali; goge ta hanyar PUT na mai samarwa) |
| Kulle samfurin | Rijistar samuwar samfuri a cikin ƙwaƙwalwar ajiya | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` |
`PATCH /api/resilience` yana karɓar sauye-sauyen mai katsewar mai samarwa ƙarƙashin `providerBreaker.oauth` da `providerBreaker.apikey`. Kowane bayanin martaba yana goyon bayan `degradationThreshold`, `failureThreshold`, da `resetTimeoutMs`; ana kuma nuna waɗannan filaye a Dashboard → Settings → Resilience.
```bash
# Goge kullen samfuri 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"}'
# Goge dukkan kulle-kullen
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-d '{"all":true}'
```
Don cikakken bayani na ra'ayi da tsoffin saitunan mai katsewa: duba [`CLAUDE.md`](../../CLAUDE.md) → "Resilience Runtime State".
---
## Ƙwarewa
Tsarin ƙwarewa don faɗaɗa OmniRoute da masu sarrafa umarni na musamman waɗanda za a iya aiwatarwa, tare da haɗe-haɗen kasuwar ƙwarewa.
| 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 rarrabawa zuwa shafuka |
| GET | `/api/skills/[id]` | Samo ƙ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 ɗanyen bayani — jiki: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
| GET | `/api/skills/executions` | Jera aiwatar da ƙwarewa na baya-bayan nan (tarihin dubawa tare da bayanan shigarwa/fitarwa/tsawon lokaci) |
| GET | `/api/skills/marketplace?q=...` | Bincike/jerin shahararru daga kasuwar SkillsMP (yana buƙatar saitin `skillsmpApiKey`) |
| POST | `/api/skills/marketplace/install` | Girka ƙwarewa ta amfani da id daga SkillsMP |
| GET | `/api/skills/skillssh?q=&limit=` | Bincika rijistar skills.sh |
| POST | `/api/skills/skillssh/install` | Girka ƙwarewa ta amfani da id daga skills.sh |
**Tabbatar da izini:** zaman gudanarwa/makullin API. Hanyoyin binciken kasuwa suna karɓar ko dai izinin gudanarwa ko makullin Bearer API (`isAuthenticated`).
---
## Ƙwaƙwalwa
Ma’ajiyar ƙwaƙwalwar tattaunawa/bayanan gaskiya mai ɗorewa, wadda aka keɓance bisa kowane API key / session.
| Hanya | Path | Bayani |
| ------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/memory` | Jera ƙwaƙwalwa — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, tare da tsarin shafuka na `offset/limit` ko `page/limit` |
| POST | `/api/memory` | Ƙirƙiri ƙwaƙwalwa — Zod na tantance body: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET | `/api/memory/[id]` | Dawo da ƙwaƙwalwa guda ɗaya |
| DELETE | `/api/memory/[id]` | Share ƙwaƙwalwa |
| GET | `/api/memory/health` | Lafiyar ƙaramin tsarin ƙwaƙwalwa (haɗin DB, backend na embeddings, matsayin vector index) |
**Auth:** management session/API key (`requireManagementAuth`). Ƙimar enum ta `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (duba `MemoryType` a cikin `src/lib/memory/types.ts`).
---
## MCP Server
OmniRoute yana zuwa da Model Context Protocol server da aka saka a ciki mai transports guda 3 (stdio, SSE, streamable-http) da tools masu keɓaɓɓun scopes. Endpoints na dashboard da ke ƙasa suna karanta bayanan matsayi/audit kuma suna wakiltar HTTP transports.
| Hanya | Path | Bayani |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Heartbeat, transport, yanayin kasancewa online, kira na ƙarshe, manyan tools, ƙimar nasarar sa’o’i 24 |
| GET | `/api/mcp/tools` | Jerin MCP tools tare da `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
| GET | `/api/mcp/sse` | Buɗe SSE stream don SSE transport (yana dawo da `503` idan an kashe MCP ko transport bai dace ba) |
| POST | `/api/mcp/sse` | Aika JSON-RPC frame a kan SSE transport |
| GET | `/api/mcp/stream` | Buɗe ɓangaren SSE na Streamable HTTP transport (saƙonnin da server ya fara aikawa) |
| POST | `/api/mcp/stream` | Aika JSON-RPC frame a kan Streamable HTTP transport |
| DELETE | `/api/mcp/stream` | Ƙare Streamable HTTP session |
| GET | `/api/mcp/audit` | Nemi cikin audit log — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | Haɗa ƙididdigar audit (jimilla, ƙimar nasara, matsakaicin tsawon lokaci, manyan tools) |
**Auth:** transports na `sse`/`stream` suna bin keɓaɓɓen tsarin auth na MCP (Bearer API key mai scope na `mcp`); routes na `status`/`tools`/`audit*` ana iya karanta su daga dashboard (ba a buƙatar ƙarin auth bayan samun damar dashboard host).
> Dukkan HTTP transports biyu suna ƙarƙashin ikon `settings.mcpEnabled` da `settings.mcpTransport` — rashin daidaituwar transport yana dawo da `400`, yanayin kashe MCP yana dawo da `503`.
---
## Sabar A2A
OmniRoute yana samar da endpoint na A2A (Agent-to-Agent) JSON-RPC 2.0 tare da wrapper na REST don dubawa/amfani da dashboard.
### JSON-RPC
```bash
POST /a2a
Authorization: Bearer your-api-key # na zaɓi ne sai dai 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 goyon baya (duk suna ƙarƙashin `settings.a2aEnabled`):
| Hanya | Bayani |
| ---------------- | ------------------------------------------------------------------------ |
| `message/send` | Gudanar da ƙwarewa kai tsaye; yana dawo da `{task, artifacts, metadata}` |
| `message/stream` | Gudanar da wannan jerin ƙwarewar ta hanyar SSE mai gudana |
| `tasks/get` | Ɗauko aiki ta amfani da `taskId` |
| `tasks/cancel` | Soke aiki ta amfani da `taskId` |
Ƙwarewar da aka tanada: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.
### Katin Wakili
```bash
GET /.well-known/agent.json
```
Yana dawo da katin wakilin A2A na jama'a (suna, bayani, iyawa, kundin ƙwarewa, tsarin auth) — ana adana shi a cache na jama'a na awa 1. Ba a buƙatar auth.
### Mataimakan REST
| Hanya | Path | Bayani |
| ----- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| GET | `/api/a2a/status` | An kunna A2A + ƙididdigar ayyuka + taƙaitaccen katin wakili da ke cache |
| GET | `/api/a2a/tasks` | Jera ayyuka — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST | `/api/a2a/tasks` | (Ba a aiwatar da shi a matsayin mataimakin REST ba — ƙirƙira ta JSON-RPC `message/send`) |
| GET | `/api/a2a/tasks/[id]` | Ɗauko aiki guda ɗaya |
| POST | `/api/a2a/tasks/[id]/cancel` | Soke aiki |
**Auth:** mataimakan REST suna aiki ba tare da auth na gudanarwa ba (dashboard na iya karantawa); hanyar JSON-RPC `/a2a` tana amfani da Bearer `OMNIROUTE_API_KEY` idan an saita shi.
---
## Cloud, Evals & Assess
| Hanya | Path | Bayani |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Tabbatar da maɓallin Bearer sannan a dawo da haɗin masu samarwa da aka ɓoye wani ɓangarensa + laƙabin samfura ga abokan cinikin daidaitawar cloud |
| POST | `/api/cloud/credentials/update` | Sabunta bayanan shaidar da aka rufaffen ga mai samarwa da aka daidaita da cloud |
| POST | `/api/cloud/model/resolve` | Daidaita id na samfuri na ma'ana zuwa takamaiman mai samarwa/samfuri ta amfani da teburin routing na gida |
| GET | `/api/cloud/models/alias` | Jera laƙabin samfura kamar yadda aka fallasa su ga daidaitawar cloud |
| GET | `/api/assess` | Karanta sabbin rabe-raben tantancewa (ga kowane mai samarwa/samfuri) |
| POST | `/api/assess` | Gudanar da tantancewa — body: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Jera tarin eval da aka tanada + gudanarwa na baya-bayan nan |
| POST | `/api/evals` | Fara gudanar da eval |
| POST | `/api/evals/suites` | Ƙirƙiri tarin eval na musamman — ana tantance body ta `evalSuiteSaveSchema` |
| GET | `/api/evals/suites/[id]` | Ɗauko tarin eval na musamman |
**Auth:** `/api/cloud/auth` yana tantance maɓallin Bearer kai tsaye; sauran hanyoyin `/api/cloud/*`, `/api/evals/*`, da `/api/assess` suna buƙatar zaman gudanarwa/maɓallin API. POST na `/api/assess` yana amfani da `validateBody` tare da tsarin scope na discriminated-union.
---
## Gudanar da ACP (Agent Client Protocol)
a matsayin ƙananan matakai. Waɗannan mashigai suna gudanar da gano wakilan ACP da kuma rajistar wakilai na musamman.
| Hanya | Tafarki | Bayani |
| ------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/acp/agents` | Jera duk sanannun wakilan CLI (ginannu a ciki + na musamman) tare da matsayin shigarwa, sigar, da binary |
| POST | `/api/acp/agents` | Yi rajistar wakilin ACP na musamman ko sabunta cache — jiki: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` ko `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Cire wakilin ACP na musamman — ma'aunin 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 (cookie na dashboard mai suna `auth_token`) ko
maɓallin API mai ikon gudanarwa.
Duba [Tsarin ACP](../frameworks/ACP.md) don cikakken bayani.
---
## Nazari & Sa-ido
Mashigan nazari na ainihin lokaci don sa ido kan zaɓin hanya, matse bayanai, da bambancin masu samarwa.
Waɗannan ne ke tallafa wa shafukan `/dashboard/analytics/*`.
### Nazarin zaɓin hanya ta atomatik
| Hanya | Tafarki | Bayani |
| ----- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| GET | `/api/analytics/auto-routing` | Haɗaɗɗun ƙididdigar zaɓin hanya ta atomatik: jimillar kira, rabon dabaru, rabon 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 matse bayanai
| Hanya | Tafarki | Bayani |
| ----- | ---------------------------- | -------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/compression` | Haɗaɗɗun ƙididdigar matse bayanai: tokens da aka adana, % na tanadi, rabon yanayi, amfani da injin |
**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 | Tafarki | Bayani |
| ----- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/diversity` | Bibiyar bambanci bisa entropy na Shannon: tana hana gazawar wuri guda ta hanyar auna yadda amfani ya bazu tsakanin 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 ikon gudanarwa.
---
## Ayyukan Admin
Wuraren haɗi na admin kawai don gudanar da ayyuka.
| Hanya | Path | Bayani |
| ----- | ------------------------ | ------------------------------------------------------------------------------------------------------ |
| GET | `/api/admin/concurrency` | Karanta iyakokin ayyukan lokaci guda na yanzu (na gaba ɗaya + na kowane mai samarwa) |
| POST | `/api/admin/concurrency` | Sabunta iyakokin ayyukan lokaci guda — body: `{global?: number, perProvider?: Record<string, number>}` |
**Tabbatar da izini:** Ana buƙatar zaman gudanarwa mai ikon admin.
---
## Gudanar da Kayan Aikin CLI
Gudanar da kayan aikin CLI da ke haɗuwa da OmniRoute (antigravity, chipotle, commandCode,
devin-cli, da sauransu). Duba [Manazartar Masu Samarwa](./PROVIDER_REFERENCE.md) don cikakken jerin.
| Hanya | Path | Bayani |
| ----- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/cli-tools/all-statuses` | Matsayin duk kayan aikin CLI (an girka, sigar, lokacin ƙarshe da aka gani) |
| GET | `/api/cli-tools/status` | Cikakken matsayin kayan aikin CLI guda ɗaya (tambayar `?tool=`) |
| POST | `/api/cli-tools/apply` | Rubuta config da aka samar na wani kayan aiki (`dryRun` yana nuna samfoti; `422` + `containerEphemeralTarget` idan yana cikin container; `migration` yana nuna tsohon Codex YAML) |
| GET | `/api/cli-tools/backups` | Jera ajiyayyun kwafin saitunan kayan aikin CLI |
| POST | `/api/cli-tools/backups` | Ƙirƙiri ajiyayyen kwafin duk saitunan kayan aikin CLI |
| POST | `/api/cli-tools/backups` | Mayarwa: wannan endpoint ɗin tare da `{tool, backupId}` a cikin body yana mayar da wannan ajiyayyen kwafin |
| GET | `/api/cli-tools/antigravity-mitm` | Matsayin proxy na Antigravity MITM (kayan aikin CLI na "antigravity-mitm") |
| POST | `/api/cli-tools/antigravity-mitm/alias` | Saita aliases na antigravity-mitm |
**Tabbatar da izini:** Ana buƙatar zaman gudanarwa.
---
## Ƙwarewar Wakilai
Gudanar da ƙwarewar wakilan AI (kama da custom GPTs na OpenAI amma na wakilai).
| Hanya | Path | Bayani |
| ------ | ---------------------------- | ----------------------------------------------------------------------------------------------- |
| GET | `/api/agent-skills` | Jera duk ƙwarewar wakilai (ginannu a ciki + na musamman) |
| GET | `/api/agent-skills/[id]` | Samo takamaiman ƙwarewar wakili |
| POST | `/api/agent-skills` | Ƙirƙiri ƙwarewar wakili ta musamman — body: `{name, description, prompt, model?, temperature?}` |
| PUT | `/api/agent-skills/[id]` | Sabunta ƙwarewar wakili ta musamman |
| DELETE | `/api/agent-skills/[id]` | Share ƙwarewar wakili ta musamman |
| GET | `/api/agent-skills/[id]/raw` | Samo ainihin prompt + metadata (ba tare da aiwatarwa ba) |
| POST | `/api/agent-skills/generate` | Amfani da AI don samar da sabuwar ƙwarewa daga bayanin harshen ɗan Adam |
**Tabbatar da izini:** Ana buƙatar zaman gudanarwa ko API key mai ikon gudanarwa.
---
## Gudanar da Cache
Gudanar da semantic cache da reasoning cache.
| Hanya | Path | Bayani |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| GET | `/api/cache` | Taƙaitaccen bayani kan cache: jimillar entries, hit rate, girman da yake ɗauka a disk |
| GET | `/api/cache/entries` | Jera entries da aka adana a cache (tare da pagination) |
| DELETE | `/api/cache/entries` | Share entries na cache (a tace ta query parameters) |
| GET | `/api/cache/stats` | Cikakkun ƙididdigar cache (na kowane provider da kowane model) |
| GET | `/api/cache/reasoning` | Matsayin reasoning cache (don sake kunna reasoning) |
| DELETE | `/api/cache/reasoning` | Share reasoning cache — query params: `?toolCallId=<id>` (guda ɗaya) ko `?provider=<p>` ko babu params (dukkansu) |
**Tabbatar da izini:** Ana buƙatar management session.
---
## Tsarin Memory
Gudanar da memory mai ɗorewa (FTS5 + vector embeddings).
| Hanya | Path | Bayani |
| ------ | ------------------ | ------------------------------------------------------------------------------ |
| GET | `/api/memory` | Jera entries na memory (a tace ta scope, type, da search query) |
| POST | `/api/memory` | Ƙirƙiri sabon entry na memory — body: `{scope, type, content, metadata?}` |
| GET | `/api/memory/[id]` | Samo takamaiman entry na memory |
| PUT | `/api/memory/[id]` | Sabunta entry na memory |
| DELETE | `/api/memory/[id]` | Share entry na memory |
| GET | `/api/memory?q=` | Bincika memory (FTS5 + vector) — ana haɗa stats a cikin response ɗin guda ɗaya |
**Tabbatar da izini:** Ana buƙatar management session ko API key mai management scope.
---
## Webhooks
Gudanar da rajistar webhook don events.
| Hanya | Path | Bayani |
| ------ | ------------------------------- | -------------------------------------------------------------------- |
| GET | `/api/webhooks` | Jera duk rajistar webhook |
| POST | `/api/webhooks` | Ƙirƙiri rajistar webhook — body: `{url, events[], secret?, active?}` |
| GET | `/api/webhooks/[id]` | Samo takamaiman rajistar webhook |
| PUT | `/api/webhooks/[id]` | Sabunta rajistar webhook |
| DELETE | `/api/webhooks/[id]` | Share rajistar webhook |
| GET | `/api/webhooks/[id]/deliveries` | Jera tarihin isarwa na webhook (success/failure log) |
| POST | `/api/webhooks/[id]/test` | Aika event na gwaji zuwa webhook |
**Tabbatar da izini:** Ana buƙatar management session.
Duba [Tsarin Webhooks](../frameworks/WEBHOOKS.md) don samun cikakken bayani kan nau'ikan events.
---
## Tsarin Skills
Sarrafa Skills (tsarin faɗaɗa ayyukan wakili).
| Hanya | Tafarki | Bayani |
| ------ | ------------------------ | ---------------------------------------------------------------------------------- |
| GET | `/api/skills` | Jera duk Skills da aka shigar (na ciki + na musamman) |
| POST | `/api/skills/install` | Shigar da Skill daga tafarkin gida ko URL |
| DELETE | `/api/skills/[id]` | Cire Skill |
| PUT | `/api/skills/[id]` | Kunna ko kashe Skill — jiki: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST | `/api/skills/executions` | Gudanar da Skill — jiki: `{skillName, apiKeyId, input?, sessionId?}` |
| GET | `/api/skills/executions` | Jera tarihin gudanarwa na duk Skills (tace da `?apiKeyId=`) |
**Tabbatar da izini:** Ana buƙatar zaman gudanarwa ko maɓallin API mai iyakar gudanarwa.
Duba [Tsarin Skills](../frameworks/SKILLS.md) don cikakkun bayanai.
---
## Plugins
Sarrafa plugins na OmniRoute (faɗaɗa ayyuka daga wasu kamfanoni).
| Hanya | Tafarki | Bayani |
| ------ | ---------------------------------- | --------------------------------- |
| GET | `/api/plugins` | Jera plugins da aka shigar |
| POST | `/api/plugins/marketplace/install` | Shigar da plugin daga marketplace |
| DELETE | `/api/plugins/[name]` | Cire plugin |
| POST | `/api/plugins/[name]/activate` | Kunna plugin |
| POST | `/api/plugins/[name]/deactivate` | Kashe plugin |
| GET | `/api/plugins/[name]/config` | Samu saitunan plugin |
| PUT | `/api/plugins/[name]/config` | Sabunta saitunan plugin |
**Tabbatar da izini:** Ana buƙatar zaman gudanarwa.
Duba [Tsarin Plugins](../frameworks/PLUGIN_SDK.md) don cikakkun bayanai.
---
## Shadow Routing
Kwatancen masu samarwa ta Shadow / A-B **ba wata kebantacciyar REST surface ba ce** — ana saita ta ne ta hanyar combo routing (duba [Auto-Combo](../routing/AUTO-COMBO.md)). Ana samar da ma'aunin kwatance na kowane combo ta `GET /api/combos/metrics`.
---
## Guardrails
Bincika guardrails na lokacin aiki (gano PII, gano shigar da umarni ta ɓoye, haɗa hangen nesa). Guardrails suna aiki a kan kowace buƙata; ana iya ficewa daga gare su ga kowane kira ta amfani da kan buƙatar `x-omniroute-disabled-guardrails` — babu hanyar kunnawa/kashewa da ake adanawa.
| Hanya | Tafarki | Bayani |
| ----- | ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| GET | `/api/guardrails` | Jera guardrails da aka yi wa rajista da matsayinsu (suna / an kunna / fifiko) |
| POST | `/api/guardrails/test` | Gudanar da gwajin bushe na bututun kafin-kira a kan samfurin shigarwa — jiki: `{input, disabledGuardrails?}` |
**Tabbatar da izini:** Ana buƙatar zaman gudanarwa.
Duba [Tsaro > Guardrails](../security/GUARDRAILS.md) don cikakkun bayanai.
---
---
## Tantance Shaida
Duba [Tantance Shaidar Gudanarwa](../guides/MANAGEMENT-AUTH.md) don nau'ikan bayanan shaidar guda huɗu (zaman dashboard, token na CLI na gida, Token Samun Dama na `oma_live_…`, maɓallin API mai iyakar gudanarwa) da yadda suka bambanta da maɓallan inference.
- Hanyoyin dashboard (`/dashboard/*`) suna amfani da cookie na `auth_token`
- Shiga yana amfani da hash ɗin kalmar sirri da aka adana; idan hakan bai yiwu ba, sai a yi amfani da `INITIAL_PASSWORD`
- Ana iya kunna ko kashe `requireLogin` ta hanyar `/api/settings/require-login`
- Hanyoyin `/v1/*` na iya buƙatar maɓallin API na Bearer idan `REQUIRE_API_KEY=true`
- “token na gudanarwa” / “maɓallin API mai iyakar gudanarwa” a cikin wannan bayani yana nufin ɗaya daga cikin nau'ikan da ke cikin wancan jagorar — ba wani ƙarin nau'in sirri marar bayani ba
> **Canji mai karya dacewa (v3.8.0)** — `/api/v1/agents/tasks/*` da wuraren ƙarshen gudanar da cooldown yanzu suna buƙatar **tantance shaidar gudanarwa** (cookie na dashboard na `auth_token` ko maɓallin API mai iyakar gudanarwa). Abokan ciniki da a baya suke kiran waɗannan hanyoyi ba tare da tantance shaida ba za su karɓi `401 Unauthorized`. Duba commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).
Reference in New Issue View Git Blame Copy Permalink