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

API Reference (Slovenčina)

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

---

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

Základná referenčná dokumentácia pre API OmniRoute. Zahŕňa verejné rozhranie /v1 a najčastejšie používané koncové body na správu; úplnými zdrojmi sú strojovo čitateľný súbor docs/openapi.yaml a strom trás v adresári src/app/api/.

---

Obsah

• Dokončenia chatu
• Exkluzívne prenájmy spravovaných relácií
• Vektorové reprezentácie
• Generovanie obrázkov
• OCR dokumentov
• Zoznam modelov
• Manifest doplnku poskytovateľa
• Koncové body kompatibility
• API súborov
• API dávok
• API vyhľadávania
• Streamovanie cez WebSocket
• Kvóty a nahlasovanie problémov
• Sémantická vyrovnávacia pamäť
• Ovládací panel a správa
• Správa kombinácií
• Webhooky
• Registrované kľúče (automatická správa)
• Protokol agentov
• Proxy servery na správu
• Odolnosť (rozšírená)
• Zručnosti
• Pamäť
• Server MCP
• Server A2A
• Cloud, vyhodnotenia a posudzovanie
• Spracovanie požiadaviek
• Autentifikácia

---

Dokončenia chatu

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
}

Vlastné hlavičky

Hlavička	Smer	Opis
X-OmniRoute-No-Cache	Požiadavka	Nastavením na true obídete vyrovnávaciu pamäť
x-omniroute-no-memory	Požiadavka	Nastavením na true sa pre túto požiadavku preskočí vkladanie pamäte a zručností (podobne ako bez vyrovnávacej pamäte; predíde sa réžii tokenov a nákladov pri každom volaní)
X-OmniRoute-Progress	Požiadavka	Nastavením na true povolíte udalosti priebehu
X-Session-Id	Požiadavka	Kľúč trvalej relácie pre externú afinitu relácie
x_session_id	Požiadavka	Akceptuje sa aj variant s podčiarkovníkom (priame HTTP)
X-OmniRoute-Session-Id	Požiadavka	Značka relácie/konverzácie zadaná volajúcim (používa sa aj pre pamäť). Ak je uvedená, uloží sa bez zmeny do call_logs.session_tag na priradenie nákladov k jednotlivým reláciám (#8249) — ak chýba, nikdy sa nevytvára
Idempotency-Key	Požiadavka	Kľúč na odstránenie duplicít (okno 5 s)
X-Request-Id	Požiadavka	Alternatívny kľúč na odstránenie duplicít
X-OmniRoute-Cache	Odpoveď	HIT alebo MISS (bez streamovania)
X-OmniRoute-Idempotent	Odpoveď	true, ak bola požiadavka deduplikovaná
X-OmniRoute-Progress	Odpoveď	enabled, ak je zapnuté sledovanie priebehu
X-OmniRoute-Session-Id	Odpoveď	Efektívne ID relácie použité službou OmniRoute
X-OmniRoute-Request-Id	Odpoveď	Korelačné ID požiadavky (ak je známe)
X-OmniRoute-Version	Odpoveď	Verzia zostavy OmniRoute (vždy uvedená)
X-OmniRoute-Cost-Saved	Odpoveď	Suma v USD, ktorú vyrovnávacia pamäť ušetrila pri HIT (iba pri zásahoch do vyrovnávacej pamäte)
X-OmniRoute-Decision	Odpoveď	Záznam smerovania: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> je stratégia kombinácie alebo single pri požiadavke bez kombinácie) — vždy je uvedený v odpovediach o dokončení

Poznámka k Nginx: ak sa spoliehate na hlavičky s podčiarkovníkmi (napríklad x_session_id), povoľte underscores_in_headers on;.

Hlavičky telemetrie nákladov: úspešné odpovede bez streamovania obsahujú aj súbor telemetrie nákladov X-OmniRoute-* — X-OmniRoute-Response-Cost (USD, pevne 10 desatinných miest; 0.0000000000 pre bezplatné položky alebo položky bez stanovenej ceny), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit a X-OmniRoute-Fallback-Attempts (iba keď > 0), spolu s X-OmniRoute-Request-Id a X-OmniRoute-Version. Tieto hlavičky poskytujú dokončenia chatu, /v1/responses, /v1/messages aj koncové body pre médiá — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations a /v1/moderations (náklady sú vždy 0). Náklady na médiá sa počítajú podľa modality (za obrázok, za sekundu, za znak, za vyhľadávaciu jednotku), ak sú k dispozícii ceny; v opačnom prípade sú 0 (fail-open).

Sémantika nákladov pri zásahu do vyrovnávacej pamäte: pri ZÁSAHU do sémantickej vyrovnávacej pamäte (X-OmniRoute-Cache-Hit: true) sa nevykoná žiadne volanie nadradenej služby, takže X-OmniRoute-Response-Cost je 0.0000000000 (prírastkové náklady na obslúženie zásahu). Pôvodné náklady, resp. náklady, ktoré by inak vznikli, sa uvádzajú samostatne v X-OmniRoute-Cost-Saved. Spotrebitelia fakturačných údajov by mali sčítavať X-OmniRoute-Response-Cost (zásahy nič nestoja); analytika vyrovnávacej pamäte môže agregovať X-OmniRoute-Cost-Saved.

Exkluzívne spravované prenájmy relácií

Exkluzívny prenájom spravovanej relácie je voliteľná zmluva smerovania nezávislá od klienta: jeden aktívny vlastník drží jedno oprávnené pripojenie OmniRoute. Neprenajíma model, nevyžaduje OAuth, neidentifikuje konkrétneho klienta ani nevyžaduje konkrétneho poskytovateľa.

Overovací API kľúč musí mať rozsah lease:exclusive a explicitný neprázdny zoznam allowedConnections. Hranica databázovej mutácie vynucuje obe polia spoločne pri vytváraní kľúča aj pri čiastočných aktualizáciách.

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

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

Úspešné odpovede na získanie, obnovenie a uvoľnenie uvádzajú časové pečiatky, state a presnú kladnú hodnotu generation, nikdy však nie vybrané pripojenie ani prihlasovacie údaje. Pri obnovení a uvoľnení sa generácia uvádza v tele JSON:

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

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

Vlastník aktívneho prenájmu môže explicitne požiadať o zobrazované metadáta svojho aktuálneho naviazania, ktoré neohrozujú súkromie:

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

{
  "state": "ACTIVE",
  "generation": 1,
  "acquiredAt": "2026-08-28T12:00:00.000Z",
  "renewedAt": "2026-08-28T12:00:30.000Z",
  "expiresAt": "2026-08-28T12:02:30.000Z",
  "connection": {
    "displayName": "Primary Codex",
    "provider": "codex"
  }
}

Táto voliteľná stavová akcia je v rámci jednej databázovej transakcie chránená nepriehľadným vlastníkom, overeným spravovaným API kľúčom a presnou aktívnou generáciou. displayName je iba orezaný nakonfigurovaný názov pripojenia; keď neexistuje bezpečný nakonfigurovaný názov, má hodnotu null. OmniRoute ho nikdy nenahrádza e-mailom ani vygenerovanou identitou účtu. Hodnota poskytovateľa je necitlivý zobrazovaný štítok a nikdy nejde o vygenerovaný identifikátor kompatibilného poskytovateľa. Prihlasovacie údaje, tokeny, súbory cookie, nespracované identifikátory pripojení alebo API kľúčov, haše vlastníkov, tajné hodnoty ohraničenia a interné údaje smerovania sú vylúčené.

Vyhľadávania s nesprávnym kľúčom, nesprávnym vlastníkom, zastaranou generáciou, chýbajúce, exspirované, uvoľnené aj zneplatnené vyhľadávania vracajú rovnakú chybu 409 LEASE_FENCE_STALE bez metadát pripojenia. Klient, ktorý dostal odpoveď o čakaní na kapacitu, nemá žiadne aktívne naviazanie, ktoré by mohol skontrolovať. Keď smerovanie zmení pripojenie aktívneho prenájmu, rovnaká generácia zostáva platná a stav atomicky vráti nové naviazanie, nikdy nie staré. Existujúci klienti zostávajú nezmenení, pretože odpovede na získanie, obnovenie, uvoľnenie a čakanie si zachovávajú svoje predchádzajúce štruktúry.

Táto serverová zmluva nemení štandardné /status služby OpenAI Codex. Štandardný Codex v súčasnosti uvádza svojho poskytovateľa modelu a vstavaný stav overenia/účtu, ale nezobrazuje ľubovoľné vlastné metadáta účtu poskytovateľa; budúca integrácia klienta musí zavolať túto akciu a rozhodnúť, ako zobraziť connection.displayName.

Každá spravovaná inferenčná požiadavka potom uvádza obe riadiace hlavičky:

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

Presný vlastník, generácia, aktívne pripojenie a overený API kľúč sú ohraničené bezprostredne pred každým podporovaným pokusom o prístup k upstreamu. Opätovné použitie vlastníka a generácie s iným kľúčom zlyhá, aj keď tento kľúč povoľuje rovnaké pripojenie. Nespracované hodnoty vlastníkov sa neuchovávajú, nezaznamenávajú do protokolov, neponechávajú v snímke požiadavky ani neposielajú upstreamu.

Dočasný konflikt vracia HTTP 429 s hlavičkou Retry-After a:

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

Táto odpoveď znamená iba to, že bežná množina oprávnených pripojení nebola prázdna a každý voľný kandidát bol držaný cudzím aktívnym prenájmom. Nepodporované modely/poskytovatelia, nesúlad so zásadami, doba čakania, kvóta, stav a ďalšie bežné zlyhania oprávnenosti si zachovávajú svoje existujúce odpovede OmniRoute.

x-omniroute-compression

Prepísanie plánu kompresie pre jednotlivú požiadavku. Má najvyššiu prioritu — prevažuje nad prepísaním kombinácie smerovania, aktívnym profilom, automatickým spúšťačom aj predvoleným nastavením panela. Hodnoty:

Hodnota	Účinok
off	Bez kompresie pre túto požiadavku.
default	Predvolený profil odvodený z panela (ignoruje aktívny profil).
engine:<id>	Jeden mechanizmus, ak je povolený, napr. engine:rtk.
<combo>	Pomenovaná kombinácia, najprv porovnaná podľa názvu (bez rozlišovania veľkosti písmen), potom podľa identifikátora.

Poznámky:

• Neznáme hodnoty sa ignorujú (požiadavka sa nikdy neodmietne); vyhodnocovanie pokračuje podľa bežného poradia priorít operátora.
• Ak má viacero kombinácií rovnaký názov, na deterministické priradenie zadajte id kombinácie.
• Kombináciu s názvom off alebo default nemožno vybrať podľa názvu (tieto kľúčové slová sa interpretujú ako prvé); na takúto kombináciu odkazujte pomocou jej identifikátora.
• Hlavný prepínač kompresie je neprekročiteľná podmienka: keď je kompresia globálne zakázaná, táto hlavička ju nemôže povoliť.

Použitý plán sa odošle späť v hlavičke odpovede:

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

kde <source> je jedna z hodnôt request-header, routing-override, active-profile, auto-trigger, default alebo off.

---

Vnorenia

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

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

Dostupní poskytovatelia: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.

Identifikátory katalógu majú formát provider/model (príklad: jina-ai/jina-embeddings-v5-omni-small). Samostatné identifikátory modelov Jina, ktoré sa nachádzajú v registri (napríklad jina-embeddings-v5-text-small, jina-reranker-v3.5), sa tiež rozpoznajú. Operácie embed/rerank/classify/segment služby Jina používajú najprv prihlasovacie údaje jina-ai z ovládacieho panela; JINA_AI_API_KEY sa použije ako záložná možnosť iba vtedy, keď neexistuje žiadny kľúč z ovládacieho panela. Karta jina-reader je určená iba pre Reader / r.jina.ai (POST /v1/web/fetch) a nikdy neposkytuje vnorenia ani opätovné zoradenie.

Modely v registri, ktoré deklarujú multimodálnu podporu, prijímajú aj najviac 32 štruktúrovaných položiek nezávislých od poskytovateľa. Typy mediálnych položiek sú text, image, audio, video a document. Ich mediálny source je buď {"type":"url","url":"https://..."}, alebo {"type":"base64","data":"...","media_type":"..."}.

Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano a alias rodiny jina-ai/jina-embeddings-v5-omni → omni-small) prijíma aj natívne dokumenty EmbeddingsV5Request služby Jina a preposiela ich bez zmien na https://api.jina.ai/v1/embeddings:

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

Natívne hodnoty { image | audio | video | pdf } môžu byť verejná URL adresa HTTPS, URI data: alebo nespracovaný base64. OmniRoute tieto objekty neprevádza na reťazce ani nenačítava natívne URL adresy obrázkov — verejné médiá načítava samotná služba Jina. Dodatočné polia Jina (task, normalized, truncate, embedding_type) sa preposielajú. Textové SKU služby Jina naďalej odmietajú netextové dokumenty.

Bezpečnostné a prenosové obmedzenia:

• Vzdialené URL adresy médií musia byť verejné a používať HTTPS. Kanonické položky {type,source:url} sa načítajú na strane servera (opätovné overenie presmerovaní, časový limit, obmedzenia veľkosti, verejný DNS, pripnutie pripojenia) a vložia sa priamo pred volaním poskytovateľa. Natívne položky Jina {image:"https://..."} sa po rovnakej kontrole verejného HTTPS prepošlú bez zmeny; URL adresu načíta Jina.
• Mediálny obsah base64 vložený priamo je obmedzený na 8 MiB dekódovaných dát na položku a 16 MiB dekódovaných dát v rámci požiadavky.

Preklad pre poskytovateľov (kanonické položky sa nikdy nepreposielajú bez zmien):

• Multimodálne modely Jina: každá položka najvyššej úrovne sa zmení na jeden objekt s kľúčom modality (text / image / audio / video / pdf), pričom pre priamo vložené médiá sa používajú dátové URI; jeden vektor na položku najvyššej úrovne.
• Rodina Gemini Embedding 2: jedno pole najvyššej úrovne sa zmení na jednu natívnu požiadavku models/{model}:embedContent s content.parts (text alebo inline_data).
• Neznáme/dynamické modely bez explicitných metadát modality odmietnu štruktúrovaný vstup s HTTP 400.

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

Nepodporované kombinácie modelu a modality vrátia HTTP 400 namiesto konverzie položky. Rozširujúce polia mimo input v starších požiadavkách s reťazcami/tokenmi sa naďalej preposielajú bez zmien.

# Zobraziť všetky modely vnorení
GET /v1/embeddings

---

Generovanie obrázkov

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

{
  "model": "openai/gpt-image-2",
  "prompt": "Nádherný západ slnka nad horami",
  "size": "1024x1024"
}

Dostupní poskytovatelia: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (lokálne), ComfyUI (lokálne).

# Zoznam všetkých modelov na generovanie obrázkov
GET /v1/images/generations

---

OCR dokumentov

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

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

model vyberá poskytovateľa OCR pomocou predpony provider/model; samotný identifikátor modelu (napr. mistral-ocr-latest) sa priradí k jeho registrovanému poskytovateľovi a pri vynechaní hodnoty model sa predvolene použije Mistral (mistral-ocr-latest). Registrovaní poskytovatelia (open-sse/config/ocrRegistry.ts):

Identifikátor poskytovateľa	Identifikátor modelu	Hodnota model	Poznámky
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest (alebo iba mistral-ocr-latest)	Synchrónne — odpoveď sa vráti priamo z jediného volania nadradenej služby.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	Asynchrónna nadradená služba (analyze + dopytovanie) — pozrite nižšie.
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	Synchrónne, prostredníctvom partnerského koncového bodu Vertex AI openapi/chat/completions — podrobnosti o autentifikácii/adrese URL nájdete nižšie.

Všetci traja poskytovatelia odpovedajú v rovnakom tele v tvare Mistral:

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

Priebeh dopytovania Azure Document Intelligence

Rozhranie API analyze služby Azure Document Intelligence je asynchrónne: počiatočná požiadavka namiesto tela vráti hlavičku Operation-Location a výsledok sa musí opakovane zisťovať. Obslužná rutina (open-sse/handlers/ocr.ts) zisťuje stav na danej adrese URL každú sekundu, najviac počas 30 pokusov, okamžite zlyhá (v zisťovaní nepokračuje), ak odpoveď na zisťovanie nemá stav ok alebo má stav "failed", a vráti 504, ak operácia po vyčerpaní počtu pokusov stále prebieha. Konečná odpoveď Azure sa pred vrátením volajúcemu normalizuje do rovnakého tvaru pages/markdown, aký používa Mistral, takže klientsky kód nemusí pre poskytovateľa implementovať osobitné spracovanie.

Autentifikácia a určenie koncového bodu OCR DeepSeek v službe Vertex AI

vertex-deepseek-ocr opätovne používa rovnakú autentifikáciu Vertex AI, ktorú OmniRoute už podporuje pre prenos konverzácií/obrázkov (open-sse/executors/vertex.ts): kľúč API pripojenia je buď poverenie Service Account vo formáte JSON (vymenené za krátkodobý prístupový token OAuth prostredníctvom postupu JWT-bearer), alebo už vydaný prístupový token OAuth, ktorý sa použije bez zmeny. Adresa URL nadradeného koncového bodu je všeobecný partnerský koncový bod Vertex openapi/chat/completions, zostavený z projektu a regiónu pripojenia — explicitné hodnoty providerSpecificData.project/providerSpecificData.region majú vždy prednosť; v opačnom prípade sa projekt odvodí z hodnoty project_id v JSON Service Account a región má predvolenú hodnotu us-central1. Obe hodnoty sa určujú v súbore open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl) a pred odoslaním do handleOcr ich používa src/app/api/v1/ocr/route.ts.

---

Zoznam modelov

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

→ Vráti všetky chatovacie, embeddingové a obrazové modely + kombinácie vo formáte OpenAI

Predpony id modelov (?prefix=)

Väčšina modelov sa uvádza s predponou poskytovateľa. To, ktorú predponu získate, riadi príznak funkcie MODELS_CATALOG_PREFIX_MODE a možno ho prepísať pre každú požiadavku pomocou parametra dotazu — užitočné pre klienta, ktorý chce prehľadný zoznam bez zmeny nastavenia platného pre celý server a všetkých ostatných:

GET /v1/models?prefix=alias        # jedno id pre každý model — krátka predpona aliasu
GET /v1/models?prefix=dual         # obe formy (predvolené nastavenie servera)
GET /v1/models?prefix=canonical    # iba úplná predpona id poskytovateľa

Režim	Vypisuje	Poznámky
dual	cc/claude-sonnet-4-6 a claude/claude-sonnet-4-6	Predvolené. Obe id smerujú na rovnaký model; zachované, aby konfigurácie klientov, ktoré mali napevno nastavenú ktorúkoľvek formu, naďalej fungovali. Katalóg sa približne zdvojnásobí.
alias	cc/claude-sonnet-4-6	Jedna položka na model. Poskytovatelia bez samostatného aliasu naďalej vypisujú svoju položku, takže sa nič nestratí.
canonical	claude/claude-sonnet-4-6	Jedna položka na model pod úplnou predponou id poskytovateľa. Poskytovatelia bez samostatného aliasu (napr. antigravity/…, agy/…) tu tiež vypisujú svoje jediné id, takže sa nič nestratí.

Zrkadlovú položku režimu dual možno rozpoznať aj bez parametra dotazu: obsahuje pole parent odkazujúce na primárne id.

Klienti, ktorí zobrazujú výber modelu, by mali požadovať ?prefix=alias — takto to robí rozšírenie OmniCopilot pre VS Code.

Varianty modelov bez premýšľania

Pre modely Claude podporujúce premýšľanie uvádza /v1/models aj variant bez premýšľania, ktorého id má predponu claude-3-omniroute-no-thinking/:

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

Výberom tohto id (napr. v konfigurácii Claude Code, ktorá vždy pripája blok thinking) sa požiadavka presmeruje späť na skutočný model <provider>/<model> s potlačeným odôvodňovaním — thinking:{type:"disabled"} na ceste /v1/messages alebo s vynechanými poľami reasoning/reasoning_effort na ceste /v1/chat/completions. Variant sa uvádza iba pre modely z rodiny Claude, ktoré podporujú premýšľanie a rešpektujú hodnotu disabled (takže sú napr. vylúčené modely fungujúce iba v adaptívnom režime, ktoré hodnotu disabled odmietajú). Prevádzkovatelia môžu tento variant pre jednotlivé modely vynútiť alebo vypnúť prostredníctvom ModelSpec.noThinkingAlias.

---

Manifest doplnku poskytovateľa

GET /api/v1/provider-plugin-manifest

Vráti manifest doplnkov poskytovateľov kompatibilný s formátom JSON, ktorý používajú Bifrost, CLIProxyAPI a budúce smerovače typu sidecar. Odpoveď sa generuje z registra poskytovateľov v TypeScripte a zámerne neobsahuje klientske tajomstvá OAuth, rozlíšenie prostredia za behu, vykonávacie funkcie, hlavičky požiadaviek ani údaje účtov.

Tento koncový bod použite, keď sidecar beží mimo procesu a nemôže priamo importovať open-sse/config/providerPluginManifestRegistry.ts.

---

Koncové body kompatibility

Metóda	Cesta	Formát
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 (úprava/inpainting)
POST	/v1/videos/generations	Generovanie videa v štýle OpenAI
POST	/v1/music/generations	Generovanie hudby v štýle OpenAI
POST	/v1/audio/transcriptions	OpenAI Audio (STT)
POST	/v1/audio/speech	OpenAI TTS (vracia zvukové telo)
POST	/v1/rerank	Preusporiadanie v štýle Cohere/Voyage
POST	/v1/classify	Klasifikácia Jina (api.jina.ai)
POST	/v1/segment	Segmentátor Jina (segment.jina.ai)
POST	/v1/moderations	OpenAI Moderations
GET	/v1/models	OpenAI
POST	/v1/messages/count_tokens	Anthropic
GET	/v1beta/models	Gemini
POST	/v1beta/models/{...path}	Gemini generateContent
POST	/v1/api/chat	Ollama
GET	/api/v1/vscode/{token}/	Alias katalógu OpenAI
GET	/api/v1/vscode/{token}/models	Alias modelov OpenAI
POST	/api/v1/vscode/{token}/chat/completions	Tokenizovaný alias OpenAI
POST	/api/v1/vscode/{token}/responses	Tokenizovaný alias OpenAI Responses
POST	/api/v1/vscode/{token}/api/chat	Tokenizovaný alias Ollama
GET	/api/v1/vscode/{token}/api/tags	Tokenizovaný alias značiek Ollama

Všetky trasy POST majú rovnakú štruktúru: Bearer your-api-key + telo JSON overené pomocou Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema atď.; pozrite si src/shared/validation/schemas.ts). Pri zlyhaní overenia schémy sa vráti stav 4xx.

Klientom, ktoré nemôžu pripojiť Authorization: Bearer ..., OmniRoute umožňuje odovzdať kľúče API aj v adrese URL, a to buď prostredníctvom kompatibilných parametrov reťazca dopytu (?token=..., ?apiKey=..., ?api_key=..., ?key=...), alebo pomocou vyhradených koncových bodov /api/v1/vscode/{token}/... zdokumentovaných nižšie.

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

# Klasifikácia Jina (prihlasovacie údaje Foundation API)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Segmentátor Jina
POST /v1/segment     { "content": "...", "return_chunks": true }

# Vyhľadávanie Jina (s.jina.ai; aliasy poskytovateľov: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

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

# TTS — vracia telo audio/mpeg (alebo požadovaný formát)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Úprava obrázka (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Generovanie videa/hudby (ID modelu s predponou poskytovateľa)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Vyhradené trasy poskytovateľov

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

Ak predpona poskytovateľa chýba, pridá sa automaticky. Pri nezhodujúcich sa modeloch sa vráti stav 400.

---

Files API

Koncový bod kompatibilný s OpenAI na prácu so súbormi pre dávkový vstup/výstup a nahrávanie súborov s určeným účelom.

Metóda	Cesta	Popis
POST	/v1/files	Nahrá súbor (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — max. 512 MiB
GET	/v1/files	Zobrazí zoznam súborov pre overený kľúč API
GET	/v1/files/[id]	Načíta metadáta súboru
DELETE	/v1/files/[id]	Odstráni súbor
GET	/v1/files/[id]/content	Odošle nespracované telo súboru späť formou streamu

Overenie: Kľúč API typu Bearer — súbory sú vymedzené podľa jednotlivých kľúčov API prostredníctvom getApiKeyRequestScope. Kľúč vidí, sťahuje a odstraňuje iba svoje vlastné súbory; relácia ovládacieho panela bez kľúča má prístup na čítanie v rámci celej inštancie; súbor bez vlastníka (anonymné nahratie alebo nahratie prostredníctvom relácie ovládacieho panela) je zamietnutý každému volajúcemu bez relácie. GET /v1/files odmietne anonymného volajúceho — aj zadaný kľúč, ktorý sa nepodarí rozpoznať — s kódom 401, a to aj vtedy, keď REQUIRE_API_KEY=false, namiesto zobrazenia súborov všetkých nájomníkov (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

Batches API

Dávkové spracovanie kompatibilné s OpenAI.

Metóda	Cesta	Popis
POST	/v1/batches	Vytvorí dávku — telo overené pomocou v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET	/v1/batches	Zobrazí zoznam dávok
GET	/v1/batches/[id]	Načíta stav dávky + request_counts
DELETE	/v1/batches/[id]	Odstráni dokončenú/neúspešnú dávku
POST	/v1/batches/[id]/cancel	Zruší prebiehajúcu dávku

Overenie: Kľúč API typu Bearer. Dávky sú vymedzené podľa jednotlivých kľúčov API na základe rovnakého trojstranného pravidla ako súbory: iba vlastný kľúč, relácia ovládacieho panela v rámci celej inštancie, záznamy s nulovým vlastníkom zamietnuté každému volajúcemu bez relácie (načítanie, odstránenie, zrušenie a kontrola input_file_id pri vytváraní). GET /v1/batches odmietne anonymného volajúceho s kódom 401, a to aj vtedy, keď REQUIRE_API_KEY=false.

---

API vyhľadávania

Abstrakcia poskytovateľov webového vyhľadávania (Tavily, Brave, Exa, Serper atď.).

Metóda	Cesta	Popis
GET	/v1/search	Zoznam nakonfigurovaných poskytovateľov vyhľadávania + ich možnosti
POST	/v1/search	Spustenie vyhľadávacieho dopytu — telo validuje v1SearchSchema, podporuje vyrovnávaciu pamäť/zlučovanie
GET	/v1/search/analytics	Štatistiky zásahov/latencie/vyrovnávacej pamäte podľa poskytovateľa

Autentifikácia: API kľúč typu Bearer (extractApiKey + isValidApiKey). Pravidlá vyhľadávania sa vynucujú prostredníctvom enforceApiKeyPolicy.

---

API načítania webu

Extrahuje obsah z URL prostredníctvom nakonfigurovaného poskytovateľa načítania webu (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

Metóda	Cesta	Popis
POST	/v1/web/fetch	Načítanie/extrakcia URL — telo validuje v1WebFetchSchema

Autentifikácia: API kľúč typu Bearer (extractApiKey + isValidApiKey). Pravidlá sa vynucujú prostredníctvom enforceApiKeyPolicy.

Záložný mechanizmus zohľadňujúci kvóty (#8297): keď nie je zadaný explicitný provider, fond (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) sa prechádza v pevnom poradí priorít (najprv sa naplní prvý) — poskytovateľ, ktorý je nakonfigurovaný, ale má obmedzenú frekvenciu požiadaviek, sa preskočí namiesto okamžitého ukončenia požiadavky a opakovateľné zlyhanie nadradenej služby alebo zlyhanie spôsobené kvótou (HTTP 429 vždy; 402/403 pre bezplatné úrovne Firecrawl/Tavily/TinyFish so štýlom kvót — nie pre Jina Reader a nikdy nie pre obyčajnú chybnú požiadavku 400) spôsobí počas spracovania požiadavky prechod na ďalšieho ešte nevyskúšaného poskytovateľa s prihlasovacími údajmi. Keď sa vyčerpajú všetci poskytovatelia vo fonde, koncový bod vráti jednu odpoveď 429 (s hlavičkou Retry-After) namiesto predchádzajúcej všeobecnej odpovede 400. Keď je vyžiadaný explicitný provider, nepoužije sa žiadny tichý záložný mechanizmus — explicitný poskytovateľ s obmedzenou frekvenciou požiadaviek alebo so zlyhaním vráti vlastnú chybu (429 pri obmedzení frekvencie požiadaviek, inak stav nadradenej služby).

---

Streamovanie cez WebSocket

GET /v1/ws?handshake=1

Overí nadviazanie spojenia s prechodom na WebSocket a vráti vzorové správy drôtového protokolu (request, cancel). Skutočné rámce WS spracúva pribalený server WS mimo tabuľky trás Next.js.

Autentifikácia: API kľúč typu Bearer počas nadväzovania spojenia.

Responses API cez WebSocket (iba codex)

# Rovnaký hostiteľ:port ako HTTP API (predvolene 20128); prepnite pripojenie:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (alebo: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Prvý rámec MUSÍ byť response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Proxy Responses-API-over-WebSocket je prepojené výhradne s codex (backend ChatGPT). Počúva na rovnakom porte ako API/ovládací panel na cestách /v1/responses, /responses a /api/v1/responses. Pri prvom rámci response.create vykoná autentifikáciu + prípravu prostredníctvom interného mosta codex-responses-ws, vyberie pripojenie OAuth codex a vytvorí tunel k wss://chatgpt.com/backend-api/codex/responses prostredníctvom transportu wreq-js. Modely, ktoré nie sú codex, sa odmietnu (codex_ws_provider_required). Na smerovanie podľa zdieľania kvóty použite model: "qtSd/<group>/codex/<model>". Implementované v app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.

Autentifikácia: API kľúč typu Bearer počas nadväzovania spojenia. Pribalený HTTP server (server-ws.mjs) musí byť aktívnym vstupným bodom (predvolene ním je, keď existuje app/server-ws.mjs).

ID modelu: použite základné ID ChatGPT (bez predpony codex/)

Codex CLI od OpenAI overuje názov modelu na strane klienta, keď je supports_websockets = true, a odmieta ID s predponou poskytovateľa, ako napríklad codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Odošlite základné ID (napr. gpt-5.5). Most OmniRoute je určený iba pre codex, takže pred vytvorením tunela k nadradenej službe opätovne vyhodnotí základné ID ako model codex (resolveCodexWsModelInfo) — aj keď by sa inak základné gpt-5.5 cez HTTP smerovalo k inému poskytovateľovi.

Konfigurácia OpenAI Codex CLI

Nasmerujte Codex CLI na OmniRoute pridaním vlastného poskytovateľa s podporou WebSocket do ~/.codex/config.toml (použite samostatný CODEX_HOME, aby ste nezasiahli do existujúcej konfigurácie):

model = "gpt-5.5"                 # základné ID — NIE "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # bez koncovej lomky; URL WS sa odvodí (v produkcii použite https/wss)
wire_api = "responses"                    # jediná podporovaná hodnota od februára 2026
supports_websockets = true                # povoľuje transport Responses-over-WS
env_key = "OMNIROUTE_API_KEY"             # obsahuje API kľúč OmniRoute (Bearer)

export OMNIROUTE_API_KEY=sk-...           # API kľúč OmniRoute (ľubovoľný kľúč, ak REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

CLI prepne base_url + /responses na WebSocket a OmniRoute vytvorí tunel k vybranému pripojeniu OAuth codex. Overené od začiatku do konca voči lokálnemu serveru: ChatGPT vracia codex.rate_limits + response.created a streamuje dokončenie.

---

Kvóty a hlásenie problémov

Metóda	Cesta	Popis
GET	/v1/quotas/check	Predbežne overí kvótu pre provider + accountId pred vydaním registrovaného kľúča
POST	/v1/issues/report	Nahlási zlyhanie kvóty alebo vydania kľúča na GitHub (vyžaduje GITHUB_ISSUES_REPO + token)

Autentifikácia: API kľúč Bearer (isAuthenticated).

---

Samoobslužné zobrazenie využitia (/api/usage/om-usage)

Každý API kľúč môže načítať svoje vlastné využitie a kvóty — bez autentifikácie na správu. Toto je koncový bod, ktorý klient (CLI, panel OmniCopilot) používa na zobrazenie výdavkov držiteľovi kľúča.

# Textová forma (historický kontrakt — obyčajný text pre terminál)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Štruktúrovaná forma — používaná používateľským rozhraním
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

Kľúč musí mať povolené allowUsageCommand (predvolene je vypnuté — správca API kľúčov na riadiacom paneli ho prepína pre jednotlivé kľúče). Bez tohto povolenia koncový bod odpovie stavom 403.

?format=json vracia rozlíšenú štruktúru, takže volajúci nikdy nečíta dátové pole z odmietnutej odpovede. Pri úspechu:

{
  "allowed": true,
  // prítomné iba vtedy, keď kľúč používa limity využitia pre konkrétny kľúč (denné/týždenné v USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // snímka kvóty vybraného poskytovateľa alebo null, ak zatiaľ nie je nič uložené vo vyrovnávacej pamäti:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // snímky všetkých pripojení, aby používateľské rozhranie mohlo zobraziť viacerých poskytovateľov vedľa seba:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

Pri odmietnutí (401 neplatný kľúč / 403 nepovolené) tá istá trasa vráti { "allowed": false, "error": { "message": "…" } } — prítomná, ale prázdna hodnota personal/provider (kľúč je povolený, ale zatiaľ sa nič nezistilo) predstavuje iný stav než odmietnutie a rozlišuje ich iba forma JSON.

Autentifikácia: vlastný API kľúč Bearer volajúceho, overený pomocou isValidApiKey — toto nie je rozhranie správy (/api/keys/…), ktoré zostáva chránené pomocou requireManagementAuth.

---

Sémantická vyrovnávacia pamäť

# Získanie štatistík vyrovnávacej pamäte
GET /api/cache/stats

# Vymazanie všetkých vyrovnávacích pamätí
DELETE /api/cache/stats

Príklad odpovede:

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

Vplyv na latenciu

ZÁSAH do sémantickej vyrovnávacej pamäte poskytne odpoveď z vyrovnávacej pamäte bez volania nadradenej služby, takže hlásená hodnota X-OmniRoute-Response-Latency je takmer nulová (bez ohľadu na pôvodnú latenciu nadradenej služby). Klienti citliví na latenciu (benchmarking, monitorovanie p50/p99) by mali skontrolovať hlavičku odpovede X-OmniRoute-Cache-Latency:

Hodnota	Význam
synthetic	Odpoveď poskytnutá z vyrovnávacej pamäte; latencia nie je skutočným časom nadradenej služby
(chýba)	Odpoveď zo skutočného volania nadradenej služby

Obídenie vyrovnávacej pamäte podľa kľúča

API kľúče môžu pomocou cacheDefaultMode vypnúť čítanie zo sémantickej vyrovnávacej pamäte:

Hodnota	Správanie
legacy	Normálne správanie vyrovnávacej pamäte (predvolené)
bypass	Úplne preskočí vyhľadávanie vo vyrovnávacej pamäti; vždy zavolá nadradenú službu

Nastavte pri vytvorení kľúča (POST /api/keys) alebo pri aktualizácii (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

Obídenie pre jednotlivú požiadavku

Každá požiadavka môže obísť vyrovnávaciu pamäť bez ohľadu na nastavenia kľúča:

X-OmniRoute-No-Cache: true

---

Ovládací panel a správa

Trasy správy (/api/* okrem verejného overenia/prihlásenia) nie sú autorizované bežnými API kľúčmi pre inferenciu. Rodiny prihlasovacích údajov, rozsahy a príklady curl: Overenie správy.

Overenie

Koncový bod	Metóda	Popis
/api/auth/login	POST	Prihlásenie
/api/auth/logout	POST	Odhlásenie
/api/settings/require-login	GET/PUT	Zapnutie/vypnutie požiadavky na prihlásenie

Správa poskytovateľov

Koncový bod	Metóda	Popis
/api/providers	GET/POST	Zobrazenie zoznamu/vytvorenie poskytovateľov
/api/providers/[id]	GET/PUT/DELETE	Správa poskytovateľa
/api/providers/[id]/test	POST	Test pripojenia k poskytovateľovi
/api/providers/[id]/models	GET	Zobrazenie zoznamu modelov poskytovateľa
/api/providers/validate	POST	Overenie konfigurácie poskytovateľa
/api/providers/bulk	POST	Hromadné pridanie API kľúčov pre JEDNÉHO poskytovateľa
/api/providers/import	POST	Import heterogénneho ZOZNAMU poskytovateľov zo spracovaného súboru CSV/JSON (#6836); výsledky čiastočných zlyhaní podľa riadkov
/api/provider-nodes*	Rôzne	Správa uzlov poskytovateľov
/api/provider-models	GET/POST/PATCH/DELETE	Vlastné modely (pridanie, aktualizácia, skrytie/zobrazenie, odstránenie)

Toky OAuth

Koncový bod	Metóda	Popis
/api/oauth/[provider]/[action]	Rôzne	OAuth špecifické pre poskytovateľa

Smerovanie a konfigurácia

Koncový bod	Metóda	Popis
/api/models/alias	GET/POST	Aliasy modelov
/api/models/catalog	GET	Všetky modely podľa poskytovateľa a typu
/api/combos*	Rôzne	Správa kombinácií
/api/keys*	Rôzne	Správa API kľúčov
/api/pricing	GET	Ceny modelov

Používanie a analytika

Endpoint	Metóda	Popis
/api/usage/history	GET	História používania
/api/usage/logs	GET	Záznamy používania
/api/usage/request-logs	GET	Záznamy na úrovni požiadaviek
/api/usage/[connectionId]	GET	Používanie podľa pripojenia
/api/usage/token-limits	GET/POST/DELETE	Rozpočty limitov tokenov podľa kľúča API
/api/usage/model-latency-stats	GET	Priebežná agregácia latencie podľa poskytovateľa/modelu (priemer/p50/p95/p99, miera úspešnosti); filtre: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health	GET	Súhrn stavu vyrovnávacej pamäte promptov nad call_logs — pomer zápisov/čítaní, distribúcia veľkosti zápisov p50/p90/p99, koncentrácia objemných zápisov, rozdelenie podľa modelu a výsledné hodnotenie healthy/degraded/thrash/no-data; parametre dopytu range (1h|24h|7d|30d, predvolené 24h) a voliteľný parameter model (#8827)

Nastavenia

Endpoint	Metóda	Popis
/api/settings	GET/PUT/PATCH	Všeobecné nastavenia
/api/settings/proxy	GET/PUT	Konfigurácia sieťového proxy servera
/api/settings/proxy/test	POST	Test pripojenia k proxy serveru
/api/settings/ip-filter	GET/PUT	Zoznam povolených/blokovaných IP adries
/api/settings/thinking-budget	GET/PUT	Režim prepisovania požiadaviek pre premýšľanie/uvažovanie (bez zmeny / automatické odstránenie / vlastný / adaptívny). Nezávisí od kompresie. Pozrite si THINKING_BUDGET.md.
/api/settings/system-prompt	GET/PUT	Globálny systémový prompt
/api/settings/compression	GET/PUT	Globálna konfigurácia kompresie
/api/settings/purge-request-history	POST	Vymazanie riadkov denníka požiadaviek a lokálnych artefaktov denníka volaní

Kontext a kompresia

Koncový bod	Metóda	Popis
/api/compression/preview	POST	Náhľad kompresie off/lite/standard/aggressive/ultra/RTK/stacked
/api/compression/language-packs	GET	Zoznam dostupných jazykových balíkov Caveman
/api/compression/rules	GET	Zoznam metadát pravidiel Caveman
/api/context/caveman/config	GET/PUT	Alias nastavení špecifických pre Caveman
/api/context/rtk/config	GET/PUT	Nastavenia špecifické pre RTK vrátane vlastných filtrov a uchovávania nespracovaného výstupu
/api/context/rtk/filters	GET	Katalóg filtrov RTK a diagnostika vlastných filtrov
/api/context/rtk/test	POST	Spustenie náhľadu/testu RTK s textovým dátovým obsahom
/api/context/rtk/raw-output/[id]	GET	Načítanie uchovaného redigovaného nespracovaného výstupu podľa ID ukazovateľa
/api/context/combos	GET/POST	Zoznam/vytvorenie kombinácií kompresie
/api/context/combos/[id]	GET/PUT/DELETE	Podrobnosti/aktualizácia/odstránenie kombinácie kompresie
/api/context/combos/[id]/assignments	GET/PUT	Priradenie kombinácií kompresie ku kombináciám smerovania
/api/context/analytics	GET	Alias analytiky kompresie

Monitorovanie

Koncový bod	Metóda	Popis
/api/sessions	GET	Sledovanie aktívnych relácií
/api/rate-limits	GET	Limity frekvencie požiadaviek pre jednotlivé účty
/api/monitoring/health	GET	Kontrola stavu + súhrn poskytovateľov (catalogCount, configuredCount, activeCount, monitoredCount). Zobrazenie správy zahŕňa credentialHealth: skalárne hodnoty vyrovnávacej pamäte sond, failedConnections, keď failed>0, a staleDbNonOkCount (nemenný test_status SQLite, nie ukazovateľ). Pozrite si MONITORING_GUIDE.md.
/api/cache/stats	GET/DELETE	Štatistiky vyrovnávacej pamäte / vymazanie
/api/modality-bridge/stats	GET	Hodnoty attempts, úspechy/bridged, zlyhania, zásahy vyrovnávacej pamäte, totalLatencyMs, latencySamples, averageLatencyMs založená na počte vzoriek a čas posledného použitia v pamäti (vynuluje sa pri reštarte; autentifikácia správy)
/api/modality-bridge/video/runtime	GET	Striktná kontrola dôveryhodného loopbacku pred autentifikáciou/sondou správy; sanitizovaná dostupnosť a verzie FFmpeg/ffprobe (no-store)
/api/modality-bridge/video/extract	POST	Interný autentifikovaný sprostredkovateľ bajtov cez dôveryhodný loopback; vstup 50 MiB, obmedzený front/výstup 32 MiB, 503 pri vyčerpanej kapacite, 499 pri odpojení, 504 pri prekročení časového limitu; nejde o verejné API na nahrávanie súborov

Zálohovanie a export/import

Endpoint	Metóda	Popis
/api/db-backups	GET	Zoznam dostupných záloh
/api/db-backups	PUT	Vytvorenie manuálnej zálohy
/api/db-backups	POST	Obnovenie z konkrétnej zálohy
/api/db-backups/export	GET	Stiahnutie databázy ako súboru .sqlite
/api/db-backups/import	POST	Nahratie súboru .sqlite na nahradenie databázy
/api/db-backups/exportAll	GET	Stiahnutie úplnej zálohy ako archívu .tar.gz

Cloudová synchronizácia

Endpoint	Metóda	Popis
/api/sync/cloud	Rôzne	Operácie cloudovej synchronizácie
/api/sync/initialize	POST	Inicializácia synchronizácie
/api/cloud/*	Rôzne	Správa cloudu

Tunely

Endpoint	Metóda	Popis
/api/tunnels/cloudflared	GET	Načítanie stavu inštalácie a behu Cloudflare Quick Tunnel pre ovládací panel
/api/tunnels/cloudflared	POST	Zapnutie alebo vypnutie Cloudflare Quick Tunnel (action=enable/disable)
/api/tunnels/ngrok	GET	Načítanie stavu behu ngrok Tunnel pre ovládací panel
/api/tunnels/ngrok	POST	Zapnutie alebo vypnutie ngrok Tunnel (action=enable/disable)

Nástroje CLI

Endpoint	Metóda	Popis
/api/cli-tools/claude-settings	GET	Stav Claude CLI
/api/cli-tools/codex-settings	GET	Stav Codex CLI
/api/cli-tools/droid-settings	GET	Stav Droid CLI
/api/cli-tools/openclaw-settings	GET	Stav OpenClaw CLI
/api/cli-tools/runtime/[toolId]	GET	Všeobecné behové prostredie CLI

Odpovede CLI obsahujú: installed, runnable, command, commandPath, runtimeMode, reason.

Agenti ACP

Endpoint	Metóda	Popis
/api/acp/agents	GET	Zoznam všetkých zistených agentov (vstavaných aj vlastných) so stavom
/api/acp/agents	POST	Pridanie vlastného agenta alebo obnovenie vyrovnávacej pamäte zisťovania
/api/acp/agents	DELETE	Odstránenie vlastného agenta podľa parametra dopytu id

Odpoveď GET obsahuje agents[] (id, name, binary, version, installed, protocol, isCustom) a summary (total, installed, notFound, builtIn, custom).

Odolnosť a limity frekvencie

Endpoint	Metóda	Popis
/api/resilience	GET/PATCH	Získanie/aktualizácia frontu požiadaviek, čakania medzi pripojeniami, ističa poskytovateľa a nastavení čakania
/api/resilience/reset	POST	Resetovanie ističov okruhu poskytovateľov
/api/resilience/model-cooldowns	GET	Zoznam aktívnych blokovaní podľa (poskytovateľa, pripojenia, modelu), zoradený podľa zostávajúceho času
/api/resilience/model-cooldowns	DELETE	Zrušenie blokovania modelu — telo {provider, model} alebo {all: true} na vymazanie všetkých
/api/rate-limits	GET	Stav limitu frekvencie pre jednotlivé účty
/api/rate-limit	GET	Globálna konfigurácia limitu frekvencie

Všetky štyri trasy /api/resilience/* vyžadujú autentifikáciu správy (requireManagementAuth). Úplné vysvetlenie rozdielov medzi ističom poskytovateľa, čakaním medzi pripojeniami a blokovaním modelu nájdete v časti Odolnosť (rozšírené).

Vyhodnotenia

Endpoint	Metóda	Popis
/api/evals	GET/POST	Zoznam súprav vyhodnotení / spustenie vyhodnotenia

Zásady

Endpoint	Metóda	Popis
/api/policies	GET/POST/DELETE	Správa zásad smerovania

Súlad

Endpoint	Metóda	Popis
/api/compliance/audit-log	GET	Denník auditu súladu (posledných N)

v1beta (kompatibilné s Gemini)

Endpoint	Metóda	Popis
/v1beta/models	GET	Zoznam modelov vo formáte Gemini
/v1beta/models/{...path}	POST	Endpoint Gemini generateContent

Tieto endpointy kopírujú formát API služby Gemini pre klientov, ktorí očakávajú natívnu kompatibilitu so súpravou Gemini SDK.

Interné / systémové API

Koncový bod	Metóda	Popis
/api/init	GET	Kontrola inicializácie aplikácie (používa sa pri prvom spustení)
/api/tags	GET	Značky modelov kompatibilné s Ollama (pre klientov Ollama)
/api/restart	POST	Spustenie korektného reštartu servera
/api/shutdown	POST	Spustenie korektného vypnutia servera
/api/system/env/repair	POST	Oprava premenných prostredia poskytovateľa OAuth

Poznámka: Tieto koncové body používa interne systém alebo slúžia na kompatibilitu s klientmi Ollama. Koncoví používatelia ich zvyčajne nevolajú.

Oprava prostredia OAuth (v3.6.1+)

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

{
  "provider": "claude-code"
}

Opraví chýbajúce alebo poškodené premenné prostredia OAuth pre konkrétneho poskytovateľa. Vráti:

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

---

Prepis zvuku

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

Prepisujte zvukové súbory pomocou ľubovoľného nakonfigurovaného poskytovateľa STT. Prvý segment cesty vyberá natívneho poskytovateľa (openai/…, deepgram/…). Brány, ktoré opätovne sprístupňujú model iného poskytovateľa, používajú kvalifikovaný identifikátor (openrouter/deepgram/nova-3).

Požiadavka:

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

Odpoveď:

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

Príklady identifikátorov modelov: openai/whisper-1 (vyžaduje kľúč OpenAI), openrouter/deepgram/nova-3 (vyžaduje kľúč OpenRouter), deepgram/nova-3 (vyžaduje natívny kľúč Deepgram). Požiadavka s nekvalifikovaným identifikátorom deepgram/nova-3 nepoužíva OpenRouter.

Podporované formáty: mp3, wav, m4a, flac, ogg, webm.

---

Kompatibilita s Ollama

Pre klientov, ktorí používajú formát API služby Ollama:

# Koncový bod chatu (formát Ollama)
POST /v1/api/chat

# Zoznam modelov (formát Ollama)
GET /api/tags

Požiadavky sa automaticky prekladajú medzi formátom Ollama a internými formátmi.

Aliasy s tokenmi pre VS Code / aliasy bez hlavičiek

Tieto aliasy použite, keď integrácia nedokáže vložiť hlavičku Authorization a potrebuje mať kľúč API vložený v základnej URL adrese.

# Alias katalógu v štýle OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Aliasy chatu v štýle OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Aliasy v štýle Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Príklad:

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"}]}'

Poznámky:

• Aliasy s tokenmi opätovne používajú rovnaké obslužné rutiny ako /v1/* a /api/tags; štruktúry odpovedí zostávajú rovnaké.
• Vždy, keď klient podporuje vlastné hlavičky, uprednostnite Authorization: Bearer ....
• Tokeny v URL adresách sa môžu objaviť v protokoloch reverzného proxy servera, histórii prehliadača a telemetrii mimo OmniRoute. Považujte ich za možnosť kompatibility, nie za predvolený spôsob autentifikácie.

---

Telemetria

# Získanie súhrnu telemetrie latencie (p50/p95/p99 pre každého poskytovateľa)
GET /api/telemetry/summary

Odpoveď:

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

---

Rozpočet

# Získanie stavu rozpočtu pre všetky kľúče API
GET /api/usage/budget

# Nastavenie alebo aktualizácia rozpočtu
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"
}

Poznámky k schéme (setBudgetSchema): apiKeyId je povinné; aspoň jedna z hodnôt dailyLimitUsd, weeklyLimitUsd alebo monthlyLimitUsd musí byť väčšia než nula. Voliteľné polia: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). Starší formát {keyId, limit, period} vráti 400 Bad Request.

Limity tokenov

Rozpočty tokenov pre jednotlivé API kľúče (odlišné od rozpočtu založeného na USD uvedeného vyššie). Vynucujú sa priamo počas spracovania požiadavky: keď využitie kľúča v aktuálnom časovom okne dosiahne jeho limit, požiadavky sa odmietnu s odpoveďou 429 Too Many Requests. Limity môžu byť obmedzené na konkrétny model, provider alebo sa môžu uplatňovať globalne na celý kľúč; keď požiadavke zodpovedá viacero limitov, použije sa najprísnejší z nich.

# Zobrazenie limitov tokenov kľúča (vrátane aktuálneho využitia časového okna)
GET /api/usage/token-limits?apiKeyId=key-123

# Vytvorenie alebo aktualizácia limitu tokenov
POST /api/usage/token-limits
Content-Type: application/json

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

# Odstránenie limitu tokenov podľa id
DELETE /api/usage/token-limits?id=tl-abc

Poznámky k schéme (setTokenLimitSchema): apiKeyId a scopeType (model | provider | global) sú povinné. scopeValue je povinné, pokiaľ scopeType nie je global (napr. id modelu pre rozsah model, id poskytovateľa pre rozsah provider). tokenLimit musí byť kladné celé číslo (konvertované z reťazca). Voliteľné: id (vynechajte pri vytváraní, uveďte pri aktualizácii), resetInterval (daily | weekly | monthly, predvolená hodnota monthly), resetTime (HH:MM), enabled (predvolená hodnota true). Odpovede GET dopĺňajú každý limit o tokensUsed, remaining, windowStart, periodStartAt a nextResetAt. Ide o koncový bod triedy správy (autorizácia je centrálne vynucovaná prostredníctvom pipeline authz).

Spracovanie požiadaviek

1. Klient odošle požiadavku na /v1/*
2. Obslužná rutina trasy zavolá handleChat, handleEmbedding, handleAudioTranscription alebo handleImageGeneration
3. Model sa rozpozná (priamy poskytovateľ/model alebo alias/combo)
4. Prihlasovacie údaje sa vyberú z lokálnej DB s filtrovaním podľa dostupnosti účtu
5. Pre chat: handleChatCore skontroluje sémantickú/signatúrnu vyrovnávaciu pamäť a načíta nastavenia kompresie combo
6. Ak je povolená, pred prekladom pre poskytovateľa sa spustí proaktívna kompresia (lite, Caveman, RTK alebo ich kombinácia)
7. Vykonávací modul poskytovateľa odošle požiadavku upstream službe
8. Odpoveď sa preloží späť do formátu klienta (chat) alebo sa vráti bez zmien (embeddings/images/audio)
9. Zaznamenajú sa údaje o využití, analytika kompresie a protokoly požiadaviek
10. Pri chybách sa podľa pravidiel combo použije záložný postup

Úplný prehľad architektúry: ARCHITECTURE.md

---

Správa combo

Kombinácie smerovania vyššej úrovne (už zhrnuté v časti /api/combos*) možno tiež mapovať v pomere 1:1 zo vzoru id modelu, čo umožňuje transparentné presmerovanie id modelu v štýle OpenAI na combo.

Metóda	Cesta	Popis
GET	/api/model-combo-mappings	Zobrazí všetky mapovania model→combo
POST	/api/model-combo-mappings	Vytvorí mapovanie — telo: {pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	Načíta jedno mapovanie
PUT	/api/model-combo-mappings/[id]	Aktualizuje polia existujúceho mapovania
DELETE	/api/model-combo-mappings/[id]	Odstráni mapovanie

Autentifikácia: relácia správy/API kľúč (requireManagementAuth).

---

Webhooky

Odber odchádzajúcich webhookov pre udalosti OmniRoute (dokončenie požiadavky, vyčerpanie kvóty, rotácia kľúča atď.).

Metóda	Cesta	Popis
GET	/api/webhooks	Zoznam webhookov (tajné kľúče sú maskované ako <prefix>...)
POST	/api/webhooks	Vytvorenie webhooku — telo: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	Získanie webhooku
PUT	/api/webhooks/[id]	Aktualizácia url/events/secret/description
DELETE	/api/webhooks/[id]	Odstránenie webhooku
POST	/api/webhooks/[id]/test	Odoslanie testovacích údajov na URL webhooku a vrátenie stavu doručenia

Autentifikácia: relácia správy/API kľúč (requireManagementAuth).

---

Registrované kľúče (automatická správa)

Používa ich subsystém automatickej správy kľúčov na vydávanie a rotáciu API kľúčov u poskytovateľa/podkladového účtu s dennými/hodinovými kvótami.

Metóda	Cesta	Popis
GET	/api/v1/registered-keys	Zoznam registrovaných kľúčov (iba maskovaný prefix)
POST	/api/v1/registered-keys	Vydanie nového registrovaného kľúča — telo: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Nespracovaný kľúč sa vráti raz. Pri odmietnutí z dôvodu kvóty vráti 429.
GET	/api/v1/registered-keys/[id]	Získanie metadát registrovaného kľúča (bez nespracovaného kľúča)
DELETE	/api/v1/registered-keys/[id]	Zrušenie registrovaného kľúča
POST	/api/v1/registered-keys/[id]/revoke	Explicitný koncový bod na zrušenie (rovnaký účinok ako DELETE)

Autentifikácia: API kľúč typu Bearer (isAuthenticated). Pozrite si tiež /v1/quotas/check a /v1/issues/report.

---

Protokol agentov

Úlohy cloudových agentov (Claude Code, Codex Cloud, OpenHands atď.) vykonávané vzdialene v mene používateľov OmniRoute.

Metóda	Cesta	Popis
GET	/api/v1/agents/tasks	Zoznam úloh — voliteľné ?provider=, ?status=, ?limit= (1–500, predvolene 50)
POST	/api/v1/agents/tasks	Vytvorenie úlohy — telo overené pomocou CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Vráti 201 s obálkou úlohy
DELETE	/api/v1/agents/tasks?id=...	Odstránenie úlohy
GET	/api/v1/agents/tasks/[id]	Načítanie úlohy — synchrónne obnoví stav z nadradeného cloudového agenta, keď je nastavené external_id
POST	/api/v1/agents/tasks/[id]	Rozlíšená akcia: {action: "approve"}, {action: "message", message} alebo {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	Odstránenie konkrétnej úlohy podľa ID

Autentifikácia: pri každej metóde sa vyžaduje autentifikácia správy (requireCloudAgentManagementAuth). Pred verziou v3.8.0 boli tieto metódy neautentifikované — zásadnú zmenu nájdete v commite 588a0333.

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

---

Proxy servery správy

Odchádzajúce HTTP(S)/SOCKS proxy servery, ktoré možno priradiť poskytovateľom, účtom alebo globálne.

Metóda	Cesta	Popis
GET	/api/v1/management/proxies	Zoznam proxy serverov (s ?id= vráti jeden; s ?id=&where_used=1 vráti graf priradení)
POST	/api/v1/management/proxies	Vytvorenie proxy servera — telo overené pomocou createProxyRegistrySchema
PATCH	/api/v1/management/proxies	Aktualizácia proxy servera — telo overené pomocou updateProxyRegistrySchema (vyžaduje id)
DELETE	/api/v1/management/proxies?id=...&force=1	Odstránenie proxy servera (na zrušenie priradení použite force=1)
GET	/api/v1/management/proxies/assignments	Zoznam priradení — možno filtrovať podľa proxy_id, scope, scope_id; odovzdaním resolve_connection_id=<id> získate aktívny proxy server pre pripojenie
PUT	/api/v1/management/proxies/assignments	Priradenie — telo overené pomocou proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Vymaže vyrovnávaciu pamäť dispečera
PUT	/api/v1/management/proxies/bulk-assign	Hromadné priradenie — telo overené pomocou bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?})
GET	/api/v1/management/proxies/health?hours=24	Súhrnný stav proxy serverov (počty úspechov/zlyhaní, latencia) za časové obdobie

Autentifikácia: relácia správy/kľúč API na každej trase (requireManagementAuth).

Trasy POST /api/v1/management/proxies/[id]/assignments a POST /api/v1/management/proxies/[id]/health uvedené v popise úlohy sú obsluhované plochými trasami /assignments a /health zobrazenými vyššie — v kódovej základni neexistujú žiadne podtrasy pre jednotlivé ID.

---

Odolnosť (rozšírené)

OmniRoute poskytuje tri nezávislé mechanizmy dočasných zlyhaní; nižšie uvedené koncové body na správu umožňujú operátorom čítať a meniť ich nastavenia:

Rozsah	Úložisko stavu	Čítanie	Resetovanie / vymazanie
Istič poskytovateľa	domain_circuit_breakers + v pamäti	/api/monitoring/health	POST /api/resilience/reset
Čakacia lehota pripojenia	rateLimitedUntil v pripojeniach poskytovateľov	/api/rate-limits, /api/providers/[id]	(opätovne sa aktivuje odložene; vymazanie cez PUT poskytovateľa)
Blokovanie modelu	Register dostupnosti modelov v pamäti	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

PATCH /api/resilience prijíma prepisy ističov poskytovateľov v rámci providerBreaker.oauth a providerBreaker.apikey. Každý profil podporuje degradationThreshold, failureThreshold a resetTimeoutMs; rovnaké polia sú dostupné v Ovládacom paneli → Nastavenia → Odolnosť.

# Vymazanie blokovania jedného modelu
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"}'

# Vymazanie všetkých blokovaní
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

Úplný koncepčný prehľad a predvolené nastavenia ističov: pozrite si CLAUDE.md → „Stav behu odolnosti“.

---

Zručnosti

Framework zručností na rozšírenie OmniRoute o vlastné spustiteľné obslužné programy spolu s integráciami trhovísk.

Metóda	Cesta	Popis
GET	/api/skills	Zoznam nainštalovaných zručností — možno filtrovať pomocou ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, so stránkovaním
GET	/api/skills/[id]	Získanie jednej zručnosti
PUT	/api/skills/[id]	Aktualizácia zručnosti (názov, popis, režim, schéma, obslužný program, značky)
DELETE	/api/skills/[id]	Odinštalovanie zručnosti
POST	/api/skills/install	Inštalácia zručnosti zo surového manifestu — telo: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	Zoznam nedávnych spustení zručností (auditný záznam so vstupmi/výstupmi/trvaním)
GET	/api/skills/marketplace?q=...	Vyhľadávanie/zoznam obľúbených položiek z trhoviska SkillsMP (vyžaduje nastavenie skillsmpApiKey)
POST	/api/skills/marketplace/install	Inštalácia zručnosti podľa id zo SkillsMP
GET	/api/skills/skillssh?q=&limit=	Vyhľadávanie v registri skills.sh
POST	/api/skills/skillssh/install	Inštalácia zručnosti podľa id zo skills.sh

Autentifikácia: relácia správy/kľúč API. Trasy vyhľadávania na trhovisku akceptujú autentifikáciu správy alebo kľúč API typu Bearer (isAuthenticated).

---

Pamäť

Trvalé úložisko konverzačnej/faktickej pamäte, oddelené podľa API kľúča/relácie.

Metóda	Cesta	Popis
GET	/api/memory	Zoznam pamätí — ?apiKeyId=, ?type=, ?sessionId=, ?q=, so stránkovaním pomocou offset/limit alebo page/limit
POST	/api/memory	Vytvorenie pamäte — telo validované pomocou Zod: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	Načítanie jednej pamäte
DELETE	/api/memory/[id]	Odstránenie pamäte
GET	/api/memory/health	Stav pamäťového subsystému (pripojenie k DB, backend vektorových reprezentácií, stav vektorového indexu)

Autentifikácia: relácia správy/API kľúč (requireManagementAuth). Výčtový typ type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (pozri MemoryType v src/lib/memory/types.ts).

---

Server MCP

OmniRoute obsahuje vstavaný server Model Context Protocol s 3 transportmi (stdio, SSE, streamable-http) a nástrojmi s definovaným rozsahom oprávnení. Koncové body ovládacieho panela uvedené nižšie načítavajú údaje o stave/audite a sprostredkúvajú HTTP transporty.

Metóda	Cesta	Popis
GET	/api/mcp/status	Signál aktivity, transport, online stav, posledné volanie, najpoužívanejšie nástroje, úspešnosť za 24 h
GET	/api/mcp/tools	Zoznam nástrojov MCP s name, description, scopes, phase, auditLevel, sourceEndpoints
GET	/api/mcp/sse	Otvorenie SSE streamu pre transport SSE (vráti 503, ak je MCP zakázané alebo sa transport nezhoduje)
POST	/api/mcp/sse	Odoslanie rámca JSON-RPC cez transport SSE
GET	/api/mcp/stream	Otvorenie SSE strany transportu Streamable HTTP (správy iniciované serverom)
POST	/api/mcp/stream	Odoslanie rámca JSON-RPC cez transport Streamable HTTP
DELETE	/api/mcp/stream	Ukončenie relácie Streamable HTTP
GET	/api/mcp/audit	Dotazovanie denníka auditu — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	Súhrnné štatistiky auditu (celkové počty, úspešnosť, priemerné trvanie, najpoužívanejšie nástroje)

Autentifikácia: transporty sse/stream rešpektujú autentifikačné rozhranie špecifické pre MCP (API kľúč Bearer s rozsahom mcp); trasy status/tools/audit* sú čitateľné z ovládacieho panela (nie je potrebná žiadna ďalšia autentifikácia okrem prístupu k hostiteľovi ovládacieho panela).

Oba HTTP transporty sú riadené nastaveniami settings.mcpEnabled a settings.mcpTransport — nezhoda transportu vráti 400, zakázaný stav MCP vráti 503.

---

Server A2A

OmniRoute poskytuje koncový bod A2A (Agent-to-Agent) JSON-RPC 2.0 spolu s obalom REST na účely kontroly a použitia v informačnom paneli.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # voliteľné, ak nie je nastavená premenná OMNIROUTE_API_KEY
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Smeruj túto programátorskú úlohu"}]
  }
}

Podporované metódy (všetky podmienené nastavením settings.a2aEnabled):

Metóda	Popis
message/send	Synchrónne vykonanie zručnosti; vráti {task, artifacts, metadata}
message/stream	Vykonanie rovnakej množiny zručností prostredníctvom streamovania SSE
tasks/get	Načíta úlohu podľa taskId
tasks/cancel	Zruší úlohu podľa taskId

Vstavané zručnosti: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Karta agenta

GET /.well-known/agent.json

Vráti verejnú kartu agenta A2A (názov, popis, funkcie, katalóg zručností, schému autentifikácie) — verejne sa ukladá do vyrovnávacej pamäte na 1 hodinu. Autentifikácia sa nevyžaduje.

Pomocné rozhrania REST

Metóda	Cesta	Popis
GET	/api/a2a/status	Stav povolenia A2A + štatistiky úloh + súhrn karty agenta z vyrovnávacej pamäte
GET	/api/a2a/tasks	Zoznam úloh — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST	/api/a2a/tasks	(Nie je implementované ako pomocné rozhranie REST — vytvorte prostredníctvom JSON-RPC message/send)
GET	/api/a2a/tasks/[id]	Načíta jednu úlohu
POST	/api/a2a/tasks/[id]/cancel	Zruší úlohu

Autentifikácia: pomocné rozhrania REST fungujú bez autentifikácie na správu (sú čitateľné z informačného panela); trasa JSON-RPC /a2a používa Bearer OMNIROUTE_API_KEY, ak je nakonfigurovaný.

---

Cloud, vyhodnotenia a posúdenie

Metóda	Cesta	Popis
POST	/api/cloud/auth	Overí kľúč Bearer a vráti maskované pripojenia poskytovateľov + aliasy modelov pre klientov cloudovej synchronizácie
POST	/api/cloud/credentials/update	Aktualizuje šifrované prihlasovacie údaje poskytovateľa synchronizovaného s cloudom
POST	/api/cloud/model/resolve	Preloží logické ID modelu na konkrétneho poskytovateľa/model pomocou lokálnej smerovacej tabuľky
GET	/api/cloud/models/alias	Zobrazí aliasy modelov sprístupnené cloudovej synchronizácii
GET	/api/assess	Načíta najnovšie kategorizácie posúdenia (podľa poskytovateľa/modelu)
POST	/api/assess	Spustí posúdenie — telo: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	Zobrazí vstavané sady vyhodnotení + najnovšie spustenia
POST	/api/evals	Spustí vyhodnotenie
POST	/api/evals/suites	Vytvorí vlastnú sadu vyhodnotení — telo overené schémou evalSuiteSaveSchema
GET	/api/evals/suites/[id]	Načíta vlastnú sadu vyhodnotení

Autentifikácia: /api/cloud/auth overuje kľúč Bearer priamo; ostatné trasy /api/cloud/*, /api/evals/* a /api/assess vyžadujú reláciu na správu/kľúč API. Požiadavka POST na /api/assess používa validateBody so schémou rozsahu typu discriminated union.

---

Správa ACP (Agent Client Protocol)

ako podradené procesy. Tieto koncové body spravujú detekciu agentov ACP a registráciu vlastných agentov.

Metóda	Cesta	Popis
GET	/api/acp/agents	Zobrazí všetkých známych agentov CLI (vstavaných aj vlastných) so stavom inštalácie, verziou a binárnym súborom
POST	/api/acp/agents	Zaregistruje vlastného agenta ACP alebo obnoví vyrovnávaciu pamäť — telo: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} alebo {action: "refresh"}
DELETE	/api/acp/agents	Odstráni vlastného agenta ACP — parameter dotazu: ?id=<agentId>

Príklad odpovede (GET /api/acp/agents):

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

Autentifikácia: Vyžaduje reláciu správy (súbor cookie auth_token ovládacieho panela) alebo kľúč API s rozsahom správy.

Úplné podrobnosti nájdete v dokumentácii ACP Framework.

---

Analytika a pozorovateľnosť

Koncové body analytiky v reálnom čase na monitorovanie smerovania, kompresie a diverzity poskytovateľov. Používajú ich stránky /dashboard/analytics/*.

Analytika automatického smerovania

Metóda	Cesta	Popis
GET	/api/analytics/auto-routing	Agregované štatistiky automatického smerovania: celkový počet volaní, rozdelenie stratégií, úrovní a hlavní poskytovatelia
GET	/api/analytics/auto-routing?days=7	Štatistiky za časové okno (predvolene 24 h)

Príklad odpovede:

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

Analytika kompresie

Metóda	Cesta	Popis
GET	/api/analytics/compression	Agregované štatistiky kompresie: ušetrené tokeny, percento úspory, rozdelenie režimov a využitie jadier

Príklad odpovede:

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

Sledovanie diverzity poskytovateľov

Metóda	Cesta	Popis
GET	/api/analytics/diversity	Sledovanie diverzity založené na Shannonovej entropii: predchádza jediným bodom zlyhania meraním rozloženia poskytovateľov

Príklad odpovede:

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

Autentifikácia: Vyžaduje reláciu správy alebo kľúč API s rozsahom správy.

---

Operácie správcu

Koncové body určené iba správcom na prevádzkovú správu.

Metóda	Cesta	Popis
GET	/api/admin/concurrency	Načítanie aktuálnych limitov súbežnosti (globálnych + pre jednotlivých poskytovateľov)
POST	/api/admin/concurrency	Aktualizácia limitov súbežnosti — telo: {global?: number, perProvider?: Record<string, number>}

Autorizácia: Vyžaduje reláciu správy s rozsahom správcu.

---

Správa nástrojov CLI

Spravujte nástroje CLI, ktoré sa integrujú so službou OmniRoute (antigravity, chipotle, commandCode, devin-cli atď.). Úplný zoznam nájdete v referenčnej príručke poskytovateľov.

Metóda	Cesta	Popis
GET	/api/cli-tools/all-statuses	Stav všetkých nástrojov CLI (nainštalovanie, verzia, posledné použitie)
GET	/api/cli-tools/status	Podrobnosti o stave jedného nástroja CLI (parameter dopytu ?tool=)
POST	/api/cli-tools/apply	Zapísanie vygenerovanej konfigurácie nástroja (dryRun zobrazí náhľad; 422 + containerEphemeralTarget pri použití kontajnera; migration upozorní na starší Codex YAML)
GET	/api/cli-tools/backups	Zoznam záloh konfigurácií nástrojov CLI
POST	/api/cli-tools/backups	Vytvorenie zálohy konfigurácií všetkých nástrojov CLI
POST	/api/cli-tools/backups	Obnovenie: rovnaký koncový bod s {tool, backupId} v tele obnoví danú zálohu
GET	/api/cli-tools/antigravity-mitm	Stav proxy MITM nástroja Antigravity (nástroj CLI „antigravity-mitm“)
POST	/api/cli-tools/antigravity-mitm/alias	Konfigurácia aliasov nástroja antigravity-mitm

Autorizácia: Vyžaduje reláciu správy.

---

Zručnosti agentov

Spravujte zručnosti agentov AI (podobné vlastným GPT od OpenAI, ale určené pre agentov).

Metóda	Cesta	Popis
GET	/api/agent-skills	Zoznam všetkých zručností agentov (vstavaných + vlastných)
GET	/api/agent-skills/[id]	Získanie konkrétnej zručnosti agenta
POST	/api/agent-skills	Vytvorenie vlastnej zručnosti agenta — telo: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	Aktualizácia vlastnej zručnosti agenta
DELETE	/api/agent-skills/[id]	Odstránenie vlastnej zručnosti agenta
GET	/api/agent-skills/[id]/raw	Získanie nespracovanej výzvy + metadát (bez vykonania)
POST	/api/agent-skills/generate	Vygenerovanie novej zručnosti pomocou AI z opisu v prirodzenom jazyku

Autorizácia: Vyžaduje reláciu správy alebo kľúč API s rozsahom správy.

---

Správa vyrovnávacej pamäte

Spravujte sémantickú vyrovnávaciu pamäť a vyrovnávaciu pamäť odôvodnení.

Metóda	Cesta	Popis
GET	/api/cache	Prehľad vyrovnávacej pamäte: celkový počet záznamov, miera zásahov, veľkosť na disku
GET	/api/cache/entries	Zoznam záznamov vo vyrovnávacej pamäti (so stránkovaním)
DELETE	/api/cache/entries	Odstránenie záznamov z vyrovnávacej pamäte (filtrovanie podľa parametrov dopytu)
GET	/api/cache/stats	Podrobné štatistiky vyrovnávacej pamäte (podľa poskytovateľa a modelu)
GET	/api/cache/reasoning	Stav vyrovnávacej pamäte odôvodnení (na opätovné prehranie odôvodnení)
DELETE	/api/cache/reasoning	Vymazanie vyrovnávacej pamäte odôvodnení — parametre dopytu: ?toolCallId=<id> (jeden), ?provider=<p> alebo bez parametrov (všetky)

Autorizácia: Vyžaduje reláciu správy.

---

Pamäťový systém

Spravujte trvalú pamäť (FTS5 + vektorové vnorenia).

Metóda	Cesta	Popis
GET	/api/memory	Zoznam záznamov pamäte (filtrovanie podľa rozsahu, typu a vyhľadávacieho dopytu)
POST	/api/memory	Vytvorenie nového záznamu pamäte — telo: {scope, type, content, metadata?}
GET	/api/memory/[id]	Získanie konkrétneho záznamu pamäte
PUT	/api/memory/[id]	Aktualizácia záznamu pamäte
DELETE	/api/memory/[id]	Odstránenie záznamu pamäte
GET	/api/memory?q=	Vyhľadávanie v pamäti (FTS5 + vektory) — štatistiky sú zahrnuté v rovnakej odpovedi

Autorizácia: Vyžaduje reláciu správy alebo kľúč API s rozsahom správy.

---

Webhooky

Spravujte odbery webhookov pre udalosti.

Metóda	Cesta	Popis
GET	/api/webhooks	Zoznam všetkých odberov webhookov
POST	/api/webhooks	Vytvorenie odberu webhooku — telo: {url, events[], secret?, active?}
GET	/api/webhooks/[id]	Získanie konkrétneho odberu webhooku
PUT	/api/webhooks/[id]	Aktualizácia odberu webhooku
DELETE	/api/webhooks/[id]	Odstránenie odberu webhooku
GET	/api/webhooks/[id]/deliveries	Zoznam histórie doručení webhooku (záznam úspechov a zlyhaní)
POST	/api/webhooks/[id]/test	Odoslanie testovacej udalosti webhooku

Autorizácia: Vyžaduje reláciu správy.

Úplný zoznam typov udalostí nájdete v dokumente Framework webhookov.

---

Framework zručností

Spravujte zručnosti (framework agentných rozšírení).

Metóda	Cesta	Popis
GET	/api/skills	Zobrazí zoznam všetkých nainštalovaných zručností (vstavaných aj vlastných)
POST	/api/skills/install	Nainštaluje zručnosť z lokálnej cesty alebo adresy URL
DELETE	/api/skills/[id]	Odinštaluje zručnosť
PUT	/api/skills/[id]	Povolí alebo zakáže zručnosť — telo: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST	/api/skills/executions	Spustí zručnosť — telo: {skillName, apiKeyId, input?, sessionId?}
GET	/api/skills/executions	Zobrazí históriu spustení všetkých zručností (filtrovanie pomocou ?apiKeyId=)

Autorizácia: Vyžaduje reláciu správy alebo kľúč API s rozsahom správy.

Úplné podrobnosti nájdete v dokumente Framework zručností.

---

Pluginy

Spravujte pluginy OmniRoute (rozšírenia tretích strán).

Metóda	Cesta	Popis
GET	/api/plugins	Zobrazí zoznam nainštalovaných pluginov
POST	/api/plugins/marketplace/install	Nainštaluje plugin z trhoviska
DELETE	/api/plugins/[name]	Odinštaluje plugin
POST	/api/plugins/[name]/activate	Aktivuje plugin
POST	/api/plugins/[name]/deactivate	Deaktivuje plugin
GET	/api/plugins/[name]/config	Získa konfiguráciu pluginu
PUT	/api/plugins/[name]/config	Aktualizuje konfiguráciu pluginu

Autorizácia: Vyžaduje reláciu správy.

Úplné podrobnosti nájdete v dokumente Framework pluginov.

---

Tieňové smerovanie

Tieňové porovnávanie poskytovateľov alebo ich porovnávanie typu A/B nie je samostatným rozhraním REST — konfiguruje sa prostredníctvom kombinovaného smerovania (pozrite si Automatické kombinácie). Metriky porovnávania pre jednotlivé kombinácie poskytuje GET /api/combos/metrics.

---

Ochranné mechanizmy

Kontrolujte ochranné mechanizmy pri behu systému (detekcia osobných údajov, detekcia vloženia škodlivej inštrukcie do promptu, premostenie videnia). Ochranné mechanizmy sa spúšťajú pri každej požiadavke; zrušenie pre jednotlivé volania sa vykonáva prostredníctvom hlavičky požiadavky x-omniroute-disabled-guardrails — neexistuje trvalé rozhranie na ich povolenie alebo zakázanie.

Metóda	Cesta	Popis
GET	/api/guardrails	Zobrazí zoznam registrovaných ochranných mechanizmov a ich stav (názov / povolenie / priorita)
POST	/api/guardrails/test	Vykoná skúšobný beh postupu pred volaním nad vzorovým vstupom — telo: {input, disabledGuardrails?}

Autorizácia: Vyžaduje reláciu správy.

Úplné podrobnosti nájdete v dokumente Zabezpečenie > Ochranné mechanizmy.

---

---

Autentifikácia

Štyri skupiny prihlasovacích údajov (relácia ovládacieho panela, lokálny token CLI, prístupový token oma_live_…, kľúč API s rozsahom správy) a ich rozdiely oproti kľúčom na inferenciu nájdete v časti Autentifikácia správy.

• Trasy ovládacieho panela (/dashboard/*) používajú súbor cookie auth_token
• Prihlásenie používa uložený hash hesla; záložnou možnosťou je INITIAL_PASSWORD
• Nastavenie requireLogin možno prepínať prostredníctvom /api/settings/require-login
• Trasy /v1/* môžu vyžadovať kľúč API typu Bearer, keď je nastavené REQUIRE_API_KEY=true
• Pojem „token správy“ / „kľúč API s rozsahom správy“ v tejto dokumentácii označuje jednu zo skupín uvedených v danej príručke — nejde o nedefinovaný dodatočný typ tajného kľúča

Nekompatibilná zmena (v3.8.0) — /api/v1/agents/tasks/* a koncové body správy doby čakania teraz vyžadujú autentifikáciu správy (súbor cookie auth_token ovládacieho panela alebo kľúč API s rozsahom správy). Klienti, ktorí predtým volali tieto trasy bez autentifikácie, dostanú odpoveď 401 Unauthorized. Pozrite si commit 588a0333 (fix(auth): require management auth for agent and cooldown APIs).