pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-21 06:12:17 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
c193595db6e560c395fdf9cf74ebd7d7f0bb9c5b
OmniRoute/docs/i18n/yo/docs/reference/API_REFERENCE.md
Diego Rodrigues de Sa e Souza 8feea123bb feat(docs): mirror every docs/ page in all 65 locales (#14106) 
* feat(docs): mirror every docs/ page in all 65 locales

Extends the documentation mirrors from the 22-page core set (#13940) to
every Markdown page under docs/: 152 sources x 65 locales = 9,880 mirrors
(6,208 new), language bars rewritten for the full locale list, state
adopted so the blocking drift gate now covers all 152 pages.

run-translation.mjs: an oversized block made only of table rows or list
items (PROVIDER_REFERENCE.md 244-row table, FREE_TIERS.md 71-item list) is
cut at item boundaries and rejoined without a blank line — the single
16-40 KB request outlived the backend socket for verbose scripts. 48
older mirrors whose tables had lost rows were retranslated with --force.

* docs(i18n): refresh mirrors for the sources the base changed since the branch cut

Section-level retranslation of the 29 docs (and README.md) whose source
or mirrors moved on release/v3.8.51 during the run, then state adoption;
the drift gate is green again on the merged tree.
2026-09-18 13:16:46 -03:00

1782 lines
135 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API Reference (Yorùbá)
🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)
---
🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)
Àkọ́tọ́ pàtàkì fún OmniRoute API. Ó ṣàlàyé ojú-ọ̀nà gbogbogbò `/v1` àti àwọn endpoint ìṣàkóso tí a ń lò jù lọ; [`docs/openapi.yaml`](../openapi.yaml) tí ẹ̀rọ lè kà àti igi route tó wà lábẹ́ `src/app/api/` ni àwọn orísun tó pé pátápátá.
---
## Àkójọ Àwọn Àkóónú
- [Àwọn Ìparí Ìfọ̀rọ̀wérọ̀](#chat-completions)
- [Àwọn Ìyálò Ìgbà Ìjókòó Àbójútó Àdáni](#exclusive-managed-session-leases)
- [Àwọn Ìfísínú](#embeddings)
- [Ṣíṣe Àwòrán](#image-generation)
- [OCR Ìwé](#document-ocr)
- [Àkójọ Àwọn Àwòṣe](#list-models)
- [Manifestu Plugin Olùpèsè](#provider-plugin-manifest)
- [Àwọn Endpoint Ìbámu](#compatibility-endpoints)
- [API Àwọn Fáìlì](#files-api)
- [API Àwọn Ìpele](#batches-api)
- [API Ìṣàwárí](#search-api)
- [Ìṣànwọlé WebSocket](#websocket-streaming)
- [Àwọn Ìdíwọ̀n & Ìjábọ̀ Ìṣòro](#quotas--issues-reporting)
- [Káṣe Ìtumọ̀](#semantic-cache)
- [Pátákó Ìdarí & Ìṣàkóso](#dashboard--management)
- [Ìṣàkóso Combo](#combo-management)
- [Àwọn Webhook](#webhooks)
- [Àwọn Kọ́kọ́rọ́ Tí a Forúkọsílẹ̀ (Ìṣàkóso Aládàáṣiṣẹ́)](#registered-keys-auto-management)
- [Ìlànà Àwọn Aṣojú](#agents-protocol)
- [Àwọn Proxy Ìṣàkóso](#management-proxies)
- [Ìfaradà (àfikún)](#resilience-extended)
- [Àwọn Ọgbọ́n](#skills)
- [Ìrántí](#memory)
- [Sẹ́fà MCP](#mcp-server)
- [Sẹ́fà A2A](#a2a-server)
- [Cloud, Àwọn Ìdánwò & Ìṣírò](#cloud-evals--assess)
- [Ṣíṣe Ìbéèrè](#request-processing)
- [Ìfàṣẹsí](#authentication)
---
## Àwọn Ìparí Ìfọ̀rọ̀wérọ̀
```bash
POST /v1/chat/completions
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "cc/claude-opus-4-6",
"messages": [
{"role": "user", "content": "Write a function to..."}
],
"stream": true
}
```
### Àwọn Header Àkànṣe
| Header | Ìtọ́sọ́nà | Àpèjúwe |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `X-OmniRoute-No-Cache` | Ìbéèrè | Ṣètò sí `true` láti forí káṣe kọjá |
| `x-omniroute-no-memory` | Ìbéèrè | Ṣètò sí `true` láti foju ìrántí + fífi àwọn ọgbọ́n sínú fún ìbéèrè yìí (ó dà bí no-cache; ó yẹra fún àfikún token/ìnáwó fún ìpè kọ̀ọ̀kan) |
| `X-OmniRoute-Progress` | Ìbéèrè | Ṣètò sí `true` fún àwọn ìṣẹ̀lẹ̀ ìlọsíwájú |
| `X-Session-Id` | Ìbéèrè | Kọ́kọ́rọ́ ìgbà ìjókòó dídì fún ìbámu ìgbà ìjókòó ìta |
| `x_session_id` | Ìbéèrè | A tún gba ẹ̀yà underscore (HTTP tààrà) |
| `X-OmniRoute-Session-Id` | Ìbéèrè | Ààmì ìgbà ìjókòó/ìfọ̀rọ̀wérọ̀ tí olùpè pèsè (ó tún ń fi ìrántí lọ́wọ́). Nígbà tí ó bá wà, a ó fi í pamọ́ gẹ́gẹ́ bí ó ṣe rí sínú `call_logs.session_tag` fún ìpín ìnáwó ìgbà ìjókòó kọ̀ọ̀kan (#8249) — a kì í dá a sílẹ̀ nígbà tí kò bá sí |
| `Idempotency-Key` | Ìbéèrè | Kọ́kọ́rọ́ ìmúkúrò àtúnṣe (fèrèsé 5s) |
| `X-Request-Id` | Ìbéèrè | Kọ́kọ́rọ́ ìmúkúrò àtúnṣe mìíràn |
| `X-OmniRoute-Cache` | Ìdáhùn | `HIT` tàbí `MISS` (tí kì í ṣe ìṣànwọlé) |
| `X-OmniRoute-Idempotent` | Ìdáhùn | `true` bí a bá ti mú àwọn àtúnṣe kúrò |
| `X-OmniRoute-Progress` | Ìdáhùn | `enabled` bí títọpinpin ìlọsíwájú bá wà ní títàn |
| `X-OmniRoute-Session-Id` | Ìdáhùn | ID ìgbà ìjókòó tó gbéṣẹ́ tí OmniRoute lò |
| `X-OmniRoute-Request-Id` | Ìdáhùn | ID ìbámu ìbéèrè (nígbà tí a bá mọ̀ ọ́) |
| `X-OmniRoute-Version` | Ìdáhùn | Ẹ̀yà ìkọ́lé OmniRoute (ó máa ń wà nígbà gbogbo) |
| `X-OmniRoute-Cost-Saved` | Ìdáhùn | USD tí káṣe fi pamọ́ lórí HIT kan (àwọn cache hit nìkan) |
| `X-OmniRoute-Decision` | Ìdáhùn | Àtẹ̀lé ìdarí ipa-ọ̀nà: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` ni ọgbọ́n combo, tàbí `single` fún ìbéèrè tí kì í ṣe combo) — ó máa ń wà nígbà gbogbo lórí àwọn ìdáhùn ìparí |
> Àkíyèsí Nginx: bí o bá gbára lé àwọn header underscore (fún àpẹẹrẹ `x_session_id`), mú `underscores_in_headers on;` ṣiṣẹ́.
> **Àwọn àkọlé tẹlémẹ́trì iye owó:** àwọn ìdáhùn àṣeyọrí tí kì í ṣe ṣiṣan tún ní àkójọpọ̀ tẹlémẹ́trì iye owó `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, nọ́ńbà alákíyèsí mẹ́wàá tí kò yí padà; `0.0000000000` fún ohun ọ̀fẹ́/tí kò ní iye owó), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit`, àti `X-OmniRoute-Fallback-Attempts` (nígbà tí ó bá > 0 nìkan), pẹ̀lú `X-OmniRoute-Request-Id` àti `X-OmniRoute-Version`. Àwọn ìparí ìfọ̀rọ̀wérọ̀, `/v1/responses`, `/v1/messages`, **àti àwọn ibi ìparí mídíà** ni wọ́n ń dá àwọn wọ̀nyí jáde — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations`, àti `/v1/moderations` (iye owó rẹ̀ máa ń jẹ́ `0` ní gbogbo ìgbà). A máa ń ṣírò iye owó mídíà gẹ́gẹ́ bí ìru rẹ̀ (fún àwòrán kọ̀ọ̀kan, fún ìṣẹ́jú-àáyá kọ̀ọ̀kan, fún àmì kọ̀ọ̀kan, fún ẹ̀ka ìṣàwárí kọ̀ọ̀kan) nígbà tí ìdíyelé bá wà; bí kò bá sí, yóò jẹ́ `0` (yóò tẹ̀síwájú láìdènà).
> **Ìtumọ̀ iye owó ìbámu-káṣì:** lórí ìbámu HIT nínú káṣì ìtumọ̀ (`X-OmniRoute-Cache-Hit: true`), a kò ṣe ìpè sí iṣẹ́ òkè-rere, nítorí náà `X-OmniRoute-Response-Cost` jẹ́ `0.0000000000` (iye owó **àfikún** fún fífi ìbámu náà ránṣẹ́). Iye owó ìpilẹ̀ṣẹ̀/tí ì bá ti jẹ́ ni a ń jabo lọ́tọ̀ nínú `X-OmniRoute-Cost-Saved`. Àwọn olùlò ìdíyelé gbọ́dọ̀ ṣàkójọpọ̀ `X-OmniRoute-Response-Cost` (àwọn ìbámu kò ná owó kankan); àwọn irinṣẹ́ ìtúpalẹ̀ káṣì sì lè ṣàkójọpọ̀ `X-OmniRoute-Cost-Saved`.
## Àwọn Ìyálò Ìgbà Ìṣiṣẹ́ Àbójútó Aládàáṣe
Ìyálò ìgbà ìṣiṣẹ́ àbójútó aládàáṣe jẹ́ àdéhùn ìdarí-ọ̀nà tí a máa ń yàn láti lò, tí kò sì dá lórí oníbàárà: olùní kan ṣoṣo tó ń ṣiṣẹ́
ni ó di àsopọ̀ OmniRoute kan tó yẹ mú. Kì í ṣe yíyálò àwòṣe, kò béèrè OAuth, kò dá
oníbàárà kan pàtó mọ̀, bẹ́ẹ̀ ni kò béèrè olupèsè kan pàtó.
Bọ́tìnì API tí ń ṣe ìfàṣẹsí gbọ́dọ̀ ní ààlà `lease:exclusive` àti àtòjọ
`allowedConnections` tí a sọ ní kedere tí kò sì ṣófo. Ààlà ìyípadà ibi ìpamọ́ dátà máa ń fipá mú kí àwọn ààyè méjèèjì wà papọ̀ nígbà
ṣíṣẹ̀dá bọ́tìnì àti àwọn ìmúdójúìwọ̀n apá kan.
```http
POST /api/v1/session-leases
Authorization: Bearer <managed-api-key>
Content-Type: application/json
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
{"action":"acquire","model":"glm/glm-4.6"}
```
Àwọn èsì àṣeyọrí fún gbígbà, ìsọdọ̀tun, àti ìtúsílẹ̀ máa ń fi àwọn àmì-àkókò, `state`, àti
`generation` rere gangan hàn, ṣùgbọ́n wọn kì í fi àsopọ̀ tàbí ẹ̀rí ìdánimọ̀ tí a yàn hàn láé. Ìsọdọ̀tun àti ìtúsílẹ̀ máa ń pèsè
generation náà nínú ara JSON:
```json
{ "action": "renew", "generation": 1 }
```
```json
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
```
Olùní ìyálò tó ń ṣiṣẹ́ lè béèrè ní kedere fún metadata àfihàn tó dáàbò bo àṣírí fún ìsopọ̀ rẹ̀ lọ́wọ́lọ́wọ́:
```json
{ "action": "status", "generation": 1 }
```
```json
{
"state": "ACTIVE",
"generation": 1,
"acquiredAt": "2026-08-28T12:00:00.000Z",
"renewedAt": "2026-08-28T12:00:30.000Z",
"expiresAt": "2026-08-28T12:02:30.000Z",
"connection": {
"displayName": "Primary Codex",
"provider": "codex"
}
}
```
Ìgbésẹ̀ status tí a yàn láti lò yìí ni a fi olùní àìfarahàn, bọ́tìnì API àbójútó tí a ti fìdí rẹ̀ múlẹ̀, àti
generation tó ń ṣiṣẹ́ gangan ṣe ààlà rẹ̀ nínú ìdúnàádúrà ibi ìpamọ́ dátà kan ṣoṣo. `displayName` jẹ́ orúkọ
àsopọ̀ tí a ṣètò tí a gé àyè àfikún rẹ̀ kúrò nìkan; yóò jẹ́ `null` nígbà tí kò bá sí orúkọ àtòjọ tó láàbò.
OmniRoute kì í fi ímeèlì tàbí ìdánimọ̀ àkọọ́lẹ̀ tí a ṣẹ̀dá rọ́pò rẹ̀ láé. Iye provider jẹ́ àmì àfihàn tí kò ní
ìsọfúnni kókó, kì í sì í ṣe ìdánimọ̀ olupèsè ibámu tí a ṣẹ̀dá láé. Ẹ̀rí ìdánimọ̀, token, cookie, àsopọ̀ gidi tàbí àwọn
id bọ́tìnì API, àwọn hash olùní, àwọn àṣírí ìdíwọ̀n, àti dátà ìdarí-ọ̀nà abẹ́nú ni a yọ kúrò.
Àwọn ìṣàwárí pẹ̀lú bọ́tìnì tí kò tọ́, olùní tí kò tọ́, generation tí ó ti pẹ́, ohun tí kò sí, ohun tó ti parí, ohun tí a ti tú sílẹ̀, àti ohun tí a ti sọ di aláìṣiṣẹ́
gbogbo wọn máa ń dá àṣìṣe `409 LEASE_FENCE_STALE` kan náà padà láìsí metadata àsopọ̀. Oníbàárà tó gba èsì dídúró de àyè kò ní ìsopọ̀ tó ń ṣiṣẹ́ láti ṣàyẹ̀wò. Nígbà tí ìdarí-ọ̀nà bá yí ìyálò tó ń ṣiṣẹ́ padà,
generation kan náà ṣì máa ń wúlò, status sì máa ń dá ìsopọ̀ tuntun padà lẹ́ẹ̀kan náà, kì í ṣe ti àtijọ́ láé.
Àwọn oníbàárà tó wà tẹ́lẹ̀ kò ní yípadà nítorí pé àwọn èsì gbígbà, ìsọdọ̀tun, ìtúsílẹ̀, àti dídúró ṣì pa
ìrísí wọn tẹ́lẹ̀ mọ́.
Àdéhùn olupin yìí kò yí `/status` OpenAI Codex àtẹ̀jáde boṣewa padà. Lọ́wọ́lọ́wọ́, Codex àtẹ̀jáde boṣewa máa ń jàbọ̀
olupèsè àwòṣe rẹ̀ àti ipò ìfàṣẹsí/àkọọ́lẹ̀ inú rẹ̀, ṣùgbọ́n kò ṣe àfihàn metadata àkọọ́lẹ̀
olupèsè àdáni èyíkéyìí; ìṣọ̀kan oníbàárà lọ́jọ́ iwájú gbọ́dọ̀ pe ìgbésẹ̀ yìí kí ó sì pinnu bí a ṣe máa
ṣàfihàn `connection.displayName`.
Lẹ́yìn náà, gbogbo ìbéèrè ìṣirò àbójútó máa ń pèsè àwọn àkọsílẹ̀ ìṣàkóso méjèèjì:
```http
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
```
Olùní gangan, generation, àsopọ̀ tó ń ṣiṣẹ́, àti bọ́tìnì API tí a ti fìdí rẹ̀ múlẹ̀ ni a máa ń ṣe ààlà wọn lẹ́sẹ̀kẹsẹ̀
ṣáájú gbogbo ìgbìyànjú upstream tí a ṣe àtìlẹ́yìn fún. Ṣíṣe àtúnlò olùní àti generation pẹ̀lú bọ́tìnì mìíràn yóò kùnà, kódà
bí bọ́tìnì yẹn bá gba àsopọ̀ kan náà láàyè. A kì í tọ́jú àwọn olùní gidi sínú ibi ìpamọ́, kọ wọ́n sínú àkọsílẹ̀,
dá wọn dúró nínú àwòrán-ìpamọ́ ìbéèrè, tàbí fi wọ́n ránṣẹ́ sí upstream.
Ìdíje fún ìgbà díẹ̀ máa ń dá HTTP `429` padà pẹ̀lú `Retry-After` àti:
```json
{
"state": "WAITING_FOR_CAPACITY",
"error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
"reason": "NO_FREE_ELIGIBLE_CONNECTION",
"retryAfter": 30
}
```
Èsì yìí túmọ̀ sí pé àkójọpọ̀ àwọn tó yẹ lásán kò ṣófo, gbogbo olùdíje ọ̀fẹ́ sì
wà lọ́wọ́ ìyálò tó ń ṣiṣẹ́ ti olùní mìíràn. Àwọn àwòṣe/olùpèsè tí kò ní àtìlẹ́yìn, àìbámu ìlànà, àkókò ìsinmi,
ìpín, ìlera, àti àwọn ìkùnà yíyẹ lásán mìíràn ṣì máa ń pa àwọn èsì OmniRoute wọn tó wà tẹ́lẹ̀ mọ́.
### `x-omniroute-compression`
Ìkọjá-ètò fún gbogbo ìbéèrè lórí ètò ìfúnpọ̀. Ó ní àṣẹ tó ga jù — ó borí ìkọjá-ètò routing-combo,
profile tó ń ṣiṣẹ́, auto-trigger, àti Default pánẹ́lì. Àwọn iye:
| Iye | Ipa |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| `off` | Kò sí ìfúnpọ̀ fún ìbéèrè yìí. |
| `default` | Profile Default tí a mú jáde láti inú pánẹ́lì (kò ka profile tó ń ṣiṣẹ́ sí). |
| `engine:<id>` | Engine kan ṣoṣo nígbà tí a bá mú un ṣiṣẹ́, fún àpẹẹrẹ `engine:rtk`. |
| `<combo>` | Combo tó ní orúkọ, tí a kọ́kọ́ bá mu nípasẹ̀ orúkọ (láìka bí lẹ́tà ṣe tóbi tàbí kékeré), lẹ́yìn náà nípasẹ̀ id. |
Àwọn àkíyèsí:
- A máa foju kọ àwọn iye àìmọ̀ (a kì í kọ ìbéèrè náà láé); ìpinnu máa tẹ̀ síwájú sí ìtẹ̀lé àṣẹ olùṣiṣẹ́ deede.
- Bí àwọn combo púpọ̀ bá ní orúkọ kan náà, fi **id** combo náà ránṣẹ́ fún ìbámu tí kò yípadà.
- Combo tí orúkọ rẹ̀ jẹ́ `off` tàbí `default` kò ṣe é yàn nípasẹ̀ orúkọ (àwọn ọ̀rọ̀ pàtàkì wọ̀nyẹn ni a kọ́kọ́ túmọ̀); tọ́ka sí irú combo bẹ́ẹ̀ nípasẹ̀ id rẹ̀.
- Yíyípadà àkọ́kọ́ ìfúnpọ̀ jẹ́ ìdènà líle: nígbà tí ìfúnpọ̀ bá jẹ́ aláìṣiṣẹ́ ní gbogbo ètò, àkọsílẹ̀ yìí kò lè mú un ṣiṣẹ́.
A máa ń fi ètò tí a lò padà hàn nínú àkọsílẹ̀ èsì:
```
X-OmniRoute-Compression: <mode>; source=<source>
```
níbi tí `<source>` ti jẹ́ ọ̀kan lára `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, tàbí `off`.
---
## Àwọn Embedding
```bash
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "nebius/Qwen/Qwen3-Embedding-8B",
"input": "The food was delicious"
}
```
Àwọn olùpèsè tó wà: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.
Àwọn id katalọ́ọ̀gù jẹ́ `provider/model` (àpẹẹrẹ: `jina-ai/jina-embeddings-v5-omni-small`). Àwọn id awoṣe Jina tí kò ní orúkọ olùpèsè, tí ó hàn nínú registry (fún àpẹẹrẹ `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) tún máa ń ṣiṣẹ́. Jina embed/rerank/classify/segment máa ń kọ́kọ́ lo àwọn ìwé-ẹ̀rí `jina-ai` inú dashboard; `JINA_AI_API_KEY` jẹ́ àṣàyàn ìpamọ́ nìkan nígbà tí kò bá sí kọ́kọ́rọ́ dashboard. Káàdì `jina-reader` jẹ́ fún Reader / `r.jina.ai` nìkan (`POST /v1/web/fetch`), kò sì ní ṣe iṣẹ́ embedding tàbí rerank láéláé.
Àwọn awoṣe registry tí ó sọ pé wọ́n ṣe àtìlẹ́yìn fún multimodal tún gba tó àwọn ohun èlò oníṣètò 32 tí kò dá lórí olùpèsè kan pàtó.
Àwọn irú ohun èlò mídíà ni `text`, `image`, `audio`, `video`, àti `document`. `source` mídíà wọn
jẹ́ bóyá `{"type":"url","url":"https://..."}` tàbí
`{"type":"base64","data":"...","media_type":"..."}`.
Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`,
àti alias ìdílé `jina-ai/jina-embeddings-v5-omni` → omni-small) tún gba àwọn ìwé EmbeddingsV5Request abinibi ti Jina,
ó sì **rán wọn síwájú láìyí wọn padà** sí `https://api.jina.ai/v1/embeddings`:
```json
{
"model": "jina-ai/jina-embeddings-v5-omni-small",
"task": "retrieval.query",
"normalized": true,
"input": [
{ "text": "a red bicycle" },
{ "image": "https://example.com/bike.png" },
{
"content": [{ "text": "caption" }, { "image": "data:image/png;base64,..." }]
}
]
}
```
Àwọn iye abinibi `{ image | audio | video | pdf }` lè jẹ́ URL HTTPS gbogbogbò, URI `data:`, tàbí
base64 aise. OmniRoute kì í sọ àwọn object wọ̀nyẹn di string tàbí gba àwọn URL àwòrán abinibi wá — Jina fúnra rẹ̀
ló ń gba mídíà gbogbogbò náà wá. Àwọn field Jina àfikún (`task`, `normalized`, `truncate`, `embedding_type`) ni a
rán síwájú. Àwọn SKU Jina tó jẹ́ text-only ṣì máa kọ àwọn ìwé tí kì í ṣe text.
Àwọn ààlà ààbò àti ìgbékalẹ̀:
- Àwọn URL mídíà jíjìn gbọ́dọ̀ jẹ́ HTTPS gbogbogbò. Àwọn ohun èlò Canonical `{type,source:url}` ni a máa ń gbà
wá ní ẹ̀gbẹ́ server (àyẹ̀wò redirect lẹ́ẹ̀kan sí i, timeout, ààlà ìwọ̀n, DNS gbogbogbò, connection pinning), a sì máa ń
fi wọ́n sínú request kí a tó pe olùpèsè. Àwọn ohun èlò Jina-native `{image:"https://..."}` ni a rán síwájú bí wọ́n ṣe rí
lẹ́yìn àyẹ̀wò public-HTTPS kan náà; Jina ló máa gba URL náà wá.
- Mídíà base64 inline ní ààlà 8 MiB tí a ti decode fún ohun èlò kọ̀ọ̀kan àti 16 MiB tí a ti decode fún gbogbo request náà.
Ìtumọ̀ sí ọna olùpèsè (a kì í rán àwọn ohun èlò canonical síwájú láìyí wọn padà):
- Àwọn awoṣe multimodal Jina: ohun èlò top-level kọ̀ọ̀kan di object kan tí a fi kọ́kọ́rọ́ modality sí
(`text` / `image` / `audio` / `video` / `pdf`), tí ó ń lo data URI fún mídíà inline; vector kan fún
ohun èlò top-level kọ̀ọ̀kan.
- Ìdílé Gemini Embedding 2: array top-level kan di request abinibi kan ṣoṣo
`models/{model}:embedContent` pẹ̀lú `content.parts` (`text` tàbí `inline_data`).
- Àwọn awoṣe àìmọ̀/dynamic tí kò ní metadata modality tó ṣe kedere máa kọ structured input pẹ̀lú HTTP 400.
```json
{
"model": "jina-ai/jina-embeddings-v5-omni-small",
"input": [
{ "type": "text", "text": "A red bicycle" },
{
"type": "image",
"source": { "type": "url", "url": "https://example.com/bicycle.png" }
}
],
"dimensions": 512,
"encoding_format": "float"
}
```
Àwọn àkópọ̀ awoṣe/modality tí a kò ṣe àtìlẹ́yìn fún máa dá HTTP 400 padà dípò fífi ipá yí ohun èlò náà padà. Àwọn field
extension tí kì í ṣe input lórí àwọn request string/token àtijọ́ ṣì máa kọjá lọ láìyípadà.
```bash
# Ṣàkọsílẹ̀ gbogbo àwọn awoṣe embedding
GET /v1/embeddings
```
---
## Ṣíṣẹ̀dá Àwòrán
```bash
POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "openai/gpt-image-2",
"prompt": "A beautiful sunset over mountains",
"size": "1024x1024"
}
```
Àwọn olupèsè tó wà: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (agbègbè), ComfyUI (agbègbè).
```bash
# Ṣàkójọ gbogbo àwọn àwòṣe àwòrán
GET /v1/images/generations
```
---
## OCR Ìwé
```bash
POST /v1/ocr
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "mistral/mistral-ocr-latest",
"document": {
"type": "document_url",
"document_url": "https://example.com/invoice.pdf"
}
}
```
`model` ń yan olupèsè OCR nípasẹ̀ ìpele `provider/model`; id àwòṣe tí kò ní ìpele (fún àpẹẹrẹ,
`mistral-ocr-latest`) yóò tọ́ka sí olupèsè rẹ̀ tí a forúkọsílẹ̀, àti pé tí a kò bá fi `model` sílẹ̀, yóò lo
Mistral (`mistral-ocr-latest`) gẹ́gẹ́ bí àkóbá. Àwọn olupèsè tí a forúkọsílẹ̀ (`open-sse/config/ocrRegistry.ts`):
| Id olupèsè | Id àwòṣe | Iye `model` | Àwọn àkíyèsí |
| ----------------------------- | -------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (tàbí `mistral-ocr-latest` láìsí ìpele) | Amúṣiṣẹ́pọ̀ — a dá èsì padà tààrà láti inú ìpè òkè kan ṣoṣo. |
| `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Òkè aláìṣiṣẹ́pọ̀ (`analyze` + ìdìbò) — wo ìsàlẹ̀. |
| `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Amúṣiṣẹ́pọ̀, nípasẹ̀ ibi ìparí alábàáṣiṣẹ́pọ̀ `openapi/chat/completions` ti Vertex AI — wo ìsàlẹ̀ fún ìfàṣẹsí/URL. |
Gbogbo àwọn olupèsè mẹ́tẹ̀ẹ̀ta ń dáhùn pẹ̀lú ara onírísí Mistral kan náà:
```json
{
"pages": [{ "index": 0, "markdown": "# Extracted text..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
```
### Ìṣàn ìdìbò Azure Document Intelligence
API `analyze` ti Azure Document Intelligence jẹ́ aláìṣiṣẹ́pọ̀: ìbéèrè àkọ́kọ́ ń dá àkọlé
`Operation-Location` padà dípò ara, a sì gbọ́dọ̀ máa dìbò fún àbájáde náà. Olùdarí náà
(`open-sse/handlers/ocr.ts`) máa ń dìbò sí URL yẹn ní gbogbo ìṣẹ́jú-àáyá kan fún ìgbìyànjú tó pọ̀ jù lọ 30, ó máa ń kùnà lẹ́sẹ̀kẹsẹ̀ (kò
tẹ̀síwájú láti dìbò) lórí èsì ìdìbò tí kì í ṣe `ok` tàbí ipò `"failed"`, ó sì dá `504` padà bí
iṣẹ́ náà bá ṣì ń lọ lẹ́yìn tí iye ìgbìyànjú bá ti parí. A máa ń ṣe èsì Azure ìkẹyìn
ní ìlànà sí onírísí `pages`/`markdown` kan náà tí Mistral ń lò kí a tó dá a padà sí
olùpè, nítorí náà kóòdù oníbàárà kò nílò láti ṣe ìtọ́jú pàtàkì fún olupèsè náà.
### Ìfàṣẹsí àti ìpinnu ibi ìparí Vertex AI DeepSeek OCR
`vertex-deepseek-ocr` tún ń lo ìfàṣẹsí Vertex AI kan náà tí OmniRoute ti ń ṣe àtìlẹ́yìn fún
ìrìnàjò ìfọ̀rọ̀wérọ̀/àwòrán (`open-sse/executors/vertex.ts`): kọ́kọ́rọ́ API àsopọ̀ náà jẹ́ yálà
ẹ̀rí Service Account JSON (tí a pààrọ̀ fún àmì ìráyè OAuth onígbà-kúkúrú nípasẹ̀ ìṣàn JWT-bearer)
tàbí àmì ìráyè OAuth tí a ti ṣẹ̀dá tẹ́lẹ̀ tí a lò bí ó ṣe rí. URL ibi ìparí òkè náà jẹ́
ibi ìparí alábàáṣiṣẹ́pọ̀ gbogbogbòò `openapi/chat/completions` ti Vertex, tí a kọ́ láti inú iṣẹ́ àti
agbègbè àsopọ̀ náà — `providerSpecificData.project`/`providerSpecificData.region` tí a sọ ní pàtó ló máa ń ṣáájú nígbà gbogbo;
bí bẹ́ẹ̀ kọ́, a máa ń yọ iṣẹ́ náà láti inú `project_id` ti Service Account JSON, agbègbè náà sì
máa ń lo `us-central1` gẹ́gẹ́ bí àkóbá. Àwọn ìpinnu méjèèjì máa ń ṣẹlẹ̀ nínú `open-sse/handlers/ocr.ts`
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`), tí
`src/app/api/v1/ocr/route.ts` ń lò kí ó tó fi ránṣẹ́ sí `handleOcr`.
---
## Ṣe Àtòjọ Àwọn Módelì
```bash
GET /v1/models
Authorization: Bearer your-api-key
→ Ó dá gbogbo àwọn módelì ìfọ̀rọ̀wérọ̀, embedding, àti àwòrán + àwọn àkópọ̀ padà ní ọ̀nà OpenAI
```
### Àwọn ìṣáájú id módelì (`?prefix=`)
Ọ̀pọ̀ àwọn módelì ni a ń polówó lábẹ́ **ìṣáájú olùpèsè** kan. Ìṣáájú tí o máa rí ni
àsíá ẹ̀ya `MODELS_CATALOG_PREFIX_MODE` ń ṣàkóso, a sì lè fagi lé e **fún ìbéèrè kọ̀ọ̀kan** pẹ̀lú
paramita ìbéèrè kan — ó wúlò fún oníbàárà tó fẹ́ àtòjọ mímọ́ láìṣe àyípadà sí ètò gbogbo
sáfà fún gbogbo àwọn mìíràn:
```bash
GET /v1/models?prefix=alias # id kan fún módelì kọ̀ọ̀kan — ìṣáájú alias kúkúrú
GET /v1/models?prefix=dual # àwọn fọ́ọ̀mù méjèèjì (àìyípadà sáfà)
GET /v1/models?prefix=canonical # ìṣáájú provider-id kíkún nìkan
```
| Ìpo | Ohun tí ó ń gbé jáde | Àwọn àkíyèsí |
| ----------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `dual` | `cc/claude-sonnet-4-6` **àti** `claude/claude-sonnet-4-6` | **Àìyípadà.** Àwọn id méjèèjì ń darí sí módelì kan náà; a pa wọ́n mọ́ kí àwọn ètò oníbàárà tí ó ti kọ ọ̀kan nínú wọn sínú kóòdù lè máa ṣiṣẹ́ nìṣó. Ó fẹ́rẹ̀ẹ́ sọ katalọ́ọ̀gù di ìlọ́po méjì. |
| `alias` | `cc/claude-sonnet-4-6` | Àkọsílẹ̀ kan fún módelì kọ̀ọ̀kan. Àwọn olùpèsè tí kò ní alias ọ̀tọ̀ ṣì ń gbé àkọsílẹ̀ wọn jáde, nítorí náà kò sí ohun tó sọnù. |
| `canonical` | `claude/claude-sonnet-4-6` | Àkọsílẹ̀ kan fún módelì kọ̀ọ̀kan lábẹ́ ìṣáájú provider-id kíkún. Àwọn olùpèsè tí kò ní alias ọ̀tọ̀ (fún àpẹẹrẹ `antigravity/…`, `agy/…`) tún ń gbé id kan ṣoṣo wọn jáde níbí, nítorí náà kò sí ohun tó sọnù. |
A tún lè dá àwòrán ojú-òpó ìpo `dual` mọ̀ láìlo paramita ìbéèrè náà: ó ní pápá `parent`
tí ó ń tọ́ka sí id àkọ́kọ́.
Àwọn oníbàárà tí ń ṣàfihàn ibi yíyan módelì yẹ kí wọ́n béèrè `?prefix=alias` — èyí ni ohun tí
[ẹ̀ka OmniCopilot VS Code](../guides/VSCODE-COPILOT.md) ń ṣe.
### Àwọn ẹ̀yà módelì tí kò ní ìrònú
Fún àwọn módelì Claude tó lè ronú, `/v1/models` tún ń polówó ẹ̀yà **tí kò ní ìrònú** tí id rẹ̀ bẹ̀rẹ̀ pẹ̀lú `claude-3-omniroute-no-thinking/`:
```
claude-3-omniroute-no-thinking/<provider>/<model>
```
Yíyan id yìí (fún àpẹẹrẹ, nínú ètò Claude Code kan tí ó máa ń so búlọ́ọ̀kù `thinking` mọ́ ọn ní gbogbo ìgbà) máa ń yanjú padà sí `<provider>/<model>` gidi pẹ̀lú dídènà ìfèrò — `thinking:{type:"disabled"}` lórí ipa ọ̀nà `/v1/messages`, tàbí yíyọ àwọn pápá `reasoning`/`reasoning_effort` kúrò lórí ipa ọ̀nà `/v1/chat/completions`. Ẹ̀yà náà ni a ń tò sí àtòjọ fún àwọn módelì ìdílé Claude tí ó ṣe àtìlẹ́yìn fún ìrònú **tí wọ́n sì** tẹ̀lé `disabled` nìkan (nítorí náà, fún àpẹẹrẹ, àwọn módelì adaptive-only tí ó kọ `disabled` sílẹ̀ ni a yọ kúrò). Àwọn olùṣàkóso lè fi ipá tan ẹ̀yà náà tàbí pa á fún módelì kọ̀ọ̀kan nípasẹ̀ `ModelSpec.noThinkingAlias`.
---
## Àkọsílẹ̀ Àfikún Olùpèsè
```bash
GET /api/v1/provider-plugin-manifest
```
Ó dá àkọsílẹ̀ àfikún olùpèsè tó ní ààbò fún JSON padà, èyí tí Bifrost, CLIProxyAPI, àti àwọn olùdarí sidecar ọjọ́ iwájú ń lò. Ìdáhùn náà ni a ń ṣe láti inú ìforúkọsílẹ̀ olùpèsè TypeScript, ó sì mọ̀ọ́mọ̀ yọ àwọn àṣírí oníbàárà OAuth, ìyanjú àyíká runtime, àwọn iṣẹ́ executor, àwọn akọlé ìbéèrè, àti dátà àkọọ́lẹ̀ kúrò.
Lo ojú-ọ̀nà yìí nígbà tí sidecar bá ń ṣiṣẹ́ níta process tí kò sì lè ṣe import
`open-sse/config/providerPluginManifestRegistry.ts` ní tààrà.
---
## Àwọn Ojú-ọ̀nà Ìbámu
| Ọ̀nà | Ipa-ọ̀nà | Fọ́ọ̀mù |
| ---- | ----------------------------------------- | ------------------------------------------ |
| POST | `/v1/chat/completions` | OpenAI |
| POST | `/v1/messages` | Anthropic |
| POST | `/v1/responses` | Àwọn Ìdáhùn OpenAI |
| POST | `/v1/embeddings` | OpenAI |
| POST | `/v1/images/generations` | Àwọn Àwòrán OpenAI |
| POST | `/v1/images/edits` | Àwọn Àwòrán OpenAI (àtúnṣe/inpaint) |
| POST | `/v1/videos/generations` | Ìṣẹ̀dá fídíò tó dàbí ti OpenAI |
| POST | `/v1/music/generations` | Ìṣẹ̀dá orin tó dàbí ti OpenAI |
| POST | `/v1/audio/transcriptions` | Ohùn OpenAI (STT) |
| POST | `/v1/audio/speech` | OpenAI TTS (ó dá ara ohùn padà) |
| POST | `/v1/rerank` | Àtúntò ipò tó dàbí Cohere/Voyage |
| POST | `/v1/classify` | Ìsọ̀rí Jina (`api.jina.ai`) |
| POST | `/v1/segment` | Olùpín Jina (`segment.jina.ai`) |
| POST | `/v1/moderations` | Àwọn Ìṣàkóso Àkóónú OpenAI |
| GET | `/v1/models` | OpenAI |
| POST | `/v1/messages/count_tokens` | Anthropic |
| GET | `/v1beta/models` | Gemini |
| POST | `/v1beta/models/{...path}` | Gemini generateContent |
| POST | `/v1/api/chat` | Ollama |
| GET | `/api/v1/vscode/{token}/` | Orúkọ ìjápọ̀ àkójọ OpenAI |
| GET | `/api/v1/vscode/{token}/models` | Orúkọ ìjápọ̀ àwọn model OpenAI |
| POST | `/api/v1/vscode/{token}/chat/completions` | Orúkọ ìjápọ̀ OpenAI tó ní token |
| POST | `/api/v1/vscode/{token}/responses` | Orúkọ ìjápọ̀ Àwọn Ìdáhùn OpenAI tó ní token |
| POST | `/api/v1/vscode/{token}/api/chat` | Orúkọ ìjápọ̀ Ollama tó ní token |
| GET | `/api/v1/vscode/{token}/api/tags` | Orúkọ ìjápọ̀ àwọn àmì Ollama tó ní token |
Gbogbo àwọn route POST ló ń tẹ̀lé ìrísí kan náà: `Bearer your-api-key` + ara JSON tí Zod ti fọwọ́sí (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, àti bẹ́ẹ̀ bẹ́ẹ̀ lọ; wo `src/shared/validation/schemas.ts`). A máa dá 4xx padà nígbà tí ìfọwọ́sí schema bá kùnà.
Fún àwọn client tí kò lè so `Authorization: Bearer ...` mọ́ ìbéèrè, OmniRoute tún gba àwọn kọ́kọ́rọ́ API nínú URL nípasẹ̀ bóyá ìbámu query-string (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) tàbí àwọn ojú-ọ̀nà pàtó `/api/v1/vscode/{token}/...` tí a ṣàkọsílẹ̀ rẹ̀ ní ìsàlẹ̀.
```bash
# Àtúntò ipò
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
# Ìsọ̀rí Jina (àwọn ẹ̀rí ìdánimọ̀ Foundation API)
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
# Olùpín Jina
POST /v1/segment { "content": "...", "return_chunks": true }
# Ìṣàwárí Jina (s.jina.ai; àwọn orúkọ ìjápọ̀ olùpèsè: jina-search, jina-ai, jina)
POST /v1/search { "query": "...", "provider": "jina-search" }
# Àwọn ìṣàkóso àkóónú
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
# TTS — ó dá ara audio/mpeg (tàbí fọ́ọ̀mù tí a béèrè) padà
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
# Àtúnṣe àwòrán (multipart)
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
# Ìṣẹ̀dá fídíò / orin (ID model tó ní ìpilẹ̀ orúkọ olùpèsè)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." }
```
### Àwọn Route Olùpèsè Pàtó
```bash
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
```
A máa fi ìpilẹ̀ orúkọ olùpèsè kún un láìfọwọ́ṣe bí kò bá sí. Àwọn model tí kò bá olùpèsè mu máa dá `400` padà.
---
## API Àwọn Fáìlì
Endpoint àwọn fáìlì tó bá OpenAI mu fún ìwọlé/ìjáde batch àti àwọn ìgbéjáde fáìlì gẹ́gẹ́ bí ìdí lílò.
| Ọ̀nà | Path | Àpèjúwe |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| POST | `/v1/files` | Gbé fáìlì kan sókè (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — 512 MiB ó pọ̀ jù |
| GET | `/v1/files` | Ṣàtòjọ àwọn fáìlì fún kọ́kọ́rọ́ API tí a ti fìdí rẹ̀ múlẹ̀ |
| GET | `/v1/files/[id]` | Gba metadata fáìlì kan padà |
| DELETE | `/v1/files/[id]` | Pa fáìlì kan rẹ́ |
| GET | `/v1/files/[id]/content` | Ṣàn ara fáìlì gidi náà padà |
**Ìfàṣẹsí:** Kọ́kọ́rọ́ API Bearer — a pín àwọn fáìlì sí ìwọ̀n kọ́kọ́rọ́ API kọ̀ọ̀kan nípasẹ̀ `getApiKeyRequestScope`. Kọ́kọ́rọ́ kan
rí, gba, ó sì lè pa àwọn fáìlì tirẹ̀ nìkan; session dashboard tí kò ní kọ́kọ́rọ́ máa ń ka gbogbo
instance náà; fáìlì tí kò ní onílé (ìgbéjáde aláìlórúkọ tàbí ti session dashboard) ni a kọ̀ fún gbogbo
olùpè tí kì í ṣe ti session. `GET /v1/files` máa kọ olùpè aláìlórúkọ — àti kọ́kọ́rọ́ tí a gbé kalẹ̀ tí
kò bá ojútùú kankan mu — pẹ̀lú `401` àní nígbà tí `REQUIRE_API_KEY=false`, dípò ṣíṣe àtòjọ àwọn fáìlì
gbogbo tenant (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).
---
## API Àwọn Ìdìpọ̀
Ṣíṣe àkójọpọ̀ ní ìdìpọ̀ tó bá OpenAI mu.
| Ọ̀nà | Ipa-ọ̀nà | Àpèjúwe |
| ------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| POST | `/v1/batches` | Ṣẹ̀dá ìdìpọ̀ — ara ni a fìdí rẹ̀ múlẹ̀ pẹ̀lú `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) |
| GET | `/v1/batches` | Ṣàtòjọ àwọn ìdìpọ̀ |
| GET | `/v1/batches/[id]` | Gba ipò ìdìpọ̀ + `request_counts` |
| DELETE | `/v1/batches/[id]` | Pa ìdìpọ̀ tí ó ti parí/tí ó kùnà rẹ́ |
| POST | `/v1/batches/[id]/cancel` | Fagilé ìdìpọ̀ tí ó ń lọ lọ́wọ́ |
**Ìfàṣẹsí:** Kọ́kọ́rọ́ API Bearer. Àwọn ìdìpọ̀ ní ààlà fún kọ́kọ́rọ́ API kọ̀ọ̀kan lábẹ́ òfin alápa-mẹ́ta kan náà bíi
àwọn fáìlì: kọ́kọ́rọ́ tirẹ̀ nìkan, session dashboard ká gbogbo instance, àwọn àkọsílẹ̀ tí kò ní olóhun ni a kọ̀ fún gbogbo
olùpè tí kì í ṣe ti session (gbígbà padà, píparẹ́, fífagilé, àti àyẹ̀wò `input_file_id` nígbà ṣíṣẹ̀dá).
`GET /v1/batches` kọ olùpè aláìlórúkọ pẹ̀lú `401` kódà nígbà tí `REQUIRE_API_KEY=false`.
## API Ìṣàwárí
Àfoyemọ̀ olùpèsè wẹ́ẹ̀bù/ìṣàwárí (Tavily, Brave, Exa, Serper, àti bẹ́ẹ̀ bẹ́ẹ̀ lọ).
| Ọ̀nà | Path | Àpèjúwe |
| ---- | ---------------------- | ------------------------------------------------------------------------------------ |
| GET | `/v1/search` | Ṣe àkójọ àwọn olùpèsè ìṣàwárí tí a ti ṣètò + àwọn agbára wọn |
| POST | `/v1/search` | Ṣe ìbéèrè ìṣàwárí — `v1SearchSchema` ń fọwọ́sí body, ó ṣe àtìlẹ́yìn caching/coalescing |
| GET | `/v1/search/analytics` | Àwọn ìṣirò hit/latency/cache fún olùpèsè kọ̀ọ̀kan |
**Ìjẹ́rìísí:** Kọ́kọ́rọ́ API Bearer (`extractApiKey` + `isValidApiKey`). A ń fi òfin ìṣàwárí múlẹ̀ nípasẹ̀ `enforceApiKeyPolicy`.
---
## API Ìgbàjáde Wẹ́ẹ̀bù
Yọ àkóónú jáde láti URL kan nípasẹ̀ olùpèsè web-fetch tí a ti ṣètò (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).
| Ọ̀nà | Ipa-ọ̀nà | Àpèjúwe |
| ---- | --------------- | -------------------------------------------------------- |
| POST | `/v1/web/fetch` | Gba/fá àkóónú URL kan — `v1WebFetchSchema` ń fọwọ́sí body |
**Ìfàṣẹsí:** Kọ́kọ́rọ́ API Bearer (`extractApiKey` + `isValidApiKey`). A ń mú ìlànà ṣiṣẹ́ nípasẹ̀ `enforceApiKeyPolicy`.
**Ìpadà-sẹ́yìn tó mọ iye quota (#8297):** nígbà tí a kò bá fi `provider` kan pàtó hàn, a máa
lọ inú àkójọpọ̀ náà
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) ní
ètò ààyò tí kò yí padà
(kún-àkọ́kọ́) — a máa fo olùpèsè tí a ti ṣètò ṣùgbọ́n tí ààlà ìbéèrè ń dí lọ
dípò kí a gé ìbéèrè náà kúrú, àti pé ìkùnà upstream tí a lè tún gbìyànjú/quota
(HTTP 429 ní gbogbo ìgbà; 402/403 fún àwọn ipele ọ̀fẹ́ Firecrawl/Tavily/TinyFish tí ó ní irú quota —
kì í ṣe fún Jina Reader, kò sì jẹ́ fún ìbéèrè búburú 400 lásán) yóò tẹ̀síwájú sí
olùpèsè tó ní ẹ̀rí ìwọlé tí a kò tíì gbìyànjú lẹ́yìn náà ní àkókò ìbéèrè. Nígbà tí gbogbo olùpèsè inú
àkójọpọ̀ náà bá ti tán, endpoint náà yóò dá `429` kan ṣoṣo padà (pẹ̀lú header `Retry-After`)
dípò `400` gbogbogbòò tẹ́lẹ̀. Nígbà tí a bá béèrè `provider` kan ní pàtó, **kò sí**
ìpadà-sẹ́yìn ní ìkọ̀kọ̀ — olùpèsè pàtó tí ààlà ìbéèrè ń dí tàbí tí ó kùnà
yóò fi àṣìṣe tirẹ̀ hàn (`429` bí ààlà ìbéèrè bá ń dí i, bí bẹ́ẹ̀ kọ́, status
upstream náà).
---
## Ṣíṣàn WebSocket
```bash
GET /v1/ws?handshake=1
```
Ó ń fọwọ́sí handshake ìgbéga WebSocket, ó sì ń dá àwọn àpẹẹrẹ ìfiránṣẹ́ protocol lórí wire padà (`request`, `cancel`). Server WS tí a dì pọ̀ mọ́ ọn ló ń bójú tó àwọn frame WS gangan níta tábìlì route Next.js.
**Ìfàṣẹsí:** Kọ́kọ́rọ́ API Bearer nígbà handshake.
### API Responses lórí WebSocket (`codex` nìkan)
```bash
# Host:port kan náà bí API HTTP (àtìlẹ́yìn 20128); ṣe ìgbéga connection náà:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (tàbí: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")
# Frame àkọ́kọ́ GBỌ́DỌ̀ jẹ́ response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```
A so aṣojú Responses-API-over-WebSocket pọ̀ **sí `codex` nìkan ṣoṣo** (backend ChatGPT).
Ó ń tẹ́tí sí port kan náà bí API/dashboard ní àwọn path `/v1/responses`,
`/responses`, àti `/api/v1/responses`. Lórí frame `response.create` àkọ́kọ́, ó
ń ṣe ìfàṣẹsí + ìmúrasílẹ̀ nípasẹ̀ bridge `codex-responses-ws` inú, ó yan
connection OAuth codex kan, ó sì ń ṣe tunnel sí `wss://chatgpt.com/backend-api/codex/responses`
nípasẹ̀ transport `wreq-js`. **A kọ àwọn model tí kì í ṣe codex** (`codex_ws_provider_required`).
Fún routing pínpín quota, lo `model: "qtSd/<group>/codex/<model>"`. A mú un ṣẹ nínú
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.
**Ìfàṣẹsí:** Kọ́kọ́rọ́ API Bearer nígbà handshake. Server HTTP tí a dì pọ̀ mọ́ ọn (`server-ws.mjs`)
gbọdọ̀ jẹ́ entrypoint tó ń ṣiṣẹ́ (ó sì rí bẹ́ẹ̀ ní àtìlẹ́yìn, nígbà tí `app/server-ws.mjs` bá wà).
#### Id model: lo id ChatGPT lásán (láìsí prefix `codex/`)
**Codex CLI** OpenAI ń fọwọ́sí orúkọ model ní ẹ̀gbẹ́ client nígbà tí
`supports_websockets = true`, ó sì **ń kọ àwọn id tí prefix olùpèsè wà níwájú wọn** bí
`codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`). Fi id **lásán** ránṣẹ́ (fún àpẹẹrẹ `gpt-5.5`). Bridge OmniRoute jẹ́
fún codex nìkan, nítorí náà ó tún ń yanjú id lásán gẹ́gẹ́ bí model codex
(`resolveCodexWsModelInfo`) kí ó tó ṣe tunnel sí upstream — bí ó tilẹ̀ jẹ́ pé id lásán
`gpt-5.5` yóò lọ sí olùpèsè mìíràn lórí HTTP bí kò bá rí bẹ́ẹ̀.
#### Ṣíṣètò Codex CLI OpenAI
Darí Codex CLI sí OmniRoute nípa fífi olùpèsè àdáni tó ṣe àtìlẹ́yìn WebSocket
kún `~/.codex/config.toml` (lo `CODEX_HOME` ọ̀tọ̀ láti yẹra fún
fífọwọ́ kan config tó ti wà):
```toml
model = "gpt-5.5" # id lásán — KÌ Í ṢE "codex/gpt-5.5"
model_provider = "omniroute"
[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1" # má ṣe fi slash sí ẹ̀yìn; a ń yọ URL WS jáde láti inú rẹ̀ (lo https/wss ní production)
wire_api = "responses" # iye kan ṣoṣo tí a ṣe àtìlẹ́yìn fún láti Feb 2026
supports_websockets = true # ń mú transport Responses-over-WS ṣiṣẹ́
env_key = "OMNIROUTE_API_KEY" # ń tọ́jú kọ́kọ́rọ́ API OmniRoute (Bearer)
```
```bash
export OMNIROUTE_API_KEY=sk-... # kọ́kọ́rọ́ API OmniRoute kan (kọ́kọ́rọ́ èyíkéyìí bí REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```
CLI náà ń ṣe ìgbéga `base_url + /responses` sí WebSocket, OmniRoute sì ń ṣe tunnel rẹ̀
sí connection OAuth codex tí a yàn. A ti fọwọ́sí i láti ìbẹ̀rẹ̀ dé òpin lórí
server agbègbè: ChatGPT ń dá `codex.rate_limits` + `response.created` padà, ó sì ń ṣàn
completion náà.
---
## Àwọn Ìwọ̀n Ìlò & Ìjábọ̀ Àwọn Ìṣòro
| Ọ̀nà | Path | Àpèjúwe |
| ---- | ------------------- | ------------------------------------------------------------------------------------ |
| GET | `/v1/quotas/check` | Ṣàyẹ̀wò ìwọ̀n ìlò fún `provider` + `accountId` ṣáájú fífi kọ́kọ́rọ́ tí a forúkọsílẹ̀ jáde |
| POST | `/v1/issues/report` | Jábọ̀ ìkùnà ìwọ̀n ìlò/fífi kọ́kọ́rọ́ jáde sí GitHub (ó nílò `GITHUB_ISSUES_REPO` + token) |
**Ìfàṣẹsí:** Kọ́kọ́rọ́ API Bearer (`isAuthenticated`).
---
## Ìlò iṣẹ́-ara-ẹni (`/api/usage/om-usage`)
Kọ́kọ́rọ́ API èyíkéyìí lè ka ìlò àti àwọn ìwọ̀n ìlò **tirẹ̀ fúnra rẹ̀** — kò nílò ìfàṣẹsí ìṣàkóso. Èyí ni endpoint tí
client kan (CLI, pánẹ́ẹ̀lì OmniCopilot) ń lò láti fi iye owó tí ẹni tó ni kọ́kọ́rọ́ ti ná hàn án.
```bash
# Fọ́ọ̀mù ọ̀rọ̀ (àdéhùn ìtàn — ọ̀rọ̀ lásán fún terminal)
curl -H "Authorization: Bearer <your-api-key>" \
http://localhost:20128/api/usage/om-usage
# Fọ́ọ̀mù tí a ṣètò — èyí tí UI ń lò
curl -H "Authorization: Bearer <your-api-key>" \
"http://localhost:20128/api/usage/om-usage?format=json"
```
Kọ́kọ́rọ́ náà gbọ́dọ̀ ní **`allowUsageCommand`** tí a ti mú ṣiṣẹ́ (kò ṣiṣẹ́ ní àkọ́kọ́ — olùṣàkóso kọ́kọ́rọ́ API ti dashboard
ń yí i padà fún kọ́kọ́rọ́ kọ̀ọ̀kan). Láìsí i, endpoint náà yóò dáhùn `403`.
`?format=json` ń dá àkópọ̀ tí a fi ìyàtọ̀ sí padà kí olùpè má bàa ka pápá dátà láti inú
ìkọ̀. Nígbà àṣeyọrí:
```jsonc
{
"allowed": true,
// yóò wà nìkan nígbà tí kọ́kọ́rọ́ náà bá yan láti lo àwọn ààlà ìlò ti kọ́kọ́rọ́ kọ̀ọ̀kan (USD ojoojúmọ́/ọ̀sọ̀ọ̀sẹ̀):
"personal": {
"dailySpentUsd": 1.25,
"dailyLimitUsd": 5,
"dailyResetAtIso": "…",
"weeklySpentUsd": 8,
"weeklyLimitUsd": 20,
"weeklyResetAtIso": "…" /* … */,
},
// àwòrán ìwọ̀n ìlò provider tí a yàn, tàbí null nígbà tí kò sí ohun tí a ti cache síbẹ̀:
"provider": {
"connectionId": "…",
"provider": "claude",
"plan": "…",
"quotas": {/* … */},
},
// àwòrán gbogbo connection, kí UI lè ṣàfihàn ọ̀pọ̀ provider lẹ́gbẹ̀ẹ́ ara wọn:
"providers": [
{ "connectionId": "…", "provider": "claude" /* … */ },
{ "provider": "codex" /* … */ },
],
}
```
Nígbà ìkọ̀ (`401` kọ́kọ́rọ́ tí kò tọ́ / `403` kò gba láàyè), route kan náà yóò dá
`{ "allowed": false, "error": { "message": "…" } }` padà — `personal`/`provider` tó wà ṣùgbọ́n tó ṣófo
(kọ́kọ́rọ́ gba láàyè, kò tíì sí ohun tí a mọ̀) jẹ́ ipò tó yàtọ̀ sí ìkọ̀, fọ́ọ̀mù JSON nìkan sì
ni ó ń fi ìyàtọ̀ wọn hàn.
**Ìfàṣẹsí:** Kọ́kọ́rọ́ API Bearer ti olùpè fúnra rẹ̀, tí a fìdí rẹ̀ múlẹ̀ pẹ̀lú `isValidApiKey` — èyí _kì í ṣe_
ojú-iṣẹ́ ìṣàkóso (`/api/keys/…`), èyí tí ó ṣì wà lẹ́yìn `requireManagementAuth`.
---
## Cache Semantic
```bash
# Gba àwọn ìṣirò cache
GET /api/cache/stats
# Pa gbogbo cache rẹ́
DELETE /api/cache/stats
```
Àpẹẹrẹ èsì:
```json
{
"semanticCache": {
"memorySize": 42,
"memoryMaxSize": 500,
"dbSize": 128,
"hitRate": 0.65
},
"idempotency": {
"activeKeys": 3,
"windowMs": 5000
}
}
```
### Ipa lórí latency
Cache semantic HIT ń pèsè èsì láti cache **láìsí ìpè upstream
kankan**, nítorí náà `X-OmniRoute-Response-Latency` tí a jábọ̀ sún mọ́ òdo
(láìka latency upstream ìpilẹ̀ṣẹ̀ sí). Àwọn client tí latency ṣe pàtàkì sí
(benchmarking, àbójútó p50/p99) gbọ́dọ̀ ṣàyẹ̀wò header èsì
`X-OmniRoute-Cache-Latency`:
| Iye | Ìtumọ̀ |
| ----------- | ---------------------------------------------------------- |
| `synthetic` | A pèsè èsì láti cache; latency kì í ṣe àkókò upstream gidi |
| _(kò sí)_ | Èsì láti inú ìpè upstream gidi |
### Yíyẹ cache kọjá fún kọ́kọ́rọ́ kọ̀ọ̀kan
Àwọn kọ́kọ́rọ́ API lè jáde kúrò nínú kíka cache semantic nípasẹ̀ `cacheDefaultMode`:
| Iye | Ìhùwàsí |
| -------- | ------------------------------------------------------------ |
| `legacy` | Ìhùwàsí cache déédéé (àkọ́kọ́) |
| `bypass` | Fò àwárí cache kọjá pátápátá; máa lo upstream ní gbogbo ìgbà |
Ṣètò rẹ̀ nígbà ṣíṣẹ̀dá kọ́kọ́rọ́ (`POST /api/keys`) tàbí nígbà ìmúdójúìwọ̀n (`PATCH /api/keys/[id]`):
```json
{ "cacheDefaultMode": "bypass" }
```
### Yíyẹ cache kọjá fún ìbéèrè kọ̀ọ̀kan
Ìbéèrè èyíkéyìí lè yọ cache sílẹ̀ láìka àwọn ètò kọ́kọ́rọ́ sí:
```
X-OmniRoute-No-Cache: true
```
---
## Pátákó Ìṣàkóso & Ìṣàkóso
Àwọn ipa-ọ̀nà ìṣàkóso (`/api/*` àyàfi ìfàṣẹ̀sí/wíwọlé gbogbogbòò) **kò** gba àṣẹ láti ọ̀dọ̀ àwọn kọ́kọ́rọ́ API ìtọ́kasí lásán.
Àwọn ìdílé ẹ̀rí ìdánimọ̀, àwọn ààlà àṣẹ, àti àwọn àpẹẹrẹ curl:
[Ìfàṣẹ̀sí Ìṣàkóso](../guides/MANAGEMENT-AUTH.md).
### Ìfàṣẹ̀sí
| Ojú-ọ̀nà | Ọ̀nà | Àpèjúwe |
| ----------------------------- | ------- | ---------------------- |
| `/api/auth/login` | POST | Wíwọlé |
| `/api/auth/logout` | POST | Jíjáde |
| `/api/settings/require-login` | GET/PUT | Tan/pa àìní fún wíwọlé |
### Ìṣàkóso Olùpèsè
| Ojú-ọ̀nà | Ọ̀nà | Àpèjúwe |
| ---------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `/api/providers` | GET/POST | Ṣàfihàn / ṣẹ̀dá àwọn olùpèsè |
| `/api/providers/[id]` | GET/PUT/DELETE | Ṣàkóso olùpèsè kan |
| `/api/providers/[id]/test` | POST | Dán àsopọ̀ olùpèsè wò |
| `/api/providers/[id]/models` | GET | Ṣàfihàn àwọn àwòṣe olùpèsè |
| `/api/providers/validate` | POST | Fìdí ìṣètò olùpèsè múlẹ̀ |
| `/api/providers/bulk` | POST | Ṣàfikún àwọn kọ́kọ́rọ́ API lọ́pọ̀lọpọ̀ fún olùpèsè KAN |
| `/api/providers/import` | POST | Gbé ÀKÓJỌ àwọn olùpèsè onírúurú wọlé láti inú fáìlì CSV/JSON tí a ti túpalẹ̀ (#6836); àwọn àbájáde ìkùnà-apá kan fún ìlà kọ̀ọ̀kan |
| `/api/provider-nodes*` | Onírúurú | Ìṣàkóso nóòdù olùpèsè |
| `/api/provider-models` | GET/POST/PATCH/DELETE | Àwọn àwòṣe àkànṣe (ṣàfikún, ṣe ìmúdójúìwọ̀n, fi pamọ́/ṣàfihàn, parẹ́) |
### Àwọn Ìṣàn OAuth
| Ojú-ọ̀nà | Ọ̀nà | Àpèjúwe |
| -------------------------------- | -------- | --------------------------- |
| `/api/oauth/[provider]/[action]` | Onírúurú | OAuth tó jẹ́ ti olùpèsè pàtó |
### Ìdarí Ọ̀nà & Ìṣètò
| Ojú-ọ̀nà | Ọ̀nà | Àpèjúwe |
| --------------------- | -------- | ---------------------------------- |
| `/api/models/alias` | GET/POST | Àwọn orúkọ ìnagijẹ àwòṣe |
| `/api/models/catalog` | GET | Gbogbo àwòṣe gẹ́gẹ́ bí olùpèsè + irú |
| `/api/combos*` | Onírúurú | Ìṣàkóso àkójọpọ̀ |
| `/api/keys*` | Onírúurú | Ìṣàkóso kọ́kọ́rọ́ API |
| `/api/pricing` | GET | Ìdíyelé àwòṣe |
### Ìlò & Ìtúpalẹ̀
| Òpin-ọ̀nà | Ọ̀nà | Àpèjúwe |
| -------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history` | GET | Ìtàn lílò |
| `/api/usage/logs` | GET | Àwọn àkọsílẹ̀ lílò |
| `/api/usage/request-logs` | GET | Àwọn àkọsílẹ̀ ní ìpele ìbéèrè |
| `/api/usage/[connectionId]` | GET | Lílò fún ìsopọ̀ kọ̀ọ̀kan |
| `/api/usage/token-limits` | GET/POST/DELETE | Àwọn ìṣúná ààlà token fún kọ́kọ́rọ́ API kọ̀ọ̀kan |
| `/api/usage/model-latency-stats` | GET | Àkójọpọ̀ àyíká ti ìdádúró fún olùpèsè/model kọ̀ọ̀kan (avg/p50/p95/p99, ìwọ̀n àṣeyọrí); àwọn àsẹ̀: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) |
| `/api/usage/cache-health` | GET | Àkótán ìlera ibi ìpamọ́ prompt lórí `call_logs` — ìpín kíkọ/kíkà, ìpínkiri ìwọ̀n-kíkọ p50/p90/p99, ìkojúpọ̀ kíkọ tó pọ̀, ìpín nípa model kọ̀ọ̀kan, àti ìdájọ́ `healthy`/`degraded`/`thrash`/`no-data`; àwọn paramita ìbéèrè `range` (`1h`\|`24h`\|`7d`\|`30d`, àìyípadà `24h`) àti `model` àṣàyàn (#8827) |
### Àwọn Ètò
| Òpin-ọ̀nà | Ọ̀nà | Àpèjúwe |
| ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings` | GET/PUT/PATCH | Àwọn ètò gbogbogbò |
| `/api/settings/proxy` | GET/PUT | Àtúnṣe proxy nẹ́tíwọ́ọ̀kì |
| `/api/settings/proxy/test` | POST | Ṣe àyẹ̀wò ìsopọ̀ proxy |
| `/api/settings/ip-filter` | GET/PUT | Àkójọ IP tí a fàyè gba/dènà |
| `/api/settings/thinking-budget` | GET/PUT | Ìpo àtúkọ **ìbéèrè** fún èrò/ìrònú (passthrough / auto-strip / custom / adaptive). Ó dá dúró lọ́tọ̀ sí ìfúnpọ̀. Wo [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). |
| `/api/settings/system-prompt` | GET/PUT | Prompt ètò gbogbogbò |
| `/api/settings/compression` | GET/PUT | Àtúnṣe ìfúnpọ̀ gbogbogbò |
| `/api/settings/purge-request-history` | POST | Pa àwọn ìlà àkọsílẹ̀ ìbéèrè àti àwọn ohun èlò àkọsílẹ̀ ìpè agbègbè rẹ́ |
### Àyíká-ọ̀rọ̀ & Ìfúnpọ̀
| Endpoint | Ọ̀nà | Àpèjúwe |
| -------------------------------------- | -------------- | ------------------------------------------------------------------- |
| `/api/compression/preview` | POST | Ṣàkọ́kọ́-wo ìfúnpọ̀ off/lite/standard/aggressive/ultra/RTK/stacked |
| `/api/compression/language-packs` | GET | Ṣàkójọ àwọn àkójọpọ̀ èdè Caveman tó wà |
| `/api/compression/rules` | GET | Ṣàkójọ metadata àwọn òfin Caveman |
| `/api/context/caveman/config` | GET/PUT | Orúkọ àfikún fún àwọn ètò tó jẹ́ ti Caveman |
| `/api/context/rtk/config` | GET/PUT | Àwọn ètò tó jẹ́ ti RTK, pẹ̀lú àwọn asẹ àdáni àti ìtọ́jú àbájáde àìṣẹ̀dá |
| `/api/context/rtk/filters` | GET | Kátálọ́ọ̀gù asẹ RTK àti àyẹ̀wò ìṣòro àwọn asẹ àdáni |
| `/api/context/rtk/test` | POST | Ṣiṣẹ́ àkọ́kọ́-wo/ìdánwò RTK lórí payload ọ̀rọ̀ kan |
| `/api/context/rtk/raw-output/[id]` | GET | Ka àbájáde àìṣẹ̀dá tí a ti bo àlàyé rẹ̀, tí a sì tọ́jú, nípa id atọ́ka |
| `/api/context/combos` | GET/POST | Ṣàkójọ/dá àpapọ̀ ìfúnpọ̀ sílẹ̀ |
| `/api/context/combos/[id]` | GET/PUT/DELETE | Àlàyé/ìṣàfikún/ìparẹ́ àpapọ̀ ìfúnpọ̀ |
| `/api/context/combos/[id]/assignments` | GET/PUT | Yan àwọn àpapọ̀ ìfúnpọ̀ sí àwọn àpapọ̀ ìdarí ipa-ọ̀nà |
| `/api/context/analytics` | GET | Orúkọ àfikún fún ìtúpalẹ̀ ìfúnpọ̀ |
### Ìṣọ́ra
| Endpoint | Ọ̀nà | Àpèjúwe |
| ------------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions` | GET | Ìtọ́pa àwọn ìgbà ìṣiṣẹ́ tó ń lọ lọ́wọ́ |
| `/api/rate-limits` | GET | Àwọn òpin ìwọ̀n fún àkọọ́lẹ̀ kọ̀ọ̀kan |
| `/api/monitoring/health` | GET | Àyẹ̀wò ìlera + àkótán olùpèsè (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Ìwòye ìṣàkóso ní `credentialHealth` nínú: àwọn iye ẹyọkan cache ìwádìí, `failedConnections` nígbà tí `failed>0`, àti `staleDbNonOkCount` (`test_status` SQLite tó dúró ṣinṣin, kì í ṣe gauge náà). Wo [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). |
| `/api/cache/stats` | GET/DELETE | Àwọn ìṣirò cache / pa á rẹ́ |
| `/api/modality-bridge/stats` | GET | `attempts` inú-memory, àwọn àṣeyọrí/`bridged`, àwọn ìkùnà, àwọn ìkànlù cache, `totalLatencyMs`, `latencySamples`, `averageLatencyMs` tí iye àpẹẹrẹ pín, àti àkókò lílò tó kẹ́yìn (ó tún padà síbẹ̀rẹ̀ nígbà àtúnṣe; ìfàṣẹ̀sí ìṣàkóso) |
| `/api/modality-bridge/video/runtime` | GET | Àyẹ̀wò trusted-loopback tó muna ṣáájú ìfàṣẹ̀sí/ìwádìí ìṣàkóso; wíwà FFmpeg/ffprobe àti àwọn version tí a ti fọ́ mọ́ (no-store) |
| `/api/modality-bridge/video/extract` | POST | Alárinà byte trusted-loopback inú-iṣẹ́ tó ní ìfàṣẹ̀sí; ìwọlé 50 MiB, ìlà tó ní ààlà/àbájáde 32 MiB, agbára `503`, ìjáwọ́ `499`, àkókò ìparí `504`; kì í ṣe API ìrùsókè gbogbogbò |
### Àfẹ́yinti & Gbigbe Jáde/Gbigbe Wọlé
| Endpoint | Ọ̀nà | Àpèjúwe |
| --------------------------- | ---- | --------------------------------------------------- |
| `/api/db-backups` | GET | Ṣàkójọ àwọn àfẹ́yìntì tó wà |
| `/api/db-backups` | PUT | Ṣẹ̀dá àfẹ́yìntì afọwọ́ṣe |
| `/api/db-backups` | POST | Mú padà láti inú àfẹ́yìntì kan pàtó |
| `/api/db-backups/export` | GET | Ṣe ìgbàsílẹ̀ ibi ìpamọ́ dátà gẹ́gẹ́ bí fáìlì .sqlite |
| `/api/db-backups/import` | POST | Ṣe àgbérù fáìlì .sqlite láti fi rọ́pò ibi ìpamọ́ dátà |
| `/api/db-backups/exportAll` | GET | Ṣe ìgbàsílẹ̀ àfẹ́yìntì kíkún gẹ́gẹ́ bí àkójọpọ̀ .tar.gz |
### Ìṣiṣẹ́pọ̀ Àwọsánmà
| Endpoint | Ọ̀nà | Àpèjúwe |
| ---------------------- | --------- | ------------------------- |
| `/api/sync/cloud` | Oríṣiríṣi | Àwọn iṣẹ́ ìṣiṣẹ́pọ̀ àwọsánmà |
| `/api/sync/initialize` | POST | Bẹ̀rẹ̀ ìṣiṣẹ́pọ̀ |
| `/api/cloud/*` | Oríṣiríṣi | Ìṣàkóso àwọsánmà |
### Àwọn Túnẹ́lì
| Endpoint | Ọ̀nà | Àpèjúwe |
| -------------------------- | ---- | ------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET | Ka ipò ìfisí/ìṣiṣẹ́ Cloudflare Quick Tunnel fún pánẹ́ẹ̀lì ìṣàkóso |
| `/api/tunnels/cloudflared` | POST | Mú Cloudflare Quick Tunnel ṣiṣẹ́ tàbí pa á (`action=enable/disable`) |
| `/api/tunnels/ngrok` | GET | Ka ipò ìṣiṣẹ́ ngrok Tunnel fún pánẹ́ẹ̀lì ìṣàkóso |
| `/api/tunnels/ngrok` | POST | Mú ngrok Tunnel ṣiṣẹ́ tàbí pa á (`action=enable/disable`) |
### Àwọn Irinṣẹ́ CLI
| Endpoint | Ọ̀nà | Àpèjúwe |
| ---------------------------------- | --- | ------------------------- |
| `/api/cli-tools/claude-settings` | GET | Ipò Claude CLI |
| `/api/cli-tools/codex-settings` | GET | Ipò Codex CLI |
| `/api/cli-tools/droid-settings` | GET | Ipò Droid CLI |
| `/api/cli-tools/openclaw-settings` | GET | Ipò OpenClaw CLI |
| `/api/cli-tools/runtime/[toolId]` | GET | Àkókò-ṣiṣe CLI gbogbogbòò |
Àwọn èsì CLI ní: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
### Àwọn Aṣojú ACP
| Endpoint | Ọ̀nà | Àpèjúwe |
| ----------------- | ------ | --------------------------------------------------------------------------- |
| `/api/acp/agents` | GET | Ṣàkójọ gbogbo àwọn aṣojú tí a ṣàwárí (tí a kọ sínú rẹ̀ + àdáni) pẹ̀lú ipò wọn |
| `/api/acp/agents` | POST | Ṣàfikún aṣojú àdáni tàbí sọ ibi ìpamọ́ ìṣàwárí di ọ̀tun |
| `/api/acp/agents` | DELETE | Yọ aṣojú àdáni kúrò nípasẹ̀ párámítà ìbéèrè `id` |
Èsì GET ní `agents[]` (id, name, binary, version, installed, protocol, isCustom) àti `summary` (total, installed, notFound, builtIn, custom).
### Ìfaradà & Àwọn Ààlà Ìwọ̀n
| Endpoint | Ọ̀nà | Àpèjúwe |
| --------------------------------- | --------- | --------------------------------------------------------------------------------------------- |
| `/api/resilience` | GET/PATCH | Gba/ṣe àtúnṣe ìlà ìbéèrè, àkókò ìtutù àsopọ̀, olùdádúró olùpèsè, àti àwọn ètò ìdúró |
| `/api/resilience/reset` | POST | Tún àwọn olùdádúró sákítì olùpèsè ṣe |
| `/api/resilience/model-cooldowns` | GET | Ṣàkójọ àwọn ìdènà tó ń ṣiṣẹ́ fún ọ̀kọ̀ọ̀kan (olùpèsè, àsopọ̀, módẹ́ẹ̀lì), tí a tò nípasẹ̀ àkókò tó kù |
| `/api/resilience/model-cooldowns` | DELETE | Pa ìdènà módẹ́ẹ̀lì rẹ́ — ara `{provider, model}` tàbí `{all: true}` láti pa gbogbo rẹ̀ |
| `/api/rate-limits` | GET | Ipò ààlà ìwọ̀n fún àkọọ́lẹ̀ kọ̀ọ̀kan |
| `/api/rate-limit` | GET | Ìṣètò ààlà ìwọ̀n gbogbogbòò |
> Gbogbo àwọn ipa ọ̀nà `/api/resilience/*` mẹ́rẹ̀ẹ̀rin nílò **ìfàṣẹsí ìṣàkóso** (`requireManagementAuth`). Wo [Ìfaradà (àfikún)](#resilience-extended) fún àlàyé kíkún nípa olùdádúró olùpèsè ní ìfiwéra pẹ̀lú àkókò ìtutù àsopọ̀ àti ìdènà módẹ́ẹ̀lì.
### Àwọn Ìdánwò Ìṣírò
| Endpoint | Ọ̀nà | Àpèjúwe |
| ------------ | -------- | -------------------------------------- |
| `/api/evals` | GET/POST | Ṣàkójọ àwọn àkójọpọ̀ ìdánwò / ṣe ìdánwò |
### Àwọn Ìlànà
| Endpoint | Ọ̀nà | Àpèjúwe |
| --------------- | --------------- | ------------------------------- |
| `/api/policies` | GET/POST/DELETE | Ṣàkóso àwọn ìlànà ìdarí ipa ọ̀nà |
### Ìbámu
| Endpoint | Ọ̀nà | Àpèjúwe |
| --------------------------- | --- | -------------------------------- |
| `/api/compliance/audit-log` | GET | Àkọsílẹ̀ àyẹ̀wò ìbámu (N tó kẹ́yìn) |
### v1beta (Tó Bá Gemini Mu)
| Endpoint | Ọ̀nà | Àpèjúwe |
| -------------------------- | ---- | ----------------------------------- |
| `/v1beta/models` | GET | Ṣàkójọ àwọn módẹ́ẹ̀lì ní fọ́ọ̀mù Gemini |
| `/v1beta/models/{...path}` | POST | Endpoint Gemini `generateContent` |
Àwọn endpoint wọ̀nyí ń ṣe àfarawé fọ́ọ̀mù API Gemini fún àwọn oníbàárà tó nílò ìbámu pẹ̀lú Gemini SDK abinibi.
### Àwọn API Abẹ́nú / Ẹ̀rọ
| Endpoint | Ọ̀nà | Àpèjúwe |
| ------------------------ | ---- | --------------------------------------------------------- |
| `/api/init` | GET | Àyẹ̀wò ìpilẹ̀ṣẹ̀ ètò (tí a máa ń lò nígbà ìṣiṣẹ́ àkọ́kọ́) |
| `/api/tags` | GET | Àwọn àmì àwòṣe tó bá Ollama mu (fún àwọn oníbàárà Ollama) |
| `/api/restart` | POST | Bẹ̀rẹ̀ àtúnṣí olupin lọ́nà tó bójú mu |
| `/api/shutdown` | POST | Bẹ̀rẹ̀ ìdádúró olupin lọ́nà tó bójú mu |
| `/api/system/env/repair` | POST | Ṣàtúnṣe àwọn àyípadà àyíká olùpèsè OAuth |
> **Àkíyèsí:** Ètò náà máa ń lo àwọn endpoint wọ̀nyí ní inú rẹ̀ tàbí fún ìbámu pẹ̀lú oníbàárà Ollama. Àwọn olùlò ìkẹyìn kì í sábà pè wọ́n.
### Àtúnṣe Àyíká OAuth _(v3.6.1+)_
```bash
POST /api/system/env/repair
Content-Type: application/json
{
"provider": "claude-code"
}
```
Ó máa ń ṣàtúnṣe àwọn àyípadà àyíká OAuth tó sọnù tàbí tó bàjẹ́ fún olùpèsè kan pàtó. Ó máa ń dá èyí padà:
```json
{
"success": true,
"repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
"backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}
```
---
## Ìkọ̀wé Ohùn sí Ọ̀rọ̀
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
```
Ṣe ìkọ̀wé àwọn fáìlì ohùn sí ọ̀rọ̀ nípa lílo olùpèsè STT èyíkéyìí tí a ti ṣètò. Apá àkọ́kọ́ ọ̀nà náà
ń yan olùpèsè abínibí (`openai/…`, `deepgram/…`). Àwọn ẹnu-ọ̀nà tí
ń tún àwòṣe olùtajà mìíràn gbé jáde máa ń lo id tó ní àfikún orúkọ
(`openrouter/deepgram/nova-3`).
**Ìbéèrè:**
```bash
curl -X POST http://localhost:20128/v1/audio/transcriptions \
-H "Authorization: Bearer your-api-key" \
-F "file=@recording.mp3" \
-F "model=openai/whisper-1"
```
**Ìdáhùn:**
```json
{
"text": "Hello, this is the transcribed audio content.",
"task": "transcribe",
"language": "en",
"duration": 12.5
}
```
**Àwọn àpẹẹrẹ id àwòṣe:** `openai/whisper-1` (ó nílò kọ́kọ́rọ́ OpenAI),
`openrouter/deepgram/nova-3` (ó nílò kọ́kọ́rọ́ OpenRouter),
`deepgram/nova-3` (ó nílò kọ́kọ́rọ́ Deepgram abínibí). Ìbéèrè
`deepgram/nova-3` lásán **kì í** lo OpenRouter.
**Àwọn ìgúnrégé tí a ṣe àtìlẹ́yìn fún:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
---
## Ìbámu Pẹ̀lú Ollama
Fún àwọn kíláyẹ́ǹtì tí ń lo ìgúnrégé API Ollama:
```bash
# Ojú-ọ̀nà ìfọ̀rọ̀wérọ̀ (ìgúnrégé Ollama)
POST /v1/api/chat
# Àtòjọ àwọn àwòṣe (ìgúnrégé Ollama)
GET /api/tags
```
A máa ń túmọ̀ àwọn ìbéèrè láìfọwọ́ṣe láàárín àwọn ìgúnrégé Ollama àti ti inú ètò.
## Àwọn Orúkọ Ìpè Tokenized fún VS Code / Tí Kò Ní Header
Lo àwọn orúkọ ìpè wọ̀nyí nígbà tí ìsopọ̀ kan kò bá lè fi header `Authorization` kún un, tí ó sì nílò kí a fi kọ́kọ́rọ́ API sínú URL ìpìlẹ̀.
```bash
# Orúkọ ìpè àkójọ-ọjà tó dà bíi ti OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models
# Àwọn orúkọ ìpè ìfọ̀rọ̀wérọ̀ tó dà bíi ti OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses
# Àwọn orúkọ ìpè tó dà bíi ti Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```
Àpẹẹrẹ:
```bash
curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'
```
Àwọn àkíyèsí:
- Àwọn orúkọ ìpè tokenized náà tún ń lo àwọn olùdarí kan náà bíi `/v1/*` àti `/api/tags`; ìrísí àwọn ìdáhùn ṣì máa ń jẹ́ ọ̀kan náà.
- Yan `Authorization: Bearer ...` nígbàkigbà tí kíláyẹ́ǹtì bá ṣe àtìlẹ́yìn fún àwọn header àdáni.
- Àwọn token tó dá lórí URL lè hàn nínú àwọn àkọsílẹ̀ reverse-proxy, ìtàn aṣàwákiri, àti telemetry ní òde OmniRoute. Ka wọ́n sí ọ̀nà àṣàyàn fún ìbámu, kì í ṣe ọ̀nà ìfàṣẹsí àìyípadà.
---
## Telemetry
```bash
# Gba àkótán telemetry ìdádúró (p50/p95/p99 fún olùpèsè kọ̀ọ̀kan)
GET /api/telemetry/summary
```
**Ìdáhùn:**
```json
{
"providers": {
"claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
"github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
}
}
```
---
## Ìnáwó Tí A Yàn Sílẹ̀
```bash
# Gba ipò ìnáwó tí a yàn sílẹ̀ fún gbogbo kọ́kọ́rọ́ API
GET /api/usage/budget
# Ṣètò tàbí ṣe ìmúdójúìwọ̀n ìnáwó tí a yàn sílẹ̀
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"
}
```
> **Àwọn àkíyèsí schema** (`setBudgetSchema`): `apiKeyId` jẹ́ dandan; ó kéré tán, ọ̀kan lára `dailyLimitUsd`, `weeklyLimitUsd`, tàbí `monthlyLimitUsd` gbọ́dọ̀ ju òdo lọ. Àwọn field àṣàyàn: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Ìrísí àtijọ́ `{keyId, limit, period}` máa ń dá `400 Bad Request` padà.
## Àwọn Ààlà Token
Àwọn ìṣúná **token** fún kọ́kọ́rọ́ API kọ̀ọ̀kan (tí ó yàtọ̀ sí Ìṣúná tó dá lórí USD lókè). A ń fipá mú wọn ṣiṣẹ́ lẹ́sẹ̀kẹsẹ̀ lórí ipa-ọ̀nà ìbéèrè: nígbà tí lílò kọ́kọ́rọ́ kan nínú àkókò rẹ̀ bá dé ààlà rẹ̀, a ó kọ àwọn ìbéèrè pẹ̀lú `429 Too Many Requests`. A lè fi ààlà kan mọ́ `model` kan pàtó, `provider` kan, tàbí kí a lò ó ní `global` káàkiri kọ́kọ́rọ́ náà; nígbà tí ọ̀pọ̀ ààlà bá bá ìbéèrè kan mu, èyí tó le jù lọ ni yóò borí.
```bash
# Ṣàfihàn àwọn ààlà token kọ́kọ́rọ́ kan (pẹ̀lú lílò àkókò lọ́wọ́lọ́wọ́)
GET /api/usage/token-limits?apiKeyId=key-123
# Ṣẹ̀dá tàbí ṣàfikún ààlà token kan
POST /api/usage/token-limits
Content-Type: application/json
{
"apiKeyId": "key-123",
"scopeType": "model",
"scopeValue": "openai/gpt-4o",
"tokenLimit": 1000000,
"resetInterval": "monthly",
"enabled": true
}
# Pa ààlà token kan rẹ́ nípasẹ̀ id
DELETE /api/usage/token-limits?id=tl-abc
```
> **Àwọn àkíyèsí schema** (`setTokenLimitSchema`): `apiKeyId` àti `scopeType` (`model` | `provider` | `global`) jẹ́ dandan. `scopeValue` jẹ́ dandan àyàfi tí `scopeType` bá jẹ́ `global` (fún àpẹẹrẹ, id model fún ìwọ̀n `model`, id provider fún ìwọ̀n `provider`). `tokenLimit` gbọ́dọ̀ jẹ́ odidi rere (a ń yí i padà láti inú string). Àwọn ohun àṣàyàn: `id` (má ṣe fi kún un láti ṣẹ̀dá, fi kún un láti ṣe àfikún), `resetInterval` (`daily` | `weekly` | `monthly`, àìyípadà rẹ̀ jẹ́ `monthly`), `resetTime` (`HH:MM`), `enabled` (àìyípadà rẹ̀ jẹ́ `true`). Àwọn ìdáhùn `GET` ń fi `tokensUsed`, `remaining`, `windowStart`, `periodStartAt`, àti `nextResetAt` kún àlàyé ààlà kọ̀ọ̀kan. Èyí jẹ́ endpoint irú ìṣàkóso (a ń fipá mú ìfàṣẹsí ṣiṣẹ́ ní àárín gbùngbùn nípasẹ̀ pipeline authz).
## Ṣíṣe Ìbéèrè
1. Client fi ìbéèrè ránṣẹ́ sí `/v1/*`
2. Route handler pe `handleChat`, `handleEmbedding`, `handleAudioTranscription`, tàbí `handleImageGeneration`
3. A yan model náà (provider/model tààrà tàbí alias/combo)
4. A yan àwọn credentials láti inú DB agbègbè pẹ̀lú ṣíṣàyẹ̀wò wíwà account
5. Fún chat: `handleChatCore` ń ṣàyẹ̀wò cache semantic/signature, ó sì ń yan àwọn ètò compression combo
6. Compression ìṣáájú ń ṣiṣẹ́ kí ìtumọ̀ provider tó bẹ̀rẹ̀ nígbà tí a bá mú un ṣiṣẹ́ (`lite`, Caveman, RTK, tàbí stacked)
7. Provider executor fi ìbéèrè ránṣẹ́ sí upstream
8. A túmọ̀ ìdáhùn padà sí format client (chat) tàbí a dá a padà bí ó ṣe rí (embeddings/images/audio)
9. A ṣàkọsílẹ̀ usage, àwọn analytics compression, àti àwọn log ìbéèrè
10. Fallback ń ṣiṣẹ́ lórí àwọn àṣìṣe gẹ́gẹ́ bí àwọn òfin combo
Ìtọ́kasí architecture kíkún: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)
---
## Ìṣàkóso Combo
Àwọn combo routing tó wà ní ipele gíga (tí a ti ṣe àkópọ̀ wọn lábẹ́ `/api/combos*`) tún lè ní ìbáramu 1:1 láti inú pattern id model kan, èyí tó ń jẹ́ kí a lè darí id model irú OpenAI lọ sí combo láìsí ìdíwọ́.
| Ọ̀nà | Ipa-ọ̀nà | Àpèjúwe |
| ------ | -------------------------------- | ---------------------------------------------------------------------------- |
| GET | `/api/model-combo-mappings` | Ṣàfihàn gbogbo àwọn ìbáramu model→combo |
| POST | `/api/model-combo-mappings` | Ṣẹ̀dá ìbáramu — body: `{pattern, comboId, priority?, enabled?, description?}` |
| GET | `/api/model-combo-mappings/[id]` | Gba ìbáramu kan ṣoṣo |
| PUT | `/api/model-combo-mappings/[id]` | Ṣe àfikún àwọn field ìbáramu tó ti wà |
| DELETE | `/api/model-combo-mappings/[id]` | Yọ ìbáramu kan kúrò |
**Auth:** session/API key ìṣàkóso (`requireManagementAuth`).
---
## Àwọn Webhook
Àwọn ìforúkọsílẹ̀ webhook tí ń jáde fún àwọn ìṣẹ̀lẹ̀ OmniRoute (ìparí ìbéèrè, lílo ìpín tán, yíyí kọ́kọ́rọ́ padà, àti bẹ́ẹ̀ bẹ́ẹ̀ lọ).
| Ọ̀nà | Ipa-ọ̀nà | Àpèjúwe |
| ------ | ------------------------- | ----------------------------------------------------------------------- |
| GET | `/api/webhooks` | Ṣàtòjọ àwọn webhook (àwọn aṣírí ni a fi `<prefix>...` bo) |
| POST | `/api/webhooks` | Ṣẹ̀dá webhook — ara: `{url, events?: ["*"], secret?, description?}` |
| GET | `/api/webhooks/[id]` | Gba webhook kan |
| PUT | `/api/webhooks/[id]` | Ṣàfikún url/events/secret/description |
| DELETE | `/api/webhooks/[id]` | Yọ webhook kan kúrò |
| POST | `/api/webhooks/[id]/test` | Fi payload ìdánwò ránṣẹ́ sí URL webhook náà kí o sì dá ipò ìfiránṣẹ́ padà |
**Ìfàṣẹsí:** sáẹ́ṣọ̀nù ìṣàkóso/kọ́kọ́rọ́ API (`requireManagementAuth`).
---
## Àwọn Kọ́kọ́rọ́ Tí A Forúkọ Sílẹ̀ (Ìṣàkóso Aládàáṣe)
Ètò abẹ́lẹ̀ ìṣàkóso kọ́kọ́rọ́ aládàáṣe ń lò ó láti pèsè àti yí àwọn kọ́kọ́rọ́ API padà pẹ̀lú olupèsè/àkọọ́lẹ̀ alátìlẹ́yìn, pẹ̀lú àwọn ìpín ojoojúmọ́/wákàtí.
| Ọ̀nà | Ipa-ọ̀nà | Àpèjúwe |
| ------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/registered-keys` | Ṣàtòjọ àwọn kọ́kọ́rọ́ tí a forúkọ sílẹ̀ (prefix tí a bo nìkan) |
| POST | `/api/v1/registered-keys` | Pèsè kọ́kọ́rọ́ tuntun tí a forúkọ sílẹ̀ — ara: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Ó dá kọ́kọ́rọ́ gidi padà **lẹ́ẹ̀kan ṣoṣo**. Ó dá `429` padà bí a bá kọ̀ ọ́ nítorí ìpín. |
| GET | `/api/v1/registered-keys/[id]` | Gba metadata kọ́kọ́rọ́ tí a forúkọ sílẹ̀ (láìsí ohun èlò gidi) |
| DELETE | `/api/v1/registered-keys/[id]` | Fagilé kọ́kọ́rọ́ tí a forúkọ sílẹ̀ |
| POST | `/api/v1/registered-keys/[id]/revoke` | Endpoint ìfagilé tààrà (ipa kan náà bí DELETE) |
**Ìfàṣẹsí:** Kọ́kọ́rọ́ API Bearer (`isAuthenticated`). Tún wo `/v1/quotas/check` àti `/v1/issues/report`.
---
## Ilana Àwọn Aṣojú
Àwọn iṣẹ́ aṣojú awọsánmà (Claude Code, Codex Cloud, OpenHands, abbl.) tí a ń ṣiṣẹ́ láti ọ̀nà jíjìn ní orúkọ àwọn olumulo OmniRoute.
| Ọ̀nà | Ojú-ọ̀nà | Àpèjúwe |
| ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/v1/agents/tasks` | Ṣàkọsílẹ̀ àwọn iṣẹ́ — `?provider=`, `?status=`, `?limit=` jẹ́ àṣàyàn (1–500, àìyípadà 50) |
| POST | `/api/v1/agents/tasks` | Ṣẹ̀dá iṣẹ́ — a fìdí body múlẹ̀ pẹ̀lú `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Ó dá `201` padà pẹ̀lú àpò iṣẹ́ |
| DELETE | `/api/v1/agents/tasks?id=...` | Pa iṣẹ́ kan rẹ́ |
| GET | `/api/v1/agents/tasks/[id]` | Ka iṣẹ́ — ó máa ń sọ ipò di ọ̀tun lẹ́sẹ̀kẹsẹ̀ láti ọ̀dọ̀ aṣojú awọsánmà òkè nígbà tí a bá ṣètò `external_id` |
| POST | `/api/v1/agents/tasks/[id]` | Ìgbésẹ̀ tí a yà sọ́tọ̀: `{action: "approve"}`, `{action: "message", message}`, tàbí `{action: "cancel"}` |
| DELETE | `/api/v1/agents/tasks/[id]` | Pa iṣẹ́ pàtó kan rẹ́ nípasẹ̀ id |
> **Ìfàṣẹsí:** a nílò ìfàṣẹsí ìṣàkóso lórí gbogbo ọ̀nà (`requireCloudAgentManagementAuth`). Ṣáájú v3.8.0, wọn kò nílò ìfàṣẹsí — wo commit `588a0333` fún ìyípadà tí kò bá ẹ̀yà àtijọ́ mu.
```bash
# Ṣẹ̀dá iṣẹ́ awọsánmà Claude Code kan
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":"..."}}'
```
---
## Àwọn Aṣojú-Àárín Ìṣàkóso
Àwọn aṣojú-àárín HTTP(S)/SOCKS jáde tí a lè fi fún àwọn olùpèsè, àwọn àkọọ́lẹ̀, tàbí fún gbogbo ètò.
| Ọ̀nà | Ojú-ọ̀nà | Àpèjúwe |
| ------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/management/proxies` | Ṣàkọsílẹ̀ àwọn aṣojú-àárín (pẹ̀lú `?id=` ó máa dá ọ̀kan padà; pẹ̀lú `?id=&where_used=1` ó máa dá àwòrán àsopọ̀ ìfiyàn padà) |
| POST | `/api/v1/management/proxies` | Ṣẹ̀dá aṣojú-àárín — a fìdí body múlẹ̀ pẹ̀lú `createProxyRegistrySchema` |
| PATCH | `/api/v1/management/proxies` | Ṣe àfikún aṣojú-àárín — a fìdí body múlẹ̀ pẹ̀lú `updateProxyRegistrySchema` (ó nílò `id`) |
| DELETE | `/api/v1/management/proxies?id=...&force=1` | Pa aṣojú-àárín rẹ́ (lo `force=1` láti yọ àwọn ìfiyàn kúrò) |
| GET | `/api/v1/management/proxies/assignments` | Ṣàkọsílẹ̀ àwọn ìfiyàn — a lè ṣe àlẹ̀mọ́ nípasẹ̀ `proxy_id`, `scope`, `scope_id`; fi `resolve_connection_id=<id>` ránṣẹ́ láti mọ aṣojú-àárín tó ń ṣiṣẹ́ fún àsopọ̀ kan |
| PUT | `/api/v1/management/proxies/assignments` | Fìyàn — a fìdí body múlẹ̀ pẹ̀lú `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Ó máa ń pa cache olùpín ká |
| PUT | `/api/v1/management/proxies/bulk-assign` | Fìyàn lọ́pọ̀ — a fìdí body múlẹ̀ pẹ̀lú `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) |
| GET | `/api/v1/management/proxies/health?hours=24` | Àkójọpọ̀ ìlera aṣojú-àárín (iye àṣeyọrí/ìkùnà, ìdádúró) láàárín àkókò kan |
**Ìfàṣẹsí:** ìgbà ìṣàkóso/kọ́kọ́rọ́ API lórí gbogbo route (`requireManagementAuth`).
> `POST /api/v1/management/proxies/[id]/assignments` àti `POST /api/v1/management/proxies/[id]/health` inú àpèjúwe iṣẹ́ ni àwọn route pẹlẹbẹ `/assignments` àti `/health` tí a fi hàn lókè ń bójú tó — kò sí àwọn subroute fún id kọ̀ọ̀kan nínú codebase náà.
---
## Ìfaradà (àfikún)
OmniRoute ń pèsè àwọn ọ̀nà mẹ́ta tí kò gbára lé ara wọn fún ìkùnà onígbà díẹ̀; àwọn endpoint ìṣàkóso tó wà nísàlẹ̀ yìí ń jẹ́ kí àwọn olùṣàkóso ka wọn kí wọ́n sì ṣàtúnṣe wọn:
| Ìwọ̀n | Ibi ìpamọ́ ipò | Kíkà | Àtúnṣètò / ìparẹ́ |
| ------------------- | ------------------------------------------ | ----------------------------------------- | --------------------------------------------------------------------- |
| Olùdáwọ́dúró olùpèsè | `domain_circuit_breakers` + inú-memory | `/api/monitoring/health` | `POST /api/resilience/reset` |
| Àkókò ìdádúró àsopọ̀ | `rateLimitedUntil` lórí àwọn àsopọ̀ olùpèsè | `/api/rate-limits`, `/api/providers/[id]` | (ó máa ń tún ṣiṣẹ́ nígbà tí a bá nílò rẹ̀; parẹ́ rẹ̀ nípasẹ̀ provider PUT) |
| Ìdènà model | Ìforúkọsílẹ̀ wíwà model inú-memory | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` |
`PATCH /api/resilience` gba àwọn àtúnṣe olùdáwọ́dúró olùpèsè lábẹ́ `providerBreaker.oauth` àti `providerBreaker.apikey`. Profile kọ̀ọ̀kan ṣe àtìlẹ́yìn fún `degradationThreshold`, `failureThreshold`, àti `resetTimeoutMs`; àwọn field kan náà tún wà ní Dashboard → Settings → Resilience.
```bash
# Pa ìdènà model kan ṣoṣo rẹ́
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"}'
# Pa gbogbo ìdènà rẹ́
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-d '{"all":true}'
```
Fún ìtọ́kasí ẹ̀kúnrẹ́rẹ́ nípa ìlànà àti àwọn àìrídìmú olùdáwọ́dúró: wo [`CLAUDE.md`](../../CLAUDE.md) → "Ipò Àkókò Ṣíṣiṣẹ́ Ìfaradà".
---
## Àwọn Ọgbọ́n
Framework ọgbọ́n fún fífẹ̀ OmniRoute sí i pẹ̀lú àwọn handler àkànṣe tí a lè ṣiṣẹ́, pẹ̀lú àwọn ìsopọ̀ marketplace.
| Method | Path | Àpèjúwe |
| ------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/skills` | Ṣàkójọ àwọn ọgbọ́n tí a ti fi sílẹ̀ — a lè ṣe àlẹ̀mọ́ pẹ̀lú `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, a sì pín wọn sí ojú ewé |
| GET | `/api/skills/[id]` | Gba ọgbọ́n kan |
| PUT | `/api/skills/[id]` | Ṣàfikún ọgbọ́n (orúkọ, àpèjúwe, mode, schema, handler, àwọn tag) |
| DELETE | `/api/skills/[id]` | Yọ ọgbọ́n kan kúrò |
| POST | `/api/skills/install` | Fi ọgbọ́n kan sílẹ̀ láti inú manifest aláìṣàtúnṣe — body: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
| GET | `/api/skills/executions` | Ṣàkójọ àwọn ìṣiṣẹ́ ọgbọ́n àìpẹ́ (àkọsílẹ̀ àyẹ̀wò pẹ̀lú àwọn input/output/àkókò tí ó gba) |
| GET | `/api/skills/marketplace?q=...` | Ṣàwárí/ṣàkójọ àwọn ohun tó gbajúmọ̀ láti marketplace SkillsMP (ó nílò ètò `skillsmpApiKey`) |
| POST | `/api/skills/marketplace/install` | Fi ọgbọ́n kan sílẹ̀ nípasẹ̀ id láti SkillsMP |
| GET | `/api/skills/skillssh?q=&limit=` | Ṣàwárí registry skills.sh |
| POST | `/api/skills/skillssh/install` | Fi ọgbọ́n kan sílẹ̀ nípasẹ̀ id láti skills.sh |
**Ìfàṣẹsí:** session ìṣàkóso/API key. Àwọn route ìṣàwárí marketplace gba ìfàṣẹsí ìṣàkóso tàbí Bearer API key (`isAuthenticated`).
---
## Ìrántí
Ibi ìpamọ́ ìrántí ìjíròrò/òtítọ́ tí ó dúró pẹ́, tí a fi ààlà sí fún kọ́kọ́ API / sáẹ́ṣọ̀nù kọ̀ọ̀kan.
| Ọ̀nà | Path | Àpèjúwe |
| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/memory` | Ṣàtòjọ àwọn ìrántí — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, pẹ̀lú ìpín ojú-ewé `offset/limit` tàbí `page/limit` |
| POST | `/api/memory` | Ṣẹ̀dá ìrántí — ara tí Zod fọwọ́sí: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET | `/api/memory/[id]` | Gba ìrántí kan padà |
| DELETE | `/api/memory/[id]` | Pa ìrántí kan rẹ́ |
| GET | `/api/memory/health` | Ìlera ẹ̀ka ìrántí (àsopọ̀ DB, ẹ̀yìn embeddings, ipò atọ́ka vector) |
**Ìfàṣẹsí:** sáẹ́ṣọ̀nù ìṣàkóso/kọ́kọ́ API (`requireManagementAuth`). Àtòjọ `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (wo `MemoryType` nínú `src/lib/memory/types.ts`).
---
## Sẹ́fà MCP
OmniRoute ní sẹ́fà Model Context Protocol tí a fi sínú rẹ̀ pẹ̀lú ọ̀nà ìgbéwọlé 3 (stdio, SSE, streamable-http) àti àwọn irinṣẹ́ tí a fi ààlà sí. Àwọn endpoint dashboard tí ó wà ní ìsàlẹ̀ yìí ń ka dátà ipò/àyẹ̀wò, wọ́n sì ń ṣe aṣojú àwọn ọ̀nà ìgbéwọlé HTTP.
| Ọ̀nà | Path | Àpèjúwe |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Ìlù-ọkàn, ọ̀nà ìgbéwọlé, ipò ori ayélujára, ìpè tó kẹ́yìn, àwọn irinṣẹ́ tó ga jù, ìwọ̀n àṣeyọrí 24h |
| GET | `/api/mcp/tools` | Àtòjọ àwọn irinṣẹ́ MCP pẹ̀lú `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
| GET | `/api/mcp/sse` | Ṣí ṣiṣàn SSE fún ọ̀nà ìgbéwọlé SSE (yóò dá `503` padà bí MCP bá jẹ́ aláìṣiṣẹ́ tàbí ọ̀nà ìgbéwọlé kò bá bára mu) |
| POST | `/api/mcp/sse` | Fi férémù JSON-RPC ránṣẹ́ lórí ọ̀nà ìgbéwọlé SSE |
| GET | `/api/mcp/stream` | Ṣí ẹ̀gbẹ́ SSE ti ọ̀nà ìgbéwọlé Streamable HTTP (àwọn ìfiránṣẹ́ tí sẹ́fà bẹ̀rẹ̀) |
| POST | `/api/mcp/stream` | Fi férémù JSON-RPC ránṣẹ́ lórí ọ̀nà ìgbéwọlé Streamable HTTP |
| DELETE | `/api/mcp/stream` | Parí sáẹ́ṣọ̀nù Streamable HTTP kan |
| GET | `/api/mcp/audit` | Ṣèwádìí àkọsílẹ̀ àyẹ̀wò — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | Àkójọpọ̀ àwọn ìṣirò àyẹ̀wò (àpapọ̀, ìwọ̀n àṣeyọrí, àárín iye àkókò, àwọn irinṣẹ́ tó ga jù) |
**Ìfàṣẹsí:** àwọn ọ̀nà ìgbéwọlé `sse`/`stream` ń tẹ̀lé ojú-ọ̀nà ìfàṣẹsí pàtó fún MCP (kọ́kọ́ Bearer API pẹ̀lú ààlà `mcp`); àwọn ipa-ọ̀nà `status`/`tools`/`audit*` ṣeé kà láti dashboard (kò nílò ìfàṣẹsí àfikún ju wíwọlé sí host dashboard lọ).
> `settings.mcpEnabled` àti `settings.mcpTransport` ló ń darí àwọn ọ̀nà ìgbéwọlé HTTP méjèèjì — àìbáramu ọ̀nà ìgbéwọlé yóò dá `400` padà, ipò MCP tí kò ṣiṣẹ́ yóò sì dá `503` padà.
---
## Olùpèsè A2A
OmniRoute ń pèsè ojú-ọ̀nà A2A (Agent-to-Agent) JSON-RPC 2.0 pẹ̀lú àbọ̀ REST fún àyẹ̀wò àti lílò dásíbọ́ọ̀du.
### JSON-RPC
```bash
POST /a2a
Authorization: Bearer your-api-key # àṣàyàn ni àyàfi tí a bá ṣètò 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"}]
}
}
```
Àwọn ọ̀nà tí a ṣàtìlẹ́yìn fún (gbogbo wọn wà lábẹ́ ìṣàkóso `settings.a2aEnabled`):
| Ọ̀nà | Àpèjúwe |
| ---------------- | -------------------------------------------------------------- |
| `message/send` | Ìmúṣẹ ọgbọ́n amúṣiṣẹpọ; ó dá `{task, artifacts, metadata}` padà |
| `message/stream` | Ìmúṣẹ SSE aláṣàn fún àkójọpọ̀ ọgbọ́n kan náà |
| `tasks/get` | Gba iṣẹ́ kan nípasẹ̀ `taskId` |
| `tasks/cancel` | Fagilé iṣẹ́ kan nípasẹ̀ `taskId` |
Àwọn ọgbọ́n inú ètò: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.
### Káàdì Aṣojú
```bash
GET /.well-known/agent.json
```
Ó dá káàdì aṣojú A2A ti gbogbo ènìyàn padà (orúkọ, àpèjúwe, àwọn agbára, àkójọ ọgbọ́n, ètò ìfàṣẹsí) — a fi pamọ́ sínú kaṣe gbogbogbò fún wákàtí 1. Kò nílò ìfàṣẹsí.
### Àwọn olùrànlọ́wọ́ REST
| Ọ̀nà | Ojú-ọ̀nà | Àpèjúwe |
| ---- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/a2a/status` | A2A ṣiṣẹ́ + àwọn ìṣirò iṣẹ́ + àkótán káàdì aṣojú inú kaṣe |
| GET | `/api/a2a/tasks` | Ṣàkójọ àwọn iṣẹ́ — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST | `/api/a2a/tasks` | (A kò tíì mú un ṣiṣẹ́ gẹ́gẹ́ bí olùrànlọ́wọ́ REST — ṣẹ̀dá nípasẹ̀ JSON-RPC `message/send`) |
| GET | `/api/a2a/tasks/[id]` | Gba iṣẹ́ kan |
| POST | `/api/a2a/tasks/[id]/cancel` | Fagilé iṣẹ́ kan |
**Ìfàṣẹsí:** àwọn olùrànlọ́wọ́ REST ń ṣiṣẹ́ láìsí ìfàṣẹsí ìṣàkóso (dásíbọ́ọ̀du lè kà wọ́n); ojú-ọ̀nà JSON-RPC `/a2a` ń lo Bearer `OMNIROUTE_API_KEY` tí a bá ti ṣètò rẹ̀.
---
## Cloud, Àwọn Evals & Ìṣàyẹ̀wò
| Ọ̀nà | Ojú-ọ̀nà | Àpèjúwe |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Jẹ́rìí kọ́kọ́rọ́ Bearer kan, kí o sì dá àwọn àsopọ̀ olùpèsè tí a fi dí apá kan padà pẹ̀lú àwọn orúkọ àpèlé awoṣe fún àwọn oníbàárà ìmúdọ́gba cloud |
| POST | `/api/cloud/credentials/update` | Ṣàfikún àwọn ẹ̀rí ìdánimọ̀ tí a paroko fún olùpèsè kan tí a mú dọ́gba pẹ̀lú cloud |
| POST | `/api/cloud/model/resolve` | Yanjú id awoṣe ọgbọ́n-orí sí olùpèsè/awoṣe pàtó ní lílo tábìlì ìtọ́sọ́nà agbègbè |
| GET | `/api/cloud/models/alias` | Ṣàkójọ àwọn orúkọ àpèlé awoṣe bí a ṣe fi wọ́n hàn fún ìmúdọ́gba cloud |
| GET | `/api/assess` | Ka àwọn ìṣàsọ̀rí ìṣàyẹ̀wò tuntun jù lọ (fún olùpèsè/awoṣe kọ̀ọ̀kan) |
| POST | `/api/assess` | Ṣe ìṣàyẹ̀wò kan — ara: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Ṣàkójọ àwọn àkójọpọ̀ eval inú ètò + àwọn ìṣiṣẹ́ tuntun jù lọ |
| POST | `/api/evals` | Bẹ̀rẹ̀ ìṣiṣẹ́ eval kan |
| POST | `/api/evals/suites` | Ṣẹ̀dá àkójọpọ̀ eval àkànṣe kan — a jẹ́rìí ara rẹ̀ pẹ̀lú `evalSuiteSaveSchema` |
| GET | `/api/evals/suites/[id]` | Gba àkójọpọ̀ eval àkànṣe kan |
**Ìfàṣẹsí:** `/api/cloud/auth` ń jẹ́rìí kọ́kọ́rọ́ Bearer kan ní tààrà; àwọn ojú-ọ̀nà `/api/cloud/*`, `/api/evals/*`, àti `/api/assess` yòókù nílò sáà ìṣàkóso/kọ́kọ́rọ́ API. POST `/api/assess` ń lo `validateBody` pẹ̀lú schema scope discriminated-union kan.
---
## Ìṣàkóso ACP (Agent Client Protocol)
gẹ́gẹ́ bí àwọn ìlànà ọmọ. Àwọn endpoint wọ̀nyí ń ṣàkóso ìṣàwárí agent ACP àti
ìforúkọsílẹ̀ agent àkànṣe.
| Ọ̀nà | Path | Àpèjúwe |
| ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/acp/agents` | Ṣe àtòjọ gbogbo àwọn agent CLI tí a mọ̀ (tí a kọ sínú rẹ̀ + àkànṣe), pẹ̀lú ipò ìṣàgbékalẹ̀, version, àti binary |
| POST | `/api/acp/agents` | Forúkọsílẹ̀ agent ACP àkànṣe kan tàbí sọ cache di tuntun — body: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` tàbí `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Yọ agent ACP àkànṣe kan kúrò — query param: `?id=<agentId>` |
**Àpẹẹrẹ ìdáhùn** (`GET /api/acp/agents`):
```json
{
"agents": [
{
"id": "claude",
"name": "Claude Code CLI",
"binary": "claude",
"version": "1.0.45",
"installed": true,
"protocol": "stdio",
"providerAlias": "claude",
"isCustom": false
},
{
"id": "my-custom-cli",
"name": "My Custom CLI",
"installed": false,
"protocol": "stdio",
"providerAlias": "my-provider",
"isCustom": true
}
],
"cacheTtlMs": 60000,
"cacheAge": 1234
}
```
**Ìfàṣẹsí:** Ó nílò session ìṣàkóso (cookie `auth_token` dashboard) tàbí
kọ́kọ́rọ́ API tí ó ní scope ìṣàkóso.
Wo [Framework ACP](../frameworks/ACP.md) fún àwọn àlàyé kíkún.
---
## Ìtúpalẹ̀ & Àkíyèsí
Àwọn endpoint ìtúpalẹ̀ ní àkókò gidi fún ṣíṣe àbójútó routing, compression, àti
oríṣiríṣi provider. Àwọn wọ̀nyí ni ó ń mú àwọn ojúewé `/dashboard/analytics/*` ṣiṣẹ́.
### Ìtúpalẹ̀ auto-routing
| Ọ̀nà | Path | Àpèjúwe |
| --- | ------------------------------------ | --------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/auto-routing` | Àkójọpọ̀ àwọn ìṣirò auto-routing: àpapọ̀ àwọn ìpè, pípín strategy, pípín tier, àwọn provider tó ga jù |
| GET | `/api/analytics/auto-routing?days=7` | Àwọn ìṣirò tí a pín sí àkókò pàtó (àìyípadà jẹ́ 24h) |
**Àpẹẹrẹ ìdáhùn**:
```json
{
"window": "24h",
"totalCalls": 1234,
"strategyBreakdown": {
"rules": 800,
"cost": 200,
"latency": 150,
"sla-aware": 50,
"lkgp": 34
},
"tierBreakdown": {
"ultra": 100,
"pro": 500,
"standard": 400,
"free": 234
},
"topProviders": [
{ "provider": "openai", "calls": 500, "avgLatencyMs": 850 },
{ "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 }
]
}
```
### Ìtúpalẹ̀ compression
| Ọ̀nà | Path | Àpèjúwe |
| --- | ---------------------------- | ------------------------------------------------------------------------------------------------------ |
| GET | `/api/analytics/compression` | Àkójọpọ̀ àwọn ìṣirò compression: àwọn token tí a fipamọ́, ìdá ọgọ́rùn-ún ìfipamọ́, pípín mode, lílo engine |
**Àpẹẹrẹ ìdáhùn**:
```json
{
"window": "24h",
"totalOriginalTokens": 5000000,
"totalCompressedTokens": 3500000,
"totalSavings": 1500000,
"savingsPct": 30.0,
"modeBreakdown": {
"lite": 400,
"standard": 600,
"aggressive": 100,
"ultra": 50,
"rtk": 84
},
"engineBreakdown": {
"caveman": 800,
"rtk": 434
}
}
```
### Títọpin oríṣiríṣi provider
| Ọ̀nà | Path | Àpèjúwe |
| --- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/analytics/diversity` | Títọpin oríṣiríṣi tí ó dá lórí entropy Shannon: ó ń dènà ibi ìkùnà kan ṣoṣo nípa dídiwọ̀n bí lílo provider ṣe tàn káàkiri |
**Àpẹẹrẹ ìdáhùn**:
```json
{
"window": "24h",
"shannonEntropy": 2.45,
"maxEntropy": 3.17,
"diversityRatio": 0.77,
"providerUsage": {
"openai": 0.4,
"anthropic": 0.25,
"google": 0.2,
"kiro": 0.15
},
"warnings": ["OpenAI accounts for 40% of traffic — consider diversifying"]
}
```
**Ìfàṣẹsí:** Ó nílò session ìṣàkóso tàbí kọ́kọ́rọ́ API tí ó ní scope ìṣàkóso.
---
## Àwọn Ìṣiṣẹ́ Alábòójútó
Àwọn endpoint fún alábòójútó nìkan láti ṣàkóso àwọn ìṣiṣẹ́.
| Ọ̀nà | Path | Àpèjúwe |
| ---- | ------------------------ | ----------------------------------------------------------------------------------------------- |
| GET | `/api/admin/concurrency` | Ka àwọn ààlà concurrency lọ́wọ́lọ́wọ́ (àpapọ̀ + fún provider kọ̀ọ̀kan) |
| POST | `/api/admin/concurrency` | Ṣàfikún àwọn ààlà concurrency — body: `{global?: number, perProvider?: Record<string, number>}` |
**Ìfàṣẹsí:** Ó nílò session ìṣàkóso pẹ̀lú scope alábòójútó.
---
## Ìṣàkóso Àwọn Irinṣẹ́ CLI
Ṣàkóso àwọn irinṣẹ́ CLI tí ó ń ṣiṣẹ́ pọ̀ mọ́ OmniRoute (antigravity, commandCode,
devin-cli, àti bẹ́ẹ̀ bẹ́ẹ̀ lọ). Wo [Ìtọ́kasí Olùpèsè](./PROVIDER_REFERENCE.md) fún àkójọ kíkún.
| Ọ̀nà | Ipa-ọ̀nà | Àpèjúwe |
| ---- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/cli-tools/all-statuses` | Ipò gbogbo àwọn irinṣẹ́ CLI (fífìsílẹ̀, ẹ̀yà, ìgbà tí a rí i kẹ́yìn) |
| GET | `/api/cli-tools/status` | Àlàyé ipò fún irinṣẹ́ CLI kan (`?tool=` query) |
| POST | `/api/cli-tools/apply` | Kọ àtúnṣe tí irinṣẹ́ kan ṣẹ̀dá (`dryRun` ń ṣàfihàn àyẹ̀wò; `422` + `containerEphemeralTarget` nígbà tí ó wà nínú container; `migration` ń ṣàkọsílẹ̀ Codex YAML àtijọ́) |
| GET | `/api/cli-tools/backups` | Ṣàkójọ àwọn àfẹ̀yìntì àtúnṣe irinṣẹ́ CLI |
| POST | `/api/cli-tools/backups` | Ṣẹ̀dá àfẹ̀yìntì gbogbo àwọn àtúnṣe irinṣẹ́ CLI |
| POST | `/api/cli-tools/backups` | Mú padà: endpoint kan náà pẹ̀lú `{tool, backupId}` nínú body yóò mú àfẹ̀yìntì náà padà |
| GET | `/api/cli-tools/antigravity-mitm` | Ipò proxy Antigravity MITM (irinṣẹ́ CLI "antigravity-mitm") |
| POST | `/api/cli-tools/antigravity-mitm/alias` | Ṣètò àwọn alias antigravity-mitm |
**Ìfàṣẹsí:** Ó nílò session ìṣàkóso.
---
## Àwọn Ọgbọ́n Agent
Ṣàkóso àwọn ọgbọ́n agent AI (ó jọ àwọn GPT àdáni ti OpenAI, ṣùgbọ́n fún àwọn agent).
| Ọ̀nà | Path | Àpèjúwe |
| ------ | ---------------------------- | ---------------------------------------------------------------------------------- |
| GET | `/api/agent-skills` | Ṣàkójọ gbogbo àwọn ọgbọ́n agent (tí a kọ sínú rẹ̀ + àdáni) |
| GET | `/api/agent-skills/[id]` | Gba ọgbọ́n agent pàtó kan |
| POST | `/api/agent-skills` | Ṣẹ̀dá ọgbọ́n agent àdáni — body: `{name, description, prompt, model?, temperature?}` |
| PUT | `/api/agent-skills/[id]` | Ṣàfikún ọgbọ́n agent àdáni kan |
| DELETE | `/api/agent-skills/[id]` | Pa ọgbọ́n agent àdáni kan rẹ́ |
| GET | `/api/agent-skills/[id]/raw` | Gba prompt àìṣàtúnṣe + metadata (láìsí ìmúṣiṣẹ́) |
| POST | `/api/agent-skills/generate` | Lo AI láti ṣẹ̀dá ọgbọ́n tuntun láti inú àpèjúwe èdè àdánidá |
**Ìfàṣẹsí:** Ó nílò session ìṣàkóso tàbí API key tí ó ní scope ìṣàkóso.
---
## Ìṣàkóso Cache
Ṣàkóso semantic cache àti reasoning cache.
| Ọ̀nà | Path | Àpèjúwe |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/cache` | Àkópọ̀ cache: àpapọ̀ àwọn àkọsílẹ̀, ìwọ̀n àṣeyọrí lílò cache, àti ìwọ̀n lórí disk |
| GET | `/api/cache/entries` | Ṣàkójọ àwọn àkọsílẹ̀ inú cache (pẹ̀lú pagination) |
| DELETE | `/api/cache/entries` | Pa àwọn àkọsílẹ̀ inú cache rẹ́ (ṣe àlẹ̀mọ́ pẹ̀lú àwọn query parameters) |
| GET | `/api/cache/stats` | Ìṣirò cache tó kún fún ẹ̀kúnrẹ́rẹ́ (fún provider kọ̀ọ̀kan àti model kọ̀ọ̀kan) |
| GET | `/api/cache/reasoning` | Ipò reasoning cache (fún ṣíṣe reasoning replay) |
| DELETE | `/api/cache/reasoning` | Pa reasoning cache rẹ́ — query params: `?toolCallId=<id>` (ọ̀kan ṣoṣo) tàbí `?provider=<p>` tàbí láìsí params (gbogbo rẹ̀) |
**Ìfàṣẹsí:** Ó nílò management session.
---
## Ètò Memory
Ṣàkóso memory tó wà pẹ́ títí (FTS5 + vector embeddings).
| Ọ̀nà | Path | Àpèjúwe |
| ------ | ------------------ | ------------------------------------------------------------------------ |
| GET | `/api/memory` | Ṣàkójọ àwọn àkọsílẹ̀ memory (ṣe àlẹ̀mọ́ nípa scope, type, àti search query) |
| POST | `/api/memory` | Ṣẹ̀dá àkọsílẹ̀ memory tuntun — body: `{scope, type, content, metadata?}` |
| GET | `/api/memory/[id]` | Gba àkọsílẹ̀ memory kan pàtó |
| PUT | `/api/memory/[id]` | Ṣe àfikún sí àkọsílẹ̀ memory kan |
| DELETE | `/api/memory/[id]` | Pa àkọsílẹ̀ memory kan rẹ́ |
| GET | `/api/memory?q=` | Ṣàwárí memory (FTS5 + vector) — àwọn ìṣirò wà nínú ìdáhùn kan náà |
**Ìfàṣẹsí:** Ó nílò management session tàbí API key tó ní management scope.
---
## Webhooks
Ṣàkóso àwọn subscription webhook fún àwọn event.
| Ọ̀nà | Path | Àpèjúwe |
| ------ | ------------------------------- | --------------------------------------------------------------------- |
| GET | `/api/webhooks` | Ṣàkójọ gbogbo àwọn subscription webhook |
| POST | `/api/webhooks` | Ṣẹ̀dá subscription webhook — body: `{url, events[], secret?, active?}` |
| GET | `/api/webhooks/[id]` | Gba subscription webhook kan pàtó |
| PUT | `/api/webhooks/[id]` | Ṣe àfikún sí subscription webhook kan |
| DELETE | `/api/webhooks/[id]` | Pa subscription webhook kan rẹ́ |
| GET | `/api/webhooks/[id]/deliveries` | Ṣàkójọ ìtàn delivery fún webhook kan (àkọsílẹ̀ àṣeyọrí/ìkùnà) |
| POST | `/api/webhooks/[id]/test` | Fi event ìdánwò ránṣẹ́ sí webhook kan |
**Ìfàṣẹsí:** Ó nílò management session.
Wo [Ètò Webhooks](../frameworks/WEBHOOKS.md) fún gbogbo àwọn irú event.
---
## Ètò Ìlànà Skills
Ṣàkóso Skills (ètò ìlànà àwọn ìfikún agentic).
| Ọ̀nà | Path | Àlàyé |
| ------ | ------------------------ | ------------------------------------------------------------------------------------- |
| GET | `/api/skills` | Ṣàkọsílẹ̀ gbogbo skills tí a ti fi sí ẹrọ (built-in + custom) |
| POST | `/api/skills/install` | Fi skill kan sí ẹrọ láti local path tàbí URL |
| DELETE | `/api/skills/[id]` | Yọ skill kan kúrò lórí ẹrọ |
| PUT | `/api/skills/[id]` | Mú skill ṣiṣẹ́ tàbí pa á — body: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST | `/api/skills/executions` | Ṣiṣẹ́ skill kan — body: `{skillName, apiKeyId, input?, sessionId?}` |
| GET | `/api/skills/executions` | Ṣàkọsílẹ̀ ìtàn ìṣiṣẹ́ fún gbogbo skills (ṣe àlẹ̀mọ́ pẹ̀lú `?apiKeyId=`) |
**Ìfàṣẹsí:** Ó nílò management session tàbí API key tí ó ní management scope.
Wo [Ètò Ìlànà Skills](../frameworks/SKILLS.md) fún gbogbo àlàyé.
---
## Plugins
Ṣàkóso àwọn plugin OmniRoute (àwọn ìfikún láti ọwọ́ ẹnikẹta).
| Ọ̀nà | Path | Àlàyé |
| ------ | ---------------------------------- | -------------------------------------- |
| GET | `/api/plugins` | Ṣàkọsílẹ̀ àwọn plugin tí a ti fi sí ẹrọ |
| POST | `/api/plugins/marketplace/install` | Fi plugin kan sí ẹrọ láti marketplace |
| DELETE | `/api/plugins/[name]` | Yọ plugin kan kúrò lórí ẹrọ |
| POST | `/api/plugins/[name]/activate` | Mú plugin kan ṣiṣẹ́ |
| POST | `/api/plugins/[name]/deactivate` | Pa plugin kan |
| GET | `/api/plugins/[name]/config` | Gba àtòpọ̀ plugin |
| PUT | `/api/plugins/[name]/config` | Ṣe àfikún àtòpọ̀ plugin |
**Ìfàṣẹsí:** Ó nílò management session.
Wo [Ètò Ìlànà Plugins](../frameworks/PLUGIN_SDK.md) fún gbogbo àlàyé.
---
## Shadow Routing
Àfiwé shadow / A-B ti àwọn olùpèsè **kì í ṣe ojú-ọ̀nà REST aládàáṣe** — a máa ń ṣètò rẹ̀ nípasẹ̀ combo routing (wo [Auto-Combo](../routing/AUTO-COMBO.md)). Àwọn òṣùwọ̀n àfiwé fún combo kọ̀ọ̀kan wà nípasẹ̀ `GET /api/combos/metrics`.
---
## Guardrails
Ṣàyẹ̀wò àwọn guardrail ní àsìkò ìṣiṣẹ́ (ìṣàwárí PII, ìṣàwárí prompt injection, vision bridging). Àwọn guardrail máa ń ṣiṣẹ́ lórí gbogbo ìbéèrè; yíyọ ara ẹni kúrò fún ìpè kọ̀ọ̀kan jẹ́ nípasẹ̀ request header `x-omniroute-disabled-guardrails` — kò sí ojú-ọ̀nà enable/disable tí a fi pamọ́.
| Ọ̀nà | Path | Àlàyé |
| ---- | ---------------------- | --------------------------------------------------------------------------------------------- |
| GET | `/api/guardrails` | Ṣàkọsílẹ̀ àwọn guardrail tí a ti forúkọsílẹ̀ àti ipò wọn (orúkọ / ṣíṣe / ìjẹ́pàtàkì) |
| POST | `/api/guardrails/test` | Ṣe àdánwò láìṣiṣẹ́ pipeline ṣáájú ìpè lórí àpẹẹrẹ input — body: `{input, disabledGuardrails?}` |
**Ìfàṣẹsí:** Ó nílò management session.
Wo [Ààbò > Guardrails](../security/GUARDRAILS.md) fún gbogbo àlàyé.
---
---
## Ìfàṣẹsí
Wo [Ìfàṣẹsí Ìṣàkóso](../guides/MANAGEMENT-AUTH.md) fún àwọn ẹbí ìwé-ẹ̀rí mẹ́rin (ìgbà dashboard, àmì local CLI, `oma_live_…` Access Token, kọ́kọ́ API tó ní ààlà ìṣàkóso) àti bí wọ́n ṣe yàtọ̀ sí àwọn kọ́kọ́ inference.
- Àwọn ipa-ọ̀nà dashboard (`/dashboard/*`) ń lo cookie `auth_token`
- Ìwọlé ń lo hash ọ̀rọ̀ aṣínà tí a ti fipamọ́; tí ìyẹn kò bá ṣiṣẹ́, yóò lo `INITIAL_PASSWORD`
- A lè tan tàbí pa `requireLogin` nípasẹ̀ `/api/settings/require-login`
- Àwọn ipa-ọ̀nà `/v1/*` lè béèrè kọ́kọ́ API Bearer nígbà tí `REQUIRE_API_KEY=true`
- “àmì ìṣàkóso” / “kọ́kọ́ API tó ní ààlà ìṣàkóso” nínú ìtọ́kasí yìí túmọ̀ sí ọ̀kan lára àwọn ẹbí tó wà nínú ìtọ́sọ́nà yẹn — kì í ṣe irú àṣírí àfikún tí a kò ṣàlàyé
> **Àyípadà tó ń ba ìbámu tẹ́lẹ̀ jẹ́ (v3.8.0)** — `/api/v1/agents/tasks/*` àti àwọn endpoint ìṣàkóso cooldown ti nílò **ìfàṣẹsí ìṣàkóso** báyìí (cookie `auth_token` dashboard tàbí kọ́kọ́ API tó ní ààlà ìṣàkóso). Àwọn client tí wọ́n ń pe àwọn ipa-ọ̀nà wọ̀nyí láìsí ìfàṣẹsí tẹ́lẹ̀ yóò gba `401 Unauthorized`. Wo commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).
Reference in New Issue View Git Blame Copy Permalink