OmniRoute/docs/i18n/ha/docs/reference/API_REFERENCE.md

API_REFERENCE (Hausa)

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

---

---

title: "Manazartar API" version: 3.8.51 lastUpdated: 2026-08-31

Manazartar API

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

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 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
• Hayar Zama Mai Sarrafawa ta Keɓance
• Embeddings
• Samar da Hoto
• OCR na Takardu
• Jerin Samfura
• Manifest ɗin Plugin na Mai Bayarwa
• Endpoints na Daidaituwa
• API na Fayiloli
• API na Batches
• API na Bincike
• Yawo ta WebSocket
• Rahoton Ƙayyadaddun Amfani da Matsaloli
• Ma'ajiyar Wucin Gadi ta Ma'ana
• Dashboard da Gudanarwa
• Gudanar da Combo
• Webhooks
• Maɓallan da Aka Yi Rajista (Gudanarwa ta Atomatik)
• Ka'idar Agents
• Proxies na Gudanarwa
• Juriya (faɗaɗaɗɗe)
• Ƙwarewa
• Ƙwaƙwalwa
• Sabar MCP
• Sabar A2A
• Cloud, Evals da Assess
• Sarrafa Buƙata
• Tabbatar da Shaida

---

Kammalawar Taɗi

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.

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:

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

{ "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:

{ "action": "status", "generation": 1 }

{
  "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:

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:

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

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:

{
  "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.

{
  "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.

# Jera dukkan samfuran embedding
GET /v1/embeddings

---

Samar da Hoto

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).

# Jera duk samfuran hoto
GET /v1/images/generations

---

OCR na Takardu

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:

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

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:

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

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.

# 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

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

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)

# 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):

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)

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.

# 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:

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

# Samo ƙididdigar cache
GET /api/cache/stats

# Share dukkan caches
DELETE /api/cache/stats

Misalin amsa:

{
  "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]):

{ "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.

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.
/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.
/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) 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+)

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:

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

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:

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:

{
  "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:

# 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.

# 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:

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

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

Amsa:

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

---

Kasafin Kuɗi

# 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.

# 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

---

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.

# Ƙ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.

# 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 → "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

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

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):

{
  "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 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:

{
  "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:

{
  "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:

{
  "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 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 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 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 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). 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 don cikakkun bayanai.

---

---

Tantance Shaida

Duba Tantance Shaidar Gudanarwa 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).