# API Reference (Filipino) 🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇱 [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) --- 🌐 **Mga Wika:** 🇺🇸 [English](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md) Pangunahing sanggunian para sa OmniRoute API. Saklaw nito ang pampublikong `/v1` surface at ang mga pinakamadalas gamiting endpoint sa pamamahala; ang nababasa ng makina na [`docs/openapi.yaml`](../openapi.yaml) at ang route tree sa ilalim ng `src/app/api/` ang mga kumpletong sanggunian. --- ## Talaan ng mga Nilalaman - [Mga Chat Completion](#chat-completions) - [Eksklusibong mga Lease ng Pinamamahalaang Session](#exclusive-managed-session-leases) - [Mga Embedding](#embeddings) - [Pagbuo ng Larawan](#image-generation) - [OCR ng Dokumento](#document-ocr) - [Listahan ng mga Modelo](#list-models) - [Manifest ng Provider Plugin](#provider-plugin-manifest) - [Mga Endpoint ng Compatibility](#compatibility-endpoints) - [Files API](#files-api) - [Batches API](#batches-api) - [Search API](#search-api) - [WebSocket Streaming](#websocket-streaming) - [Pag-uulat ng mga Quota at Isyu](#quotas--issues-reporting) - [Semantic Cache](#semantic-cache) - [Dashboard at Pamamahala](#dashboard--management) - [Pamamahala ng Combo](#combo-management) - [Mga Webhook](#webhooks) - [Mga Nakarehistrong Key (Awtomatikong Pamamahala)](#registered-keys-auto-management) - [Protocol ng mga Agent](#agents-protocol) - [Mga Proxy sa Pamamahala](#management-proxies) - [Katatagan (pinalawak)](#resilience-extended) - [Mga Skill](#skills) - [Memory](#memory) - [MCP Server](#mcp-server) - [A2A Server](#a2a-server) - [Cloud, mga Eval at Assess](#cloud-evals--assess) - [Pagproseso ng Request](#request-processing) - [Authentication](#authentication) --- ## Mga Chat Completion ```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 } ``` ### Mga Custom Header | Header | Direksyon | Paglalarawan | | ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `X-OmniRoute-No-Cache` | Request | Itakda sa `true` upang lampasan ang cache | | `x-omniroute-no-memory` | Request | Itakda sa `true` upang laktawan ang pag-inject ng memory + skills para sa request na ito (tumutulad sa no-cache; iniiwasan ang overhead sa token/gastos sa bawat call) | | `X-OmniRoute-Progress` | Request | Itakda sa `true` para sa mga event ng progreso | | `X-Session-Id` | Request | Sticky session key para sa external session affinity | | `x_session_id` | Request | Tinatanggap din ang variant na may underscore (direktang HTTP) | | `X-OmniRoute-Session-Id` | Request | Tag ng session/conversation na ibinigay ng caller (ginagamit din ng memory). Kapag mayroon, pinapanatili nang eksakto sa `call_logs.session_tag` para sa pag-uugnay ng gastos sa bawat session (#8249) — hindi kailanman binubuo kapag wala | | `Idempotency-Key` | Request | Dedup key (5s na palugit) | | `X-Request-Id` | Request | Alternatibong dedup key | | `X-OmniRoute-Cache` | Response | `HIT` o `MISS` (hindi streaming) | | `X-OmniRoute-Idempotent` | Response | `true` kung na-deduplicate | | `X-OmniRoute-Progress` | Response | `enabled` kung naka-on ang pagsubaybay sa progreso | | `X-OmniRoute-Session-Id` | Response | Epektibong session ID na ginamit ng OmniRoute | | `X-OmniRoute-Request-Id` | Response | ID para sa pag-uugnay ng request (kapag nalalaman) | | `X-OmniRoute-Version` | Response | Bersyon ng build ng OmniRoute (laging naroroon) | | `X-OmniRoute-Cost-Saved` | Response | Halagang USD na naiwasang gastusin dahil sa cache sa isang HIT (mga cache hit lamang) | | `X-OmniRoute-Decision` | Response | Bakas ng routing: `strategy=; provider=; latency_ms=` (ang `` ay ang combo strategy, o `single` para sa request na hindi combo) — laging naroroon sa mga completion response | > Paalala tungkol sa Nginx: kung umaasa ka sa mga header na may underscore (halimbawa, `x_session_id`), i-enable ang `underscores_in_headers on;`. > **Mga header ng telemetry ng gastos:** kasama rin sa mga matagumpay na tugon na hindi streaming ang hanay ng telemetry ng gastos na `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, nakapirming 10 decimal; `0.0000000000` para sa libre/walang presyo), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit`, at `X-OmniRoute-Fallback-Attempts` (kapag > 0 lamang), kasama ang `X-OmniRoute-Request-Id` at `X-OmniRoute-Version`. Inilalabas ang mga ito ng mga chat completion, `/v1/responses`, `/v1/messages`, **at ng mga media endpoint** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations`, at `/v1/moderations` (palaging `0` ang gastos). Kinakalkula ang gastos sa media ayon sa bawat modality (bawat larawan, bawat segundo, bawat character, bawat search-unit) kapag may available na pagpepresyo; kung wala, `0` ito (fail-open). > **Semantika ng gastos sa cache hit:** sa isang HIT ng semantic cache (`X-OmniRoute-Cache-Hit: true`), walang ginagawang upstream call, kaya ang `X-OmniRoute-Response-Cost` ay `0.0000000000` (ang **karagdagang** gastos sa paghahatid ng hit). Hiwalay na iniuulat sa `X-OmniRoute-Cost-Saved` ang orihinal/gastos na sana ay natamo. Dapat pagsamahin ng mga consumer ng billing ang `X-OmniRoute-Response-Cost` (walang gastos ang mga hit); maaaring pagsama-samahin ng cache analytics ang `X-OmniRoute-Cost-Saved`. ## Mga Eksklusibong Pinamamahalaang Lease ng Session Ang eksklusibong pinamamahalaang pag-lease ng session ay isang opt-in at client-neutral na kontrata sa pagruruta: isang aktibong may-ari ang humahawak sa isang kwalipikadong koneksyon ng OmniRoute. Hindi ito nagle-lease ng modelo, nangangailangan ng OAuth, tumutukoy sa partikular na client, o nangangailangan ng partikular na provider. Ang API key na ginagamit sa pagpapatotoo ay dapat may scope na `lease:exclusive` at tahasang hindi bakanteng listahan ng `allowedConnections`. Magkasamang ipinapatupad ng hangganan ng mutation sa database ang dalawang field kapag gumagawa ng key at nagsasagawa ng mga bahagyang update. ```http POST /api/v1/session-leases Authorization: Bearer Content-Type: application/json X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> {"action":"acquire","model":"glm/glm-4.6"} ``` Inilalantad ng matagumpay na mga tugon sa pagkuha, pag-renew, at pag-release ang mga timestamp, `state`, at ang eksaktong positibong `generation`, ngunit hindi kailanman ang napiling koneksyon o mga kredensyal. Ibinibigay ng pag-renew at pag-release ang generation sa JSON body: ```json { "action": "renew", "generation": 1 } ``` ```json { "action": "release", "generation": 1, "reason": "OWNER_EXIT" } ``` Maaaring tahasang humiling ang aktibong may-ari ng lease ng metadata sa pagpapakita na ligtas sa privacy para sa kasalukuyan nitong binding: ```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" } } ``` Ang opt-in na status action na ito ay nililimitahan ng opaque na may-ari, napatotohanang pinamamahalaang API key, at eksaktong aktibong generation sa iisang transaksyon sa database. Ang `displayName` ay ang naka-trim na naka-configure na pangalan lamang ng koneksyon; ito ay `null` kapag walang umiiral na ligtas at naka-configure na pangalan. Hindi kailanman ipinapalit ng OmniRoute ang isang email o nabuong pagkakakilanlan ng account. Ang value ng provider ay isang hindi sensitibong label sa pagpapakita at hindi kailanman isang nabuong identifier ng compatible provider. Hindi kasama ang mga kredensyal, token, cookie, raw na koneksyon o mga API key id, mga hash ng may-ari, mga fencing secret, at panloob na data sa pagruruta. Ang mga lookup na may maling key, maling may-ari, lipas na generation, nawawala, nag-expire, na-release, at napawalang-bisa ay pawang nagbabalik ng parehong error na `409 LEASE_FENCE_STALE` nang walang metadata ng koneksyon. Ang client na nakatanggap ng tugon para sa paghihintay ng kapasidad ay walang aktibong binding na maaaring siyasatin. Kapag inililipat ng pagruruta ang isang aktibong lease, nananatiling valid ang parehong generation at atomikong ibinabalik ng status ang bagong binding, at hindi kailanman ang luma. Nananatiling hindi nagbabago ang mga umiiral na client dahil pinananatili ng mga tugon sa pagkuha, pag-renew, pag-release, at paghihintay ang dati nilang mga anyo. Hindi binabago ng kontratang ito ng server ang stock na OpenAI Codex `/status`. Kasalukuyang iniuulat ng stock na Codex ang model provider nito at built-in na estado ng pagpapatotoo/account ngunit hindi nito nire-render ang arbitraryong metadata ng account ng custom provider; dapat tawagin ng isang integrasyon ng client sa hinaharap ang action na ito at magpasya kung paano ipapakita ang `connection.displayName`. Pagkatapos, ibinibigay ng bawat pinamamahalaang kahilingan sa inference ang parehong control header: ```http X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> X-OmniRoute-Lease-Generation: 1 ``` Kaagad na nililimitahan ang eksaktong may-ari, generation, aktibong koneksyon, at napatotohanang API key bago ang bawat sinusuportahang upstream na pagtatangka. Nabibigo ang muling paggamit sa may-ari at generation gamit ang ibang key kahit pinapahintulutan ng key na iyon ang parehong koneksyon. Hindi pine-persist, nila-log, pinananatili sa snapshot ng kahilingan, o ipinapasa upstream ang mga raw na may-ari. Ang pansamantalang kompetisyon sa kapasidad ay nagbabalik ng HTTP `429` na may `Retry-After` at: ```json { "state": "WAITING_FOR_CAPACITY", "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" }, "reason": "NO_FREE_ELIGIBLE_CONNECTION", "retryAfter": 30 } ``` Nangangahulugan lamang ang tugon na ito na hindi bakante ang karaniwang hanay ng mga kwalipikadong koneksyon at ang bawat libreng kandidato ay hawak ng aktibong lease ng ibang may-ari. Pinananatili ng mga hindi sinusuportahang modelo/provider, hindi pagtutugma ng patakaran, cooldown, quota, kalagayan, at iba pang karaniwang pagkabigo sa pagiging kwalipikado ang kanilang mga umiiral na tugon ng OmniRoute. ### `x-omniroute-compression` Override ng compression plan sa bawat kahilingan. Ito ang may pinakamataas na precedence—nangingibabaw sa override ng routing-combo, aktibong profile, auto-trigger, at Default ng panel. Mga value: | Value | Epekto | | ------------- | ---------------------------------------------------------------------------------------------------------- | | `off` | Walang compression para sa kahilingang ito. | | `default` | Ang Default profile na nagmula sa panel (binabalewala ang aktibong profile). | | `engine:` | Isang engine kapag naka-enable, hal. `engine:rtk`. | | `` | Isang pinangalanang combo, unang itinutugma ayon sa pangalan (case-insensitive), pagkatapos ay ayon sa id. | Mga tala: - Binabalewala ang mga hindi kilalang value (hindi kailanman tinatanggihan ang kahilingan); babalik ang resolution sa normal na precedence ng operator. - Kung magkakapareho ang pangalan ng maraming combo, ipasa ang **id** ng combo para sa deterministikong pagtutugma. - Hindi maaaring piliin ayon sa pangalan ang isang combo na may pangalang `off` o `default` (unang binibigyang-kahulugan ang mga keyword na iyon); tukuyin ang ganitong combo gamit ang id nito. - Ang pangunahing switch ng compression ay isang mahigpit na gate: kapag naka-disable ang compression sa pangkalahatan, hindi ito maaaring i-enable ng header na ito. Ibinabalik sa response header ang inilapat na plan: ``` X-OmniRoute-Compression: ; source= ``` kung saan ang `` ay isa sa `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, o `off`. --- ## Mga Embedding ```bash POST /v1/embeddings Authorization: Bearer your-api-key Content-Type: application/json { "model": "nebius/Qwen/Qwen3-Embedding-8B", "input": "The food was delicious" } ``` Mga available na provider: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI. Ang mga catalog id ay `provider/model` (halimbawa: `jina-ai/jina-embeddings-v5-omni-small`). Nalulutas din ang mga bare na Jina model id na lumalabas sa registry (halimbawa, `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`). Ginagamit muna ng Jina embed/rerank/classify/segment ang mga credential na `jina-ai` sa dashboard; fallback lamang ang `JINA_AI_API_KEY` kapag walang dashboard key. Ang `jina-reader` card ay para lamang sa Reader / `r.jina.ai` (`POST /v1/web/fetch`) at hindi kailanman naghahatid ng mga embedding o rerank. Ang mga registry model na nag-a-advertise ng multimodal support ay tumatanggap din ng hanggang 32 provider-neutral na structured item. Ang mga uri ng media item ay `text`, `image`, `audio`, `video`, at `document`. Ang kanilang media `source` ay alinman sa `{"type":"url","url":"https://..."}` o `{"type":"base64","data":"...","media_type":"..."}`. Ang Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`, at ang family alias na `jina-ai/jina-embeddings-v5-omni` → omni-small) ay tumatanggap din ng mga native na EmbeddingsV5Request doc ng Jina at **ipinapasa ang mga ito nang buo** sa `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,..." }] } ] } ``` Ang mga native na value na `{ image | audio | video | pdf }` ay maaaring pampublikong HTTPS URL, `data:` URI, o raw base64. Hindi ginagawang string ng OmniRoute ang mga object na iyon o kinukuha ang mga native na image URL — ang Jina mismo ang kumukuha ng pampublikong media. Ipinapasa ang mga karagdagang Jina field (`task`, `normalized`, `truncate`, `embedding_type`). Tinatanggihan pa rin ng mga text-only na Jina SKU ang mga doc na hindi text. Mga limitasyon sa seguridad at transport: - Dapat pampublikong HTTPS ang mga remote media URL. Kinukuha sa server-side ang mga canonical na `{type,source:url}` item (muling pag-validate ng redirect, timeout, mga limitasyon sa laki, pampublikong DNS, pag-pin ng koneksyon) at ini-inline bago ang provider call. Ang mga Jina-native na `{image:"https://..."}` item ay ipinapasa nang walang pagbabago pagkatapos ng parehong pagsusuri sa pampublikong HTTPS; kinukuha ng Jina ang URL. - Limitado sa 8 MiB na decoded data bawat item at 16 MiB na decoded data sa buong request ang inline base64 media. Pagsasalin para sa provider (ang mga canonical na item ay hindi kailanman ipinapasa nang walang pagbabago): - Mga Jina multimodal model: ang bawat top-level na item ay nagiging isang object na may key ayon sa modality (`text` / `image` / `audio` / `video` / `pdf`) gamit ang mga data URI para sa inline media; isang vector bawat top-level na item. - Pamilya ng Gemini Embedding 2: ang isang top-level na array ay nagiging iisang native na `models/{model}:embedContent` request na may `content.parts` (`text` o `inline_data`). - Tinatanggihan ng mga unknown/dynamic model na walang tahasang modality metadata ang structured input gamit ang 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" } ``` Nagbabalik ng HTTP 400 ang mga hindi suportadong kumbinasyon ng model/modality sa halip na i-coerce ang item. Ang mga non-input extension field sa mga legacy na string/token request ay patuloy na ipinapasa nang walang pagbabago. ```bash # Ilista ang lahat ng embedding model GET /v1/embeddings ``` --- ## Pagbuo ng Larawan ```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" } ``` Mga available na provider: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (lokal), ComfyUI (lokal). ```bash # Ilista ang lahat ng modelo ng larawan GET /v1/images/generations ``` --- ## OCR ng Dokumento ```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" } } ``` Pinipili ng `model` ang OCR provider sa pamamagitan ng prefix na `provider/model`; ang isang model id na walang prefix (hal. `mistral-ocr-latest`) ay iniuugnay sa nakarehistrong provider nito, at kung hindi ibinigay ang `model`, gagamitin bilang default ang Mistral (`mistral-ocr-latest`). Mga nakarehistrong provider (`open-sse/config/ocrRegistry.ts`): | Provider id | Model id | Value ng `model` | Mga Tala | | ----------------------------- | -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (o `mistral-ocr-latest` lamang) | Synchronous — direktang ibinabalik ang tugon mula sa iisang upstream call. | | `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Asynchronous na upstream (`analyze` + poll) — tingnan sa ibaba. | | `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Synchronous, sa pamamagitan ng partner endpoint na `openapi/chat/completions` ng Vertex AI — tingnan sa ibaba para sa auth/URL. | Tumutugon ang lahat ng tatlong provider gamit ang parehong body na may format ng Mistral: ```json { "pages": [{ "index": 0, "markdown": "# Extracted text..." }], "model": "mistral-ocr-latest", "usage_info": { "pages_processed": 1 } } ``` ### Daloy ng pag-poll sa Azure Document Intelligence Asynchronous ang `analyze` API ng Azure Document Intelligence: nagbabalik ang paunang request ng `Operation-Location` header sa halip na body, at kailangang paulit-ulit na i-poll ang resulta. Ang handler (`open-sse/handlers/ocr.ts`) ay nagpo-poll sa URL na iyon bawat segundo nang hanggang 30 pagtatangka, agad na nabibigo (hindi nagpapatuloy sa pag-poll) kapag may poll response na hindi `ok` o status na `"failed"`, at nagbabalik ng `504` kung tumatakbo pa rin ang operasyon matapos maubos ang nakalaang bilang ng pagtatangka. Ang panghuling tugon ng Azure ay ina-normalize sa parehong format na `pages`/`markdown` na ginagamit ng Mistral bago ito ibalik sa caller, kaya hindi kailangang magkaroon ng espesyal na pagproseso ang client code para sa provider. ### Authentication at endpoint resolution ng Vertex AI DeepSeek OCR Muling ginagamit ng `vertex-deepseek-ocr` ang parehong authentication ng Vertex AI na sinusuportahan na ng OmniRoute para sa traffic ng chat/larawan (`open-sse/executors/vertex.ts`): ang API key ng koneksyon ay maaaring isang Service Account JSON credential (ipinagpapalit para sa panandaliang OAuth access token sa pamamagitan ng JWT-bearer flow) o isang nagawa nang OAuth access token na ginagamit nang walang pagbabago. Ang upstream endpoint URL ay ang generic na partner endpoint na `openapi/chat/completions` ng Vertex, na binubuo mula sa project at region ng koneksyon — palaging nangingibabaw ang tahasang `providerSpecificData.project`/`providerSpecificData.region`; kung wala nito, kinukuha ang project mula sa `project_id` ng Service Account JSON at ang default na region ay `us-central1`. Isinasagawa ang parehong resolution sa `open-sse/handlers/ocr.ts` (`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`), na ginagamit ng `src/app/api/v1/ocr/route.ts` bago ipadala sa `handleOcr`. --- ## Ilista ang mga Modelo ```bash GET /v1/models Authorization: Bearer your-api-key → Ibinabalik ang lahat ng chat, embedding, at image model + mga combo sa format ng OpenAI ``` ### Mga prefix ng model id (`?prefix=`) Karamihan sa mga modelo ay inilalathala sa ilalim ng isang **provider prefix**. Ang prefix na makukuha mo ay kinokontrol ng `MODELS_CATALOG_PREFIX_MODE` feature flag, at maaaring i-override **sa bawat request** gamit ang isang query parameter — kapaki-pakinabang para sa client na nais ng malinis na listahan nang hindi binabago ang setting sa buong server para sa lahat: ```bash GET /v1/models?prefix=alias # isang id bawat modelo — ang maikling alias prefix GET /v1/models?prefix=dual # parehong anyo (default ng server) GET /v1/models?prefix=canonical # ang buong provider-id prefix lamang ``` | Mode | Inilalabas | Mga Tala | | ----------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dual` | `cc/claude-sonnet-4-6` **at** `claude/claude-sonnet-4-6` | **Default.** Parehong nagru-route ang dalawang id sa iisang modelo; pinanatili ito upang patuloy na gumana ang mga configuration ng client na naka-hardcode sa alinmang anyo. Halos dinodoble nito ang catalog. | | `alias` | `cc/claude-sonnet-4-6` | Isang entry bawat modelo. Inilalabas pa rin ng mga provider na walang natatanging alias ang kanilang entry, kaya walang nawawala. | | `canonical` | `claude/claude-sonnet-4-6` | Isang entry bawat modelo sa ilalim ng buong provider-id prefix. Inilalabas din dito ng mga provider na walang natatanging alias (hal. `antigravity/…`, `agy/…`) ang kanilang nag-iisang id, kaya walang nawawala. | Makikilala rin ang isang mirror na nasa `dual` mode kahit wala ang query parameter: mayroon itong `parent` field na tumuturo sa pangunahing id. Ang mga client na nagre-render ng model picker ay dapat humiling ng `?prefix=alias` — ito ang ginagawa ng [OmniCopilot VS Code extension](../guides/VSCODE-COPILOT.md). ### Mga variant ng modelo na walang thinking Para sa mga Claude model na may kakayahang mag-thinking, naglalathala rin ang `/v1/models` ng isang **no-thinking** variant na ang id ay may prefix na `claude-3-omniroute-no-thinking/`: ``` claude-3-omniroute-no-thinking// ``` Kapag pinili ang id na ito (hal. sa isang Claude Code config na palaging naglalakip ng `thinking` block), ibinabalik ito sa tunay na `/` nang naka-suppress ang reasoning — `thinking:{type:"disabled"}` sa `/v1/messages` path, o inaalis ang mga `reasoning`/`reasoning_effort` field sa `/v1/chat/completions` path. Inililista lamang ang variant para sa mga Claude-family model na sumusuporta sa thinking **at** sumusunod sa `disabled` (kaya hindi kasama, halimbawa, ang mga adaptive-only model na tumatanggi sa `disabled`). Maaaring sapilitang i-on o i-off ng mga operator ang variant para sa bawat modelo sa pamamagitan ng `ModelSpec.noThinkingAlias`. --- ## Manifest ng Provider Plugin ```bash GET /api/v1/provider-plugin-manifest ``` Ibinabalik ang JSON-safe na manifest ng provider plugin na ginagamit ng Bifrost, CLIProxyAPI, at mga sidecar router sa hinaharap. Binubuo ang tugon mula sa TypeScript provider registry at sadyang hindi isinasama ang mga OAuth client secret, runtime environment resolution, executor function, request header, at account data. Gamitin ang endpoint na ito kapag tumatakbo ang isang sidecar nang out-of-process at hindi nito direktang ma-import ang `open-sse/config/providerPluginManifestRegistry.ts`. --- ## Mga Endpoint para sa Compatibility | Pamamaraan | Path | Format | | ---------- | ----------------------------------------- | ------------------------------------- | | 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 (pag-edit/inpaint) | | POST | `/v1/videos/generations` | Pagbuo ng video na istilong OpenAI | | POST | `/v1/music/generations` | Pagbuo ng musika na istilong OpenAI | | POST | `/v1/audio/transcriptions` | OpenAI Audio (STT) | | POST | `/v1/audio/speech` | OpenAI TTS (nagbabalik ng audio body) | | POST | `/v1/rerank` | Rerank na istilong Cohere/Voyage | | POST | `/v1/classify` | Jina classify (`api.jina.ai`) | | POST | `/v1/segment` | Jina segmenter (`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}/` | OpenAI catalog alias | | GET | `/api/v1/vscode/{token}/models` | OpenAI models alias | | POST | `/api/v1/vscode/{token}/chat/completions` | OpenAI tokenized alias | | POST | `/api/v1/vscode/{token}/responses` | OpenAI Responses tokenized alias | | POST | `/api/v1/vscode/{token}/api/chat` | Ollama tokenized alias | | GET | `/api/v1/vscode/{token}/api/tags` | Ollama tags tokenized alias | Iisa ang anyo ng lahat ng POST route: `Bearer your-api-key` + JSON body na na-validate ng Zod (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, atbp., tingnan ang `src/shared/validation/schemas.ts`). Nagbabalik ng 4xx kapag nabigo ang schema validation. Para sa mga client na hindi makapaglakip ng `Authorization: Bearer ...`, tumatanggap din ang OmniRoute ng mga API key sa URL sa pamamagitan ng query-string compatibility (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) o ng mga nakalaang `/api/v1/vscode/{token}/...` endpoint na nakadokumento sa ibaba. ```bash # Rerank POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] } # Jina classify (mga kredensyal ng Foundation API) POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] } # Jina segmenter POST /v1/segment { "content": "...", "return_chunks": true } # Jina search (s.jina.ai; mga provider alias: jina-search, jina-ai, jina) POST /v1/search { "query": "...", "provider": "jina-search" } # Mga moderation POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." } # TTS — nagbabalik ng audio/mpeg (o hiniling na format) na body POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" } # Pag-edit ng image (multipart) POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png # Pagbuo ng video / musika (model id na may provider prefix) POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." } POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." } ``` ### Mga Nakalaang Provider Route ```bash POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` Awtomatikong idinaragdag ang provider prefix kung nawawala ito. Nagbabalik ng `400` ang mga hindi nagtutugmang model. --- ## Files API Endpoint ng mga file na compatible sa OpenAI para sa batch na input/output at mga pag-upload ayon sa layunin ng file. | Paraan | Path | Paglalarawan | | ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | POST | `/v1/files` | Mag-upload ng file (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — maximum na 512 MiB | | GET | `/v1/files` | Ilista ang mga file para sa napatunayang API key | | GET | `/v1/files/[id]` | Kunin ang metadata ng file | | DELETE | `/v1/files/[id]` | Mag-delete ng file | | GET | `/v1/files/[id]/content` | I-stream pabalik ang raw na nilalaman ng file | **Awtorisasyon:** Bearer API key — ang saklaw ng mga file ay ayon sa bawat API key sa pamamagitan ng `getApiKeyRequestScope`. Ang isang key ay makakakita, makakapag-download, at makakapag-delete lamang ng sarili nitong mga file; binabasa ng dashboard session na walang key ang buong instance; ang file na walang may-ari (anonymous o in-upload sa dashboard session) ay ipinagkakait sa bawat caller na hindi session. Tinatanggihan ng `GET /v1/files` ang isang anonymous na caller — at ang ibinigay na key na hindi ma-resolve — gamit ang `401` kahit na `REQUIRE_API_KEY=false`, sa halip na ilista ang mga file ng bawat tenant (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523). --- ## Batches API Batch processing na compatible sa OpenAI. | Paraan | Path | Paglalarawan | | ------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------- | | POST | `/v1/batches` | Gumawa ng batch — bina-validate ang body ng `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) | | GET | `/v1/batches` | Ilista ang mga batch | | GET | `/v1/batches/[id]` | Kunin ang status ng batch + `request_counts` | | DELETE | `/v1/batches/[id]` | Mag-delete ng natapos/nabigong batch | | POST | `/v1/batches/[id]/cancel` | Kanselahin ang batch na kasalukuyang pinoproseso | **Awtorisasyon:** Bearer API key. Ang saklaw ng mga batch ay ayon sa bawat API key sa ilalim ng parehong tatlong-posibleng panuntunan gaya ng mga file: sariling key lamang, saklaw ang buong instance para sa dashboard session, ipinagkakait sa bawat caller na hindi session ang mga record na null ang may-ari (pagkuha, pag-delete, pagkansela, at ang pagsusuri sa `input_file_id` sa paggawa). Tinatanggihan ng `GET /v1/batches` ang isang anonymous na caller gamit ang `401` kahit na `REQUIRE_API_KEY=false`. --- ## Search API Abstraksiyon ng provider ng web/search (Tavily, Brave, Exa, Serper, atbp.). | Pamamaraan | Path | Paglalarawan | | ---------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------- | | GET | `/v1/search` | Ilista ang mga naka-configure na provider ng paghahanap + mga kakayahan | | POST | `/v1/search` | Magpatakbo ng query sa paghahanap — bina-validate ng `v1SearchSchema` ang body, sumusuporta sa caching/coalescing | | GET | `/v1/search/analytics` | Mga istatistika ng hit/latency/cache para sa bawat provider | **Auth:** Bearer API key (`extractApiKey` + `isValidApiKey`). Ipinapatupad ang patakaran sa paghahanap sa pamamagitan ng `enforceApiKeyPolicy`. --- ## Web Fetch API Kumuha ng content mula sa isang URL sa pamamagitan ng naka-configure na web-fetch provider (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract). | Pamamaraan | Path | Paglalarawan | | ---------- | --------------- | --------------------------------------------------------------------------- | | POST | `/v1/web/fetch` | Kunin/i-scrape ang isang URL — bina-validate ng `v1WebFetchSchema` ang body | **Auth:** Bearer API key (`extractApiKey` + `isValidApiKey`). Ipinapatupad ang patakaran sa pamamagitan ng `enforceApiKeyPolicy`. **Fallback na isinasaalang-alang ang quota (#8297):** kapag walang ibinigay na tahasang `provider`, ang pool (`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) ay sinusundan ayon sa nakapirming pagkakasunod-sunod ng priyoridad (fill-first) — nilalaktawan ang isang naka-configure ngunit nalilimitahan ang rate na provider sa halip na agad na ihinto ang request, at ang isang maaaring subukang muli/quota na upstream failure (HTTP 429 palagi; 402/403 para sa mga libreng tier ng Firecrawl/Tavily/TinyFish na may istilong quota — hindi para sa Jina Reader, at hindi kailanman para sa karaniwang 400 bad request) ay lumilipat sa susunod na hindi pa nasusubukang provider na may credential sa oras ng request. Kapag naubos na ang bawat provider sa pool, nagbabalik ang endpoint ng iisang `429` (na may `Retry-After` header) sa halip ng dating generic na `400`. Kapag tahasang hiniling ang isang `provider`, **walang** tahimik na fallback — inilalabas ng tahasang provider na nalilimitahan ang rate o pumapalya ang sarili nitong error (`429` kung nalilimitahan ang rate, kung hindi ay ang upstream status). --- ## WebSocket Streaming ```bash GET /v1/ws?handshake=1 ``` Bina-validate ang isang WebSocket upgrade handshake at ibinabalik ang mga halimbawang mensahe ng wire protocol (`request`, `cancel`). Ang mga aktuwal na WS frame ay pinangangasiwaan ng kasamang WS server sa labas ng route table ng Next.js. **Auth:** Bearer API key habang isinasagawa ang handshake. ### Responses API sa pamamagitan ng WebSocket (codex lamang) ```bash # Parehong host:port ng HTTP API (default 20128); i-upgrade ang koneksyon: wscat -c "ws://localhost:20128/v1/responses?api_key=" # (o: -H "Authorization: Bearer ") # Ang unang frame ay DAPAT na response.create: { "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] } ``` Ang proxy ng Responses-API-over-WebSocket ay nakakonekta **eksklusibo sa `codex`** (ChatGPT backend). Nakikinig ito sa parehong port ng API/dashboard sa mga path na `/v1/responses`, `/responses`, at `/api/v1/responses`. Sa unang `response.create` frame, nagsasagawa ito ng authentication + paghahanda sa pamamagitan ng internal na `codex-responses-ws` bridge, pumipili ng codex OAuth connection, at nagtu-tunnel sa `wss://chatgpt.com/backend-api/codex/responses` sa pamamagitan ng `wreq-js` transport. **Tinatanggihan ang mga model na hindi codex** (`codex_ws_provider_required`). Para sa quota-share routing, gamitin ang `model: "qtSd//codex/"`. Ipinatupad sa `app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`. **Auth:** Bearer API key habang isinasagawa ang handshake. Ang kasamang HTTP server (`server-ws.mjs`) ay dapat ang aktibong entrypoint (ito ang default kapag umiiral ang `app/server-ws.mjs`). #### Model id: gamitin ang hubad na ChatGPT id (walang `codex/` prefix) Bina-validate ng OpenAI **Codex CLI** ang pangalan ng model sa panig ng client kapag `supports_websockets = true` at **tinatanggihan ang mga id na may prefix ng provider** gaya ng `codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account`). Ipadala ang **hubad** na id (hal. `gpt-5.5`). Codex-only ang bridge ng OmniRoute, kaya muli nitong nire-resolve ang hubad na id bilang isang codex model (`resolveCodexWsModelInfo`) bago mag-tunnel upstream — kahit na ang hubad na `gpt-5.5` ay karaniwang iru-route sa ibang provider sa pamamagitan ng HTTP. #### Pag-configure sa OpenAI Codex CLI Ituro ang Codex CLI sa OmniRoute sa pamamagitan ng pagdaragdag ng custom na provider na may suporta sa WebSocket sa `~/.codex/config.toml` (gumamit ng hiwalay na `CODEX_HOME` upang maiwasang mabago ang umiiral na config): ```toml model = "gpt-5.5" # hubad na id — HINDI "codex/gpt-5.5" model_provider = "omniroute" [model_providers.omniroute] name = "OmniRoute (WS)" base_url = "http://localhost:20128/v1" # walang trailing slash; awtomatikong binubuo ang WS URL (gumamit ng https/wss sa production) wire_api = "responses" # ang tanging sinusuportahang value mula noong Peb 2026 supports_websockets = true # ine-enable ang Responses-over-WS transport env_key = "OMNIROUTE_API_KEY" # naglalaman ng OmniRoute API key (Bearer) ``` ```bash export OMNIROUTE_API_KEY=sk-... # isang OmniRoute API key (anumang key kung REQUIRE_API_KEY=false) codex exec "Responda apenas: PONG" ``` Ina-upgrade ng CLI ang `base_url + /responses` sa isang WebSocket at itu-tunnel ito ng OmniRoute sa napiling codex OAuth connection. Na-validate nang end-to-end laban sa lokal na server: Nagbabalik ang ChatGPT ng `codex.rate_limits` + `response.created` at ini-stream ang completion. --- ## Mga Quota at Pag-uulat ng mga Isyu | Paraan | Path | Paglalarawan | | ------ | ------------------- | ---------------------------------------------------------------------------------------------------------- | | GET | `/v1/quotas/check` | Paunang i-validate ang quota para sa isang `provider` + `accountId` bago mag-isyu ng nakarehistrong key | | POST | `/v1/issues/report` | Mag-ulat sa GitHub ng pagkabigo sa quota/pag-isyu ng key (nangangailangan ng `GITHUB_ISSUES_REPO` + token) | **Auth:** Bearer API key (`isAuthenticated`). --- ## Pansariling paggamit (`/api/usage/om-usage`) Maaaring basahin ng anumang API key ang **sarili nitong** paggamit at mga quota — walang management auth. Ito ang endpoint na ginagamit ng isang client (CLI, ang OmniCopilot panel) upang ipakita sa may-ari ng key ang kanyang gastos. ```bash # Text na anyo (ang makasaysayang kontrata — plain text para sa isang terminal) curl -H "Authorization: Bearer " \ http://localhost:20128/api/usage/om-usage # Nakabalangkas na anyo — ang ginagamit ng isang UI curl -H "Authorization: Bearer " \ "http://localhost:20128/api/usage/om-usage?format=json" ``` Dapat naka-enable ang **`allowUsageCommand`** sa key (naka-off bilang default — itinatakda ito ng API-key manager ng dashboard para sa bawat key). Kung wala ito, sasagot ang endpoint ng `403`. Nagbabalik ang `?format=json` ng isang natatanging hugis upang hindi kailanman magbasa ang tumatawag ng isang field ng data mula sa isang pagtanggi. Kapag matagumpay: ```jsonc { "allowed": true, // naroroon lamang kapag pinili ng key ang mga limitasyon sa paggamit kada key (araw-araw/lingguhang USD): "personal": { "dailySpentUsd": 1.25, "dailyLimitUsd": 5, "dailyResetAtIso": "…", "weeklySpentUsd": 8, "weeklyLimitUsd": 20, "weeklyResetAtIso": "…" /* … */, }, // ang snapshot ng napiling quota ng provider, o null kapag wala pang naka-cache: "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */}, }, // snapshot ng bawat koneksyon, upang ma-render ng isang UI ang ilang provider nang magkatabi: "providers": [ { "connectionId": "…", "provider": "claude" /* … */ }, { "provider": "codex" /* … */ }, ], } ``` Kapag tinanggihan (`401` maling key / `403` hindi pinapayagan), ibinabalik ng parehong route ang `{ "allowed": false, "error": { "message": "…" } }` — ang umiiral ngunit walang laman na `personal`/`provider` (pinapayagan ang key, wala pang nakuhang impormasyon) ay ibang estado mula sa pagtanggi, at ang JSON na anyo lamang ang nakapaghihiwalay sa mga ito. **Auth:** sariling Bearer API key ng tumatawag, na bina-validate gamit ang `isValidApiKey` — _hindi_ ito ang management surface (`/api/keys/…`), na nananatiling protektado ng `requireManagementAuth`. --- ## Semantic Cache ```bash # Kunin ang mga estadistika ng cache GET /api/cache/stats # I-clear ang lahat ng cache DELETE /api/cache/stats ``` Halimbawa ng response: ```json { "semanticCache": { "memorySize": 42, "memoryMaxSize": 500, "dbSize": 128, "hitRate": 0.65 }, "idempotency": { "activeKeys": 3, "windowMs": 5000 } } ``` ### Epekto sa latency Inihahatid ng isang semantic cache HIT ang response mula sa cache **nang walang upstream call**, kaya halos zero ang iniulat na `X-OmniRoute-Response-Latency` (anuman ang orihinal na upstream latency). Dapat suriin ng mga client na sensitibo sa latency (benchmarking, p50/p99 monitoring) ang response header na `X-OmniRoute-Cache-Latency`: | Value | Kahulugan | | ----------- | ----------------------------------------------------------------------------- | | `synthetic` | Inihatid ang response mula sa cache; hindi tunay na upstream time ang latency | | _(wala)_ | Response mula sa tunay na upstream call | ### Pag-bypass ng cache kada key Maaaring hindi gumamit ng semantic cache reads ang mga API key sa pamamagitan ng `cacheDefaultMode`: | Value | Gawi | | -------- | ---------------------------------------------------------------- | | `legacy` | Normal na gawi ng cache (default) | | `bypass` | Ganap na laktawan ang cache lookup; palaging tumawag sa upstream | Itakda sa paggawa ng key (`POST /api/keys`) o pag-update (`PATCH /api/keys/[id]`): ```json { "cacheDefaultMode": "bypass" } ``` ### Pag-bypass kada request Maaaring i-bypass ng anumang request ang cache anuman ang mga setting ng key: ``` X-OmniRoute-No-Cache: true ``` --- ## Dashboard at Pamamahala Ang mga ruta ng pamamahala (`/api/*` maliban sa pampublikong auth/login) ay **hindi** pinahihintulutan ng mga karaniwang inference API key. Para sa mga pamilya ng kredensyal, saklaw, at mga halimbawa ng curl: [Authentication sa Pamamahala](../guides/MANAGEMENT-AUTH.md). ### Authentication | Endpoint | Paraan | Paglalarawan | | ----------------------------- | ------- | --------------------------------- | | `/api/auth/login` | POST | Mag-login | | `/api/auth/logout` | POST | Mag-logout | | `/api/settings/require-login` | GET/PUT | I-toggle kung kailangan ang login | ### Pamamahala ng Provider | Endpoint | Paraan | Paglalarawan | | ---------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `/api/providers` | GET/POST | Ilista / gumawa ng mga provider | | `/api/providers/[id]` | GET/PUT/DELETE | Pamahalaan ang isang provider | | `/api/providers/[id]/test` | POST | Subukan ang koneksyon ng provider | | `/api/providers/[id]/models` | GET | Ilista ang mga modelo ng provider | | `/api/providers/validate` | POST | Patunayan ang config ng provider | | `/api/providers/bulk` | POST | Maramihang magdagdag ng mga API key para sa ISANG provider | | `/api/providers/import` | POST | Mag-import ng magkakaibang LISTAHAN ng provider mula sa na-parse na CSV/JSON file (#6836); mga resulta ng bahagyang pagkabigo sa bawat row | | `/api/provider-nodes*` | Iba-iba | Pamamahala ng node ng provider | | `/api/provider-models` | GET/POST/PATCH/DELETE | Mga custom na modelo (magdagdag, mag-update, magtago/magpakita, magtanggal) | ### Mga Daloy ng OAuth | Endpoint | Paraan | Paglalarawan | | -------------------------------- | ------- | ------------------------------- | | `/api/oauth/[provider]/[action]` | Iba-iba | OAuth na partikular sa provider | ### Routing at Config | Endpoint | Paraan | Paglalarawan | | --------------------- | -------- | -------------------------------------- | | `/api/models/alias` | GET/POST | Mga alias ng modelo | | `/api/models/catalog` | GET | Lahat ng modelo ayon sa provider + uri | | `/api/combos*` | Iba-iba | Pamamahala ng combo | | `/api/keys*` | Iba-iba | Pamamahala ng API key | | `/api/pricing` | GET | Pagpepresyo ng modelo | ### Paggamit at Analytics | Endpoint | Paraan | Paglalarawan | | -------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/usage/history` | GET | Kasaysayan ng paggamit | | `/api/usage/logs` | GET | Mga log ng paggamit | | `/api/usage/request-logs` | GET | Mga log sa antas ng kahilingan | | `/api/usage/[connectionId]` | GET | Paggamit kada koneksyon | | `/api/usage/token-limits` | GET/POST/DELETE | Mga badyet sa limitasyon ng token kada API key | | `/api/usage/model-latency-stats` | GET | Patuloy na pinagsama-samang latency kada provider/model (avg/p50/p95/p99, antas ng tagumpay); mga filter: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) | | `/api/usage/cache-health` | GET | Buod ng kalagayan ng prompt cache sa `call_logs` — ratio ng pagsulat/pagbasa, distribusyon ng laki ng pagsulat na p50/p90/p99, konsentrasyon ng mabibigat na pagsulat, paghahati kada model, at hatol na `healthy`/`degraded`/`thrash`/`no-data`; mga query param na `range` (`1h`\|`24h`\|`7d`\|`30d`, default na `24h`) at opsyonal na `model` (#8827) | ### Mga Setting | Endpoint | Paraan | Paglalarawan | | ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/api/settings` | GET/PUT/PATCH | Mga pangkalahatang setting | | `/api/settings/proxy` | GET/PUT | Configuration ng network proxy | | `/api/settings/proxy/test` | POST | Subukan ang koneksyon sa proxy | | `/api/settings/ip-filter` | GET/PUT | Allowlist/blocklist ng IP | | `/api/settings/thinking-budget` | GET/PUT | Mode ng muling pagsulat sa **kahilingan** para sa thinking/reasoning (passthrough / auto-strip / custom / adaptive). Hiwalay sa compression. Tingnan ang [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). | | `/api/settings/system-prompt` | GET/PUT | Pandaigdigang system prompt | | `/api/settings/compression` | GET/PUT | Pandaigdigang configuration ng compression | | `/api/settings/purge-request-history` | POST | Burahin ang mga row ng log ng kahilingan at mga lokal na artifact ng call log | ### Konteksto at Compression | Endpoint | Paraan | Paglalarawan | | -------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------- | | `/api/compression/preview` | POST | I-preview ang off/lite/standard/aggressive/ultra/RTK/stacked na compression | | `/api/compression/language-packs` | GET | Ilista ang mga available na Caveman language pack | | `/api/compression/rules` | GET | Ilista ang metadata ng mga panuntunan ng Caveman | | `/api/context/caveman/config` | GET/PUT | Alias ng mga setting na partikular sa Caveman | | `/api/context/rtk/config` | GET/PUT | Mga setting na partikular sa RTK, kabilang ang mga custom na filter at pagpapanatili ng raw output | | `/api/context/rtk/filters` | GET | Katalogo ng RTK filter at mga diagnostic ng custom na filter | | `/api/context/rtk/test` | POST | Patakbuhin ang RTK preview/test gamit ang isang text payload | | `/api/context/rtk/raw-output/[id]` | GET | Basahin ang pinanatiling na-redact na raw output gamit ang pointer id | | `/api/context/combos` | GET/POST | Ilista/lumikha ng compression combo | | `/api/context/combos/[id]` | GET/PUT/DELETE | Detalye/pag-update/pagtanggal ng compression combo | | `/api/context/combos/[id]/assignments` | GET/PUT | Italaga ang mga compression combo sa mga routing combo | | `/api/context/analytics` | GET | Alias ng analytics ng compression | ### Pagsubaybay | Endpoint | Paraan | Paglalarawan | | ------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/sessions` | GET | Pagsubaybay sa mga aktibong session | | `/api/rate-limits` | GET | Mga rate limit para sa bawat account | | `/api/monitoring/health` | GET | Pagsusuri sa kalagayan + buod ng provider (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Kabilang sa management view ang `credentialHealth`: mga scalar ng probe cache, `failedConnections` kapag `failed>0`, at `staleDbNonOkCount` (sticky na `test_status` ng SQLite, hindi ang gauge). Tingnan ang [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). | | `/api/cache/stats` | GET/DELETE | Mga estadistika ng cache / i-clear | | `/api/modality-bridge/stats` | GET | Mga nasa memory na `attempts`, mga tagumpay/`bridged`, mga pagkabigo, mga cache hit, `totalLatencyMs`, `latencySamples`, `averageLatencyMs` na nakabatay sa bilang ng sample, at oras ng huling paggamit (nire-reset sa pag-restart; management auth) | | `/api/modality-bridge/video/runtime` | GET | Mahigpit na trusted-loopback check bago ang management auth/probe; na-sanitize na availability at mga bersyon ng FFmpeg/ffprobe (no-store) | | `/api/modality-bridge/video/extract` | POST | Internal na authenticated trusted-loopback byte broker; 50 MiB na input, may limitasyong queue/32 MiB na output, `503` kapag puno ang kapasidad, `499` kapag nadiskonekta, `504` kapag lumampas sa deadline; hindi isang pampublikong upload API | ### Backup at Pag-export/Pag-import | Endpoint | Paraan | Paglalarawan | | --------------------------- | ------ | ----------------------------------------------------- | | `/api/db-backups` | GET | Ilista ang mga available na backup | | `/api/db-backups` | PUT | Gumawa ng manual na backup | | `/api/db-backups` | POST | Mag-restore mula sa isang partikular na backup | | `/api/db-backups/export` | GET | I-download ang database bilang .sqlite file | | `/api/db-backups/import` | POST | Mag-upload ng .sqlite file upang palitan ang database | | `/api/db-backups/exportAll` | GET | I-download ang buong backup bilang .tar.gz archive | ### Pag-sync sa Cloud | Endpoint | Paraan | Paglalarawan | | ---------------------- | ------- | --------------------------- | | `/api/sync/cloud` | Iba-iba | Mga operasyon ng cloud sync | | `/api/sync/initialize` | POST | Simulan ang pag-sync | | `/api/cloud/*` | Iba-iba | Pamamahala sa cloud | ### Mga Tunnel | Endpoint | Paraan | Paglalarawan | | -------------------------- | ------ | -------------------------------------------------------------------------------------- | | `/api/tunnels/cloudflared` | GET | Basahin ang status ng pag-install/runtime ng Cloudflare Quick Tunnel para sa dashboard | | `/api/tunnels/cloudflared` | POST | I-enable o i-disable ang Cloudflare Quick Tunnel (`action=enable/disable`) | | `/api/tunnels/ngrok` | GET | Basahin ang runtime status ng ngrok Tunnel para sa dashboard | | `/api/tunnels/ngrok` | POST | I-enable o i-disable ang ngrok Tunnel (`action=enable/disable`) | ### Mga CLI Tool | Endpoint | Paraan | Paglalarawan | | ---------------------------------- | ------ | -------------------------- | | `/api/cli-tools/claude-settings` | GET | Status ng Claude CLI | | `/api/cli-tools/codex-settings` | GET | Status ng Codex CLI | | `/api/cli-tools/droid-settings` | GET | Status ng Droid CLI | | `/api/cli-tools/openclaw-settings` | GET | Status ng OpenClaw CLI | | `/api/cli-tools/runtime/[toolId]` | GET | Pangkalahatang CLI runtime | Kasama sa mga tugon ng CLI ang: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. ### Mga ACP Agent | Endpoint | Paraan | Paglalarawan | | ----------------- | ------ | ------------------------------------------------------------------ | | `/api/acp/agents` | GET | Ilista ang lahat ng natukoy na agent (built-in + custom) at status | | `/api/acp/agents` | POST | Magdagdag ng custom na agent o i-refresh ang detection cache | | `/api/acp/agents` | DELETE | Mag-alis ng custom na agent gamit ang `id` query param | Kasama sa tugon ng GET ang `agents[]` (id, name, binary, version, installed, protocol, isCustom) at `summary` (total, installed, notFound, builtIn, custom). ### Resilience at Mga Rate Limit | Endpoint | Paraan | Paglalarawan | | --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------ | | `/api/resilience` | GET/PATCH | Kunin/i-update ang request queue, connection cooldown, provider breaker, at mga setting ng paghihintay | | `/api/resilience/reset` | POST | I-reset ang mga provider circuit breaker | | `/api/resilience/model-cooldowns` | GET | Ilista ang mga aktibong lockout kada (provider, connection, model), inayos ayon sa natitirang oras | | `/api/resilience/model-cooldowns` | DELETE | Alisin ang model lockout — body na `{provider, model}` o `{all: true}` upang burahin ang lahat | | `/api/rate-limits` | GET | Status ng rate limit kada account | | `/api/rate-limit` | GET | Global na configuration ng rate limit | > Kinakailangan ng lahat ng apat na `/api/resilience/*` route ang **management auth** (`requireManagementAuth`). Tingnan ang [Resilience (pinalawak)](#resilience-extended) para sa kumpletong paghahambing ng provider breaker, connection cooldown, at model lockout. ### Mga Eval | Endpoint | Paraan | Paglalarawan | | ------------ | -------- | ---------------------------------------------------- | | `/api/evals` | GET/POST | Ilista ang mga eval suite / magpatakbo ng evaluation | ### Mga Patakaran | Endpoint | Paraan | Paglalarawan | | --------------- | --------------- | --------------------------------- | | `/api/policies` | GET/POST/DELETE | Pamahalaan ang mga routing policy | ### Pagsunod | Endpoint | Paraan | Paglalarawan | | --------------------------- | ------ | -------------------------------- | | `/api/compliance/audit-log` | GET | Audit log ng pagsunod (huling N) | ### v1beta (Compatible sa Gemini) | Endpoint | Paraan | Paglalarawan | | -------------------------- | ------ | ---------------------------------------- | | `/v1beta/models` | GET | Ilista ang mga model sa format ng Gemini | | `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | Ginagaya ng mga endpoint na ito ang format ng API ng Gemini para sa mga client na nangangailangan ng native na compatibility sa Gemini SDK. ### Mga Internal / System API | Endpoint | Paraan | Paglalarawan | | ------------------------ | ------ | ------------------------------------------------------------------------- | | `/api/init` | GET | Pagsusuri sa pagsisimula ng application (ginagamit sa unang pagpapatakbo) | | `/api/tags` | GET | Mga tag ng model na compatible sa Ollama (para sa mga Ollama client) | | `/api/restart` | POST | Mag-trigger ng maayos na pag-restart ng server | | `/api/shutdown` | POST | Mag-trigger ng maayos na pag-shutdown ng server | | `/api/system/env/repair` | POST | Ayusin ang mga environment variable ng OAuth provider | > **Tandaan:** Ginagamit ang mga endpoint na ito sa loob ng system o para sa compatibility sa Ollama client. Karaniwang hindi direktang tinatawag ang mga ito ng mga end user. ### Pag-aayos ng OAuth Environment _(v3.6.1+)_ ```bash POST /api/system/env/repair Content-Type: application/json { "provider": "claude-code" } ``` Inaayos ang mga nawawala o sirang OAuth environment variable para sa isang partikular na provider. Ibinabalik nito ang: ```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" } ``` --- ## Transkripsyon ng Audio ```bash POST /v1/audio/transcriptions Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` I-transcribe ang mga audio file gamit ang anumang naka-configure na STT provider. Pinipili ng unang segment ng path ang native na provider (`openai/…`, `deepgram/…`). Gumagamit ang mga gateway na muling nag-e-export ng modelo ng ibang vendor ng qualified id (`openrouter/deepgram/nova-3`). **Kahilingan:** ```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" ``` **Tugon:** ```json { "text": "Hello, this is the transcribed audio content.", "task": "transcribe", "language": "en", "duration": 12.5 } ``` **Mga halimbawang model id:** `openai/whisper-1` (nangangailangan ng OpenAI key), `openrouter/deepgram/nova-3` (nangangailangan ng OpenRouter key), `deepgram/nova-3` (nangangailangan ng native na Deepgram key). Ang kahilingang `deepgram/nova-3` lamang ay **hindi** gumagamit ng OpenRouter. **Mga sinusuportahang format:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- ## Compatibility sa Ollama Para sa mga client na gumagamit ng format ng API ng Ollama: ```bash # Endpoint ng chat (format ng Ollama) POST /v1/api/chat # Listahan ng modelo (format ng Ollama) GET /api/tags ``` Awtomatikong isinasalin ang mga kahilingan sa pagitan ng mga format ng Ollama at mga internal na format. ## Mga Tokenized na Alias para sa VS Code / Mga Alias na Walang Header Gamitin ang mga alias na ito kapag hindi makapaglagay ang isang integration ng `Authorization` header at kailangang i-embed ang API key sa base URL. ```bash # Alias ng catalog na OpenAI-style GET /api/v1/vscode/{token}/ GET /api/v1/vscode/{token}/models # Mga alias ng chat na OpenAI-style POST /api/v1/vscode/{token}/chat/completions POST /api/v1/vscode/{token}/responses # Mga alias na Ollama-style POST /api/v1/vscode/{token}/api/chat GET /api/v1/vscode/{token}/api/tags ``` Halimbawa: ```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"}]}' ``` Mga tala: - Muling ginagamit ng mga tokenized na alias ang parehong mga handler gaya ng `/v1/*` at `/api/tags`; nananatiling magkapareho ang mga anyo ng tugon. - Piliin ang `Authorization: Bearer ...` hangga't sinusuportahan ng client ang mga custom na header. - Maaaring lumabas ang mga token na nakabatay sa URL sa mga log ng reverse proxy, history ng browser, at telemetry sa labas ng OmniRoute. Ituring ang mga ito bilang opsyon para sa compatibility, hindi bilang default na paraan ng authentication. --- ## Telemetry ```bash # Kunin ang buod ng telemetry ng latency (p50/p95/p99 para sa bawat provider) GET /api/telemetry/summary ``` **Tugon:** ```json { "providers": { "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } } } ``` --- ## Badyet ```bash # Kunin ang katayuan ng badyet para sa lahat ng API key GET /api/usage/budget # Magtakda o mag-update ng badyet 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" } ``` > **Mga tala sa schema** (`setBudgetSchema`): kinakailangan ang `apiKeyId`; dapat mas mataas sa zero ang kahit isa sa `dailyLimitUsd`, `weeklyLimitUsd`, o `monthlyLimitUsd`. Mga opsyonal na field: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Nagbabalik ng `400 Bad Request` ang lumang anyong `{keyId, limit, period}`. ## Mga Limitasyon sa Token Mga badyet sa **token** para sa bawat API key (hiwalay sa badyet na nakabatay sa USD sa itaas). Ipinapatupad nang inline sa path ng request: kapag umabot sa limit ang paggamit ng isang key sa kasalukuyang window nito, tatanggihan ang mga request gamit ang `429 Too Many Requests`. Maaaring ilapat ang mga limitasyon sa isang partikular na `model`, isang `provider`, o `global` sa buong key; kapag maraming limitasyon ang tumugma sa isang request, ang pinakamahigpit ang mananaig. ```bash # Ilista ang mga limitasyon sa token ng isang key (kasama ang kasalukuyang paggamit sa window) GET /api/usage/token-limits?apiKeyId=key-123 # Gumawa o mag-update ng limitasyon sa 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 } # Magtanggal ng limitasyon sa token ayon sa id DELETE /api/usage/token-limits?id=tl-abc ``` > **Mga tala sa schema** (`setTokenLimitSchema`): Kinakailangan ang `apiKeyId` at `scopeType` (`model` | `provider` | `global`). Kinakailangan ang `scopeValue` maliban kung `global` ang `scopeType` (hal. isang model id para sa saklaw na `model`, isang provider id para sa saklaw na `provider`). Dapat ay positibong integer ang `tokenLimit` (kino-convert mula sa string). Opsyonal: `id` (huwag isama upang gumawa, isama upang mag-update), `resetInterval` (`daily` | `weekly` | `monthly`, default na `monthly`), `resetTime` (`HH:MM`), `enabled` (default na `true`). Pinagyayaman ng mga tugon sa `GET` ang bawat limitasyon gamit ang `tokensUsed`, `remaining`, `windowStart`, `periodStartAt`, at `nextResetAt`. Isa itong management-class endpoint (sentral na ipinapatupad ng authz pipeline ang awtentikasyon). ## Pagproseso ng Request 1. Nagpapadala ang client ng request sa `/v1/*` 2. Tinatawag ng route handler ang `handleChat`, `handleEmbedding`, `handleAudioTranscription`, o `handleImageGeneration` 3. Tinutukoy ang model (direktang provider/model o alias/combo) 4. Pinipili ang mga credential mula sa lokal na DB nang may pag-filter batay sa availability ng account 5. Para sa chat: sinusuri ng `handleChatCore` ang semantic/signature cache at tinutukoy ang mga setting ng combo compression 6. Tumatakbo ang proactive compression bago ang provider translation kapag naka-enable (`lite`, Caveman, RTK, o stacked) 7. Ipinapadala ng provider executor ang upstream request 8. Isinasalin pabalik ang tugon sa format ng client (chat) o ibinabalik nang walang pagbabago (embeddings/images/audio) 9. Itinatala ang paggamit, analytics ng compression, at mga log ng request 10. Inilalapat ang fallback kapag may mga error alinsunod sa mga panuntunan ng combo Kumpletong sanggunian sa arkitektura: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md) --- ## Pamamahala ng Combo Ang mga higher-level routing combo (na naibuod na sa ilalim ng `/api/combos*`) ay maaari ding i-map nang 1:1 mula sa pattern ng model id, na nagbibigay-daan sa transparent na pag-redirect ng isang OpenAI-style model id patungo sa isang combo. | Paraan | Path | Paglalarawan | | ------ | -------------------------------- | --------------------------------------------------------------------------------- | | GET | `/api/model-combo-mappings` | Ilista ang lahat ng model→combo mapping | | POST | `/api/model-combo-mappings` | Gumawa ng mapping — body: `{pattern, comboId, priority?, enabled?, description?}` | | GET | `/api/model-combo-mappings/[id]` | Kunin ang isang mapping | | PUT | `/api/model-combo-mappings/[id]` | I-update ang mga field ng isang umiiral na mapping | | DELETE | `/api/model-combo-mappings/[id]` | Mag-alis ng mapping | **Auth:** management session/API key (`requireManagementAuth`). --- ## Mga Webhook Mga outbound na subscription sa webhook para sa mga event ng OmniRoute (pagkumpleto ng request, pagkaubos ng quota, pag-rotate ng key, atbp.). | Paraan | Path | Paglalarawan | | ------ | ------------------------- | ---------------------------------------------------------------------------- | | GET | `/api/webhooks` | Ilista ang mga webhook (naka-mask ang mga secret bilang `...`) | | POST | `/api/webhooks` | Gumawa ng webhook — body: `{url, events?: ["*"], secret?, description?}` | | GET | `/api/webhooks/[id]` | Kunin ang isang webhook | | PUT | `/api/webhooks/[id]` | I-update ang url/events/secret/description | | DELETE | `/api/webhooks/[id]` | Alisin ang isang webhook | | POST | `/api/webhooks/[id]/test` | Magpadala ng test payload sa URL ng webhook at ibalik ang status ng delivery | **Auth:** session/API key para sa pamamahala (`requireManagementAuth`). --- ## Mga Rehistradong Key (Awtomatikong Pamamahala) Ginagamit ng subsystem para sa awtomatikong pamamahala ng key upang mag-isyu at mag-rotate ng mga API key gamit ang isang backing provider/account, na may mga pang-araw-araw/oras-oras na quota. | Paraan | Path | Paglalarawan | | ------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/registered-keys` | Ilista ang mga rehistradong key (naka-mask na prefix lamang) | | POST | `/api/v1/registered-keys` | Mag-isyu ng bagong rehistradong key — body: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Ibinabalik ang raw key nang **isang beses**. Nagbabalik ng `429` kapag tinanggihan dahil sa quota. | | GET | `/api/v1/registered-keys/[id]` | Kunin ang metadata ng isang rehistradong key (walang raw na materyal) | | DELETE | `/api/v1/registered-keys/[id]` | Bawiin ang isang rehistradong key | | POST | `/api/v1/registered-keys/[id]/revoke` | Tahasang endpoint para sa pagbawi (kapareho ng epekto ng DELETE) | **Auth:** Bearer API key (`isAuthenticated`). Tingnan din ang `/v1/quotas/check` at `/v1/issues/report`. --- ## Protocol ng Mga Agent Mga gawain ng cloud agent (Claude Code, Codex Cloud, OpenHands, atbp.) na isinasagawa nang malayuan para sa mga user ng OmniRoute. | Paraan | Path | Paglalarawan | | ------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/agents/tasks` | Ilista ang mga gawain — opsyonal ang `?provider=`, `?status=`, `?limit=` (1–500, default na 50) | | POST | `/api/v1/agents/tasks` | Gumawa ng gawain — bina-validate ang body ng `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Nagbabalik ng `201` kasama ang task envelope | | DELETE | `/api/v1/agents/tasks?id=...` | Mag-delete ng gawain | | GET | `/api/v1/agents/tasks/[id]` | Basahin ang gawain — sini-synchronize ang pag-refresh ng status mula sa upstream cloud agent kapag nakatakda ang `external_id` | | POST | `/api/v1/agents/tasks/[id]` | Aksiyong may pantukoy: `{action: "approve"}`, `{action: "message", message}`, o `{action: "cancel"}` | | DELETE | `/api/v1/agents/tasks/[id]` | Mag-delete ng partikular na gawain ayon sa id | > **Auth:** kinakailangan ang management auth sa bawat paraan (`requireCloudAgentManagementAuth`). Bago ang v3.8.0, hindi nangangailangan ng authentication ang mga ito — tingnan ang commit `588a0333` para sa breaking change. ```bash # Gumawa ng Claude Code cloud task 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":"..."}}' ``` --- ## Mga Management Proxy Mga outbound HTTP(S)/SOCKS proxy na maaaring italaga sa mga provider, account, o sa pangkalahatan. | Paraan | Path | Paglalarawan | | ------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/management/proxies` | Ilista ang mga proxy (kapag may `?id=`, isa ang ibinabalik; kapag may `?id=&where_used=1`, ibinabalik ang assignment graph) | | POST | `/api/v1/management/proxies` | Gumawa ng proxy — bina-validate ang body ng `createProxyRegistrySchema` | | PATCH | `/api/v1/management/proxies` | I-update ang proxy — bina-validate ang body ng `updateProxyRegistrySchema` (nangangailangan ng `id`) | | DELETE | `/api/v1/management/proxies?id=...&force=1` | Mag-delete ng proxy (gamitin ang `force=1` upang alisin ang mga assignment) | | GET | `/api/v1/management/proxies/assignments` | Ilista ang mga assignment — maaaring i-filter ayon sa `proxy_id`, `scope`, `scope_id`; ipasa ang `resolve_connection_id=` upang tukuyin ang aktibong proxy para sa isang koneksyon | | PUT | `/api/v1/management/proxies/assignments` | Magtalaga — bina-validate ang body ng `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Nililinis ang dispatcher cache | | PUT | `/api/v1/management/proxies/bulk-assign` | Maramihang magtalaga — bina-validate ang body ng `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) | | GET | `/api/v1/management/proxies/health?hours=24` | Pinagsama-samang kalagayan ng proxy (bilang ng tagumpay/pagkabigo, latency) sa loob ng isang yugto | **Auth:** management session/API key sa bawat route (`requireManagementAuth`). > Ang `POST /api/v1/management/proxies/[id]/assignments` at `POST /api/v1/management/proxies/[id]/health` sa paglalarawan ng gawain ay sineserbisyuhan ng mga flat na route na `/assignments` at `/health` na ipinapakita sa itaas — walang mga per-id na subroute sa codebase. --- ## Katatagan (pinalawak) Nagbibigay ang OmniRoute ng tatlong magkakahiwalay na mekanismo para sa mga pansamantalang pagkabigo; hinahayaan ng mga management endpoint sa ibaba ang mga operator na basahin at i-override ang mga ito: | Saklaw | Imbakan ng estado | Pagbasa | Pag-reset / pag-clear | | --------------------- | -------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------- | | Breaker ng provider | `domain_circuit_breakers` + nasa memorya | `/api/monitoring/health` | `POST /api/resilience/reset` | | Cooldown ng koneksyon | `rateLimitedUntil` sa mga koneksyon ng provider | `/api/rate-limits`, `/api/providers/[id]` | (muling pinapagana nang lazy; i-clear sa pamamagitan ng provider PUT) | | Lockout ng modelo | Registry ng availability ng modelo na nasa memorya | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` | Tumatanggap ang `PATCH /api/resilience` ng mga override sa breaker ng provider sa ilalim ng `providerBreaker.oauth` at `providerBreaker.apikey`. Sinusuportahan ng bawat profile ang `degradationThreshold`, `failureThreshold`, at `resetTimeoutMs`; makikita rin ang parehong mga field sa Dashboard → Settings → Resilience. ```bash # I-clear ang lockout ng isang modelo 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"}' # Burahin ang lahat ng lockout curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \ -H "Cookie: auth_token=..." \ -d '{"all":true}' ``` Para sa kumpletong konseptuwal na sanggunian at mga default ng breaker: tingnan ang [`CLAUDE.md`](../../CLAUDE.md) → "Estado ng Resilience Runtime". --- ## Mga Skill Framework ng skill para palawakin ang OmniRoute gamit ang mga custom na executable handler, kasama ang mga marketplace integration. | Paraan | Path | Paglalarawan | | ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/skills` | Ilista ang mga naka-install na skill — maaaring i-filter ayon sa `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, may pagination | | GET | `/api/skills/[id]` | Kunin ang isang skill | | PUT | `/api/skills/[id]` | I-update ang skill (pangalan, paglalarawan, mode, schema, handler, mga tag) | | DELETE | `/api/skills/[id]` | I-uninstall ang isang skill | | POST | `/api/skills/install` | Mag-install ng skill mula sa raw manifest — body: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` | | GET | `/api/skills/executions` | Ilista ang mga kamakailang execution ng skill (audit trail na may mga input/output/tagal) | | GET | `/api/skills/marketplace?q=...` | Maghanap/listahan ng mga popular na skill mula sa SkillsMP marketplace (nangangailangan ng setting na `skillsmpApiKey`) | | POST | `/api/skills/marketplace/install` | Mag-install ng skill ayon sa id mula sa SkillsMP | | GET | `/api/skills/skillssh?q=&limit=` | Maghanap sa registry ng skills.sh | | POST | `/api/skills/skillssh/install` | Mag-install ng skill ayon sa id mula sa skills.sh | **Auth:** management session/API key. Tumatanggap ang mga route sa paghahanap sa marketplace ng management auth o Bearer API key (`isAuthenticated`). --- ## Memorya Persistenteng imbakan ng memoryang pang-usapan/paktuwal, na nakasaklaw sa bawat API key / session. | Paraan | Path | Paglalarawan | | ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/memory` | Ilista ang mga memorya — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, na may `offset/limit` o `page/limit` na pagination | | POST | `/api/memory` | Gumawa ng memorya — body na vina-validate ng Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` | | GET | `/api/memory/[id]` | Kunin ang isang memorya | | DELETE | `/api/memory/[id]` | Magtanggal ng memorya | | GET | `/api/memory/health` | Kalagayan ng subsystem ng memorya (konektibidad ng DB, embeddings backend, katayuan ng vector index) | **Awtorisasyon:** management session/API key (`requireManagementAuth`). `type` enum: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (tingnan ang `MemoryType` sa `src/lib/memory/types.ts`). --- ## MCP Server May kasamang naka-embed na Model Context Protocol server ang OmniRoute na may 3 transport (stdio, SSE, streamable-http) at mga tool na may saklaw. Binabasa ng mga dashboard endpoint sa ibaba ang data ng katayuan/audit at pini-proxy ang mga HTTP transport. | Paraan | Path | Paglalarawan | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- | | GET | `/api/mcp/status` | Heartbeat, transport, online na katayuan, huling tawag, mga nangungunang tool, 24h na antas ng tagumpay | | GET | `/api/mcp/tools` | Listahan ng mga MCP tool na may `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` | | GET | `/api/mcp/sse` | Magbukas ng SSE stream para sa SSE transport (nagbabalik ng `503` kung naka-disable ang MCP o hindi tugma ang transport) | | POST | `/api/mcp/sse` | Magpadala ng JSON-RPC frame sa SSE transport | | GET | `/api/mcp/stream` | Magbukas ng SSE side ng Streamable HTTP transport (mga mensaheng sinimulan ng server) | | POST | `/api/mcp/stream` | Magpadala ng JSON-RPC frame sa Streamable HTTP transport | | DELETE | `/api/mcp/stream` | Tapusin ang isang Streamable HTTP session | | GET | `/api/mcp/audit` | Mag-query sa audit log — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` | | GET | `/api/mcp/audit/stats` | Pinagsama-samang mga istatistika ng audit (mga kabuuan, antas ng tagumpay, karaniwang tagal, mga nangungunang tool) | **Awtorisasyon:** sinusunod ng mga `sse`/`stream` transport ang auth surface na partikular sa MCP (Bearer API key na may saklaw na `mcp`); mababasa mula sa dashboard ang mga route na `status`/`tools`/`audit*` (walang kinakailangang karagdagang awtorisasyon bukod sa pag-abot sa dashboard host). > Ang parehong HTTP transport ay kinokontrol ng `settings.mcpEnabled` at `settings.mcpTransport` — ang hindi pagtugma ng transport ay nagbabalik ng `400`, at ang naka-disable na katayuan ng MCP ay nagbabalik ng `503`. --- ## Server ng A2A Naglalantad ang OmniRoute ng A2A (Agent-to-Agent) JSON-RPC 2.0 endpoint at isang REST wrapper para sa inspeksiyon/paggamit sa dashboard. ### JSON-RPC ```bash POST /a2a Authorization: Bearer your-api-key # opsyonal maliban kung nakatakda ang 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"}] } } ``` Mga suportadong method (lahat ay nakadepende sa `settings.a2aEnabled`): | Method | Paglalarawan | | ---------------- | ------------------------------------------------------------------------------- | | `message/send` | Sinkronos na pagpapatakbo ng skill; nagbabalik ng `{task, artifacts, metadata}` | | `message/stream` | Streaming SSE na pagpapatakbo ng parehong hanay ng mga skill | | `tasks/get` | Kunin ang isang task ayon sa `taskId` | | `tasks/cancel` | Kanselahin ang isang task ayon sa `taskId` | Mga built-in na skill: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`. ### Card ng Ahente ```bash GET /.well-known/agent.json ``` Ibinabalik ang pampublikong A2A agent card (pangalan, paglalarawan, mga kakayahan, catalog ng mga skill, auth scheme) — naka-cache nang pampubliko sa loob ng 1h. Hindi kailangan ng auth. ### Mga REST helper | Method | Path | Paglalarawan | | ------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/a2a/status` | Naka-enable ang A2A + mga estadistika ng task + buod ng naka-cache na agent card | | GET | `/api/a2a/tasks` | Ilista ang mga task — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` | | POST | `/api/a2a/tasks` | (Hindi ipinatupad bilang REST helper — gumawa sa pamamagitan ng JSON-RPC `message/send`) | | GET | `/api/a2a/tasks/[id]` | Kunin ang isang task | | POST | `/api/a2a/tasks/[id]/cancel` | Kanselahin ang isang task | **Auth:** tumatakbo ang mga REST helper nang walang management auth (nababasa ng dashboard); ginagamit ng JSON-RPC `/a2a` route ang Bearer `OMNIROUTE_API_KEY` kung naka-configure. --- ## Cloud, Mga Eval at Pagtatasa | Method | Path | Paglalarawan | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- | | POST | `/api/cloud/auth` | Beripikahin ang isang Bearer key at ibalik ang mga naka-mask na koneksiyon ng provider + mga model alias para sa mga cloud sync client | | POST | `/api/cloud/credentials/update` | I-update ang mga naka-encrypt na credential para sa isang cloud-synced na provider | | POST | `/api/cloud/model/resolve` | I-resolve ang isang logical model id sa isang kongkretong provider/model gamit ang lokal na routing table | | GET | `/api/cloud/models/alias` | Ilista ang mga model alias ayon sa pagkakalantad sa cloud sync | | GET | `/api/assess` | Basahin ang pinakabagong mga kategorya ng pagtatasa (bawat provider/model) | | POST | `/api/assess` | Magpatakbo ng pagtatasa — body: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` | | GET | `/api/evals` | Ilista ang mga built-in na eval suite + mga pinakabagong run | | POST | `/api/evals` | Mag-trigger ng isang eval run | | POST | `/api/evals/suites` | Gumawa ng custom na eval suite — bina-validate ang body ng `evalSuiteSaveSchema` | | GET | `/api/evals/suites/[id]` | Kunin ang isang custom na eval suite | **Auth:** direktang bina-validate ng `/api/cloud/auth` ang isang Bearer key; nangangailangan ang iba pang `/api/cloud/*`, `/api/evals/*`, at `/api/assess` route ng management session/API key. Gumagamit ang `/api/assess` POST ng `validateBody` na may discriminated-union scope schema. --- ## Pamamahala ng ACP (Agent Client Protocol) bilang mga child process. Pinamamahalaan ng mga endpoint na ito ang pagtukoy sa ACP agent at pagpaparehistro ng custom agent. | Paraan | Path | Paglalarawan | | ------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/acp/agents` | Ilista ang lahat ng kilalang CLI agent (built-in + custom), kasama ang status ng pag-install, version, at binary | | POST | `/api/acp/agents` | Magparehistro ng custom ACP agent o i-refresh ang cache — body: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` o `{action: "refresh"}` | | DELETE | `/api/acp/agents` | Mag-alis ng custom ACP agent — query param: `?id=` | **Halimbawa ng tugon** (`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 } ``` **Auth:** Nangangailangan ng session sa pamamahala (`auth_token` cookie ng dashboard) o API key na may saklaw sa pamamahala. Tingnan ang [ACP Framework](../frameworks/ACP.md) para sa kumpletong detalye. --- ## Analytics at Observability Mga real-time na analytics endpoint para sa pagsubaybay sa routing, compression, at pagkakaiba-iba ng provider. Ginagamit ng mga ito ang mga page na `/dashboard/analytics/*`. ### Analytics ng auto-routing | Paraan | Path | Paglalarawan | | ------ | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/auto-routing` | Pinagsama-samang estadistika ng auto-routing: kabuuang tawag, distribusyon ng strategy, distribusyon ng tier, mga nangungunang provider | | GET | `/api/analytics/auto-routing?days=7` | Mga estadistika ayon sa saklaw ng oras (default na 24h) | **Halimbawa ng tugon**: ```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 } ] } ``` ### Analytics ng compression | Paraan | Path | Paglalarawan | | ------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/compression` | Pinagsama-samang estadistika ng compression: mga natipid na token, porsiyento ng natipid, distribusyon ng mode, paggamit ng engine | **Halimbawa ng tugon**: ```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 } } ``` ### Pagsubaybay sa pagkakaiba-iba ng provider | Paraan | Path | Paglalarawan | | ------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/diversity` | Pagsubaybay sa pagkakaiba-iba batay sa Shannon entropy: pinipigilan ang mga single point of failure sa pamamagitan ng pagsukat sa pagkakalat ng provider | **Halimbawa ng tugon**: ```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"] } ``` **Auth:** Nangangailangan ng session sa pamamahala o API key na may saklaw sa pamamahala. --- ## Mga Operasyon ng Admin Mga endpoint na para lamang sa admin para sa pamamahala ng operasyon. | Paraan | Path | Paglalarawan | | ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------ | | GET | `/api/admin/concurrency` | Basahin ang kasalukuyang mga limitasyon sa concurrency (pangkalahatan + bawat provider) | | POST | `/api/admin/concurrency` | I-update ang mga limitasyon sa concurrency — body: `{global?: number, perProvider?: Record}` | **Awtorisasyon:** Nangangailangan ng session sa pamamahala na may saklaw na admin. --- ## Pamamahala ng mga CLI Tool Pamahalaan ang mga CLI tool na nagsasama sa OmniRoute (antigravity, chipotle, commandCode, devin-cli, atbp.). Tingnan ang [Sanggunian ng Provider](./PROVIDER_REFERENCE.md) para sa kumpletong listahan. | Paraan | Path | Paglalarawan | | ------ | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/cli-tools/all-statuses` | Katayuan ng lahat ng CLI tool (naka-install, bersyon, huling nakita) | | GET | `/api/cli-tools/status` | Mga detalye ng katayuan para sa isang CLI tool (`?tool=` query) | | POST | `/api/cli-tools/apply` | Isulat ang nabuong config ng tool (nagbibigay ang `dryRun` ng preview; `422` + `containerEphemeralTarget` kapag nasa container; itinatala ng `migration` ang legacy na Codex YAML) | | GET | `/api/cli-tools/backups` | Ilista ang mga backup ng configuration ng CLI tool | | POST | `/api/cli-tools/backups` | Gumawa ng backup ng lahat ng configuration ng CLI tool | | POST | `/api/cli-tools/backups` | I-restore: nire-restore ng parehong endpoint na may `{tool, backupId}` sa body ang backup na iyon | | GET | `/api/cli-tools/antigravity-mitm` | Katayuan ng Antigravity MITM proxy (ang "antigravity-mitm" CLI tool) | | POST | `/api/cli-tools/antigravity-mitm/alias` | I-configure ang mga alias ng antigravity-mitm | **Awtorisasyon:** Nangangailangan ng session sa pamamahala. --- ## Mga Kasanayan ng Agent Pamahalaan ang mga kasanayan ng AI agent (katulad ng mga custom GPT ng OpenAI ngunit para sa mga agent). | Paraan | Path | Paglalarawan | | ------ | ---------------------------- | -------------------------------------------------------------------------------------------------- | | GET | `/api/agent-skills` | Ilista ang lahat ng kasanayan ng agent (built-in + custom) | | GET | `/api/agent-skills/[id]` | Kunin ang isang partikular na kasanayan ng agent | | POST | `/api/agent-skills` | Gumawa ng custom na kasanayan ng agent — body: `{name, description, prompt, model?, temperature?}` | | PUT | `/api/agent-skills/[id]` | I-update ang custom na kasanayan ng agent | | DELETE | `/api/agent-skills/[id]` | Tanggalin ang custom na kasanayan ng agent | | GET | `/api/agent-skills/[id]/raw` | Kunin ang raw na prompt + metadata (walang pagpapatupad) | | POST | `/api/agent-skills/generate` | Bumuo gamit ang AI ng bagong kasanayan mula sa paglalarawan sa natural na wika | **Awtorisasyon:** Nangangailangan ng session sa pamamahala o API key na may saklaw sa pamamahala. --- ## Pamamahala ng Cache Pamahalaan ang semantic cache at reasoning cache. | Paraan | Path | Paglalarawan | | ------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------- | | GET | `/api/cache` | Pangkalahatang-ideya ng cache: kabuuang entry, hit rate, laki sa disk | | GET | `/api/cache/entries` | Ilista ang mga naka-cache na entry (may pagination) | | DELETE | `/api/cache/entries` | Tanggalin ang mga entry sa cache (i-filter ayon sa mga query parameter) | | GET | `/api/cache/stats` | Detalyadong estadistika ng cache (bawat provider, bawat model) | | GET | `/api/cache/reasoning` | Katayuan ng reasoning cache (para sa reasoning replay) | | DELETE | `/api/cache/reasoning` | I-clear ang reasoning cache — mga query param: `?toolCallId=` (isa) o `?provider=

` o walang param (lahat) | **Awtorisasyon:** Nangangailangan ng management session. --- ## Sistema ng Memory Pamahalaan ang persistent memory (FTS5 + vector embeddings). | Paraan | Path | Paglalarawan | | ------ | ------------------ | ------------------------------------------------------------------------------ | | GET | `/api/memory` | Ilista ang mga entry sa memory (i-filter ayon sa scope, type, at search query) | | POST | `/api/memory` | Gumawa ng bagong entry sa memory — body: `{scope, type, content, metadata?}` | | GET | `/api/memory/[id]` | Kunin ang isang partikular na entry sa memory | | PUT | `/api/memory/[id]` | I-update ang isang entry sa memory | | DELETE | `/api/memory/[id]` | Tanggalin ang isang entry sa memory | | GET | `/api/memory?q=` | Maghanap sa memory (FTS5 + vector) — kasama ang stats sa parehong tugon | **Awtorisasyon:** Nangangailangan ng management session o API key na may management scope. --- ## Mga Webhook Pamahalaan ang mga subscription sa webhook para sa mga event. | Paraan | Path | Paglalarawan | | ------ | ------------------------------- | ------------------------------------------------------------------------------- | | GET | `/api/webhooks` | Ilista ang lahat ng subscription sa webhook | | POST | `/api/webhooks` | Gumawa ng subscription sa webhook — body: `{url, events[], secret?, active?}` | | GET | `/api/webhooks/[id]` | Kunin ang isang partikular na subscription sa webhook | | PUT | `/api/webhooks/[id]` | I-update ang isang subscription sa webhook | | DELETE | `/api/webhooks/[id]` | Tanggalin ang isang subscription sa webhook | | GET | `/api/webhooks/[id]/deliveries` | Ilista ang kasaysayan ng delivery para sa isang webhook (log ng tagumpay/palya) | | POST | `/api/webhooks/[id]/test` | Magpadala ng pansubok na event sa isang webhook | **Awtorisasyon:** Nangangailangan ng management session. Tingnan ang [Framework ng Mga Webhook](../frameworks/WEBHOOKS.md) para sa lahat ng uri ng event. --- ## Framework ng Skills Pamahalaan ang Skills (ang framework ng mga agentic extension). | Pamamaraan | Path | Paglalarawan | | ---------- | ------------------------ | -------------------------------------------------------------------------------------------- | | GET | `/api/skills` | Ilista ang lahat ng naka-install na skill (built-in + custom) | | POST | `/api/skills/install` | Mag-install ng skill mula sa lokal na path o URL | | DELETE | `/api/skills/[id]` | Mag-uninstall ng skill | | PUT | `/api/skills/[id]` | I-enable o i-disable ang skill — body: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` | | POST | `/api/skills/executions` | Magpatakbo ng skill — body: `{skillName, apiKeyId, input?, sessionId?}` | | GET | `/api/skills/executions` | Ilista ang kasaysayan ng pagpapatakbo para sa lahat ng skill (i-filter ayon sa `?apiKeyId=`) | **Auth:** Nangangailangan ng session sa pamamahala o API key na may saklaw sa pamamahala. Tingnan ang [Framework ng Skills](../frameworks/SKILLS.md) para sa kumpletong detalye. --- ## Mga Plugin Pamahalaan ang mga plugin ng OmniRoute (mga third-party extension). | Pamamaraan | Path | Paglalarawan | | ---------- | ---------------------------------- | ----------------------------------------- | | GET | `/api/plugins` | Ilista ang mga naka-install na plugin | | POST | `/api/plugins/marketplace/install` | Mag-install ng plugin mula sa marketplace | | DELETE | `/api/plugins/[name]` | Mag-uninstall ng plugin | | POST | `/api/plugins/[name]/activate` | I-activate ang plugin | | POST | `/api/plugins/[name]/deactivate` | I-deactivate ang plugin | | GET | `/api/plugins/[name]/config` | Kunin ang configuration ng plugin | | PUT | `/api/plugins/[name]/config` | I-update ang configuration ng plugin | **Auth:** Nangangailangan ng session sa pamamahala. Tingnan ang [Framework ng Mga Plugin](../frameworks/PLUGIN_SDK.md) para sa kumpletong detalye. --- ## Shadow Routing Ang shadow / A-B comparison ng mga provider ay **hindi isang standalone na REST surface** — kino-configure ito sa pamamagitan ng combo routing (tingnan ang [Auto-Combo](../routing/AUTO-COMBO.md)). Ang mga metric ng paghahambing sa bawat combo ay ibinibigay ng `GET /api/combos/metrics`. --- ## Mga Guardrail Suriin ang mga runtime guardrail (PII detection, prompt injection detection, vision bridging). Tumatakbo ang mga guardrail sa bawat request; ang pag-opt out sa bawat call ay sa pamamagitan ng `x-omniroute-disabled-guardrails` request header — walang naka-persist na surface para i-enable/i-disable ito. | Pamamaraan | Path | Paglalarawan | | ---------- | ---------------------- | ------------------------------------------------------------------------------------------------------ | | GET | `/api/guardrails` | Ilista ang mga nakarehistrong guardrail at ang status ng mga ito (pangalan / naka-enable / priyoridad) | | POST | `/api/guardrails/test` | I-dry-run ang pre-call pipeline sa isang sample na input — body: `{input, disabledGuardrails?}` | **Auth:** Nangangailangan ng session sa pamamahala. Tingnan ang [Seguridad > Mga Guardrail](../security/GUARDRAILS.md) para sa kumpletong detalye. --- --- ## Pagpapatunay Tingnan ang [Pagpapatunay sa Pamamahala](../guides/MANAGEMENT-AUTH.md) para sa apat na pamilya ng kredensyal (session ng dashboard, lokal na CLI token, `oma_live_…` Access Token, API key na may saklaw na pamamahala) at kung paano naiiba ang mga ito sa mga inference key. - Gumagamit ang mga ruta ng dashboard (`/dashboard/*`) ng `auth_token` cookie - Ginagamit sa pag-login ang naka-save na password hash; babalik sa `INITIAL_PASSWORD` kung hindi ito magagamit - Maaaring i-toggle ang `requireLogin` sa pamamagitan ng `/api/settings/require-login` - Maaaring mangailangan ang mga rutang `/v1/*` ng Bearer API key kapag `REQUIRE_API_KEY=true` - Ang "token sa pamamahala" / "API key na may saklaw na pamamahala" sa sangguniang ito ay nangangahulugang isa sa mga pamilya sa gabay na iyon — hindi isang karagdagang uri ng sikretong hindi tinukoy > **Hindi backward-compatible na pagbabago (v3.8.0)** — Nangangailangan na ngayon ang `/api/v1/agents/tasks/*` at ang mga endpoint sa pamamahala ng cooldown ng **pagpapatunay sa pamamahala** (`auth_token` cookie ng dashboard o isang API key na may saklaw na pamamahala). Makakatanggap ang mga client na dating tumatawag sa mga rutang ito nang walang pagpapatunay ng `401 Unauthorized`. Tingnan ang commit na `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).