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

API Reference (Kiswahili)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 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 · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

🌐 Lugha: 🇺🇸 Kiingereza | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 Azərbaycan dili | 🇧🇬 Български | 🇧🇩 বাংলা | 🇨🇿 Čeština | 🇩🇰 Dansk | 🇩🇪 Deutsch | 🇬🇷 Ελληνικά | 🇪🇸 Español | 🇪🇪 Eesti | 🇮🇷 فارسی | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇪 Gaeilge | 🇮🇳 ગુજરાતી | 🇳🇬 Hausa | 🇮🇱 עברית | 🇮🇳 हिन्दी | 🇭🇷 Hrvatski | 🇭🇺 Magyar | 🇦🇲 Հայերեն | 🇮🇩 Bahasa Indonesia | 🇳🇬 Igbo | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇬🇪 ქართული | 🇰🇭 ខ្មែរ | 🇮🇳 ಕನ್ನಡ | 🇰🇷 한국어 | 🇱🇹 Lietuvių | 🇱🇻 Latviešu | 🇮🇳 മലയാളം | 🇮🇳 मराठी | 🇲🇾 Bahasa Melayu | 🇲🇹 Malti | 🇲🇲 မြန်မာ | 🇳🇵 नेपाली | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇮🇳 ଓଡ଼ିଆ | 🇮🇳 ਪੰਜਾਬੀ | 🇵🇭 Filipino | 🇵🇱 Polski | 🇵🇹 Português (Portugal) | 🇧🇷 Português (Brasil) | 🇷🇴 Română | 🇷🇺 Русский | 🇱🇰 සිංහල | 🇸🇰 Slovenčina | 🇸🇮 Slovenščina | 🇷🇸 Српски | 🇸🇪 Svenska | 🇰🇪 Kiswahili | 🇮🇳 தமிழ் | 🇮🇳 తెలుగు | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇵🇰 اردو | 🇺🇿 Oʻzbekcha | 🇻🇳 Tiếng Việt | 🇳🇬 Yorùbá | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

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

---

Yaliyomo

• Ukamilishaji wa Gumzo
• Ukodishaji wa Kipekee wa Vipindi Vinavyodhibitiwa
• Upachikaji
• Uundaji wa Picha
• OCR ya Hati
• Orodha ya Miundo
• Manifesti ya Programu-jalizi ya Mtoa Huduma
• Vituo vya Mwisho vya Uoanifu
• API ya Faili
• API ya Makundi
• API ya Utafutaji
• Utiririshaji wa WebSocket
• Ripoti za Vikomo na Matatizo
• Akiba ya Kisemantiki
• Dashibodi na Usimamizi
• Usimamizi wa Mchanganyiko
• Webhooks
• Funguo Zilizosajiliwa (Usimamizi Otomatiki)
• Itifaki ya Mawakala
• Proksi za Usimamizi
• Ustahimilivu (uliopanuliwa)
• Ujuzi
• Kumbukumbu
• Seva ya MCP
• Seva ya A2A
• Wingu, Tathmini na Upimaji
• Uchakataji wa Maombi
• Uthibitishaji

---

Ukamilishaji wa Gumzo

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

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

Vichwa Maalum

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

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

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

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

Ukodishaji wa Vipindi Vinavyosimamiwa wa Kipekee

Ukodishaji wa vipindi vinavyosimamiwa wa kipekee ni mkataba wa uelekezaji wa hiari, usiofungamana na mteja mahususi: mmiliki mmoja anayetumika anashikilia muunganisho mmoja unaostahiki wa OmniRoute. Haukodishi modeli, hauhitaji OAuth, hautambui mteja mahususi, wala hauhitaji mtoa huduma mahususi.

Ufunguo wa API unaotumika kuthibitisha utambulisho lazima uwe na wigo lease:exclusive na orodha bayana isiyo tupu ya allowedConnections. Mpaka wa mabadiliko ya hifadhidata hutekeleza masharti yote mawili pamoja wakati wa kuunda ufunguo na kufanya masasisho ya sehemu.

POST /api/v1/session-leases
Authorization: Bearer <managed-api-key>
Content-Type: application/json
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>

{"action":"acquire","model":"glm/glm-4.6"}

Majibu yaliyofaulu ya kupata, kusasisha na kuachilia huonyesha mihuri ya muda, state, na thamani chanya halisi ya generation, lakini kamwe hayaonyeshi muunganisho uliochaguliwa au vitambulisho. Kusasisha na kuachilia huwasilisha generation katika mwili wa JSON:

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

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

Mmiliki wa ukodishaji unaotumika anaweza kuomba bayana metadata salama kwa faragha ya kuonyesha kwa ufungamanisho wake wa sasa:

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

Kitendo hiki cha hali cha hiari kinalindwa na mmiliki fiche, ufunguo wa API unaosimamiwa uliothibitishwa, na generation halisi inayotumika ndani ya muamala mmoja wa hifadhidata. displayName ni jina la muunganisho lililosanidiwa lililoondolewa nafasi za pembeni pekee; huwa null wakati hakuna jina salama lililosanidiwa. OmniRoute haibadilishi kamwe jina hilo kwa barua pepe au utambulisho wa akaunti uliozalishwa. Thamani ya mtoa huduma ni lebo isiyo nyeti ya kuonyesha na kamwe si kitambulishi kilichozalishwa cha mtoa huduma tangamanifu. Vitambulisho, tokeni, vidakuzi, vitambulishi ghafi vya muunganisho au ufunguo wa API, hashi za wamiliki, siri za uzio, na data ya ndani ya uelekezaji havijumuishwi.

Utafutaji wenye ufunguo usio sahihi, mmiliki asiye sahihi, generation iliyopitwa na wakati, unaokosekana, uliokwisha muda, ulioachiliwa, au uliobatilishwa, wote hurudisha hitilafu ileile ya 409 LEASE_FENCE_STALE bila metadata ya muunganisho. Mteja aliyepokea jibu la kusubiri nafasi hana ufungamanisho unaotumika wa kukagua. Uelekezaji unapohamisha ukodishaji unaotumika, generation ileile hubaki halali na hali hurudisha kiatomiki ufungamanisho mpya, kamwe si wa zamani. Wateja waliopo hawabadiliki kwa sababu majibu ya kupata, kusasisha, kuachilia na kusubiri huhifadhi miundo yao ya awali.

Mkataba huu wa seva haubadilishi /status ya kawaida ya OpenAI Codex. Codex ya kawaida kwa sasa huripoti mtoa huduma wa modeli yake na hali iliyojengewa ndani ya uthibitishaji/akaunti lakini haionyeshi metadata holela ya akaunti ya mtoa huduma maalum; ujumuishaji wa mteja wa baadaye lazima uite kitendo hiki na kuamua jinsi ya kuonyesha connection.displayName.

Kisha kila ombi la utambuzi linalosimamiwa huwasilisha vichwa vyote viwili vya udhibiti:

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

Mmiliki halisi, generation, muunganisho unaotumika, na ufunguo wa API uliothibitishwa hulindwa mara moja kabla ya kila jaribio linalotumika la mfumo wa juu. Kucheza tena mmiliki na generation kwa ufunguo mwingine hushindwa hata wakati ufunguo huo unaruhusu muunganisho huohuo. Wamiliki ghafi hawahifadhiwi, hawawekwi kwenye kumbukumbu, hawabakizwi kwenye picha ya ombi, wala hawatumwi kwa mfumo wa juu.

Ushindani wa muda mfupi hurudisha HTTP 429 pamoja na Retry-After na:

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

Jibu hili linamaanisha tu kwamba mkusanyiko wa kawaida unaostahiki haukuwa tupu na kila muunganisho huru uliotarajiwa ulikuwa umeshikiliwa na ukodishaji unaotumika wa mmiliki mwingine. Modeli/watoa huduma wasiotumika, kutolingana kwa sera, kipindi cha kusubiri, kikomo cha matumizi, afya, na mapungufu mengine ya kawaida ya ustahiki huhifadhi majibu yao yaliyopo ya OmniRoute.

x-omniroute-compression

Ubatilishaji kwa kila ombi wa mpango wa mbano. Una kipaumbele cha juu zaidi — unashinda ubatilishaji wa mchanganyiko wa uelekezaji, wasifu unaotumika, kichochezi kiotomatiki, na Default ya paneli. Thamani:

Thamani	Athari
off	Hakuna mbano kwa ombi hili.
default	Wasifu wa Default unaotokana na paneli (hupuuza wasifu unaotumika).
engine:<id>	Injini moja inapowezeshwa, k.m. engine:rtk.
<combo>	Mchanganyiko wenye jina, unaolinganishwa kwanza kwa jina (bila kujali ukubwa wa herufi), kisha kwa id.

Vidokezo:

• Thamani zisizojulikana hupuuzwa (ombi halikataliwi kamwe); utatuzi huendelea hadi kwenye mpangilio wa kawaida wa kipaumbele cha waendeshaji.
• Ikiwa michanganyiko mingi ina jina moja, wasilisha id ya mchanganyiko ili kupata ulinganishaji thabiti.
• Mchanganyiko ambao jina lake ni off au default hauwezi kuchaguliwa kwa jina (maneno hayo muhimu hutafsiriwa kwanza); rejelea mchanganyiko huo kwa id yake.
• Swichi kuu ya mbano ni kizuizi madhubuti: mbano unapozimwa kwa mfumo mzima, kichwa hiki hakiwezi kuuwezesha.

Mpango uliotumika hurudishwa katika kichwa cha jibu:

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

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

---

Upachikaji

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

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

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

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

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

Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano, na lakabu ya familia jina-ai/jina-embeddings-v5-omni → omni-small) pia inakubali hati asilia za EmbeddingsV5Request za Jina na kuzituma bila kuzibadilisha hadi https://api.jina.ai/v1/embeddings:

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "task": "retrieval.query",
  "normalized": true,
  "input": [
    { "text": "a red bicycle" },
    { "image": "https://example.com/bike.png" },
    {
      "content": [{ "text": "caption" }, { "image": "data:image/png;base64,..." }]
    }
  ]
}

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

Mipaka ya usalama na usafirishaji:

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

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

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

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "input": [
    { "type": "text", "text": "A red bicycle" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/bicycle.png" }
    }
  ],
  "dimensions": 512,
  "encoding_format": "float"
}

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

# Orodhesha modeli zote za upachikaji
GET /v1/embeddings

---

Uzalishaji wa Picha

POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "openai/gpt-image-2",
  "prompt": "A beautiful sunset over mountains",
  "size": "1024x1024"
}

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

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

---

OCR ya Hati

POST /v1/ocr
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "mistral/mistral-ocr-latest",
  "document": {
    "type": "document_url",
    "document_url": "https://example.com/invoice.pdf"
  }
}

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

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

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

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

Mtiririko wa upigaji kura wa Azure Document Intelligence

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

Uthibitishaji na utatuzi wa endpoint wa Vertex AI DeepSeek OCR

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

---

Orodhesha Modeli

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

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

Viambishi awali vya id ya modeli (?prefix=)

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

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

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

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

Wateja wanaoonyesha kiteuzi cha modeli wanapaswa kuomba ?prefix=alias — hivi ndivyo kiendelezi cha OmniCopilot cha VS Code hufanya.

Vibadala vya modeli visivyo na kufikiri

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

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

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

---

Manifesti ya Programu-jalizi ya Mtoa Huduma

GET /api/v1/provider-plugin-manifest

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

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

---

Endpoint za Utangamano

Mbinu	Njia	Muundo
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 (uhariri/inpaint)
POST	/v1/videos/generations	Uzalishaji wa video wa mtindo wa OpenAI
POST	/v1/music/generations	Uzalishaji wa muziki wa mtindo wa OpenAI
POST	/v1/audio/transcriptions	OpenAI Audio (STT)
POST	/v1/audio/speech	OpenAI TTS (hurejesha mwili wa sauti)
POST	/v1/rerank	Upangaji upya wa mtindo wa Cohere/Voyage
POST	/v1/classify	Uainishaji wa Jina (api.jina.ai)
POST	/v1/segment	Kigawanyaji cha 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}/	Lakabu ya katalogi ya OpenAI
GET	/api/v1/vscode/{token}/models	Lakabu ya modeli za OpenAI
POST	/api/v1/vscode/{token}/chat/completions	Lakabu yenye tokeni ya OpenAI
POST	/api/v1/vscode/{token}/responses	Lakabu yenye tokeni ya OpenAI Responses
POST	/api/v1/vscode/{token}/api/chat	Lakabu yenye tokeni ya Ollama
GET	/api/v1/vscode/{token}/api/tags	Lakabu yenye tokeni ya lebo za Ollama

Njia zote za POST zinafuata muundo uleule: Bearer your-api-key + mwili wa JSON uliothibitishwa na Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema, n.k., angalia src/shared/validation/schemas.ts). 4xx hurejeshwa uthibitishaji wa schema unaposhindwa.

Kwa wateja wasioweza kuambatisha Authorization: Bearer ..., OmniRoute pia hukubali funguo za API kwenye URL kupitia ama utangamano wa mfuatano wa hoja (?token=..., ?apiKey=..., ?api_key=..., ?key=...) au endpoint maalum za /api/v1/vscode/{token}/... zilizoelezwa hapa chini.

# Upangaji upya
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

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

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

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

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

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

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

# Uzalishaji wa video / muziki (kitambulisho cha modeli chenye kiambishi awali cha mtoa huduma)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Njia Maalum za Watoa Huduma

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

Kiambishi awali cha mtoa huduma huongezwa kiotomatiki ikiwa hakipo. Modeli zisizolingana hurejesha 400.

---

API ya Faili

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

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

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

---

API ya Makundi

Uchakataji wa makundi unaooana na OpenAI.

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

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

---

API ya Utafutaji

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

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

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

---

API ya Kuchota Maudhui ya Wavuti

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

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

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

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

---

Utiririshaji wa WebSocket

GET /v1/ws?handshake=1

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

Uthibitishaji: Ufunguo wa API wa Bearer wakati wa handshake.

API ya Responses kupitia WebSocket (codex pekee)

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

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

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

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

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

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

Kusanidi OpenAI Codex CLI

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

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

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

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

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

---

Vikomo na Kuripoti Matatizo

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

Uthibitishaji: Ufunguo wa API wa Bearer (isAuthenticated).

---

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

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

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

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

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

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

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

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

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

---

Akiba ya Kisemantiki

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

# Futa akiba zote
DELETE /api/cache/stats

Mfano wa jibu:

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

Athari kwa muda wa kusubiri

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

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

Kupitisha akiba kwa kila ufunguo

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

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

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

{ "cacheDefaultMode": "bypass" }

Kupitisha akiba kwa kila ombi

Ombi lolote linaweza kupitisha akiba bila kujali mipangilio ya ufunguo:

X-OmniRoute-No-Cache: true

---

Dashibodi na Usimamizi

Njia za usimamizi (/api/* isipokuwa uthibitishaji/uingiaji wa umma) haziidhinishwi na funguo za kawaida za API za uelekezaji. Aina za vitambulisho, mawanda, na mifano ya curl: Uthibitishaji wa Usimamizi.

Uthibitishaji

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

Usimamizi wa Watoa Huduma

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

Mitiririko ya OAuth

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

Uelekezaji na Usanidi

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

Matumizi na Uchanganuzi

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

Mipangilio

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

Muktadha na Ubanaji

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

Ufuatiliaji

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

Hifadhi Nakala na Uhamishaji/Uingizaji

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

Usawazishaji wa Wingu

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

Vichuguu

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

Zana za CLI

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

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

Mawakala wa ACP

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

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

Ustahimilivu na Vikomo vya Kasi

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

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

Tathmini

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

Sera

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

Utiifu

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

v1beta (Inayotangamana na Gemini)

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

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

API za Ndani / Mfumo

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

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

Urekebishaji wa Mazingira ya OAuth (v3.6.1+)

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

{
  "provider": "claude-code"
}

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

{
  "success": true,
  "repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
  "backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}

---

Unukuzi wa Sauti

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

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

Ombi:

curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@recording.mp3" \
  -F "model=openai/whisper-1"

Jibu:

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

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

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

---

Uoanifu na Ollama

Kwa wateja wanaotumia umbizo la API la Ollama:

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

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

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

Majina Mbadala ya VS Code Yenye Tokeni / Yasiyo na Vichwa

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

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

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

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

Mfano:

curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'

Vidokezo:

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

---

Telemetria

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

Jibu:

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

---

Bajeti

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

# Weka au sasisha bajeti
POST /api/usage/budget
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "dailyLimitUsd": 5.00,
  "weeklyLimitUsd": 30.00,
  "monthlyLimitUsd": 100.00,
  "warningThreshold": 0.8,
  "resetInterval": "monthly"
}

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

Vikomo vya Tokeni

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

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

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

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

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

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

Uchakataji wa Ombi

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

Rejeleo kamili la usanifu: ARCHITECTURE.md

---

Usimamizi wa Michanganyiko

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

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

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

---

Webhooks

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

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

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

---

Funguo Zilizosajiliwa (Usimamizi Otomatiki)

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

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

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

---

Itifaki ya Mawakala

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

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

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

# Unda jukumu la wingu la Claude Code
curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Authorization: Bearer your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'

---

Proksi za Usimamizi

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

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

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

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

---

Ustahimilivu (uliopanuliwa)

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

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

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

# Futa uzuiaji wa modeli moja
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-4o-mini"}'

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

Kwa marejeleo kamili ya dhana na chaguo-msingi za vikatiza: tazama CLAUDE.md → "Hali ya Wakati wa Utekelezaji ya Ustahimilivu".

---

Ujuzi

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

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

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

---

Kumbukumbu

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

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

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

---

Seva ya MCP

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

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

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

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

---

Seva ya A2A

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

JSON-RPC

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

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

Mbinu zinazotumika (zote hudhibitiwa na settings.a2aEnabled):

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

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

Kadi ya Ajenti

GET /.well-known/agent.json

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

Visaidizi vya REST

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

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

---

Wingu, Tathmini za Utendaji na Ukadiriaji

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

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

---

Usimamizi wa ACP (Agent Client Protocol)

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

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

Mfano wa jibu (GET /api/acp/agents):

{
  "agents": [
    {
      "id": "claude",
      "name": "Claude Code CLI",
      "binary": "claude",
      "version": "1.0.45",
      "installed": true,
      "protocol": "stdio",
      "providerAlias": "claude",
      "isCustom": false
    },
    {
      "id": "my-custom-cli",
      "name": "My Custom CLI",
      "installed": false,
      "protocol": "stdio",
      "providerAlias": "my-provider",
      "isCustom": true
    }
  ],
  "cacheTtlMs": 60000,
  "cacheAge": 1234
}

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

Tazama Mfumo wa ACP kwa maelezo kamili.

---

Uchanganuzi na Uangalizi

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

Uchanganuzi wa uelekezaji kiotomatiki

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

Mfano wa jibu:

{
  "window": "24h",
  "totalCalls": 1234,
  "strategyBreakdown": {
    "rules": 800,
    "cost": 200,
    "latency": 150,
    "sla-aware": 50,
    "lkgp": 34
  },
  "tierBreakdown": {
    "ultra": 100,
    "pro": 500,
    "standard": 400,
    "free": 234
  },
  "topProviders": [
    { "provider": "openai", "calls": 500, "avgLatencyMs": 850 },
    { "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 }
  ]
}

Uchanganuzi wa mgandamizo

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

Mfano wa jibu:

{
  "window": "24h",
  "totalOriginalTokens": 5000000,
  "totalCompressedTokens": 3500000,
  "totalSavings": 1500000,
  "savingsPct": 30.0,
  "modeBreakdown": {
    "lite": 400,
    "standard": 600,
    "aggressive": 100,
    "ultra": 50,
    "rtk": 84
  },
  "engineBreakdown": {
    "caveman": 800,
    "rtk": 434
  }
}

Ufuatiliaji wa utofauti wa watoa huduma

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

Mfano wa jibu:

{
  "window": "24h",
  "shannonEntropy": 2.45,
  "maxEntropy": 3.17,
  "diversityRatio": 0.77,
  "providerUsage": {
    "openai": 0.4,
    "anthropic": 0.25,
    "google": 0.2,
    "kiro": 0.15
  },
  "warnings": ["OpenAI accounts for 40% of traffic — consider diversifying"]
}

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

---

Operesheni za Msimamizi

Endpointi za wasimamizi pekee kwa ajili ya usimamizi wa kiutendaji.

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

Uthibitishaji: Inahitaji kipindi cha usimamizi chenye wigo wa msimamizi.

---

Usimamizi wa Zana za CLI

Dhibiti zana za CLI zinazounganishwa na OmniRoute (antigravity, chipotle, commandCode, devin-cli, n.k.). Tazama Rejeleo la Watoa Huduma kwa orodha kamili.

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

Uthibitishaji: Inahitaji kipindi cha usimamizi.

---

Ujuzi wa Mawakala

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

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

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

---

Usimamizi wa Akiba

Dhibiti akiba ya kisemantiki na akiba ya uchanganuzi.

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

Uthibitishaji: Inahitaji kipindi cha usimamizi.

---

Mfumo wa Kumbukumbu

Dhibiti kumbukumbu endelevu (FTS5 + upachikaji wa vekta).

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

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

---

Webhooks

Dhibiti usajili wa webhook kwa matukio.

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

Uthibitishaji: Inahitaji kipindi cha usimamizi.

Angalia Mfumo wa Webhooks kwa aina zote za matukio.

---

Mfumo wa Skills

Dhibiti Skills (mfumo wa viendelezi vya kiwakala).

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

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

Tazama Mfumo wa Skills kwa maelezo kamili.

---

Programu-jalizi

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

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

Uthibitishaji: Inahitaji kipindi cha usimamizi.

Tazama Mfumo wa Programu-jalizi kwa maelezo kamili.

---

Uelekezaji Kivuli

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

---

Vizuizi vya Usalama

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

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

Uthibitishaji: Inahitaji kipindi cha usimamizi.

Tazama Usalama > Vizuizi vya Usalama kwa maelezo kamili.

---

---

Uthibitishaji

Tazama Uthibitishaji wa Usimamizi kwa familia nne za vitambulisho (kipindi cha dashibodi, tokeni ya ndani ya CLI, Tokeni ya Ufikiaji ya oma_live_…, ufunguo wa API wenye wigo wa usimamizi) na jinsi zinavyotofautiana na funguo za uelekezaji.

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

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