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

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

1777 lines
123 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 (Igbo)
🌐 **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) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)
---
---
title: "Ntụaka API"
version: 3.8.51
lastUpdated: 2026-08-31
---
# Ntụaka API
🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [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) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)
Ntụaka bụ isi maka API OmniRoute. Ọ na-ekpuchi ihu ọha `/v1` na endpoint njikwa ndị a kacha eji eme ihe; [`docs/openapi.yaml`](../openapi.yaml) nke igwe nwere ike ịgụ na osisi route dị n'okpuru `src/app/api/` bụ isi mmalite zuru ezu.
---
## Ndepụta Ihe Dị N'ime
- [Mmecha Mkparịtaụka](#chat-completions)
- [Mgbazinye Oge Nnọkọ A Na-achịkwa Nanị Ya](#exclusive-managed-session-leases)
- [Embeddings](#embeddings)
- [Imepụta Onyonyo](#image-generation)
- [OCR Akwụkwọ](#document-ocr)
- [Ndepụta Ụdị](#list-models)
- [Manifest Ngwa Mgbakwunye Onye Na-eweta Ọrụ](#provider-plugin-manifest)
- [Ebe Njikọ Ndakọrịta](#compatibility-endpoints)
- [API Faịlụ](#files-api)
- [API Batches](#batches-api)
- [API Ọchụchọ](#search-api)
- [Mgbasa WebSocket](#websocket-streaming)
- [Kwọta & Ịkọ Nsogbu](#quotas--issues-reporting)
- [Cache Semantic](#semantic-cache)
- [Dashboard & Nchịkwa](#dashboard--management)
- [Nchịkwa Combo](#combo-management)
- [Webhooks](#webhooks)
- [Igodo E Debanyere Aha (Nchịkwa Akpaaka)](#registered-keys-auto-management)
- [Protocol Ndị Agent](#agents-protocol)
- [Proxies Nchịkwa](#management-proxies)
- [Ike Iguzogide Nsogbu (gbasawanyere)](#resilience-extended)
- [Nkà](#skills)
- [Ebe Ncheta](#memory)
- [Sava MCP](#mcp-server)
- [Sava A2A](#a2a-server)
- [Cloud, Evals & Assess](#cloud-evals--assess)
- [Nhazi Arịrịọ](#request-processing)
- [Nyocha Njirimara](#authentication)
---
## Mmecha Mkparịtaụka
```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
}
```
### Headers Ahaziri Ahazi
| Header | Ntụziaka | Nkọwa |
| ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `X-OmniRoute-No-Cache` | Arịrịọ | Tọọ ya ka ọ bụrụ `true` iji gafere cache |
| `x-omniroute-no-memory` | Arịrịọ | Tọọ ya ka ọ bụrụ `true` iji kwụsị itinye ebe ncheta + nkà maka arịrịọ a (ọ na-eme ka no-cache; ọ na-ezere mgbakwunye token/ọnụahịa nke oku ọ bụla) |
| `X-OmniRoute-Progress` | Arịrịọ | Tọọ ya ka ọ bụrụ `true` maka mmemme ọganihu |
| `X-Session-Id` | Arịrịọ | Igodo nnọkọ na-adịgide maka njikọ nnọkọ mpụga |
| `x_session_id` | Arịrịọ | A na-anabatakwa ụdị nwere akara underscore (HTTP ozugbo) |
| `X-OmniRoute-Session-Id` | Arịrịọ | Akara nnọkọ/mkparịtaụka onye na-akpọ nyere (ọ na-enyekwa ebe ncheta ozi). Mgbe ọ dị, a na-echekwa ya kpọmkwem na `call_logs.session_tag` maka ịkọ ọnụahịa n'otu nnọkọ (#8249) — anaghị emepụta ya mgbe ọ na-adịghị |
| `Idempotency-Key` | Arịrịọ | Igodo iwepụ oyiri (oghere oge 5s) |
| `X-Request-Id` | Arịrịọ | Igodo iwepụ oyiri ọzọ |
| `X-OmniRoute-Cache` | Nzaghachi | `HIT` ma ọ bụ `MISS` (na-enweghị mgbasa) |
| `X-OmniRoute-Idempotent` | Nzaghachi | `true` ma ọ bụrụ na ewepụla oyiri |
| `X-OmniRoute-Progress` | Nzaghachi | `enabled` ma ọ bụrụ na agbanyere nsuso ọganihu |
| `X-OmniRoute-Session-Id` | Nzaghachi | ID nnọkọ dị irè nke OmniRoute ji mee ihe |
| `X-OmniRoute-Request-Id` | Nzaghachi | ID njikọ arịrịọ (mgbe a maara ya) |
| `X-OmniRoute-Version` | Nzaghachi | Ụdị build OmniRoute (ọ na-adị mgbe niile) |
| `X-OmniRoute-Cost-Saved` | Nzaghachi | USD nke cache zere na HIT (naanị cache hits) |
| `X-OmniRoute-Decision` | Nzaghachi | Ndekọ ụzọ: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` bụ atụmatụ combo, ma ọ bụ `single` maka arịrịọ na-abụghị combo) — ọ na-adị mgbe niile na nzaghachi mmecha |
> Ndetu Nginx: ọ bụrụ na ị dabere na headers nwere akara underscore (dịka ọmụmaatụ `x_session_id`), gbanye `underscores_in_headers on;`.
> **Nkụnye-isi telemetrị ọnụahịa:** nzaghachi ihe ịga nke ọma na-abụghị streaming na-ebukwa nchịkọta telemetrị ọnụahịa `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, ọnụọgụ ntụpọ 10 kwụ ọtọ; `0.0000000000` maka nke efu/nke a na-enyeghị ọnụahịa), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit`, na `X-OmniRoute-Fallback-Attempts` (naanị mgbe > 0), tinyere `X-OmniRoute-Request-Id` na `X-OmniRoute-Version`. Chat completions, `/v1/responses`, `/v1/messages`, **yana endpoints mgbasa ozi** na-ewepụta ha — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations`, na `/v1/moderations` (ọnụahịa ya bụ `0` mgbe niile). A na-agbakọ ọnụahịa mgbasa ozi dabere n'ụdị modality ọ bụla (kwa onyonyo, kwa sekọnd, kwa mkpụrụedemede, kwa nkeji ọchụchọ) mgbe ọnụahịa dị; ma ọ bụghị ya, ọ bụ `0` (fail-open).
> **Nkọwa ọnụahịa cache-hit:** mgbe semantic-cache bụ HIT (`X-OmniRoute-Cache-Hit: true`), a naghị akpọ upstream, ya mere `X-OmniRoute-Response-Cost` bụ `0.0000000000` (ọnụahịa **mgbakwunye** nke izipu hit ahụ). A na-akọ ọnụahịa mbụ/ọnụahịa ọ gaara abụ iche na `X-OmniRoute-Cost-Saved`. Ndị na-eji data ịgba ụgwọ kwesịrị ịchịkọta `X-OmniRoute-Response-Cost` (hits anaghị efu ego); nyocha cache nwere ike ịchịkọta `X-OmniRoute-Cost-Saved`.
## Mgbazinye Oge Nnọkọ A Na-achịkwa Nanị Ya
Mgbazinye oge nnọkọ a na-achịkwa nanị ya bụ nkwekọrịta nhazi ụzọ nke onye ahịa ọ bụla nwere ike iji ma ọ bụrụ na ọ họrọ: otu onye nwe na-arụ ọrụ
na-ejide otu njikọ OmniRoute tozuru etozu. Ọ naghị agbazinye model, achọ OAuth, mata otu
onye ahịa kpọmkwem, ma ọ bụ chọọ otu provider kpọmkwem.
API key a na-eji eme nkwenye njirimara ga-enwerịrị scope `lease:exclusive` na ndepụta
`allowedConnections` doro anya nke na-abụghị efu. Ókè mgbanwe database na-amanye ka e nwee field abụọ ahụ ọnụ mgbe a na-emepụta key
na mgbe a na-eme mmelite akụkụ ụfọdụ.
```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"}
```
Nzaghachi acquire, renew, na release gara nke ọma na-egosipụta timestamp, `state`, na
`generation` ziri ezi nke dị mma, mana ha anaghị egosi njikọ ahọpụtara ma ọ bụ credentials. Renew na release na-enye
generation n'ime JSON body:
```json
{ "action": "renew", "generation": 1 }
```
```json
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
```
Onye nwe lease na-arụ ọrụ nwere ike ịrịọ metadata ngosipụta na-echekwa nzuzo n'ụzọ doro anya maka binding ya dị ugbu a:
```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"
}
}
```
A na-echebe action status a a na-ahọrọ iji site n'aka owner na-enweghị nkọwa, managed API key e mere nkwenye njirimara ya, na
generation na-arụ ọrụ ziri ezi n'ime otu transaction database. `displayName` bụ naanị aha
njikọ ahaziri nke ewepụrụ oghere ndị dị na nsọtụ ya; ọ bụ `null` mgbe enweghị aha ahaziri dị nchebe.
OmniRoute anaghị eji email ma ọ bụ njirimara account emepụtara dochie ya. Uru provider bụ label ngosipụta na-enweghị
ozi nzuzo, ọ bụghịkwa identifier compatible-provider emepụtara. A naghị etinye credentials, tokens, cookies, raw connection ma ọ bụ
API key ids, owner hashes, fencing secrets, na data nhazi ụzọ dị n'ime.
Nchọpụta jiri key na-ezighi ezi, owner na-ezighi ezi, generation ochie, ihe na-efu, nke kubigara oge, nke a tọhapụrụ, na nke a kagburu
na-eweghachi otu error `409 LEASE_FENCE_STALE` ahụ na-enweghị metadata njikọ. Onye ahịa natara nzaghachi ichere capacity enweghị binding na-arụ ọrụ ọ ga-enyocha. Mgbe routing na-ebufe lease na-arụ ọrụ,
otu generation ahụ ka na-adị ire, status na-eweghachikwa binding ọhụrụ ahụ n'otu atomic operation, ọ bụghị nke ochie.
Ndị ahịa dị ugbu a anaghị agbanwe n'ihi na nzaghachi acquire, renew, release, na waiting na-ejigide
usoro ha gara aga.
Nkwekọrịta server a anaghị agbanwe stock OpenAI Codex `/status`. Ugbu a, stock Codex na-akọ
model provider ya na ọnọdụ authentication/account arụnyere n'ime ya, mana ọ naghị egosipụta metadata
account provider omenala ọ bụla; njikọta client ga-eme n'ọdịnihu ga-akpọ action a ma kpebie otu esi
egosipụta `connection.displayName`.
Arịrịọ managed inference ọ bụla ga-enyezi control header abụọ ahụ:
```http
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
```
A na-echebe owner ziri ezi, generation, njikọ na-arụ ọrụ, na API key e mere nkwenye njirimara ya ozugbo
tupu mbọ upstream ọ bụla akwadoro. Iji key ọzọ kpọgharịa owner na generation ga-ada ọbụna
mgbe key ahụ nyere ikike iji otu njikọ ahụ. A naghị echekwa raw owners, edekọ ha na log, debe ha n'ime
request snapshot, ma ọ bụ zipụ ha upstream.
Asọmpi nwa oge na-eweghachi HTTP `429` ya na `Retry-After` na:
```json
{
"state": "WAITING_FOR_CAPACITY",
"error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
"reason": "NO_FREE_ELIGIBLE_CONNECTION",
"retryAfter": 30
}
```
Nzaghachi a pụtara naanị na ordinary eligible set abụghị efu nakwa na lease na-arụ ọrụ nke onye ọzọ
jidere candidate niile nwere onwe ha. Model/provider anaghị akwado, policy mismatch, cooldown, quota,
health, na ọdịda eligibility ndị ọzọ a na-ahụkarị na-ejigide nzaghachi OmniRoute ha dị ugbu a.
### `x-omniroute-compression`
Override nke compression plan maka arịrịọ ọ bụla. Ọ nwere precedence kachasị elu — ọ na-emeri override routing-combo,
active profile, auto-trigger, na Default nke panel. Uru:
| Uru | Mmetụta |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `off` | Enweghị compression maka arịrịọ a. |
| `default` | Default profile sitere na panel (ọ na-eleghara active profile anya). |
| `engine:<id>` | Otu engine mgbe enyere ya ikike, dịka `engine:rtk`. |
| `<combo>` | Combo nwere aha, nke a ga-ebu ụzọ dakọtara site n'aha (na-eleghara nnukwu ma ọ bụ obere mkpụrụedemede anya), emesịa site na id. |
Ndetu:
- A na-eleghara uru amaghi anya (a naghị ajụ arịrịọ ahụ); resolution na-aga n'ihu ruo na usoro precedence nkịtị.
- Ọ bụrụ na ọtụtụ combo nwere otu aha, nyefee **id** nke combo ka matching wee bụrụ nke a pụrụ ikpebi otu ụzọ.
- Enweghị ike ịhọrọ combo aha ya bụ `off` ma ọ bụ `default` site n'aha (a na-akọwa keyword ndị ahụ mbụ); jiri id ya rụtụ aka na combo dị otu ahụ.
- Master compression switch bụ hard gate: mgbe agbanyụrụ compression n'ụwa niile, header a enweghị ike ịgbanye ya.
A na-ezipụ plan etinyere azụ n'ime response header:
```
X-OmniRoute-Compression: <mode>; source=<source>
```
ebe `<source>` bụ otu n'ime `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, ma ọ bụ `off`.
---
## Embeddings
```bash
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "nebius/Qwen/Qwen3-Embedding-8B",
"input": "The food was delicious"
}
```
Ndị na-eweta ọrụ dị: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.
NJ katalọgụ bụ `provider/model` (ọmụmaatụ: `jina-ai/jina-embeddings-v5-omni-small`). NJ ụdị Jina na-enweghị aha onye na-eweta ọrụ nke pụtara na ndekọ ahụ (dịka ọmụmaatụ `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) na-arụkwa ọrụ. Ọrụ embed/rerank/classify/segment nke Jina na-ebu ụzọ jiri nzere `jina-ai` dị na dashboard; a na-eji `JINA_AI_API_KEY` naanị dịka nhọrọ ndabere mgbe enweghị igodo dashboard. Kaadị `jina-reader` bụ naanị maka Reader / `r.jina.ai` (`POST /v1/web/fetch`), ọ naghị enye embeddings ma ọ bụ rerank ma ọlị.
Ụdị ndị dị na ndekọ nke na-egosi na ha na-akwado multimodal na-anabatakwa ihe ahaziri n'ụdị data na-anọpụ iche n'ebe onye na-eweta ọrụ nọ, ruo ihe 32.
Ụdị ihe mgbasa ozi bụ `text`, `image`, `audio`, `video`, na `document`. `source` nke mgbasa ozi ha
bụ ma ọ bụ `{"type":"url","url":"https://..."}` ma ọ bụ
`{"type":"base64","data":"...","media_type":"..."}`.
Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`,
na aha nnọchi anya ezinụlọ `jina-ai/jina-embeddings-v5-omni` → omni-small) na-anabatakwa docs EmbeddingsV5Request nke Jina
ma **na-ebufe ha dịka ha dị** gaa na `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,..." }]
}
]
}
```
Ụkpụrụ `{ image | audio | video | pdf }` nke Jina nwere ike ịbụ URL HTTPS ọha, URI `data:`, ma ọ bụ raw
base64. OmniRoute anaghị atụgharị objects ndị ahụ ka ha bụrụ string ma ọ bụ budata URL onyonyo native — Jina n'onwe ya na-ewepụta
mgbasa ozi ọha. A na-ebufe fields Jina ndị ọzọ (`task`, `normalized`, `truncate`, `embedding_type`).
SKU Jina ndị bụ naanị ederede ka na-ajụ docs na-abụghị ederede.
Oke nchekwa na mbufe:
- URL mgbasa ozi dị n'ebe dị anya ga-abụrịrị HTTPS ọha. A na-ebudata ihe Canonical `{type,source:url}`
n'akụkụ server (nyochaghachi redirect, timeout, oke nha, DNS ọha, na connection pinning), tinye ha
n'ime arịrịọ tupu oku onye na-eweta ọrụ. A na-ebufe ihe Jina-native `{image:"https://..."}` dịka ha dị
mgbe e mechara otu nyocha HTTPS ọha ahụ; Jina na-ebudata URL ahụ.
- Mgbasa ozi base64 etinyere n'ime arịrịọ nwere oke 8 MiB mgbe e decoded ihe ọ bụla, yana 16 MiB mgbe e decoded ihe niile dị n'arịrịọ ahụ.
Ntughari maka onye na-eweta ọrụ (anaghị ebufe ihe canonical dịka ha dị):
- Ụdị Jina multimodal: ihe ọ bụla dị n'ọkwa kachasị elu na-aghọ otu object nwere igodo modality
(`text` / `image` / `audio` / `video` / `pdf`), na-eji data URI maka mgbasa ozi inline; otu vector maka
ihe ọ bụla dị n'ọkwa kachasị elu.
- Ezinụlọ Gemini Embedding 2: otu array dị n'ọkwa kachasị elu na-aghọ otu arịrịọ native
`models/{model}:embedContent` nwere `content.parts` (`text` ma ọ bụ `inline_data`).
- Ụdị amaghi ama/dynamic na-enweghị metadata modality doro anya na-ajụ structured input site na 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"
}
```
Ngwakọta model/modality ndị anaghị akwado na-eweghachi HTTP 400 kama ịmanye mgbanwe n'ihe ahụ. Fields mgbakwunye ndị na-abụghị input
na arịrịọ string/token ochie ka na-agafe dịka ha dị.
```bash
# Depụta ụdị embedding niile
GET /v1/embeddings
```
---
## Mmepụta Onyonyo
```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"
}
```
Ndị na-eweta ọrụ dị: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (nke mpaghara), ComfyUI (nke mpaghara).
```bash
# Depụta ụdị onyonyo niile
GET /v1/images/generations
```
---
## OCR Akwụkwọ
```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` na-ahọrọ onye na-eweta OCR site na mbido `provider/model`; id ụdị nke kwụụrụ onwe ya (dịka
`mistral-ocr-latest`) na-ejikọta na onye na-eweta ya e debanyere aha, ma ọ bụrụ na ahapụrụ `model`, ndabara ya bụ
Mistral (`mistral-ocr-latest`). Ndị na-eweta e debanyere aha (`open-sse/config/ocrRegistry.ts`):
| Id onye na-eweta | Id ụdị | Uru `model` | Nkọwa |
| ----------------------------- | -------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (ma ọ bụ naanị `mistral-ocr-latest`) | Mekọrịta ozugbo — a na-eweghachi nzaghachi ozugbo site n'otu oku upstream ahụ. |
| `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Upstream anaghị arụkọ ọrụ ozugbo (`analyze` + nyocha ugboro ugboro) — lee n'okpuru. |
| `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Mekọrịta ozugbo, site na endpoint onye mmekọ `openapi/chat/completions` nke Vertex AI — lee n'okpuru maka nyocha ikike/URL. |
Ndị na-eweta ọrụ atọ ahụ niile na-azaghachi n'ime body nwere nhazi Mistral yiri ibe ha:
```json
{
"pages": [{ "index": 0, "markdown": "# Extracted text..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
```
### Usoro nyocha ugboro ugboro nke Azure Document Intelligence
API `analyze` nke Azure Document Intelligence anaghị arụkọ ọrụ ozugbo: arịrịọ mbụ na-eweghachi
header `Operation-Location` kama body, a ga-enyochakwa nsonaazụ ya ugboro ugboro. Handler ahụ
(`open-sse/handlers/ocr.ts`) na-enyocha URL ahụ kwa sekọnd ruo mbọ 30, kwụsị ozugbo (ọ
gaghị anọgide na-enyocha) ma ọ bụrụ na nzaghachi nyocha abụghị `ok` ma ọ bụ ọkwa bụ `"failed"`, ma na-eweghachi `504` ma ọ bụrụ na
ọrụ ahụ ka na-aga n'ihu mgbe ọnụọgụ mbọ e nyere gwụsịrị. A na-ahazi nzaghachi ikpeazụ nke Azure
ka ọ bụrụ otu nhazi `pages`/`markdown` nke Mistral na-eji tupu e weghachiri ya nye
onye kpọrọ ya, ya mere koodu client agaghị achọ ijikwa onye na-eweta ọrụ ahụ n'ụzọ pụrụ iche.
### Nnyocha ikike na mkpebi endpoint nke Vertex AI DeepSeek OCR
`vertex-deepseek-ocr` na-eji otu nyocha ikike Vertex AI ahụ OmniRoute kwadoro ugbua maka
okporo ụzọ chat/onyonyo (`open-sse/executors/vertex.ts`): API key nke njikọ ahụ bụ ma
credential JSON nke Service Account (nke a gbanwere ka ọ bụrụ token nnweta OAuth dị mkpụmkpụ site na usoro JWT-bearer)
ma ọ bụ token nnweta OAuth emepụtarala nke a na-eji dịka ọ dị. URL endpoint upstream bụ endpoint
onye mmekọ `openapi/chat/completions` izugbe nke Vertex, nke e ji project na
region nke njikọ ahụ wuo — `providerSpecificData.project`/`providerSpecificData.region` e kọwara kpọmkwem na-ebute ụzọ mgbe niile;
ma ọ bụghị ya, a na-enweta project site na `project_id` dị na JSON nke Service Account, ebe region
na-eji `us-central1` dịka ndabara. Mkpebi abụọ ahụ na-eme na `open-sse/handlers/ocr.ts`
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`), nke
`src/app/api/v1/ocr/route.ts` na-eji tupu iziga ya na `handleOcr`.
---
## Depụta Ụdịdị
```bash
GET /v1/models
Authorization: Bearer your-api-key
→ Ọ na-eweghachi ụdịdị nkata, embedding, na onyonyo niile + ngwakọta ha n'ụdị OpenAI
```
### Nganiihu id ụdịdị (`?prefix=`)
A na-egosipụta ọtụtụ ụdịdị n'okpuru **nganiihu onye na-eweta ọrụ**. Ọkọlọtọ atụmatụ `MODELS_CATALOG_PREFIX_MODE` na-achịkwa nganiihu ị ga-enweta, ma enwere ike iji query parameter dochie ya **maka arịrịọ ọ bụla** — nke a bara uru maka client chọrọ ndepụta dị ọcha n'agbanweghị ntọala sava niile maka ndị ọzọ:
```bash
GET /v1/models?prefix=alias # otu id maka ụdịdị ọ bụla — nganiihu alias dị mkpụmkpụ
GET /v1/models?prefix=dual # ụdị abụọ ahụ (ndabara sava)
GET /v1/models?prefix=canonical # naanị nganiihu provider-id zuru ezu
```
| Ọnọdụ | Ihe ọ na-ewepụta | Nkọwa |
| ----------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual` | `cc/claude-sonnet-4-6` **na** `claude/claude-sonnet-4-6` | **Ndabara.** id abụọ ahụ na-eduga n'otu ụdịdị ahụ; e debere ha ka nhazi client ndị tinyere otu n'ime ụdị abụọ ahụ kpọmkwem nọgide na-arụ ọrụ. Ọ fọrọ nke nta ka ọ mụbaa katalọgụ ahụ okpukpu abụọ. |
| `alias` | `cc/claude-sonnet-4-6` | Otu ntinye maka ụdịdị ọ bụla. Ndị na-eweta ọrụ na-enweghị alias pụrụ iche ka na-ewepụta ntinye ha, ya mere ọ dịghị ihe na-efu. |
| `canonical` | `claude/claude-sonnet-4-6` | Otu ntinye maka ụdịdị ọ bụla n'okpuru nganiihu provider-id zuru ezu. Ndị na-eweta ọrụ na-enweghị alias pụrụ iche (dịka `antigravity/…`, `agy/…`) na-ewepụtakwa naanị id ha ebe a, ya mere ọ dịghị ihe na-efu. |
A pụkwara ịmata mirror nọ n'ọnọdụ `dual` na-enweghị query parameter: ọ nwere field `parent` nke na-atụ aka na id bụ isi.
Client ndị na-egosipụta ihe nhọpụta ụdịdị kwesịrị ịrịọ `?prefix=alias` — nke a bụ ihe
[OmniCopilot VS Code extension](../guides/VSCODE-COPILOT.md) na-eme.
### Ụdịdị dị iche iche na-enweghị echiche
Maka ụdịdị Claude nwere ikike iche echiche, `/v1/models` na-egosipụtakwa ụdị **na-enweghị echiche** nke id ya nwere nganiihu `claude-3-omniroute-no-thinking/`:
```
claude-3-omniroute-no-thinking/<provider>/<model>
```
Ịhọrọ id a (dịka ọmụmaatụ, na nhazi Claude Code nke na-etinye block `thinking` mgbe niile) na-eme ka ọ laghachi na ezigbo `<provider>/<model>` ma gbanyụọ ịtụgharị uche — `thinking:{type:"disabled"}` n'ụzọ `/v1/messages`, ma ọ bụ iwepụ field `reasoning`/`reasoning_effort` n'ụzọ `/v1/chat/completions`. A na-edepụta ụdị a naanị maka ụdịdị ezinụlọ Claude ndị na-akwado iche echiche **ma** na-asọpụrụ `disabled` (ya mere, dịka ọmụmaatụ, a naghị etinye ụdịdị adaptive-only ndị na-ajụ `disabled`). Ndị na-ahụ maka sistemụ nwere ike ịmanye ụdị a ka ọ dị ma ọ bụ ghara ịdị maka ụdịdị ọ bụla site na `ModelSpec.noThinkingAlias`.
---
## Manifest Ngwa Mgbakwunye Onye Na-enye Ọrụ
```bash
GET /api/v1/provider-plugin-manifest
```
Ọ na-eweghachi manifest JSON dị nchebe nke ngwa mgbakwunye onye na-enye ọrụ nke Bifrost, CLIProxyAPI, na ndị rawụta sidecar n'ọdịnihu na-eji. A na-emepụta nzaghachi ahụ site na ndekọ ndị na-enye ọrụ TypeScript, ma kpachapụ anya wepụ ihe nzuzo ndị ahịa OAuth, mkpebi gburugburu ebe a na-arụ ọrụ, ọrụ ndị mmezu, nkụnye isi arịrịọ, na data akaụntụ.
Jiri endpoint a mgbe sidecar na-arụ ọrụ n'èzí usoro ma ọ nweghị ike ibubata
`open-sse/config/providerPluginManifestRegistry.ts` ozugbo.
---
## Endpoint Ndakọrịta
| Usoro | Ụzọ | Ọdịdị |
| ----- | ----------------------------------------- | -------------------------------------- |
| POST | `/v1/chat/completions` | OpenAI |
| POST | `/v1/messages` | Anthropic |
| POST | `/v1/responses` | OpenAI Responses |
| POST | `/v1/embeddings` | OpenAI |
| POST | `/v1/images/generations` | OpenAI Images |
| POST | `/v1/images/edits` | OpenAI Images (nrụzi/inpaint) |
| POST | `/v1/videos/generations` | Mmepụta vidiyo n'ụdị OpenAI |
| POST | `/v1/music/generations` | Mmepụta egwu n'ụdị OpenAI |
| POST | `/v1/audio/transcriptions` | OpenAI Audio (STT) |
| POST | `/v1/audio/speech` | OpenAI TTS (na-eweghachi ahụ ọdịyo) |
| POST | `/v1/rerank` | Nhazigharị n'ụdị Cohere/Voyage |
| POST | `/v1/classify` | Nkewapụta Jina (`api.jina.ai`) |
| POST | `/v1/segment` | Onye nkewa Jina (`segment.jina.ai`) |
| POST | `/v1/moderations` | OpenAI Moderations |
| GET | `/v1/models` | OpenAI |
| POST | `/v1/messages/count_tokens` | Anthropic |
| GET | `/v1beta/models` | Gemini |
| POST | `/v1beta/models/{...path}` | Gemini generateContent |
| POST | `/v1/api/chat` | Ollama |
| GET | `/api/v1/vscode/{token}/` | Aha ọzọ maka katalọgụ OpenAI |
| GET | `/api/v1/vscode/{token}/models` | Aha ọzọ maka ụdị OpenAI |
| POST | `/api/v1/vscode/{token}/chat/completions` | Aha ọzọ OpenAI nwere token |
| POST | `/api/v1/vscode/{token}/responses` | Aha ọzọ OpenAI Responses nwere token |
| POST | `/api/v1/vscode/{token}/api/chat` | Aha ọzọ Ollama nwere token |
| GET | `/api/v1/vscode/{token}/api/tags` | Aha ọzọ maka mkpado Ollama nwere token |
Ụzọ POST niile na-agbaso otu nhazi: `Bearer your-api-key` + ahụ JSON nke Zod kwadoro (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, wdg., lee `src/shared/validation/schemas.ts`). A na-eweghachi 4xx ma ọ bụrụ na nkwado schema ada.
Maka ndị ahịa na-enweghị ike itinye `Authorization: Bearer ...`, OmniRoute na-anabatakwa igodo API n'ime URL site na ndakọrịta eriri ajụjụ (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) ma ọ bụ endpoint `/api/v1/vscode/{token}/...` ndị akọwapụtara n'okpuru.
```bash
# Hazigharịa ọkwa
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
# Nkewapụta Jina (nzere Foundation API)
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
# Onye nkewa Jina
POST /v1/segment { "content": "...", "return_chunks": true }
# Ọchụchọ Jina (s.jina.ai; aha ndị ọzọ nke onye na-enye ọrụ: jina-search, jina-ai, jina)
POST /v1/search { "query": "...", "provider": "jina-search" }
# Nlekọta ọdịnaya
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
# TTS — na-eweghachi ahụ audio/mpeg (ma ọ bụ ọdịdị a rịọrọ)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
# Nrụzi onyonyo (multipart)
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
# Mmepụta vidiyo / egwu (ID ụdị nwere nganiihu onye na-enye ọrụ)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." }
```
### Ụzọ Ndị Na-enye Ọrụ Raara Ahụ
```bash
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
```
A na-agbakwunye nganiihu onye na-enye ọrụ na-akpaghị aka ma ọ bụrụ na ọ dịghị. Ụdị ndị na-adabaghị na-eweghachi `400`.
---
## API Faịlụ
Endpoint faịlụ dakọtara na OpenAI maka ntinye/mmepụta n'ìgwè na ibugo faịlụ dịka ebumnuche ha si dị.
| Usoro | Ụzọ | Nkọwa |
| ------ | ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| POST | `/v1/files` | Bulite faịlụ (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — kacha 512 MiB |
| GET | `/v1/files` | Depụta faịlụ maka API key e jiri nyochaa njirimara |
| GET | `/v1/files/[id]` | Nweta metadata faịlụ |
| DELETE | `/v1/files/[id]` | Hichapụ faịlụ |
| GET | `/v1/files/[id]/content` | Nyefee ọdịnaya faịlụ ahụ na-agbanweghị agbanweghachi |
**Nyocha njirimara:** Bearer API key — a na-ekewapụta faịlụ n'otu n'otu dịka API key si dị site na `getApiKeyRequestScope`.
---
## API Batches
Nhazi ọrụ n'ìgwè nke dakọtara na OpenAI.
| Usoro | Ụzọ | Nkọwa |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------- |
| POST | `/v1/batches` | Mepụta batch — `v1BatchCreateSchema` na-enyocha body (`input_file_id`, `endpoint`, `completion_window`) |
| GET | `/v1/batches` | Depụta batches |
| GET | `/v1/batches/[id]` | Nweta ọnọdụ batch + `request_counts` |
| DELETE | `/v1/batches/[id]` | Hichapụ batch gwụchara/kụrụ afọ n'ala |
| POST | `/v1/batches/[id]/cancel` | Kagbuo batch a ka na-arụ ọrụ |
**Nyocha njirimara:** Bearer API key. A na-ekewapụta batches n'otu n'otu dịka API key si dị.
---
## API Ọchụchọ
Nchịkọta abstraction maka ndị na-eweta ọchụchọ/webụ (Tavily, Brave, Exa, Serper, wdg.).
| Usoro | Ụzọ | Nkọwa |
| ----- | ---------------------- | ------------------------------------------------------------------------------------ |
| GET | `/v1/search` | Depụta ndị na-eweta ọchụchọ ahaziri + ikike ha |
| POST | `/v1/search` | Mee ajụjụ ọchụchọ — `v1SearchSchema` na-enyocha body, ọ na-akwado caching/coalescing |
| GET | `/v1/search/analytics` | Ọnụọgụ hit/latency/cache nke onye na-eweta ọ bụla |
**Nyocha njirimara:** Bearer API key (`extractApiKey` + `isValidApiKey`). A na-amanye iwu ọchụchọ site na `enforceApiKeyPolicy`.
---
## Web Fetch API
Wepụta ọdịnaya site na URL site n’aka onye na-eweta ọrụ web-fetch ahaziri (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).
| Usoro | Ụzọ | Nkọwa |
| ----- | --------------- | ------------------------------------------------------------- |
| POST | `/v1/web/fetch` | Weta/hichapụ ọdịnaya URL — `v1WebFetchSchema` na-enyocha body |
**Nkwenye:** Igodo API Bearer (`extractApiKey` + `isValidApiKey`). A na-amanye iwu site na `enforceApiKeyPolicy`.
**Ndaghachi azụ na-eburu oke n’uche (#8297):** mgbe enyeghị `provider` kpọmkwem, a na-agafe pool ahụ
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) n’usoro
mkpa edoziri
(fill-first) — a na-awụli onye na-eweta ọrụ ahaziri mana oke arịrịọ gbochiri ya
kama ịkwụsị arịrịọ ahụ ozugbo, ọdịda upstream a pụrụ ịnwale ọzọ/nke metụtara oke
(HTTP 429 mgbe niile; 402/403 maka ọkwa efu ndị nwere ụdị oke nke Firecrawl/Tavily/TinyFish —
ọ bụghị maka Jina Reader, ọ dịghịkwa mgbe ọ bụ arịrịọ ọjọọ 400 nkịtị) na-aga n’ihu ruo
onye na-eweta ọrụ ọzọ nwere nzere nke a na-anwalebeghị n’oge arịrịọ ahụ. Mgbe ndị na-eweta ọrụ niile dị na
pool agwụla, endpoint ahụ na-eweghachi naanị otu `429` (nwere header `Retry-After`)
kama `400` izugbe nke mbụ. Mgbe a rịọrọ `provider` kpọmkwem,
**enweghị** ndaghachi azụ zoro ezo — onye na-eweta ọrụ kpọmkwem nke oke arịrịọ gbochiri ma ọ bụ nke dara
na-egosi njehie nke ya (`429` ma ọ bụrụ na oke arịrịọ gbochiri ya, ma ọ bụghị ya, status
upstream).
---
## Mgbasa WebSocket
```bash
GET /v1/ws?handshake=1
```
Na-enyocha handshake nkwalite WebSocket ma weghachite ozi atụ nke protocol wire (`request`, `cancel`). Sava WS agbakwunyere, nke dị n’èzí tebụl route Next.js, na-ahụ maka frame WS ndị ahụ n’ezie.
**Nkwenye:** Igodo API Bearer n’oge handshake.
### Responses API site na WebSocket (naanị codex)
```bash
# Otu host:port ahụ nke HTTP API (ndabara 20128); kwalite njikọ ahụ:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (ma ọ bụ: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")
# Frame mbụ GA-ABỤRỊRỊ response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```
E jikọtara proxy Responses-API-over-WebSocket **naanị na `codex`** (backend ChatGPT).
Ọ na-ege ntị n’otu port ahụ API/dashboard ji, n’ụzọ `/v1/responses`,
`/responses`, na `/api/v1/responses`. N’elu frame `response.create` mbụ, ọ
na-eme nkwenye + nkwadebe site na bridge `codex-responses-ws` dị n’ime, họrọ
njikọ OAuth codex, ma mepụta tunnel gaa `wss://chatgpt.com/backend-api/codex/responses`
site na transport `wreq-js`. **A na-ajụ model ndị na-abụghị codex** (`codex_ws_provider_required`).
Maka routing nkekọ oke, jiri `model: "qtSd/<group>/codex/<model>"`. E mejuputara ya na
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.
**Nkwenye:** Igodo API Bearer n’oge handshake. Sava HTTP agbakwunyere (`server-ws.mjs`)
ga-abụrịrị entrypoint na-arụ ọrụ (ọ bụ ya na ndabara mgbe `app/server-ws.mjs` dị).
#### NJ model: jiri NJ ChatGPT nkịtị (enweghị prefix `codex/`)
OpenAI **Codex CLI** na-enyocha aha model n’akụkụ client mgbe
`supports_websockets = true`, ma **na-ajụ NJ nwere prefix onye na-eweta ọrụ** dịka
`codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`). Zipu NJ **nkịtị** (dịka `gpt-5.5`). Bridge OmniRoute bụ
naanị maka codex, ya mere ọ na-ekpebi ọzọ na NJ nkịtị bụ model codex
(`resolveCodexWsModelInfo`) tupu o mepụta tunnel gaa upstream — n’agbanyeghị na
`gpt-5.5` nkịtị ga-aga onye na-eweta ọrụ ọzọ site na HTTP ma ọ bụghị ya.
#### Ịhazigharị OpenAI Codex CLI
Duzie Codex CLI na OmniRoute site n’ịtinye onye na-eweta ọrụ omenala nwere nkwado
WebSocket na `~/.codex/config.toml` (jiri `CODEX_HOME` dị iche ka ị ghara imetụ
config dị ugbu a aka):
```toml
model = "gpt-5.5" # NJ nkịtị — Ọ BỤGHỊ "codex/gpt-5.5"
model_provider = "omniroute"
[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1" # enweghị slash n’azụ; a na-ewepụta URL WS site na ya (jiri https/wss na production)
wire_api = "responses" # naanị value a na-akwado kemgbe Feb 2026
supports_websockets = true # na-eme ka transport Responses-over-WS rụọ ọrụ
env_key = "OMNIROUTE_API_KEY" # na-ejide igodo API OmniRoute (Bearer)
```
```bash
export OMNIROUTE_API_KEY=sk-... # igodo API OmniRoute (igodo ọ bụla ma ọ bụrụ na REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```
CLI na-akwalite `base_url + /responses` ka ọ bụrụ WebSocket, OmniRoute wee mepụta tunnel ya
gaa na njikọ OAuth codex ahọpụtara. E nyochara ya site na mmalite ruo na njedebe megide sava
mpaghara: ChatGPT na-eweghachi `codex.rate_limits` + `response.created` ma na-agbasa
mmecha ahụ.
---
## Oke ojiji & Ịkọ nsogbu
| Usoro | Ụzọ | Nkọwa |
| ----- | ------------------- | ---------------------------------------------------------------------------------------- |
| GET | `/v1/quotas/check` | Buru ụzọ nyochaa oke ojiji maka `provider` + `accountId` tupu inye igodo e debanyere aha |
| POST | `/v1/issues/report` | Kọọrọ GitHub ọdịda nke oke ojiji/inye igodo (chọrọ `GITHUB_ISSUES_REPO` + token) |
**Nyocha ikike:** Igodo API Bearer (`isAuthenticated`).
---
## Ojiji nke onye nwe ya (`/api/usage/om-usage`)
Igodo API ọ bụla nwere ike ịgụ ojiji na oke ojiji **nke ya** — ọ chọghị ikike njikwa. Nke a bụ endpoint nke
client (CLI, panel OmniCopilot) na-eji egosi onye ji igodo ego ole o mefuru.
```bash
# Ụdị ederede (nkwekọrịta ochie — ederede nkịtị maka terminal)
curl -H "Authorization: Bearer <your-api-key>" \
http://localhost:20128/api/usage/om-usage
# Ụdị ahaziri ahazi — nke UI na-eji
curl -H "Authorization: Bearer <your-api-key>" \
"http://localhost:20128/api/usage/om-usage?format=json"
```
A ga-agbanyerịrị **`allowUsageCommand`** maka igodo ahụ (a na-agbanyụ ya na ndabara — onye njikwa igodo API
nke dashboard na-agbanye ma ọ bụ gbanyụọ ya maka igodo ọ bụla). Na-enweghị ya, endpoint ahụ na-aza `403`.
`?format=json` na-eweghachi nhazi nwere akara ọdịiche ka onye na-akpọ ghara ịgụ mpaghara data sitere na
ọjụjụ. Mgbe ọ gara nke ọma:
```jsonc
{
"allowed": true,
// dị naanị mgbe igodo ahụ họọrọ oke ojiji nke otu igodo (USD kwa ụbọchị/kwa izu):
"personal": {
"dailySpentUsd": 1.25,
"dailyLimitUsd": 5,
"dailyResetAtIso": "…",
"weeklySpentUsd": 8,
"weeklyLimitUsd": 20,
"weeklyResetAtIso": "…" /* … */,
},
// snapshot oke ojiji provider ahọpụtara, ma ọ bụ null mgbe ọ nweghị ihe echekwara:
"provider": {
"connectionId": "…",
"provider": "claude",
"plan": "…",
"quotas": {/* … */},
},
// snapshot njikọ niile, ka UI nwee ike igosi ọtụtụ provider n'akụkụ ibe ha:
"providers": [
{ "connectionId": "…", "provider": "claude" /* … */ },
{ "provider": "codex" /* … */ },
],
}
```
Mgbe a jụrụ (`401` igodo na-adịghị mma / `403` anaghị ekwe) otu route ahụ na-eweghachi
`{ "allowed": false, "error": { "message": "…" } }` — `personal`/`provider` dị ma tọgbọ chakoo
(ekwere igodo ahụ, mana amụtabeghị ihe ọ bụla) bụ ọnọdụ dị iche na ọjụjụ, naanị ụdị JSON
na-egosi ọdịiche dị n'etiti ha.
**Nyocha ikike:** igodo API Bearer nke onye na-akpọ, nke `isValidApiKey` nyochara — nke a _abụghị_
akụkụ njikwa (`/api/keys/…`), nke ka nọ n'azụ `requireManagementAuth`.
---
## Cache Semantic
```bash
# Nweta ọnụ ọgụgụ cache
GET /api/cache/stats
# Hichapụ cache niile
DELETE /api/cache/stats
```
Ọmụmaatụ nzaghachi:
```json
{
"semanticCache": {
"memorySize": 42,
"memoryMaxSize": 500,
"dbSize": 128,
"hitRate": 0.65
},
"idempotency": {
"activeKeys": 3,
"windowMs": 5000
}
}
```
### Mmetụta n'oge nzaghachi
Mgbe semantic cache HIT mere, ọ na-enye nzaghachi sitere na cache **na-enweghị ịkpọ
upstream**, ya mere `X-OmniRoute-Response-Latency` a kọọrọ na-adị nso na efu
(n'agbanyeghị oge nzaghachi upstream mbụ). Ndị client oge nzaghachi na-emetụta
(benchmarking, nlekota p50/p99) kwesịrị ịlele header nzaghachi
`X-OmniRoute-Cache-Latency`:
| Uru | Ihe ọ pụtara |
| ----------- | ------------------------------------------------------------------ |
| `synthetic` | Enyere nzaghachi site na cache; oge ahụ abụghị oge upstream n'ezie |
| _(adịghị)_ | Nzaghachi sitere na oku upstream n'ezie |
### Ịgafe cache maka igodo ọ bụla
Igodo API nwere ike ịhọrọ ịghara ịgụ semantic cache site na `cacheDefaultMode`:
| Uru | Omume |
| -------- | --------------------------------------------------- |
| `legacy` | Omume cache nkịtị (ndabara) |
| `bypass` | Mafee nchọ cache kpamkpam; kpọọ upstream mgbe niile |
Tọọ ya mgbe a na-emepụta igodo (`POST /api/keys`) ma ọ bụ na-emelite ya (`PATCH /api/keys/[id]`):
```json
{ "cacheDefaultMode": "bypass" }
```
### Ịgafe cache maka arịrịọ ọ bụla
Arịrịọ ọ bụla nwere ike ịgafe cache n'agbanyeghị ntọala igodo:
```
X-OmniRoute-No-Cache: true
```
---
## Dashboard & Nlekọta
Ụzọ nlekọta (`/api/*` ma e wezụga auth/login ọha) **anaghị** anabata ikike site na
igodo API inference nkịtị. Maka ezinụlọ nzere, scopes, na ihe atụ curl:
[Otentikeshọn Nlekọta](../guides/MANAGEMENT-AUTH.md).
### Otentikeshọn
| Endpoint | Method | Nkọwa |
| ----------------------------- | ------- | -------------------------- |
| `/api/auth/login` | POST | Banye |
| `/api/auth/logout` | POST | Pụọ |
| `/api/settings/require-login` | GET/PUT | Gbanye/gbanyụọ mkpa ịbanye |
### Nlekọta Provider
| Endpoint | Method | Nkọwa |
| ---------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `/api/providers` | GET/POST | Depụta / mepụta providers |
| `/api/providers/[id]` | GET/PUT/DELETE | Jikwaa otu provider |
| `/api/providers/[id]/test` | POST | Nwalee njikọ provider |
| `/api/providers/[id]/models` | GET | Depụta models nke provider |
| `/api/providers/validate` | POST | Nyochaa config provider |
| `/api/providers/bulk` | POST | Tinye ọtụtụ igodo API n'otu oge maka OTU provider |
| `/api/providers/import` | POST | Bubata NDEPỤTA providers dịgasị iche site na faịlụ CSV/JSON a parsedịrị (#6836); nsonaazụ ọdịda akụkụ n'ahịrị ọ bụla |
| `/api/provider-nodes*` | Dịgasị iche | Nlekọta node provider |
| `/api/provider-models` | GET/POST/PATCH/DELETE | Models ahaziri iche (tinye, melite, zoo/gosi, hichapụ) |
### Usoro OAuth
| Endpoint | Method | Nkọwa |
| -------------------------------- | ----------- | ---------------------------- |
| `/api/oauth/[provider]/[action]` | Dịgasị iche | OAuth kpọmkwem maka provider |
### Routing & Config
| Endpoint | Method | Nkọwa |
| --------------------- | ----------- | -------------------------------- |
| `/api/models/alias` | GET/POST | Aha nnọchi models |
| `/api/models/catalog` | GET | Models niile dịka provider + ụdị |
| `/api/combos*` | Dịgasị iche | Nlekọta combo |
| `/api/keys*` | Dịgasị iche | Nlekọta igodo API |
| `/api/pricing` | GET | Ọnụahịa model |
### Ojiji & Nnyocha Data
| Endpoint | Usoro | Nkọwa |
| -------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history` | GET | Akụkọ ojiji |
| `/api/usage/logs` | GET | Ndekọ ojiji |
| `/api/usage/request-logs` | GET | Ndekọ n'ogo arịrịọ |
| `/api/usage/[connectionId]` | GET | Ojiji nke njikọ ọ bụla |
| `/api/usage/token-limits` | GET/POST/DELETE | Oke mmefu token maka API key ọ bụla |
| `/api/usage/model-latency-stats` | GET | Nchịkọta latency na-aga n'ihu maka provider/model ọ bụla (avg/p50/p95/p99, ọnụọgụ ihe ịga nke ọma); ihe nzacha: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) |
| `/api/usage/cache-health` | GET | Nchịkọta ọnọdụ prompt-cache n'ime `call_logs` — oke write/read, nkesa nha write p50/p90/p99, mkpokọta heavy-write, nkewa n'ụdị model ọ bụla, yana mkpebi `healthy`/`degraded`/`thrash`/`no-data`; query params `range` (`1h`\|`24h`\|`7d`\|`30d`, ndabara bụ `24h`) na `model` nke bụ nhọrọ (#8827) |
### Ntọala
| Endpoint | Usoro | Nkọwa |
| ------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings` | GET/PUT/PATCH | Ntọala izugbe |
| `/api/settings/proxy` | GET/PUT | Nhazi proxy netwọkụ |
| `/api/settings/proxy/test` | POST | Nwalee njikọ proxy |
| `/api/settings/ip-filter` | GET/PUT | Ndepụta IP ndị anabatara/ndị egbochiri |
| `/api/settings/thinking-budget` | GET/PUT | Ụdị idegharị **arịrịọ** thinking/reasoning (passthrough / auto-strip / custom / adaptive). Ọ nọọrọ onwe ya na compression. Hụ [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). |
| `/api/settings/system-prompt` | GET/PUT | System prompt zuru ụwa ọnụ |
| `/api/settings/compression` | GET/PUT | Nhazi compression zuru ụwa ọnụ |
| `/api/settings/purge-request-history` | POST | Hichapụ ahịrị ndekọ arịrịọ na artifact call-log dị na mpaghara |
### Context & Compression
| Endpoint | Usoro | Nkọwa |
| -------------------------------------- | -------------- | ---------------------------------------------------------------------------- |
| `/api/compression/preview` | POST | Lelee mkpakọ off/lite/standard/aggressive/ultra/RTK/stacked tupu oge eruo |
| `/api/compression/language-packs` | GET | Depụta ngwugwu asụsụ Caveman dịnụ |
| `/api/compression/rules` | GET | Depụta metadata iwu Caveman |
| `/api/context/caveman/config` | GET/PUT | Aha ọzọ maka ntọala ndị metụtara Caveman |
| `/api/context/rtk/config` | GET/PUT | Ntọala ndị metụtara RTK, gụnyere nzacha ahaziri iche na njigide nsonaazụ raw |
| `/api/context/rtk/filters` | GET | Katalọgụ nzacha RTK na nchọpụta nsogbu nzacha ahaziri iche |
| `/api/context/rtk/test` | POST | Mee nlele tupu oge eruo/ule RTK megide payload ederede |
| `/api/context/rtk/raw-output/[id]` | GET | Gụọ nsonaazụ raw e zoro ozi ya ma debe ya site na pointer id |
| `/api/context/combos` | GET/POST | Depụta/mepụta ngwakọta mkpakọ |
| `/api/context/combos/[id]` | GET/PUT/DELETE | Nkọwa/mmelite/nhichapụ ngwakọta mkpakọ |
| `/api/context/combos/[id]/assignments` | GET/PUT | Kenye ngwakọta mkpakọ na ngwakọta routing |
| `/api/context/analytics` | GET | Aha ọzọ maka nyocha data mkpakọ |
### Nlekota
| Endpoint | Usoro | Nkọwa |
| ------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions` | GET | Nsochi session ndị na-arụ ọrụ |
| `/api/rate-limits` | GET | Oke ọnụego maka akaụntụ ọ bụla |
| `/api/monitoring/health` | GET | Nyocha ahụike + nchịkọta provider (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Nlele njikwa gụnyere `credentialHealth`: ọnụọgụ probe-cache, `failedConnections` mgbe `failed>0`, na `staleDbNonOkCount` (`test_status` SQLite na-anọgide adịgide, ọ bụghị gauge). Hụ [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). |
| `/api/cache/stats` | GET/DELETE | Statistik cache / hichapụ |
| `/api/modality-bridge/stats` | GET | `attempts` dị na ebe nchekwa, ihe ịga nke ọma/`bridged`, ọdịda, cache hits, `totalLatencyMs`, `latencySamples`, `averageLatencyMs` nke denominator ya bụ sample, na oge ojiji ikpeazụ (a na-atọgharị ya mgbe e bidoro ọzọ; njirimara njikwa) |
| `/api/modality-bridge/video/runtime` | GET | Nyocha trusted-loopback siri ike tupu njirimara njikwa/probe; nnweta na ụdị FFmpeg/ffprobe e mere ka ha ghara ikpughe ozi dị mkpa (no-store) |
| `/api/modality-bridge/video/extract` | POST | Byte broker trusted-loopback nke ime ụlọ nwere njirimara; ntinye 50 MiB, queue nwere oke/nsonaazụ 32 MiB, `503` mgbe capacity zuru, `499` mgbe njikọ kwụsịrị, `504` mgbe deadline gafere; ọ bụghị API upload ọha |
### Nkwado ndabere & Mbupụ/Mbubata
| Endpoint | Usoro | Nkọwa |
| --------------------------- | ----- | ------------------------------------------------ |
| `/api/db-backups` | GET | Depụta ndabere ndị dị |
| `/api/db-backups` | PUT | Mepụta ndabere aka |
| `/api/db-backups` | POST | Weghachite site na ndabere akọwapụtara |
| `/api/db-backups/export` | GET | Budata nchekwa data dịka faịlụ .sqlite |
| `/api/db-backups/import` | POST | Bulite faịlụ .sqlite iji dochie nchekwa data |
| `/api/db-backups/exportAll` | GET | Budata ndabere zuru ezu dịka ebe-nchekwa .tar.gz |
### Mmekọrịta Ígwé Ojii
| Endpoint | Usoro | Nkọwa |
| ---------------------- | ------------ | ----------------------- |
| `/api/sync/cloud` | Dị iche iche | Ọrụ mmekọrịta ígwé ojii |
| `/api/sync/initialize` | POST | Bido mmekọrịta |
| `/api/cloud/*` | Dị iche iche | Njikwa ígwé ojii |
### Ọwara
| Endpoint | Usoro | Nkọwa |
| -------------------------- | ----- | ------------------------------------------------------------------------ |
| `/api/tunnels/cloudflared` | GET | Gụọ ọnọdụ nrụnye/ọrụ Cloudflare Quick Tunnel maka dashboard |
| `/api/tunnels/cloudflared` | POST | Gbanye ma ọ bụ gbanyụọ Cloudflare Quick Tunnel (`action=enable/disable`) |
| `/api/tunnels/ngrok` | GET | Gụọ ọnọdụ ọrụ ngrok Tunnel maka dashboard |
| `/api/tunnels/ngrok` | POST | Gbanye ma ọ bụ gbanyụọ ngrok Tunnel (`action=enable/disable`) |
### Ngwaọrụ CLI
| Endpoint | Usoro | Nkọwa CLI |
| ---------------------------------- | ----- | ------------------ |
| `/api/cli-tools/claude-settings` | GET | Ọnọdụ Claude CLI |
| `/api/cli-tools/codex-settings` | GET | Ọnọdụ Codex CLI |
| `/api/cli-tools/droid-settings` | GET | Ọnọdụ Droid CLI |
| `/api/cli-tools/openclaw-settings` | GET | Ọnọdụ OpenClaw CLI |
| `/api/cli-tools/runtime/[toolId]` | GET | Oge ọrụ CLI izugbe |
Nzaghachi CLI gụnyere: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
### Ndị Nnochiteanya ACP
| Endpoint | Usoro | Nkọwa |
| ----------------- | ------ | ------------------------------------------------------------------------------------------- |
| `/api/acp/agents` | GET | Depụta ndị nnochiteanya niile achọpụtara (ndị arụnyere n'ime ya + omenala) tinyere ọnọdụ ha |
| `/api/acp/agents` | POST | Tinye onye nnochiteanya omenala ma ọ bụ mee ka cache nchọpụta dị ọhụrụ |
| `/api/acp/agents` | DELETE | Wepụ onye nnochiteanya omenala site na paramita ajụjụ `id` |
Nzaghachi GET gụnyere `agents[]` (id, name, binary, version, installed, protocol, isCustom) na `summary` (total, installed, notFound, builtIn, custom).
### Nkwụsi Ike & Oke Ọsọ
| Endpoint | Usoro | Nkọwa |
| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------- |
| `/api/resilience` | GET/PATCH | Nweta/melite kwụ ọrụ arịrịọ, oge njikọ ga-ajụ oyi, ihe nkwụsị onye na-eweta ọrụ, na ntọala nchere |
| `/api/resilience/reset` | POST | Tọgharịa ihe nkwụsị sekit nke ndị na-eweta ọrụ |
| `/api/resilience/model-cooldowns` | GET | Depụta mkpọchi ndị na-arụ ọrụ kwa-(onye na-eweta ọrụ, njikọ, model), hazie ha dịka oge fọdụrụ |
| `/api/resilience/model-cooldowns` | DELETE | Hichapụ mkpọchi model — body `{provider, model}` ma ọ bụ `{all: true}` iji hichapụ ihe niile |
| `/api/rate-limits` | GET | Ọnọdụ oke ọsọ kwa akaụntụ |
| `/api/rate-limit` | GET | Nhazi oke ọsọ zuru ụwa ọnụ |
> Ụzọ `/api/resilience/*` anọ ahụ niile chọrọ **njirimara njikwa** (`requireManagementAuth`). Lee [Nkwụsi Ike (gbasawanyere)](#resilience-extended) maka nkọwa zuru ezu banyere ihe nkwụsị onye na-eweta ọrụ vs oge njikọ ga-ajụ oyi vs mkpọchi model.
### Nnwale Ntụle
| Endpoint | Usoro | Nkọwa |
| ------------ | -------- | ---------------------------------- |
| `/api/evals` | GET/POST | Depụta nchịkọta nnwale / mee ntụle |
### Iwu
| Endpoint | Usoro | Nkọwa |
| --------------- | --------------- | -------------------- |
| `/api/policies` | GET/POST/DELETE | Jikwaa iwu nhọrọ ụzọ |
### Nrubeisi
| Endpoint | Usoro | Nkọwa |
| --------------------------- | ----- | --------------------------------- |
| `/api/compliance/audit-log` | GET | Ndekọ nyocha nrubeisi (N ikpeazụ) |
### v1beta (Dakọtara na Gemini)
| Endpoint | Usoro | Nkọwa |
| -------------------------- | ----- | --------------------------------- |
| `/v1beta/models` | GET | Depụta model n'ụdị Gemini |
| `/v1beta/models/{...path}` | POST | Endpoint Gemini `generateContent` |
Endpoint ndị a na-eṅomi usoro API Gemini maka client ndị na-atụ anya ndakọrịta SDK Gemini nke mbụ.
### API Ime / Sistemụ
| Ebe njedebe | Usoro | Nkọwa |
| ------------------------ | ----- | -------------------------------------------------------------- |
| `/api/init` | GET | Nlele mmalite ngwa (a na-eji ya na nke mbụ a na-agba ngwa ahụ) |
| `/api/tags` | GET | Mkpado ụdịdị dakọtara na Ollama (maka ndị ahịa Ollama) |
| `/api/restart` | POST | Kpalite mbugharị sava n'ụzọ dị nro |
| `/api/shutdown` | POST | Kpalite mmechi sava n'ụzọ dị nro |
| `/api/system/env/repair` | POST | Dozie mgbanwe gburugburu ebe obibi nke onye na-eweta OAuth |
> **Rịba ama:** Sistemu na-eji ebe njedebe ndị a n'ime ya ma ọ bụ maka ndakọrịta na ndị ahịa Ollama. Ndị ọrụ ikpeazụ anaghị akpọkarị ha ozugbo.
### Ndozi Gburugburụ Ebe Obibi OAuth _(v3.6.1+)_
```bash
POST /api/system/env/repair
Content-Type: application/json
{
"provider": "claude-code"
}
```
Na-arụzi mgbanwe gburugburu ebe obibi OAuth ndị na-efu efu ma ọ bụ ndị mebiri emebi maka otu onye na-eweta kpọmkwem. Ọ na-eweghachi:
```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"
}
```
---
## Ntụgharị Edemede Ọdịyo
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
```
Jiri onye na-enye STT ọ bụla ahaziri iji tụgharị faịlụ ọdịyo gaa n'edemede. Akụkụ mbụ nke ụzọ ahụ
na-ahọrọ onye na-enye ọrụ ahụ kpọmkwem (`openai/…`, `deepgram/…`). Ọnụ ụzọ ndị
na-ebupụgharị ụdị nke onye nrụpụta ọzọ na-eji id a kọwara nke ọma
(`openrouter/deepgram/nova-3`).
**Arị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"
```
**Nzaghachi:**
```json
{
"text": "Ndewo, nke a bụ ọdịnaya ọdịyo a tụgharịrị gaa n'edemede.",
"task": "transcribe",
"language": "en",
"duration": 12.5
}
```
**Ihe atụ id ụdị:** `openai/whisper-1` (chọrọ igodo OpenAI),
`openrouter/deepgram/nova-3` (chọrọ igodo OpenRouter),
`deepgram/nova-3` (chọrọ igodo Deepgram kpọmkwem). Arịrịọ
`deepgram/nova-3` na-enweghị mgbakwunye **anaghị** eji OpenRouter.
**Ụdị ndị a na-akwado:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
---
## Ndakọrịta Ollama
Maka ndị ahịa na-eji usoro API nke Ollama:
```bash
# Ebe njedebe nkata (usoro Ollama)
POST /v1/api/chat
# Ndepụta ụdị (usoro Ollama)
GET /api/tags
```
A na-atụgharị arịrịọ na-akpaghị aka n'etiti usoro Ollama na usoro dị n'ime.
## Aha Ọzọ VS Code Nwere Token / Na-enweghị Header
Jiri aha ndị ọzọ ndị a mgbe njikọ enweghị ike itinye header `Authorization` ma chọọ ka etinye igodo API n'ime URL ntọala.
```bash
# Aha ọzọ katalọgụ n'ụdị OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models
# Aha ọzọ nkata n'ụdị OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses
# Aha ndị ọzọ n'ụdị Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```
Ihe atụ:
```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"}]}'
```
Nkọwa:
- Aha ndị ọzọ nwere token na-ejikwa otu handlers ndị `/v1/*` na `/api/tags` na-eji; ọdịdị nzaghachi na-anọgide otu.
- Họrọ `Authorization: Bearer ...` mgbe ọ bụla onye ahịa na-akwado headers ahaziri iche.
- Tokens dabere na URL nwere ike ịpụta na ndekọ reverse-proxy, akụkọ ihe nchọgharị, na telemetry dị na mpụga OmniRoute. Were ha dịka nhọrọ ndakọrịta, ọ bụghị usoro nkwenye njirimara ndabara.
---
## Telemetry
```bash
# Nweta nchịkọta telemetry nke oge igbu oge (p50/p95/p99 maka onye na-enye ọrụ ọ bụla)
GET /api/telemetry/summary
```
**Nzaghachi:**
```json
{
"providers": {
"claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
"github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
}
}
```
---
## Mmefu Ego
```bash
# Nweta ọnọdụ mmefu ego maka igodo API niile
GET /api/usage/budget
# Tọọ ma ọ bụ melite mmefu ego
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"
}
```
> **Nkọwa schema** (`setBudgetSchema`): `apiKeyId` dị mkpa; opekata mpe otu n'ime `dailyLimitUsd`, `weeklyLimitUsd`, ma ọ bụ `monthlyLimitUsd` ga-adịrịrị karịa efu. Fields nhọrọ: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Ọdịdị ochie `{keyId, limit, period}` na-eweghachi `400 Bad Request`.
## Oke Token
Mmefu **token** maka igodo API ọ bụla (dị iche na Mmefu dabere na USD dị n’elu). A na-amanye ya ozugbo n’ụzọ arịrịọ: mgbe ojiji igodo n’ime windo dị ugbu a ruru oke ya, a na-ajụ arịrịọ ndị ọzọ site na `429 Too Many Requests`. Enwere ike ịkọwapụta oke maka `model` kpọmkwem, `provider`, ma ọ bụ tinye ya n’ogo `global` n’ofe igodo ahụ; mgbe ọtụtụ oke dabara n’otu arịrịọ, nke kacha sie ike ga-emeri.
```bash
# Depụta oke token nke otu igodo (gụnyere ojiji windo dị ugbu a)
GET /api/usage/token-limits?apiKeyId=key-123
# Mepụta ma ọ bụ melite oke token
POST /api/usage/token-limits
Content-Type: application/json
{
"apiKeyId": "key-123",
"scopeType": "model",
"scopeValue": "openai/gpt-4o",
"tokenLimit": 1000000,
"resetInterval": "monthly",
"enabled": true
}
# Hichapụ oke token site na id
DELETE /api/usage/token-limits?id=tl-abc
```
> **Nkọwa schema** (`setTokenLimitSchema`): `apiKeyId` na `scopeType` (`model` | `provider` | `global`) bụ ihe achọrọ. A chọrọ `scopeValue` ma e wezụga mgbe `scopeType` bụ `global` (dịka ọmụmaatụ, id model maka scope `model`, ma ọ bụ id provider maka scope `provider`). `tokenLimit` ga-abụrịrị integer dị mma (a na-agbanwe ya site na string). Nhọrọ ndị ọzọ: `id` (hapụ ya iji mepụta, tinye ya iji melite), `resetInterval` (`daily` | `weekly` | `monthly`, ndabara bụ `monthly`), `resetTime` (`HH:MM`), `enabled` (ndabara bụ `true`). Nzaghachi `GET` na-agbakwunye `tokensUsed`, `remaining`, `windowStart`, `periodStartAt`, na `nextResetAt` na oke ọ bụla. Nke a bụ endpoint nke klaasị njikwa (authz pipeline na-amanye auth n’etiti usoro).
## Nhazi Arịrịọ
1. Client na-eziga arịrịọ na `/v1/*`
2. Route handler na-akpọ `handleChat`, `handleEmbedding`, `handleAudioTranscription`, ma ọ bụ `handleImageGeneration`
3. A na-achọpụta model (provider/model kpọmkwem ma ọ bụ alias/combo)
4. A na-ahọrọ credentials site na DB mpaghara site n’iji nzacha nnweta account
5. Maka chat: `handleChatCore` na-enyocha semantic/signature cache ma na-achọpụta ntọala mkpakọ combo
6. Mkpakọ proactive na-arụ ọrụ tupu ntụgharị provider mgbe enyere ya ohere (`lite`, Caveman, RTK, ma ọ bụ ndị e jikọtara ọnụ)
7. Provider executor na-eziga arịrịọ upstream
8. A na-atụgharị nzaghachi laghachi n’usoro client (chat) ma ọ bụ weghachite ya otu ọ dị (embeddings/images/audio)
9. A na-edekọ ojiji, nyocha mkpakọ, na ndekọ arịrịọ
10. A na-etinye fallback mgbe njehie mere dịka iwu combo si dị
Ntụaka nhazi zuru ezu: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)
---
## Njikwa Combo
A pụkwara ịmapụta combo routing dị elu (nke a chịkọtalarị n’okpuru `/api/combos*`) 1:1 site na ụkpụrụ id model, nke na-enye ohere ibugharị id model ụdị OpenAI gaa na combo n’enweghị ihe mgbochi.
| Method | Path | Nkọwa |
| ------ | -------------------------------- | ------------------------------------------------------------------------------ |
| GET | `/api/model-combo-mappings` | Depụta mappings model→combo niile |
| POST | `/api/model-combo-mappings` | Mepụta mapping — body: `{pattern, comboId, priority?, enabled?, description?}` |
| GET | `/api/model-combo-mappings/[id]` | Weta otu mapping |
| PUT | `/api/model-combo-mappings/[id]` | Melite fields nke mapping dị adị |
| DELETE | `/api/model-combo-mappings/[id]` | Wepụ mapping |
**Auth:** session/API key njikwa (`requireManagementAuth`).
---
## Webhooks
Ndenye aha webhook ndị na-apụ apụ maka mmemme OmniRoute (mmecha arịrịọ, mmebi oke ojiji, mgbanwe igodo, wdg.).
| Usoro | Ụzọ | Nkọwa |
| ------ | ------------------------- | -------------------------------------------------------------------- |
| GET | `/api/webhooks` | Depụta webhooks (a na-ekpuchi ihe nzuzo dịka `<prefix>...`) |
| POST | `/api/webhooks` | Mepụta webhook — ahụ: `{url, events?: ["*"], secret?, description?}` |
| GET | `/api/webhooks/[id]` | Nweta otu webhook |
| PUT | `/api/webhooks/[id]` | Melite url/events/secret/description |
| DELETE | `/api/webhooks/[id]` | Wepụ otu webhook |
| POST | `/api/webhooks/[id]/test` | Ziga payload nnwale na URL webhook ma weghachite ọnọdụ nnyefe |
**Nkwenye njirimara:** nnọkọ njikwa/igodo API (`requireManagementAuth`).
---
## Igodo E Debanyere Aha (Njikwa Akpaka)
Usoro nta njikwa igodo akpaka na-eji ya ewepụta ma gbanwee igodo API n'aka onye na-eweta ọrụ/akaụntụ nkwado, yana oke ojiji kwa ụbọchị/kwa elekere.
| Usoro | Ụzọ | Nkọwa |
| ------ | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/registered-keys` | Depụta igodo ndị e debanyere aha (naanị prefix e kpuchiri ekpuchi) |
| POST | `/api/v1/registered-keys` | Wepụta igodo ọhụrụ e debanyere aha — ahụ: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Na-eweghachite igodo ahụ n'onwe ya **otu ugboro**. Na-eweghachite `429` ma ọ bụrụ na oke ojiji ajụ arịrịọ ahụ. |
| GET | `/api/v1/registered-keys/[id]` | Nweta metadata nke igodo e debanyere aha (enweghị igodo ahụ n'onwe ya) |
| DELETE | `/api/v1/registered-keys/[id]` | Kagbuo igodo e debanyere aha |
| POST | `/api/v1/registered-keys/[id]/revoke` | Endpoint maka ịkagbu kpọmkwem (otu mmetụta ahụ dịka DELETE) |
**Nkwenye njirimara:** Igodo Bearer API (`isAuthenticated`). Leekwa `/v1/quotas/check` na `/v1/issues/report`.
---
## Protokọlụ Ndị Ọrụ Nnọchiteanya
Ọrụ ndị ọrụ nnọchiteanya igwe ojii (Claude Code, Codex Cloud, OpenHands, wdg.) a na-arụ n'ebe dị anya n'aha ndị ọrụ OmniRoute.
| Usoro | Ụzọ | Nkọwa |
| ------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/agents/tasks` | Depụta ọrụ — `?provider=`, `?status=`, `?limit=` bụ nhọrọ (1–500, ndabara bụ 50) |
| POST | `/api/v1/agents/tasks` | Mepụta ọrụ — `CreateCloudAgentTaskSchema` na-enyocha body (`providerId`, `prompt`, `source`, `options?`). Ọ na-eweghachi `201` tinyere envelopu ọrụ |
| DELETE | `/api/v1/agents/tasks?id=...` | Hichapụ otu ọrụ |
| GET | `/api/v1/agents/tasks/[id]` | Gụọ ọrụ — ọ na-emelite ọnọdụ ozugbo site n'aka onye ọrụ nnọchiteanya igwe ojii dị n'elu mgbe edobere `external_id` |
| POST | `/api/v1/agents/tasks/[id]` | Omume a na-amata iche: `{action: "approve"}`, `{action: "message", message}`, ma ọ bụ `{action: "cancel"}` |
| DELETE | `/api/v1/agents/tasks/[id]` | Jiri id hichapụ otu ọrụ kpọmkwem |
> **Nyocha ikike:** a chọrọ nyocha ikike njikwa n'usoro ọ bụla (`requireCloudAgentManagementAuth`). Tupu v3.8.0, usoro ndị a achọghị nyocha ikike — lee commit `588a0333` maka mgbanwe na-emebi ndakọrịta.
```bash
# Mepụta ọrụ igwe ojii Claude Code
curl -X POST http://localhost:20128/api/v1/agents/tasks \
-H "Authorization: Bearer your-management-key" \
-H "Content-Type: application/json" \
-d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'
```
---
## Proxy Njikwa
Proxy HTTP(S)/SOCKS na-apụ apụ nke enwere ike ikenye ndị na-eweta ọrụ, akaụntụ, ma ọ bụ n'ụwa niile.
| Usoro | Ụzọ | Nkọwa |
| ------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/management/proxies` | Depụta proxy (iji `?id=` na-eweghachi otu; iji `?id=&where_used=1` na-eweghachi eserese nke ikenye ha) |
| POST | `/api/v1/management/proxies` | Mepụta proxy — `createProxyRegistrySchema` na-enyocha body |
| PATCH | `/api/v1/management/proxies` | Melite proxy — `updateProxyRegistrySchema` na-enyocha body (ọ chọrọ `id`) |
| DELETE | `/api/v1/management/proxies?id=...&force=1` | Hichapụ proxy (jiri `force=1` kewapụ ikenye ndị dị na ya) |
| GET | `/api/v1/management/proxies/assignments` | Depụta ikenye — enwere ike iji `proxy_id`, `scope`, `scope_id` nzacha ya; nyefee `resolve_connection_id=<id>` iji chọpụta proxy na-arụ ọrụ maka njikọ |
| PUT | `/api/v1/management/proxies/assignments` | Kenye — `proxyAssignmentSchema` na-enyocha body (`{scope, scopeId?, proxyId?}`). Ọ na-ehichapụ cache dispatcher |
| PUT | `/api/v1/management/proxies/bulk-assign` | Kenye n'ìgwè — `bulkProxyAssignmentSchema` na-enyocha body (`{scope, scopeIds[], proxyId?}`) |
| GET | `/api/v1/management/proxies/health?hours=24` | Chịkọta ọnọdụ ahụike proxy (ọnụọgụ ihe gara nke ọma/daara, oge nzaghachi) n'ime otu oge |
**Nyocha ikike:** a chọrọ session njikwa/igodo API n'ụzọ ọ bụla (`requireManagementAuth`).
> `POST /api/v1/management/proxies/[id]/assignments` na `POST /api/v1/management/proxies/[id]/health` dị na nkọwa ọrụ ahụ bụ ụzọ `/assignments` na `/health` kwụ ọtọ e gosiri n'elu na-ejere ha ozi — enweghị subroute kwa id na codebase ahụ.
---
## Nkwụsi ike (gbasatụrụ)
OmniRoute na-enye usoro atọ nọọrọ onwe ha maka ọdịda nwa oge; ebe njikwa ndị dị n'okpuru na-enye ndị na-ahụ maka sistemụ ohere ịgụ ma gbanwee ha:
| Oke | Ebe a na-echekwa steeti | Ịgụ | Tọgharịa / hichapụ |
| ------------------- | --------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------- |
| Ihe nkwụsị provider | `domain_circuit_breakers` + ebe nchekwa | `/api/monitoring/health` | `POST /api/resilience/reset` |
| Oge nchere njikọ | `rateLimitedUntil` na njikọ provider | `/api/rate-limits`, `/api/providers/[id]` | (na-emegharị onwe ya mgbe e mesịrị; hichapụ site na provider PUT) |
| Mkpọchi model | Ndebanye nnweta model dị na ebe nchekwa | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` |
`PATCH /api/resilience` na-anabata mgbanwe ihe nkwụsị provider n'okpuru `providerBreaker.oauth` na `providerBreaker.apikey`. Profaịlụ ọ bụla na-akwado `degradationThreshold`, `failureThreshold`, na `resetTimeoutMs`; a na-egosikwa otu mpaghara ndị a na Dashboard → Settings → Resilience.
```bash
# Hichapụ mkpọchi otu model
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"}'
# Hichapụ mkpọchi niile
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-d '{"all":true}'
```
Maka ntụaka echiche zuru ezu na ụkpụrụ ndabara nke ihe nkwụsị: lee [`CLAUDE.md`](../../CLAUDE.md) → "Steeti Oge Ọrụ nke Nkwụsi Ike".
---
## Nkà
Usoro nkà maka iji njikwa a haziri ahazi nke enwere ike imepụta gbasaa OmniRoute, tinyere njikọ ahịa.
| Usoro | Ụzọ | Nkọwa |
| ------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/skills` | Depụta nkà arụnyere — enwere ike iji `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local` nyochaa ya, ma kewaa ya na peeji |
| GET | `/api/skills/[id]` | Nweta otu nkà |
| PUT | `/api/skills/[id]` | Melite nkà (aha, nkọwa, ọnọdụ, schema, njikwa, mkpado) |
| DELETE | `/api/skills/[id]` | Wepụ nkà arụnyere |
| POST | `/api/skills/install` | Wụnye nkà site na manifest raw — body: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
| GET | `/api/skills/executions` | Depụta arụmọrụ nkà ndị mere nso nso a (ndekọ nyocha nwere ntinye/mmepụta/ogologo oge) |
| GET | `/api/skills/marketplace?q=...` | Chọọ/depụta ihe ndị ewu ewu site n'ahịa SkillsMP (chọrọ ntọala `skillsmpApiKey`) |
| POST | `/api/skills/marketplace/install` | Wụnye nkà site na SkillsMP site na id |
| GET | `/api/skills/skillssh?q=&limit=` | Chọọ n'akwụkwọ ndebanye skills.sh |
| POST | `/api/skills/skillssh/install` | Wụnye nkà site na skills.sh site na id |
**Nyocha ikike:** nnọkọ njikwa/igodo API. Ụzọ ọchụchọ ahịa na-anabata ma nyocha ikike njikwa ma ọ bụ igodo API Bearer (`isAuthenticated`).
---
## Ncheta
Ebe nchekwa ncheta mkparịta ụka/eziokwu na-adịgide adịgide, nke e kewara dịka API key / session si dị.
| Method | Path | Description |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/memory` | Depụta ncheta — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, yana nhazi ibe site na `offset/limit` ma ọ bụ `page/limit` |
| POST | `/api/memory` | Mepụta ncheta — Zod na-enyocha body: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET | `/api/memory/[id]` | Nweta otu ncheta |
| DELETE | `/api/memory/[id]` | Hichapụ ncheta |
| GET | `/api/memory/health` | Ọnọdụ ahụike nke usoro nta ncheta (njikọ DB, backend embeddings, ọnọdụ vector index) |
**Nyocha ikike:** management session/API key (`requireManagementAuth`). Enum `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (lee `MemoryType` na `src/lib/memory/types.ts`).
---
## Sava MCP
OmniRoute na-abịa na sava Model Context Protocol agbakwunyere nke nwere ụzọ mbufe 3 (stdio, SSE, streamable-http) na ngwaọrụ e kenyere oke. Endpoint dashboard ndị dị n'okpuru na-agụ data ọnọdụ/nyocha ma na-eme proxy maka ụzọ mbufe HTTP.
| Method | Path | Description |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Heartbeat, ụzọ mbufe, ọnọdụ online, oku ikpeazụ, ngwaọrụ kachasị eji, ọnụego ihe ịga nke ọma n'ime awa 24 |
| GET | `/api/mcp/tools` | Ndepụta ngwaọrụ MCP nwere `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
| GET | `/api/mcp/sse` | Mepee iyi SSE maka ụzọ mbufe SSE (na-eweghachi `503` ma ọ bụrụ na agbanyụghị MCP ma ọ bụ na ụzọ mbufe adabaghị) |
| POST | `/api/mcp/sse` | Zipụ fremụ JSON-RPC site n'ụzọ mbufe SSE |
| GET | `/api/mcp/stream` | Mepee akụkụ SSE nke ụzọ mbufe Streamable HTTP (ozi sava malitere) |
| POST | `/api/mcp/stream` | Zipụ fremụ JSON-RPC site n'ụzọ mbufe Streamable HTTP |
| DELETE | `/api/mcp/stream` | Kwụsị session Streamable HTTP |
| GET | `/api/mcp/audit` | Jụọ ndekọ nyocha — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | Chịkọta ọnụ ọgụgụ nyocha (ngụkọta, ọnụego ihe ịga nke ọma, nkezi oge, ngwaọrụ kachasị eji) |
**Nyocha ikike:** ụzọ mbufe `sse`/`stream` na-agbaso usoro nyocha ikike pụrụ iche nke MCP (Bearer API key nwere scope `mcp`); enwere ike ịgụ route `status`/`tools`/`audit*` site na dashboard (ọ dịghị nyocha ikike ọzọ achọrọ ma e wezụga inwe ike iru host dashboard).
> `settings.mcpEnabled` na `settings.mcpTransport` na-achịkwa ụzọ mbufe HTTP abụọ ahụ — ụzọ mbufe na-adabaghị na-eweghachi `400`, ebe ọnọdụ MCP agbanyụghị na-eweghachi `503`.
---
## Sava A2A
OmniRoute na-ewepụta endpoint A2A (Agent-to-Agent) JSON-RPC 2.0 yana ihe mkpuchi REST maka nyocha/ojiji dashboard.
### JSON-RPC
```bash
POST /a2a
Authorization: Bearer your-api-key # nhọrọ ma ọ bụrụ na edoghị 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"}]
}
}
```
Ụzọ ndị akwadoro (ha niile dabere na `settings.a2aEnabled`):
| Ụzọ | Nkọwa |
| ---------------- | --------------------------------------------------------------- |
| `message/send` | Mmezu nka n'otu oge; na-eweghachi `{task, artifacts, metadata}` |
| `message/stream` | Mmezu SSE na-asọba nke otu nchịkọta nka ahụ |
| `tasks/get` | Were ọrụ site na `taskId` |
| `tasks/cancel` | Kagbuo ọrụ site na `taskId` |
Nka ndị etinyere n'ime ya: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.
### Kaadị Agent
```bash
GET /.well-known/agent.json
```
Na-eweghachi kaadị agent A2A ọhaneze (aha, nkọwa, ikike, katalọgụ nka, usoro auth) — a na-echekwa ya n'ihu ọha ruo 1h. Achọghị auth.
### Ndị enyemaka REST
| Ụzọ | Path | Nkọwa |
| ---- | ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
| GET | `/api/a2a/status` | A2A agbanyere + ọnụ ọgụgụ ọrụ + nchịkọta kaadị agent echekwara |
| GET | `/api/a2a/tasks` | Depụta ọrụ — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST | `/api/a2a/tasks` | (Emebeghị ya dịka onye enyemaka REST — mepụta site na JSON-RPC `message/send`) |
| GET | `/api/a2a/tasks/[id]` | Nweta otu ọrụ |
| POST | `/api/a2a/tasks/[id]/cancel` | Kagbuo ọrụ |
**Auth:** ndị enyemaka REST na-arụ ọrụ na-enweghị auth njikwa (dashboard nwere ike ịgụ ha); ụzọ JSON-RPC `/a2a` na-eji Bearer `OMNIROUTE_API_KEY` ma ọ bụrụ na ahaziri ya.
---
## Cloud, Evals & Assess
| Ụzọ | Path | Nkọwa |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Nyochaa igodo Bearer ma weghachi njikọ provider ndị ezoro akụkụ ha + aha nnọchi model maka ndị ahịa cloud sync |
| POST | `/api/cloud/credentials/update` | Melite credentials ezoro ezo maka provider e jikọrọ na cloud |
| POST | `/api/cloud/model/resolve` | Jiri tebụl routing mpaghara tụgharịa logical model id ka ọ bụrụ provider/model a kapịrị ọnụ |
| GET | `/api/cloud/models/alias` | Depụta aha nnọchi model dịka e si kpughee ha nye cloud sync |
| GET | `/api/assess` | Gụọ nhazi assessment kachasị ọhụrụ (maka provider/model nke ọ bụla) |
| POST | `/api/assess` | Mee assessment — body: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Depụta eval suites ndị etinyere n'ime ya + mmezu ndị kachasị ọhụrụ |
| POST | `/api/evals` | Kpalite mmezu eval |
| POST | `/api/evals/suites` | Mepụta eval suite ahaziri iche — a na-eji `evalSuiteSaveSchema` enyocha body |
| GET | `/api/evals/suites/[id]` | Nweta eval suite ahaziri iche |
**Auth:** `/api/cloud/auth` na-enyocha igodo Bearer ozugbo; ụzọ `/api/cloud/*`, `/api/evals/*`, na `/api/assess` ndị ọzọ chọrọ session njikwa/API key. POST `/api/assess` na-eji `validateBody` yana schema scope nke discriminated-union.
---
## Nchịkwa ACP (Agent Client Protocol)
dị ka usoro ụmụ. Ebe njedebe ndị a na-ahụ maka nchọpụta ndị nnọchi anya ACP na ndebanye aha ndị nnọchi anya ahaziri iche.
| Usoro | Ụzọ | Nkọwa |
| ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/acp/agents` | Depụta ndị nnọchi anya CLI niile a maara (ndị arụnyere n'ime ya + ndị ahaziri iche), tinyere ọnọdụ nrụnye, ụdị, na faịlụ binary |
| POST | `/api/acp/agents` | Debanye aha onye nnọchi anya ACP ahaziri iche ma ọ bụ mee ka cache dị ọhụrụ — body: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` ma ọ bụ `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Wepụ onye nnọchi anya ACP ahaziri iche — query param: `?id=<agentId>` |
**Ọmụmaatụ nzaghachi** (`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
}
```
**Nkwenye njirimara:** Ọ chọrọ nnọkọ njikwa (dashboard `auth_token` cookie) ma ọ bụ igodo API nwere ikike njikwa.
Lee [Usoro ACP](../frameworks/ACP.md) maka nkọwa zuru ezu.
---
## Nnyocha Data & Nlele Ọnọdụ
Ebe njedebe nnyocha data ozugbo maka nyochaa ntụgharị ụzọ, mkpakọ, na ụdịdị dị iche iche nke ndị na-eweta ọrụ. Ndị a na-akwado peeji `/dashboard/analytics/*`.
### Nnyocha data ntụgharị ụzọ akpaaka
| Usoro | Ụzọ | Nkọwa |
| ----- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/auto-routing` | Nchịkọta ọnụ ọgụgụ ntụgharị ụzọ akpaaka: oku niile, nkesa atụmatụ, nkesa ọkwa, ndị na-eweta ọrụ kachasị elu |
| GET | `/api/analytics/auto-routing?days=7` | Ọnụ ọgụgụ dabere na windo oge (ndabara bụ awa 24) |
**Ọmụmaatụ nzaghachi**:
```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 }
]
}
```
### Nnyocha data mkpakọ
| Usoro | Ụzọ | Nkọwa |
| ----- | ---------------------------- | ------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/compression` | Nchịkọta ọnụ ọgụgụ mkpakọ: token echekwara, pasent ego echekwara, nkesa ọnọdụ, ojiji engine |
**Ọmụmaatụ nzaghachi**:
```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
}
}
```
### Nsuso ụdịdị dị iche iche nke ndị na-eweta ọrụ
| Usoro | Ụzọ | Nkọwa |
| ----- | -------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/diversity` | Nsuso ụdịdị dị iche iche dabere na entropy Shannon: na-egbochi otu ebe ọdịda site n'ịtụ mgbasa nke ndị na-eweta ọrụ |
**Ọmụmaatụ nzaghachi**:
```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"]
}
```
**Nkwenye njirimara:** Ọ chọrọ nnọkọ njikwa ma ọ bụ igodo API nwere ikike njikwa.
---
## Ọrụ Nchịkwa
Ebe njedebe ndị naanị onye nchịkwa nwere ike iji maka njikwa ọrụ.
| Usoro | Ụzọ | Nkọwa |
| ----- | ------------------------ | --------------------------------------------------------------------------------------- |
| GET | `/api/admin/concurrency` | Gụọ oke concurrency dị ugbu a (nke zuru ụwa ọnụ + nke onye na-eweta ọ bụla) |
| POST | `/api/admin/concurrency` | Melite oke concurrency — ahụ: `{global?: number, perProvider?: Record<string, number>}` |
**Nyocha ikike:** Chọrọ nnọkọ njikwa nwere ikike onye nchịkwa.
---
## Njikwa Ngwaọrụ CLI
Jikwaa ngwaọrụ CLI ndị na-ejikọta na OmniRoute (antigravity, chipotle, commandCode,
devin-cli, wdg.). Lee [Ntụaka Onye Na-eweta](./PROVIDER_REFERENCE.md) maka ndepụta zuru ezu.
| Usoro | Ụzọ | Nkọwa |
| ----- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/cli-tools/all-statuses` | Ọnọdụ ngwaọrụ CLI niile (arụnyere, ụdị, oge ikpeazụ a hụrụ ya) |
| GET | `/api/cli-tools/status` | Nkọwa ọnọdụ maka otu ngwaọrụ CLI (ajụjụ `?tool=`) |
| POST | `/api/cli-tools/apply` | Dee config e mepụtara maka ngwaọrụ (`dryRun` na-egosi ihe ga-apụta; `422` + `containerEphemeralTarget` mgbe ọ nọ na container; `migration` na-akọwa Codex YAML ochie) |
| GET | `/api/cli-tools/backups` | Depụta nkwado ndabere config ngwaọrụ CLI |
| POST | `/api/cli-tools/backups` | Mepụta nkwado ndabere nke config ngwaọrụ CLI niile |
| POST | `/api/cli-tools/backups` | Weghachite: otu ebe njedebe ahụ nwere `{tool, backupId}` n'ahụ na-eweghachite nkwado ndabere ahụ |
| GET | `/api/cli-tools/antigravity-mitm` | Ọnọdụ proxy Antigravity MITM (ngwaọrụ CLI "antigravity-mitm") |
| POST | `/api/cli-tools/antigravity-mitm/alias` | Hazie aha nnọchi antigravity-mitm |
**Nyocha ikike:** Chọrọ nnọkọ njikwa.
---
## Nkà Ndị Nnọchi Anya
Jikwaa nkà ndị nnọchi anya AI (dị ka GPT ahaziri iche nke OpenAI, mana maka ndị nnọchi anya).
| Usoro | Ụzọ | Nkọwa |
| ------ | ---------------------------- | --------------------------------------------------------------------------------------------------- |
| GET | `/api/agent-skills` | Depụta nkà ndị nnọchi anya niile (nke arụnyere n'ime + nke ahaziri iche) |
| GET | `/api/agent-skills/[id]` | Nweta otu nkà onye nnọchi anya kpọmkwem |
| POST | `/api/agent-skills` | Mepụta nkà onye nnọchi anya ahaziri iche — ahụ: `{name, description, prompt, model?, temperature?}` |
| PUT | `/api/agent-skills/[id]` | Melite nkà onye nnọchi anya ahaziri iche |
| DELETE | `/api/agent-skills/[id]` | Hichapụ nkà onye nnọchi anya ahaziri iche |
| GET | `/api/agent-skills/[id]/raw` | Nweta prompt nke mbụ + metadata (enweghị mmezu) |
| POST | `/api/agent-skills/generate` | Jiri AI mepụta nkà ọhụrụ site na nkọwa e dere n'asụsụ mmadụ |
**Nyocha ikike:** Chọrọ nnọkọ njikwa ma ọ bụ igodo API nwere ikike njikwa.
---
## Njikwa Cache
Jikwaa cache semantic na cache ntụgharị uche.
| Method | Path | Nkọwa |
| ------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/cache` | Nchịkọta cache: ngụkọta ndenye, ọnụego hit, nha dị na diski |
| GET | `/api/cache/entries` | Depụta ndenye ndị dị na cache (ya na pagination) |
| DELETE | `/api/cache/entries` | Hichapụ ndenye cache (jiri query parameters nyochaa) |
| GET | `/api/cache/stats` | Nkọwa ọnụ ọgụgụ cache zuru ezu (maka provider ọ bụla, maka model ọ bụla) |
| GET | `/api/cache/reasoning` | Ọnọdụ cache ntụgharị uche (maka ịkpọgharị ntụgharị uche) |
| DELETE | `/api/cache/reasoning` | Hichapụ cache ntụgharị uche — query params: `?toolCallId=<id>` (otu) ma ọ bụ `?provider=<p>` ma ọ bụ enweghị params (niile) |
**Nkwenye:** Chọrọ session njikwa.
---
## Sistemụ Ncheta
Jikwaa ncheta na-adịgide adịgide (FTS5 + vector embeddings).
| Method | Path | Nkọwa |
| ------ | ------------------ | ---------------------------------------------------------------------- |
| GET | `/api/memory` | Depụta ndenye ncheta (jiri scope, type, search query nyochaa) |
| POST | `/api/memory` | Mepụta ndenye ncheta ọhụrụ — body: `{scope, type, content, metadata?}` |
| GET | `/api/memory/[id]` | Nweta otu ndenye ncheta akọwapụtara |
| PUT | `/api/memory/[id]` | Melite otu ndenye ncheta |
| DELETE | `/api/memory/[id]` | Hichapụ otu ndenye ncheta |
| GET | `/api/memory?q=` | Chọọ n'ime ncheta (FTS5 + vector) — agụnyere stats na response ahụ |
**Nkwenye:** Chọrọ session njikwa ma ọ bụ API key nwere scope njikwa.
---
## Webhooks
Jikwaa ndebanye webhook maka events.
| Method | Path | Nkọwa |
| ------ | ------------------------------- | ------------------------------------------------------------------- |
| GET | `/api/webhooks` | Depụta ndebanye webhook niile |
| POST | `/api/webhooks` | Mepụta ndebanye webhook — body: `{url, events[], secret?, active?}` |
| GET | `/api/webhooks/[id]` | Nweta otu ndebanye webhook akọwapụtara |
| PUT | `/api/webhooks/[id]` | Melite otu ndebanye webhook |
| DELETE | `/api/webhooks/[id]` | Hichapụ otu ndebanye webhook |
| GET | `/api/webhooks/[id]/deliveries` | Depụta akụkọ delivery maka webhook (ndekọ ihe ịga nke ọma/ọdịda) |
| POST | `/api/webhooks/[id]/test` | Ziga test event na webhook |
**Nkwenye:** Chọrọ session njikwa.
Lee [Framework Webhooks](../frameworks/WEBHOOKS.md) maka ụdị event niile.
---
## Usoro Skills
Jikwaa Skills (usoro ndọtị agentic).
| Usoro | Ụzọ | Nkọwa |
| ------ | ------------------------ | ----------------------------------------------------------------------------------------- |
| GET | `/api/skills` | Depụta skills niile arụnyere (ndị e wuru n'ime ya + ndị ahaziri iche) |
| POST | `/api/skills/install` | Wụnye skill site n’ụzọ mpaghara ma ọ bụ URL |
| DELETE | `/api/skills/[id]` | Wepụ skill arụnyere |
| PUT | `/api/skills/[id]` | Gbanye ma ọ bụ gbanyụọ skill — ahụ: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST | `/api/skills/executions` | Mee skill — ahụ: `{skillName, apiKeyId, input?, sessionId?}` |
| GET | `/api/skills/executions` | Depụta akụkọ mmezu maka skills niile (jiri `?apiKeyId=` nyochaa) |
**Nkwenye njirimara:** Ọ chọrọ nnọkọ njikwa ma ọ bụ API key nwere ikike njikwa.
Lee [Usoro Skills](../frameworks/SKILLS.md) maka nkọwa zuru ezu.
---
## Plugins
Jikwaa plugins OmniRoute (ndọtị ndị ọzọ mepụtara).
| Usoro | Ụzọ | Nkọwa |
| ------ | ---------------------------------- | ------------------------ |
| GET | `/api/plugins` | Depụta plugins arụnyere |
| POST | `/api/plugins/marketplace/install` | Wụnye plugin site n’ahịa |
| DELETE | `/api/plugins/[name]` | Wepụ plugin arụnyere |
| POST | `/api/plugins/[name]/activate` | Mee ka plugin rụọ ọrụ |
| POST | `/api/plugins/[name]/deactivate` | Kwụsị plugin ịrụ ọrụ |
| GET | `/api/plugins/[name]/config` | Nweta nhazi plugin |
| PUT | `/api/plugins/[name]/config` | Melite nhazi plugin |
**Nkwenye njirimara:** Ọ chọrọ nnọkọ njikwa.
Lee [Usoro Plugins](../frameworks/PLUGIN_SDK.md) maka nkọwa zuru ezu.
---
## Shadow Routing
Ntụnyere Shadow / A-B nke providers **abụghị REST surface kwụụrụ onwe ya** — a na-ahazi ya site na combo routing (lee [Auto-Combo](../routing/AUTO-COMBO.md)). A na-enye metrik ntụnyere nke combo ọ bụla site na `GET /api/combos/metrics`.
---
## Guardrails
Nyochaa guardrails nke runtime (nchọpụta PII, nchọpụta prompt injection, vision bridging). Guardrails na-arụ ọrụ na arịrịọ ọ bụla; ịpụ na ya maka otu ọkpụkpọ bụ site na request header `x-omniroute-disabled-guardrails` — enweghị ebe echekwara maka ịgbanye/ịgbanyụọ ya.
| Usoro | Ụzọ | Nkọwa |
| ----- | ---------------------- | ------------------------------------------------------------------------------------------------ |
| GET | `/api/guardrails` | Depụta guardrails ndị e debanyere aha na ọnọdụ ha (aha / agbanyere / mkpa) |
| POST | `/api/guardrails/test` | Mee nnwale akọrọ nke pipeline tupu ọkpụkpọ n’elu input atụ — ahụ: `{input, disabledGuardrails?}` |
**Nkwenye njirimara:** Ọ chọrọ nnọkọ njikwa.
Lee [Nchekwa > Guardrails](../security/GUARDRAILS.md) maka nkọwa zuru ezu.
---
---
## Nkwenye njirimara
Lee [Nkwenye Njirimara Njikwa](../guides/MANAGEMENT-AUTH.md) maka ezinụlọ nzere anọ ahụ (nnọkọ dashboard, token CLI mpaghara, Token Nnweta `oma_live_…`, API key nwere oke njikwa) na etu ha si dị iche na igodo inference.
- Ụzọ dashboard (`/dashboard/*`) na-eji kuki `auth_token`
- Nbanye na-eji hash okwuntughe echekwara; ma ọ bụrụ na nke ahụ ada, ọ na-eji `INITIAL_PASSWORD`
- Enwere ike ịgbanwuo `requireLogin` site na `/api/settings/require-login`
- Ụzọ `/v1/*` nwere ike ịchọ Bearer API key mgbe `REQUIRE_API_KEY=true`
- “token njikwa” / “API key nwere oke njikwa” n'ime ntụaka a pụtara otu n'ime ezinụlọ ndị dị na ntuziaka ahụ — ọ bụghị ụdị nzuzo ọzọ a na-akọwaghị
> **Mgbanwe na-emebi ndakọrịta (v3.8.0)** — `/api/v1/agents/tasks/*` na endpoint njikwa cooldown chọrọzi **nkwenye njirimara njikwa** (kuki dashboard `auth_token` ma ọ bụ API key nwere oke njikwa). Ndị ahịa kpọburu ụzọ ndị a na-enweghị nkwenye njirimara ga-enweta `401 Unauthorized`. Lee commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).
Reference in New Issue View Git Blame Copy Permalink