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

API Reference (Čeština)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 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í dokumentace k API OmniRoute. Popisuje veřejné rozhraní /v1 a nejpoužívanější koncové body pro správu; úplnými zdroji jsou strojově čitelný soubor docs/openapi.yaml a strom tras v src/app/api/.

---

Obsah

• Dokončování chatu
• Výhradní pronájmy spravovaných relací
• Vektorové reprezentace
• Generování obrázků
• OCR dokumentů
• Seznam modelů
• Manifest pluginu poskytovatele
• Koncové body kompatibility
• API souborů
• API dávek
• API vyhledávání
• Streamování přes WebSocket
• Kvóty a hlášení problémů
• Sémantická mezipaměť
• Řídicí panel a správa
• Správa kombinací
• Webhooky
• Registrované klíče (automatická správa)
• Protokol agentů
• Proxy servery pro správu
• Odolnost (rozšířená)
• Dovednosti
• Paměť
• Server MCP
• Server A2A
• Cloud, vyhodnocování a posuzování
• Zpracování požadavků
• Ověřování

---

Dokončování 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	Směr	Popis
X-OmniRoute-No-Cache	Požadavek	Nastavením na true obejdete mezipaměť
x-omniroute-no-memory	Požadavek	Nastavením na true přeskočíte pro tento požadavek vkládání paměti a dovedností (obdobně jako bez mezipaměti; zabrání režii tokenů a nákladů na jednotlivá volání)
X-OmniRoute-Progress	Požadavek	Nastavením na true povolíte události průběhu
X-Session-Id	Požadavek	Klíč připnuté relace pro externí afinitu relací
x_session_id	Požadavek	Přijímána je také varianta s podtržítkem (přímé HTTP)
X-OmniRoute-Session-Id	Požadavek	Značka relace/konverzace zadaná volajícím (používá ji také paměť). Pokud je uvedena, uloží se beze změny do call_logs.session_tag pro přiřazení nákladů jednotlivým relacím (#8249) — pokud chybí, nikdy se nevytváří
Idempotency-Key	Požadavek	Klíč pro odstranění duplicit (časové okno 5 s)
X-Request-Id	Požadavek	Alternativní klíč pro odstranění duplicit
X-OmniRoute-Cache	Odpověď	HIT nebo MISS (bez streamování)
X-OmniRoute-Idempotent	Odpověď	true, pokud byly odstraněny duplicity
X-OmniRoute-Progress	Odpověď	enabled, pokud je zapnuto sledování průběhu
X-OmniRoute-Session-Id	Odpověď	Efektivní ID relace používané službou OmniRoute
X-OmniRoute-Request-Id	Odpověď	ID pro korelaci požadavku (pokud je známo)
X-OmniRoute-Version	Odpověď	Verze sestavení OmniRoute (vždy uvedena)
X-OmniRoute-Cost-Saved	Odpověď	Částka v USD, kterou mezipaměť ušetřila při výsledku HIT (pouze při nalezení v mezipaměti)
X-OmniRoute-Decision	Odpověď	Trasování směrování: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> je strategie kombinace, nebo single u požadavku bez kombinace) — vždy uvedeno v odpovědích po dokončení

Poznámka k Nginx: pokud spoléháte na hlavičky s podtržítky (například x_session_id), povolte underscores_in_headers on;.

Hlavičky telemetrie nákladů: úspěšné odpovědi bez streamování obsahují také sadu telemetrie nákladů X-OmniRoute-* — X-OmniRoute-Response-Cost (USD, pevně 10 desetinných míst; 0.0000000000 pro bezplatné položky nebo položky bez stanovené 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 (pouze pokud > 0) spolu s X-OmniRoute-Request-Id a X-OmniRoute-Version. Tyto hlavičky vracejí dokončení chatu, /v1/responses, /v1/messages i koncové body pro média — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations a /v1/moderations (náklady jsou vždy 0). Náklady na média se počítají podle modality (za obrázek, za sekundu, za znak, za vyhledávací jednotku), pokud jsou k dispozici cenové údaje; jinak jsou 0 (při chybě se pokračuje).

Sémantika nákladů při zásahu do mezipaměti: při ZÁSAHU do sémantické mezipaměti (X-OmniRoute-Cache-Hit: true) není provedeno žádné volání upstreamu, takže X-OmniRoute-Response-Cost je 0.0000000000 (přírůstkové náklady na obsloužení zásahu). Původní/předpokládané náklady jsou vykázány samostatně v X-OmniRoute-Cost-Saved. Systémy zpracovávající fakturační údaje by měly sčítat X-OmniRoute-Response-Cost (zásahy nic nestojí); analytické systémy mezipaměti mohou agregovat X-OmniRoute-Cost-Saved.

Výhradní spravované pronájmy relací

Výhradní pronájem spravovaných relací je volitelná, na klientovi nezávislá směrovací smlouva: jeden aktivní vlastník drží jedno způsobilé připojení OmniRoute. Nepronajímá model, nevyžaduje OAuth, neidentifikuje konkrétního klienta ani nevyžaduje konkrétního poskytovatele.

Ověřovaný API klíč musí mít oprávnění lease:exclusive a explicitní neprázdný seznam allowedConnections. Hranice databázových mutací vynucuje obě pole společně při vytvoření klíče i při částečných aktualizací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"}

Úspěšné odpovědi na získání, obnovení a uvolnění zpřístupňují časová razítka, state a přesnou kladnou hodnotu generation, nikdy však vybrané připojení ani přihlašovací údaje. Obnovení a uvolnění předávají generaci v těle JSON:

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

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

Aktivní vlastník pronájmu si může explicitně vyžádat metadata vhodná k bezpečnému zobrazení pro svou aktuální vazbu:

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

Tato volitelná akce stavu je v rámci jedné databázové transakce ohraničena neprůhledným vlastníkem, ověřeným spravovaným API klíčem a přesnou aktivní generací. displayName je pouze oříznutý nakonfigurovaný název připojení; pokud žádný bezpečný nakonfigurovaný název neexistuje, má hodnotu null. OmniRoute nikdy nenahrazuje tento název e-mailem ani vygenerovanou identitou účtu. Hodnota poskytovatele je necitlivý popisek pro zobrazení a nikdy nejde o vygenerovaný identifikátor kompatibilního poskytovatele. Přihlašovací údaje, tokeny, soubory cookie, nezpracované identifikátory připojení nebo API klíčů, otisky vlastníků, tajné hodnoty pro ohraničení a interní směrovací data jsou vyloučeny.

Vyhledání s nesprávným klíčem, nesprávným vlastníkem, zastaralou generací nebo vyhledání chybějícího, prošlého, uvolněného či zneplatněného pronájmu vždy vrátí stejnou chybu 409 LEASE_FENCE_STALE bez metadat připojení. Klient, který obdržel odpověď o čekání na kapacitu, nemá žádnou aktivní vazbu, kterou by mohl zkontrolovat. Když směrování převede aktivní pronájem, zůstává platná stejná generace a stav atomicky vrátí novou vazbu, nikdy ne tu starou. Stávající klienti zůstávají beze změny, protože odpovědi na získání, obnovení, uvolnění a čekání si zachovávají své předchozí struktury.

Tato serverová smlouva nemění standardní /status OpenAI Codex. Standardní Codex aktuálně hlásí svého poskytovatele modelu a vestavěný stav ověření/účtu, ale nezobrazuje libovolná metadata účtů vlastních poskytovatelů; budoucí integrace klienta musí zavolat tuto akci a rozhodnout, jak zobrazit connection.displayName.

Každý spravovaný inferenční požadavek poté předává obě řídicí hlavičky:

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

Přesný vlastník, generace, aktivní připojení a ověřený API klíč jsou ohraničeny bezprostředně před každým podporovaným pokusem o přístup k nadřazené službě. Opakované použití vlastníka a generace s jiným klíčem selže, i když tento klíč povoluje stejné připojení. Nezpracované hodnoty vlastníků se neukládají, nezaznamenávají do protokolů, neuchovávají ve snímku požadavku ani nepředávají nadřazené službě.

Dočasná kolize vrátí HTTP 429 s Retry-After a:

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

Tato odpověď pouze znamená, že běžná množina způsobilých připojení nebyla prázdná a každý volný kandidát byl držen cizím aktivním pronájmem. Nepodporované modely/poskytovatelé, neshoda zásad, doba zklidnění, kvóta, stav služby a další běžná selhání způsobilosti si zachovávají své stávající odpovědi OmniRoute.

x-omniroute-compression

Přepsání plánu komprese pro jednotlivý požadavek. Má nejvyšší prioritu — přebíjí přepsání směrovací kombinace, aktivní profil, automatické spuštění i výchozí nastavení panelu. Hodnoty:

Hodnota	Účinek
off	Pro tento požadavek se nepoužije žádná komprese.
default	Výchozí profil odvozený z panelu (ignoruje aktivní profil).
engine:<id>	Jeden modul, pokud je povolen, např. engine:rtk.
<combo>	Pojmenovaná kombinace, nejprve porovnaná podle názvu (bez rozlišení velikosti písmen), poté podle id.

Poznámky:

• Neznámé hodnoty jsou ignorovány (požadavek není nikdy odmítnut); vyhodnocení pokračuje podle běžného pořadí priorit operátorů.
• Pokud má více kombinací stejný název, předejte id kombinace, aby bylo nalezení jednoznačné.
• Kombinaci s názvem off nebo default nelze vybrat podle názvu (tato klíčová slova jsou interpretována jako první); na takovou kombinaci odkazujte pomocí jejího id.
• Hlavní přepínač komprese je nepřekročitelná podmínka: pokud je komprese globálně zakázána, tato hlavička ji nemůže povolit.

Použitý plán se vrací v hlavičce odpovědi:

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

kde <source> je jedna z hodnot request-header, routing-override, active-profile, auto-trigger, default nebo off.

---

Embeddingy

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

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

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

Identifikátory katalogu mají tvar provider/model (příklad: jina-ai/jina-embeddings-v5-omni-small). Samostatné identifikátory modelů Jina uvedené v registru (například jina-embeddings-v5-text-small, jina-reranker-v3.5) se také správně rozpoznají. Operace embed/rerank/classify/segment od Jina používají přednostně přihlašovací údaje jina-ai z řídicího panelu; JINA_AI_API_KEY slouží pouze jako záložní možnost, pokud v řídicím panelu žádný klíč neexistuje. Karta jina-reader je určena pouze pro Reader / r.jina.ai (POST /v1/web/fetch) a nikdy neposkytuje embeddingy ani reranking.

Modely v registru, které deklarují podporu multimodality, přijímají také až 32 strukturovaných položek nezávislých na poskytovateli. Typy multimediálních položek jsou text, image, audio, video a document. Jejich multimediální source je buď {"type":"url","url":"https://..."}, nebo {"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) přijímá také nativní dokumenty EmbeddingsV5Request od Jina a předává je beze změny 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,..." }]
    }
  ]
}

Nativní hodnoty { image | audio | video | pdf } mohou být veřejná adresa URL používající HTTPS, identifikátor URI data: nebo nezpracovaný base64. OmniRoute tyto objekty nepřevádí na řetězce ani nestahuje nativní adresy URL obrázků — veřejná média načítá sama Jina. Dodatečná pole Jina (task, normalized, truncate, embedding_type) se předávají dále. Textové SKU Jina nadále odmítají netextové dokumenty.

Bezpečnostní a přenosová omezení:

• Vzdálené adresy URL médií musí být veřejné a používat HTTPS. Kanonické položky {type,source:url} se načítají na straně serveru (opakované ověření přesměrování, časový limit, omezení velikosti, veřejné DNS, připnutí připojení) a před voláním poskytovatele se vloží přímo do požadavku. Nativní položky Jina {image:"https://..."} se předávají beze změny po stejné kontrole veřejného HTTPS; adresu URL načte Jina.
• Multimédia vložená jako base64 jsou omezena na 8 MiB dekódovaných dat na položku a 16 MiB dekódovaných dat v rámci celého požadavku.

Převod pro poskytovatele (kanonické položky se nikdy nepředávají beze změny):

• Multimodální modely Jina: každá položka nejvyšší úrovně se převede na jeden objekt s klíčem modality (text / image / audio / video / pdf), přičemž pro vložená média se použijí identifikátory URI typu data; jeden vektor na každou položku nejvyšší úrovně.
• Rodina Gemini Embedding 2: jedno pole nejvyšší úrovně se převede na jediný nativní požadavek models/{model}:embedContent s content.parts (text nebo inline_data).
• Neznámé/dynamické modely bez explicitních metadat modality odmítnou strukturovaný 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é kombinace modelu a modality vrátí HTTP 400 namísto převodu položky. Rozšiřující pole mimo vstup se u starších požadavků s řetězci/tokeny nadále předávají beze změny.

# Vypsat všechny embeddingové modely
GET /v1/embeddings

---

Generování obrázků

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

{
  "model": "openai/gpt-image-2",
  "prompt": "Krásný západ slunce nad horami",
  "size": "1024x1024"
}

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

# Vypsat všechny modely pro generování obrázků
GET /v1/images/generations

---

OCR dokumentů

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 vybírá poskytovatele OCR pomocí prefixu provider/model; samotné ID modelu (např. mistral-ocr-latest) se přeloží na jeho registrovaného poskytovatele a při vynechání model se jako výchozí použije Mistral (mistral-ocr-latest). Registrovaní poskytovatelé (open-sse/config/ocrRegistry.ts):

ID poskytovatele	ID modelu	Hodnota model	Poznámky
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest (nebo samotné mistral-ocr-latest)	Synchronní — odpověď je vrácena přímo z jediného volání nadřazené služby.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	Asynchronní nadřazená služba (analyze + dotazování) — viz níže.
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	Synchronní, prostřednictvím partnerského koncového bodu openapi/chat/completions služby Vertex AI — podrobnosti o ověřování a URL viz níže.

Všichni tři poskytovatelé odpovídají ve stejném formátu těla jako Mistral:

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

Průběh dotazování služby Azure Document Intelligence

API analyze služby Azure Document Intelligence je asynchronní: počáteční požadavek vrací namísto těla hlavičku Operation-Location a na výsledek je nutné se opakovaně dotazovat. Obslužná rutina (open-sse/handlers/ocr.ts) se na danou URL dotazuje každou sekundu, maximálně však 30krát; při odpovědi na dotazování, která není ok, nebo při stavu "failed" okamžitě skončí s chybou (v dotazování nepokračuje) a vrátí 504, pokud operace běží i po vyčerpání povoleného počtu pokusů. Konečná odpověď Azure je před vrácením volajícímu normalizována do stejného formátu pages/markdown, jaký používá Mistral, takže klientský kód nemusí poskytovatele řešit jako zvláštní případ.

Ověřování a určení koncového bodu pro Vertex AI DeepSeek OCR

vertex-deepseek-ocr znovu používá stejné ověřování Vertex AI, které již OmniRoute podporuje pro provoz chatu a obrázků (open-sse/executors/vertex.ts): klíčem API připojení je buď přihlašovací údaj Service Account ve formátu JSON (vyměněný za krátkodobý přístupový token OAuth prostřednictvím toku JWT bearer), nebo již vydaný přístupový token OAuth použitý beze změny. URL nadřazeného koncového bodu je obecný partnerský koncový bod Vertex openapi/chat/completions, sestavený z projektu a oblasti připojení — explicitní providerSpecificData.project/providerSpecificData.region má vždy přednost; jinak je projekt odvozen z project_id v JSON Service Account a jako výchozí oblast se použije us-central1. Obě hodnoty se určují v open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl) a jsou použity v src/app/api/v1/ocr/route.ts před předáním do handleOcr.

---

Výpis modelů

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

→ Vrátí všechny chatovací, embeddingové a obrazové modely + kombinace ve formátu OpenAI

Prefixy ID modelů (?prefix=)

Většina modelů je zveřejňována pod prefixem poskytovatele. Použitý prefix je řízen příznakem funkce MODELS_CATALOG_PREFIX_MODE a lze jej přepsat pro každý požadavek pomocí parametru dotazu — což je užitečné pro klienta, který chce přehledný seznam, aniž by měnil nastavení serveru pro všechny ostatní:

GET /v1/models?prefix=alias        # jedno ID na model — krátký alias prefixu
GET /v1/models?prefix=dual         # obě podoby (výchozí nastavení serveru)
GET /v1/models?prefix=canonical    # pouze úplný prefix ID poskytovatele

Režim	Vrací	Poznámky
dual	cc/claude-sonnet-4-6 a claude/claude-sonnet-4-6	Výchozí. Obě ID směrují na stejný model; tato možnost je zachována, aby nadále fungovaly konfigurace klientů, které napevno používají jednu z těchto podob. Přibližně zdvojnásobuje velikost katalogu.
alias	cc/claude-sonnet-4-6	Jedna položka na model. Poskytovatelé bez samostatného aliasu svou položku přesto vracejí, takže se nic neztratí.
canonical	claude/claude-sonnet-4-6	Jedna položka na model pod úplným prefixem ID poskytovatele. Poskytovatelé bez samostatného aliasu (např. antigravity/…, agy/…) zde také vracejí své jediné ID, takže se nic neztratí.

Zrcadlenou položku v režimu dual lze rozpoznat také bez parametru dotazu: obsahuje pole parent odkazující na primární ID.

Klienti zobrazující výběr modelu by měli používat ?prefix=alias — takto postupuje rozšíření OmniCopilot pro VS Code.

Varianty modelů bez přemýšlení

Pro modely Claude podporující přemýšlení zveřejňuje /v1/models také variantu bez přemýšlení, jejíž ID má prefix claude-3-omniroute-no-thinking/:

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

Výběr tohoto ID (např. v konfiguraci Claude Code, která vždy připojuje blok thinking) se přeloží zpět na skutečný model <provider>/<model> s potlačeným uvažováním — pomocí thinking:{type:"disabled"} na cestě /v1/messages, nebo odstraněním polí reasoning/reasoning_effort na cestě /v1/chat/completions. Tato varianta je uvedena pouze pro modely rodiny Claude, které podporují přemýšlení a zároveň respektují hodnotu disabled (takže jsou například vyloučeny modely podporující pouze adaptivní režim, které hodnotu disabled odmítají). Provozovatelé mohou tuto variantu pro jednotlivé modely vynutit nebo zakázat prostřednictvím ModelSpec.noThinkingAlias.

---

Manifest pluginů poskytovatelů

GET /api/v1/provider-plugin-manifest

Vrací manifest pluginů poskytovatelů kompatibilní s JSON, který používají Bifrost, CLIProxyAPI a budoucí postranní směrovače. Odpověď se generuje z registru poskytovatelů v TypeScriptu a záměrně nezahrnuje klientská tajemství OAuth, řešení běhového prostředí, spouštěcí funkce, hlavičky požadavků ani údaje účtů.

Tento koncový bod použijte, když postranní proces běží mimo hlavní proces a nemůže přímo importovat open-sse/config/providerPluginManifestRegistry.ts.

---

Koncové body kompatibility

Metoda	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 (úpravy/inpainting)
POST	/v1/videos/generations	Generování videa ve stylu OpenAI
POST	/v1/music/generations	Generování hudby ve stylu OpenAI
POST	/v1/audio/transcriptions	OpenAI Audio (STT)
POST	/v1/audio/speech	OpenAI TTS (vrací tělo se zvukem)
POST	/v1/rerank	Přeřazení ve stylu Cohere/Voyage
POST	/v1/classify	Klasifikace 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 katalogu OpenAI
GET	/api/v1/vscode/{token}/models	Alias modelů 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ček Ollama

Všechny trasy POST mají stejnou strukturu: Bearer your-api-key + tělo JSON ověřené pomocí Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema atd., viz src/shared/validation/schemas.ts). Při selhání ověření schématu se vrátí stav 4xx.

Klientům, kteří nemohou připojit Authorization: Bearer ..., umožňuje OmniRoute předat klíče API také v URL, a to buď prostřednictvím kompatibilních parametrů řetězce dotazu (?token=..., ?apiKey=..., ?api_key=..., ?key=...), nebo pomocí vyhrazených koncových bodů /api/v1/vscode/{token}/... popsaných níže.

# Přeřazení
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Klasifikace Jina (přihlašovací ú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 }

# Vyhledávání Jina (s.jina.ai; aliasy poskytovatele: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# Moderování
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — vrací tělo audio/mpeg (nebo tělo v požadovaném formátu)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

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

# Generování videa / hudby (ID modelu s prefixem poskytovatele)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Vyhrazené trasy poskytovatelů

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

Pokud prefix poskytovatele chybí, přidá se automaticky. Při neshodě modelů se vrátí 400.

---

Files API

Endpoint kompatibilní s OpenAI pro dávkový vstup/výstup a nahrávání souborů s určeným účelem.

Metoda	Cesta	Popis
POST	/v1/files	Nahraje soubor (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — maximálně 512 MiB
GET	/v1/files	Vypíše soubory pro ověřený API klíč
GET	/v1/files/[id]	Načte metadata souboru
DELETE	/v1/files/[id]	Smaže soubor
GET	/v1/files/[id]/content	Odešle zpět nezpracovaný obsah souboru jako stream

Ověření: API klíč typu Bearer — rozsah souborů je omezen na jednotlivé API klíče prostřednictvím getApiKeyRequestScope. Klíč může zobrazit, stáhnout a smazat pouze vlastní soubory; relace ovládacího panelu bez klíče má přístup k celé instanci; přístup k souboru bez vlastníka (anonymně nahranému nebo nahranému prostřednictvím relace ovládacího panelu) je odepřen všem volajícím bez relace. GET /v1/files odmítne anonymního volajícího — stejně jako poskytnutý klíč, který nelze přeložit — s kódem 401, i když je REQUIRE_API_KEY=false, namísto vypsání souborů všech klientů (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

Batches API

Dávkové zpracování kompatibilní s OpenAI.

Metoda	Cesta	Popis
POST	/v1/batches	Vytvoří dávku — tělo ověřené pomocí v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET	/v1/batches	Vypíše dávky
GET	/v1/batches/[id]	Načte stav dávky a request_counts
DELETE	/v1/batches/[id]	Smaže dokončenou nebo neúspěšnou dávku
POST	/v1/batches/[id]/cancel	Zruší probíhající dávku

Ověření: API klíč typu Bearer. Rozsah dávek je omezen na jednotlivé API klíče podle stejného trojstranného pravidla jako u souborů: pouze vlastní klíč, relace ovládacího panelu v rámci celé instance, záznamy s vlastníkem null jsou odepřeny všem volajícím bez relace (načtení, smazání, zrušení a kontrola input_file_id při vytváření). GET /v1/batches odmítne anonymního volajícího s kódem 401, i když je REQUIRE_API_KEY=false.

---

Vyhledávací API

Abstrakce poskytovatelů webového vyhledávání (Tavily, Brave, Exa, Serper atd.).

Metoda	Cesta	Popis
GET	/v1/search	Vypíše nakonfigurované poskytovatele vyhledávání a jejich možnosti
POST	/v1/search	Spustí vyhledávací dotaz — tělo ověřuje v1SearchSchema, podporuje ukládání do mezipaměti/slučování
GET	/v1/search/analytics	Statistiky zásahů, latence a mezipaměti pro jednotlivé poskytovatele

Ověření: API klíč typu Bearer (extractApiKey + isValidApiKey). Zásady vyhledávání jsou vynucovány prostřednictvím enforceApiKeyPolicy.

---

API pro načítání webu

Extrahuje obsah z URL prostřednictvím nakonfigurovaného poskytovatele načítání webu (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

Metoda	Cesta	Popis
POST	/v1/web/fetch	Načte/extrahuje URL — tělo ověřuje v1WebFetchSchema

Ověření: API klíč typu Bearer (extractApiKey + isValidApiKey). Zásady jsou vynucovány prostřednictvím enforceApiKeyPolicy.

Záložní přepínání zohledňující kvóty (#8297): pokud není zadán explicitní provider, fond (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) je procházen v pevném pořadí priorit (fill-first) — nakonfigurovaný poskytovatel s omezenou četností požadavků je přeskočen, místo aby požadavek okamžitě ukončil, a opakovatelná chyba upstreamu nebo chyba kvóty (HTTP 429 vždy; 402/403 pro bezplatné úrovně Firecrawl/Tavily/TinyFish se stylem kvót — nikoli pro Jina Reader a nikdy pro běžný chybný požadavek 400) způsobí za běhu požadavku přechod k dalšímu dosud nevyzkoušenému poskytovateli s přihlašovacími údaji. Když jsou vyčerpáni všichni poskytovatelé ve fondu, koncový bod vrátí jedinou odpověď 429 (s hlavičkou Retry-After) namísto dřívější obecné odpovědi 400. Pokud je vyžádán explicitní provider, k žádnému tichému záložnímu přepnutí nedojde — explicitní poskytovatel s omezenou četností požadavků nebo s chybou vrátí svou vlastní chybu (429 při omezení četnosti požadavků, jinak stav upstreamu).

---

Streamování přes WebSocket

GET /v1/ws?handshake=1

Ověří handshake pro upgrade na WebSocket a vrátí ukázkové zprávy přenosového protokolu (request, cancel). Skutečné rámce WS zpracovává přibalený server WS mimo tabulku tras Next.js.

Ověření: API klíč typu Bearer během handshaku.

Responses API přes WebSocket (pouze codex)

# Stejný hostitel:port jako HTTP API (výchozí 20128); upgradujte připojení:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (nebo: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# První rámec MUSÍ být response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Proxy Responses API přes WebSocket je propojena výhradně s codex (backend ChatGPT). Naslouchá na stejném portu jako API/řídicí panel na cestách /v1/responses, /responses a /api/v1/responses. Při prvním rámci response.create provede ověření a přípravu prostřednictvím interního mostu codex-responses-ws, vybere připojení codex OAuth a tuneluje do wss://chatgpt.com/backend-api/codex/responses prostřednictvím transportu wreq-js. Modely jiné než codex jsou odmítnuty (codex_ws_provider_required). Pro směrování podle sdílené kvóty použijte model: "qtSd/<group>/codex/<model>". Implementováno v app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.

Ověření: API klíč typu Bearer během handshaku. Přibalený HTTP server (server-ws.mjs) musí být aktivním vstupním bodem (což ve výchozím nastavení je, pokud existuje app/server-ws.mjs).

ID modelu: použijte holé ID ChatGPT (bez prefixu codex/)

OpenAI Codex CLI ověřuje název modelu na straně klienta, pokud supports_websockets = true, a odmítá ID s prefixem poskytovatele, například codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Odešlete holé ID (např. gpt-5.5). Most OmniRoute je určen pouze pro codex, takže před tunelováním do upstreamu znovu vyhodnotí holé ID jako model codex (resolveCodexWsModelInfo) — i když by jinak bylo holé gpt-5.5 přes HTTP směrováno k jinému poskytovateli.

Konfigurace OpenAI Codex CLI

Nasměrujte Codex CLI na OmniRoute přidáním vlastního poskytovatele s podporou WebSocket do ~/.codex/config.toml (použijte samostatný CODEX_HOME, abyste nezasáhli do existující konfigurace):

model = "gpt-5.5"                 # holé ID — NE „codex/gpt-5.5“
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # bez koncového lomítka; URL WS se odvodí (v produkci použijte https/wss)
wire_api = "responses"                    # jediná podporovaná hodnota od února 2026
supports_websockets = true                # povolí transport Responses přes WS
env_key = "OMNIROUTE_API_KEY"             # obsahuje API klíč OmniRoute (Bearer)

export OMNIROUTE_API_KEY=sk-...           # API klíč OmniRoute (libovolný klíč, pokud REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

CLI upgraduje base_url + /responses na WebSocket a OmniRoute jej tuneluje do vybraného připojení codex OAuth. Ověřeno kompletně od začátku do konce vůči místnímu serveru: ChatGPT vrací codex.rate_limits + response.created a streamuje dokončení.

---

Kvóty a hlášení problémů

Metoda	Cesta	Popis
GET	/v1/quotas/check	Předběžné ověření kvóty pro provider + accountId před vydáním registrovaného klíče
POST	/v1/issues/report	Nahlášení selhání kvóty nebo vydání klíče na GitHub (vyžaduje GITHUB_ISSUES_REPO + token)

Ověření: Bearer API klíč (isAuthenticated).

---

Samoobslužné zobrazení využití (/api/usage/om-usage)

Libovolný API klíč může načíst své vlastní využití a kvóty — bez ověření pro správu. Toto je koncový bod, který klient (CLI, panel OmniCopilot) používá k zobrazení útraty držitele klíče.

# Textová podoba (historický kontrakt — prostý text pro terminál)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Strukturovaná podoba — používá ji uživatelské rozhraní
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

Klíč musí mít povolenou možnost allowUsageCommand (ve výchozím nastavení je vypnutá — správce API klíčů na řídicím panelu ji přepíná pro každý klíč zvlášť). Bez ní koncový bod odpoví stavem 403.

?format=json vrací rozlišitelnou strukturu, takže volající nikdy nečte datové pole z odpovědi o zamítnutí. Při úspěchu:

{
  "allowed": true,
  // přítomno pouze tehdy, když má klíč aktivované limity využití pro jednotlivý klíč (denní/týdenní v USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // snímek kvóty vybraného poskytovatele, nebo null, pokud zatím není nic v mezipaměti:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // snímek každého připojení, aby uživatelské rozhraní mohlo zobrazit několik poskytovatelů vedle sebe:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

Při zamítnutí (401 neplatný klíč / 403 nepovoleno) stejná trasa vrátí { "allowed": false, "error": { "message": "…" } } — přítomné, ale prázdné personal/provider (klíč je povolen, ale zatím nebyla získána žádná data) představuje jiný stav než zamítnutí a rozlišuje je pouze podoba JSON.

Ověření: vlastní Bearer API klíč volajícího, ověřený pomocí isValidApiKey — toto není rozhraní pro správu (/api/keys/…), které zůstává chráněné pomocí requireManagementAuth.

---

Sémantická mezipaměť

# Získání statistik mezipaměti
GET /api/cache/stats

# Vymazání všech mezipamětí
DELETE /api/cache/stats

Příklad odpovědi:

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

Dopad na latenci

ZÁSAH do sémantické mezipaměti poskytne odpověď z mezipaměti bez volání nadřazené služby, takže hlášená hodnota X-OmniRoute-Response-Latency je téměř nulová (bez ohledu na původní latenci nadřazené služby). Klienti citliví na latenci (benchmarking, monitorování p50/p99) by měli kontrolovat hlavičku odpovědi X-OmniRoute-Cache-Latency:

Hodnota	Význam
synthetic	Odpověď poskytnutá z mezipaměti; latence není skutečný čas upstreamu
(chybí)	Odpověď ze skutečného volání upstreamu

Obejití mezipaměti pro jednotlivé klíče

API klíče mohou pomocí cacheDefaultMode vypnout čtení ze sémantické mezipaměti:

Hodnota	Chování
legacy	Běžné chování mezipaměti (výchozí)
bypass	Zcela přeskočit vyhledávání v mezipaměti; vždy volat upstream

Nastavte při vytvoření klíče (POST /api/keys) nebo aktualizaci (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

Obejití pro jednotlivý požadavek

Libovolný požadavek může obejít mezipaměť bez ohledu na nastavení klíče:

X-OmniRoute-No-Cache: true

---

Řídicí panel a správa

Trasy pro správu (/api/* kromě veřejného ověřování/přihlášení) nejsou autorizovány běžnými API klíči pro inferenci. Rodiny přihlašovacích údajů, rozsahy oprávnění a příklady použití curl: Ověřování pro správu.

Ověřování

Koncový bod	Metoda	Popis
/api/auth/login	POST	Přihlášení
/api/auth/logout	POST	Odhlášení
/api/settings/require-login	GET/PUT	Přepnutí povinného přihlášení

Správa poskytovatelů

Koncový bod	Metoda	Popis
/api/providers	GET/POST	Výpis / vytvoření poskytovatelů
/api/providers/[id]	GET/PUT/DELETE	Správa poskytovatele
/api/providers/[id]/test	POST	Otestování připojení k poskytovateli
/api/providers/[id]/models	GET	Výpis modelů poskytovatele
/api/providers/validate	POST	Ověření konfigurace poskytovatele
/api/providers/bulk	POST	Hromadné přidání API klíčů pro JEDNOHO poskytovatele
/api/providers/import	POST	Import heterogenního SEZNAMU poskytovatelů z analyzovaného souboru CSV/JSON (#6836); výsledky částečných selhání po řádcích
/api/provider-nodes*	Různé	Správa uzlů poskytovatelů
/api/provider-models	GET/POST/PATCH/DELETE	Vlastní modely (přidání, aktualizace, skrytí/zobrazení, odstranění)

Toky OAuth

Koncový bod	Metoda	Popis specifický pro poskytovatele
/api/oauth/[provider]/[action]	Různé	OAuth specifický pro poskytovatele

Směrování a konfigurace

Koncový bod	Metoda	Popis
/api/models/alias	GET/POST	Aliasy modelů
/api/models/catalog	GET	Všechny modely podle poskytovatele + typu
/api/combos*	Různé	Správa kombinací
/api/keys*	Různé	Správa API klíčů
/api/pricing	GET	Ceny modelů

Využití a analytika

Endpoint	Metoda	Popis
/api/usage/history	GET	Historie využití
/api/usage/logs	GET	Protokoly využití
/api/usage/request-logs	GET	Protokoly na úrovni požadavků
/api/usage/[connectionId]	GET	Využití podle připojení
/api/usage/token-limits	GET/POST/DELETE	Rozpočty limitů tokenů podle klíče API
/api/usage/model-latency-stats	GET	Průběžné agregované statistiky latence podle poskytovatele/modelu (průměr/p50/p95/p99, míra úspěšnosti); filtry: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health	GET	Souhrn stavu mezipaměti promptů nad call_logs — poměr zápisů/čtení, rozdělení velikosti zápisů p50/p90/p99, koncentrace intenzivních zápisů, rozdělení podle modelu a výsledek healthy/degraded/thrash/no-data; parametry dotazu range (1h|24h|7d|30d, výchozí 24h) a volitelný model (#8827)

Nastavení

Endpoint	Metoda	Popis
/api/settings	GET/PUT/PATCH	Obecná nastavení
/api/settings/proxy	GET/PUT	Konfigurace síťového proxy serveru
/api/settings/proxy/test	POST	Otestování připojení přes proxy server
/api/settings/ip-filter	GET/PUT	Seznam povolených/blokovaných IP adres
/api/settings/thinking-budget	GET/PUT	Režim přepisu požadavku na rozpočet přemýšlení/uvažování (beze změny / automatické odstranění / vlastní / adaptivní). Nezávislý na kompresi. Viz THINKING_BUDGET.md.
/api/settings/system-prompt	GET/PUT	Globální systémový prompt
/api/settings/compression	GET/PUT	Globální konfigurace komprese
/api/settings/purge-request-history	POST	Vymazání řádků protokolu požadavků a místních artefaktů protokolu volání

Kontext a komprese

Endpoint	Metoda	Popis
/api/compression/preview	POST	Náhled komprese off/lite/standard/aggressive/ultra/RTK/stacked
/api/compression/language-packs	GET	Seznam dostupných jazykových balíčků Caveman
/api/compression/rules	GET	Seznam metadat pravidel Caveman
/api/context/caveman/config	GET/PUT	Alias pro nastavení specifická pro Caveman
/api/context/rtk/config	GET/PUT	Nastavení specifická pro RTK, včetně vlastních filtrů a uchovávání nezpracovaného výstupu
/api/context/rtk/filters	GET	Katalog filtrů RTK a diagnostika vlastních filtrů
/api/context/rtk/test	POST	Spuštění náhledu/testu RTK nad textovou datovou částí
/api/context/rtk/raw-output/[id]	GET	Načtení uchovaného anonymizovaného nezpracovaného výstupu podle ID ukazatele
/api/context/combos	GET/POST	Seznam/vytvoření kombinací komprese
/api/context/combos/[id]	GET/PUT/DELETE	Podrobnosti/aktualizace/odstranění kombinace komprese
/api/context/combos/[id]/assignments	GET/PUT	Přiřazení kombinací komprese ke kombinacím směrování
/api/context/analytics	GET	Alias analytiky komprese

Monitorování

Endpoint	Metoda	Popis
/api/sessions	GET	Sledování aktivních relací
/api/rate-limits	GET	Limity požadavků pro jednotlivé účty
/api/monitoring/health	GET	Kontrola stavu + souhrn poskytovatelů (catalogCount, configuredCount, activeCount, monitoredCount). Zobrazení pro správu zahrnuje credentialHealth: skalární hodnoty mezipaměti sond, failedConnections, když failed>0, a staleDbNonOkCount (trvalá hodnota test_status v SQLite, nikoli ukazatel). Viz MONITORING_GUIDE.md.
/api/cache/stats	GET/DELETE	Statistiky mezipaměti / vymazání
/api/modality-bridge/stats	GET	Hodnoty attempts, úspěšné pokusy/bridged, selhání, zásahy mezipaměti, totalLatencyMs, latencySamples, hodnota averageLatencyMs vypočtená podle počtu vzorků a čas posledního použití uložené v paměti (resetují se při restartu; ověření pro správu)
/api/modality-bridge/video/runtime	GET	Striktní kontrola důvěryhodného místního rozhraní před ověřením/sondou pro správu; sanitizované informace o dostupnosti a verzích FFmpeg/ffprobe (no-store)
/api/modality-bridge/video/extract	POST	Interní ověřovaný zprostředkovatel bajtů přes důvěryhodné místní rozhraní; vstup 50 MiB, omezená fronta/výstup 32 MiB, kapacita 503, odpojení 499, překročení časového limitu 504; nejde o veřejné API pro nahrávání souborů

Zálohování a export/import

Endpoint	Metoda	Popis
/api/db-backups	GET	Vypsat dostupné zálohy
/api/db-backups	PUT	Vytvořit ruční zálohu
/api/db-backups	POST	Obnovit z konkrétní zálohy
/api/db-backups/export	GET	Stáhnout databázi jako soubor .sqlite
/api/db-backups/import	POST	Nahrát soubor .sqlite a nahradit databázi
/api/db-backups/exportAll	GET	Stáhnout úplnou zálohu jako archiv .tar.gz

Cloudová synchronizace

Endpoint	Metoda	Popis
/api/sync/cloud	Různé	Operace cloudové synchronizace
/api/sync/initialize	POST	Inicializovat synchronizaci
/api/cloud/*	Různé	Správa cloudu

Tunely

Endpoint	Metoda	Popis
/api/tunnels/cloudflared	GET	Načíst stav instalace a běhu Cloudflare Quick Tunnel pro řídicí panel
/api/tunnels/cloudflared	POST	Povolit nebo zakázat Cloudflare Quick Tunnel (action=enable/disable)
/api/tunnels/ngrok	GET	Načíst stav běhu ngrok Tunnel pro řídicí panel
/api/tunnels/ngrok	POST	Povolit nebo zakázat ngrok Tunnel (action=enable/disable)

Nástroje CLI

Endpoint	Metoda	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	Obecné prostředí CLI

Odpovědi CLI zahrnují: installed, runnable, command, commandPath, runtimeMode, reason.

Agenti ACP

Endpoint	Metoda	Popis
/api/acp/agents	GET	Vypsat všechny zjištěné agenty (vestavěné + vlastní) včetně stavu
/api/acp/agents	POST	Přidat vlastního agenta nebo aktualizovat mezipaměť detekce
/api/acp/agents	DELETE	Odebrat vlastního agenta podle parametru dotazu id

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

Odolnost a limity požadavků

Endpoint	Metoda	Popis
/api/resilience	GET/PATCH	Získat/aktualizovat frontu požadavků, prodlevu připojení, jistič poskytovatele a nastavení čekání
/api/resilience/reset	POST	Resetovat jističe okruhů poskytovatelů
/api/resilience/model-cooldowns	GET	Vypsat aktivní blokace podle (poskytovatele, připojení, modelu), seřazené podle zbývajícího času
/api/resilience/model-cooldowns	DELETE	Zrušit blokaci modelu — tělo {provider, model} nebo {all: true} pro vymazání všech
/api/rate-limits	GET	Stav limitu požadavků pro jednotlivé účty
/api/rate-limit	GET	Globální konfigurace limitu požadavků

Všechny čtyři trasy /api/resilience/* vyžadují ověření pro správu (requireManagementAuth). Úplný rozbor jističe poskytovatele, prodlevy připojení a blokace modelu najdete v části Odolnost (rozšířené).

Vyhodnocení

Endpoint	Metoda	Popis
/api/evals	GET/POST	Vypsat sady vyhodnocení / spustit vyhodnocení

Zásady

Endpoint	Metoda	Popis
/api/policies	GET/POST/DELETE	Spravovat zásady směrování

Soulad s předpisy

Endpoint	Metoda	Popis
/api/compliance/audit-log	GET	Protokol auditu souladu (posledních N)

v1beta (kompatibilní s Gemini)

Endpoint	Metoda	Popis
/v1beta/models	GET	Vypsat modely ve formátu Gemini
/v1beta/models/{...path}	POST	Endpoint Gemini generateContent

Tyto endpointy kopírují formát API Gemini pro klienty, kteří očekávají nativní kompatibilitu se sadou Gemini SDK.

Interní / systémová API

Koncový bod	Metoda	Popis
/api/init	GET	Kontrola inicializace aplikace (používá se při prvním spuštění)
/api/tags	GET	Značky modelů kompatibilní s Ollama (pro klienty Ollama)
/api/restart	POST	Spustí korektní restart serveru
/api/shutdown	POST	Spustí korektní vypnutí serveru
/api/system/env/repair	POST	Opraví proměnné prostředí poskytovatele OAuth

Poznámka: Tyto koncové body používá interně systém nebo slouží ke kompatibilitě s klienty Ollama. Koncoví uživatelé je obvykle nevolají.

Oprava prostředí OAuth (v3.6.1+)

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

{
  "provider": "claude-code"
}

Opraví chybějící nebo poškozené proměnné prostředí OAuth pro konkrétního poskytovatele. Vrací:

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

---

Přepis zvuku

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

Přepisujte zvukové soubory pomocí libovolného nakonfigurovaného poskytovatele STT. První segment cesty vybírá nativního poskytovatele (openai/…, deepgram/…). Brány, které znovu zpřístupňují model jiného poskytovatele, používají kvalifikovaný identifikátor (openrouter/deepgram/nova-3).

Požadavek:

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

Odpověď:

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

Příklady identifikátorů modelů: openai/whisper-1 (vyžaduje klíč OpenAI), openrouter/deepgram/nova-3 (vyžaduje klíč OpenRouter), deepgram/nova-3 (vyžaduje nativní klíč Deepgram). Požadavek se samotným deepgram/nova-3 nepoužívá OpenRouter.

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

---

Kompatibilita s Ollama

Pro klienty, kteří používají formát API služby Ollama:

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

# Výpis modelů (formát Ollama)
GET /api/tags

Požadavky jsou automaticky převáděny mezi formátem Ollama a interními formáty.

Tokenizované aliasy pro VS Code / aliasy bez hlaviček

Tyto aliasy použijte, pokud integrace nemůže vložit hlavičku Authorization a potřebuje mít klíč API vložený do základní adresy URL.

# Alias katalogu ve stylu OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Aliasy chatu ve stylu OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Aliasy ve stylu Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Pří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:

• Tokenizované aliasy používají stejné obslužné rutiny jako /v1/* a /api/tags; struktura odpovědí zůstává identická.
• Pokud klient podporuje vlastní hlavičky, upřednostněte Authorization: Bearer ....
• Tokeny v adrese URL se mohou objevit v protokolech reverzního proxy serveru, historii prohlížeče a telemetrii mimo OmniRoute. Považujte je za možnost zajišťující kompatibilitu, nikoli za výchozí režim ověřování.

---

Telemetrie

# Získání souhrnu telemetrie latence (p50/p95/p99 pro každého poskytovatele)
GET /api/telemetry/summary

Odpověď:

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

---

Rozpočet

# Získání stavu rozpočtu pro všechny klíče API
GET /api/usage/budget

# Nastavení nebo aktualizace 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 ke schématu (setBudgetSchema): apiKeyId je povinné; alespoň jedna z hodnot dailyLimitUsd, weeklyLimitUsd nebo monthlyLimitUsd musí být větší než nula. Volitelná pole: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). Zastaralá struktura {keyId, limit, period} vrací 400 Bad Request.

Limity tokenů

Rozpočty tokenů pro jednotlivé klíče API (odlišné od výše uvedeného rozpočtu založeného na USD). Vynucují se přímo během zpracování požadavku: jakmile využití klíče v aktuálním časovém okně dosáhne stanoveného limitu, požadavky jsou odmítnuty s chybou 429 Too Many Requests. Limity lze omezit na konkrétní model, provider nebo je použít globálně (global) pro celý klíč; pokud požadavku odpovídá více limitů, použije se ten nejpřísnější.

# Výpis limitů tokenů klíče (včetně aktuálního využití časového okna)
GET /api/usage/token-limits?apiKeyId=key-123

# Vytvoření nebo aktualizace limitu 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
}

# Odstranění limitu tokenů podle id
DELETE /api/usage/token-limits?id=tl-abc

Poznámky ke schématu (setTokenLimitSchema): apiKeyId a scopeType (model | provider | global) jsou povinné. scopeValue je povinné, pokud scopeType není global (např. id modelu pro rozsah model, id poskytovatele pro rozsah provider). tokenLimit musí být kladné celé číslo (převedené z řetězce). Volitelné: id (vynechte při vytváření, zadejte při aktualizaci), resetInterval (daily | weekly | monthly, výchozí hodnota monthly), resetTime (HH:MM), enabled (výchozí hodnota true). Odpovědi GET rozšiřují každý limit o tokensUsed, remaining, windowStart, periodStartAt a nextResetAt. Jde o koncový bod třídy pro správu (ověřování se centrálně vynucuje prostřednictvím autorizačního kanálu).

Zpracování požadavků

1. Klient odešle požadavek na /v1/*
2. Obslužná rutina trasy zavolá handleChat, handleEmbedding, handleAudioTranscription nebo handleImageGeneration
3. Model je vyhodnocen (přímý poskytovatel/model nebo alias/kombinace)
4. Přihlašovací údaje jsou vybrány z místní databáze s filtrováním podle dostupnosti účtu
5. Pro chat: handleChatCore zkontroluje mezipaměť sémantických shod/podpisů a vyhodnotí nastavení komprese kombinace
6. Pokud je povolena, před překladem pro poskytovatele se spustí proaktivní komprese (lite, Caveman, RTK nebo jejich vrstvená kombinace)
7. Vykonavatel poskytovatele odešle požadavek nadřazené službě
8. Odpověď je převedena zpět do formátu klienta (chat) nebo vrácena beze změny (vektorové reprezentace/obrázky/zvuk)
9. Zaznamená se využití, analytika komprese a protokoly požadavků
10. Při chybách se podle pravidel kombinace použije záložní varianta

Úplný popis architektury: ARCHITECTURE.md

---

Správa kombinací

Kombinace směrování vyšší úrovně (již shrnuté v části /api/combos*) lze také mapovat v poměru 1:1 ze vzoru id modelu, což umožňuje transparentní přesměrování id modelu ve stylu OpenAI na kombinaci.

Metoda	Cesta	Popis
GET	/api/model-combo-mappings	Výpis všech mapování model→kombinace
POST	/api/model-combo-mappings	Vytvoření mapování — tělo: {pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	Načtení jednoho mapování
PUT	/api/model-combo-mappings/[id]	Aktualizace polí existujícího mapování
DELETE	/api/model-combo-mappings/[id]	Odstranění mapování

Ověření: relace pro správu / klíč API (requireManagementAuth).

---

Webhooky

Odběry odchozích webhooků pro události OmniRoute (dokončení požadavku, vyčerpání kvóty, rotace klíče atd.).

Metoda	Cesta	Popis
GET	/api/webhooks	Vypíše webhooky (tajné klíče jsou maskovány jako <prefix>...)
POST	/api/webhooks	Vytvoří webhook — tělo: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	Načte webhook
PUT	/api/webhooks/[id]	Aktualizuje url/events/secret/description
DELETE	/api/webhooks/[id]	Odstraní webhook
POST	/api/webhooks/[id]/test	Odešle testovací datovou část na URL webhooku a vrátí stav doručení

Ověření: relace správy / API klíč (requireManagementAuth).

---

Registrované klíče (automatická správa)

Podsystém automatické správy klíčů je používá k vydávání a rotaci API klíčů u poskytovatele nebo účtu na pozadí s denními a hodinovými kvótami.

Metoda	Cesta	Popis
GET	/api/v1/registered-keys	Vypíše registrované klíče (pouze maskovaná předpona)
POST	/api/v1/registered-keys	Vydá nový registrovaný klíč — tělo: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Nezpracovaný klíč vrátí pouze jednou. Při odmítnutí kvůli kvótě vrátí 429.
GET	/api/v1/registered-keys/[id]	Načte metadata registrovaného klíče (bez nezpracovaného klíče)
DELETE	/api/v1/registered-keys/[id]	Zneplatní registrovaný klíč
POST	/api/v1/registered-keys/[id]/revoke	Explicitní koncový bod pro zneplatnění (stejný účinek jako DELETE)

Ověření: API klíč Bearer (isAuthenticated). Viz také /v1/quotas/check a /v1/issues/report.

---

Protokol agentů

Úlohy cloudových agentů (Claude Code, Codex Cloud, OpenHands atd.) spouštěné vzdáleně jménem uživatelů OmniRoute.

Metoda	Cesta	Popis
GET	/api/v1/agents/tasks	Seznam úloh — volitelné ?provider=, ?status=, ?limit= (1–500, výchozí hodnota 50)
POST	/api/v1/agents/tasks	Vytvoření úlohy — tělo ověřované pomocí CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Vrací 201 s obálkou úlohy
DELETE	/api/v1/agents/tasks?id=...	Odstranění úlohy
GET	/api/v1/agents/tasks/[id]	Načtení úlohy — synchronně aktualizuje stav z nadřazeného cloudového agenta, pokud je nastaveno external_id
POST	/api/v1/agents/tasks/[id]	Rozlišená akce: {action: "approve"}, {action: "message", message} nebo {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	Odstranění konkrétní úlohy podle ID

Ověření: U každé metody je vyžadováno ověření pro správu (requireCloudAgentManagementAuth). Před verzí v3.8.0 nebyly tyto metody ověřovány — změnu narušující zpětnou kompatibilitu naleznete v commitu 588a0333.

# Vytvoření cloudové ú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 pro správu

Odchozí proxy servery HTTP(S)/SOCKS, které lze přiřadit poskytovatelům, účtům nebo globálně.

Metoda	Cesta	Popis
GET	/api/v1/management/proxies	Seznam proxy serverů (s ?id= vrátí jeden; s ?id=&where_used=1 vrátí graf přiřazení)
POST	/api/v1/management/proxies	Vytvoření proxy serveru — tělo ověřované pomocí createProxyRegistrySchema
PATCH	/api/v1/management/proxies	Aktualizace proxy serveru — tělo ověřované pomocí updateProxyRegistrySchema (vyžaduje id)
DELETE	/api/v1/management/proxies?id=...&force=1	Odstranění proxy serveru (pro odpojení přiřazení použijte force=1)
GET	/api/v1/management/proxies/assignments	Seznam přiřazení — lze filtrovat podle proxy_id, scope, scope_id; předáním resolve_connection_id=<id> zjistíte aktivní proxy server pro dané připojení
PUT	/api/v1/management/proxies/assignments	Přiřazení — tělo ověřované pomocí proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Vymaže mezipaměť dispečera
PUT	/api/v1/management/proxies/bulk-assign	Hromadné přiřazení — tělo ověřované pomocí bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?})
GET	/api/v1/management/proxies/health?hours=24	Agregovaný stav proxy serverů (počty úspěchů/neúspěchů, latence) za časové období

Ověření: Na každé trase je vyžadována relace pro správu nebo klíč API (requireManagementAuth).

Trasy POST /api/v1/management/proxies/[id]/assignments a POST /api/v1/management/proxies/[id]/health z popisu úlohy jsou obsluhovány výše uvedenými plochými trasami /assignments a /health — v kódové základně neexistují žádné dílčí trasy podle ID.

---

Odolnost (rozšířená)

OmniRoute poskytuje tři nezávislé mechanismy pro dočasná selhání; níže uvedené koncové body pro správu umožňují operátorům číst a přepisovat jejich stav:

Rozsah	Úložiště stavu	Čtení	Resetování / vymazání
Jistič poskytovatele	domain_circuit_breakers + v paměti	/api/monitoring/health	POST /api/resilience/reset
Prodleva připojení	rateLimitedUntil u připojení poskytovatele	/api/rate-limits, /api/providers/[id]	(znovu se aktivuje až při použití; vymazání přes PUT poskytovatele)
Uzamčení modelu	Registr dostupnosti modelů v paměti	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

PATCH /api/resilience přijímá přepsání jističe poskytovatele v providerBreaker.oauth a providerBreaker.apikey. Každý profil podporuje degradationThreshold, failureThreshold a resetTimeoutMs; stejná pole jsou dostupná v Řídicí panel → Nastavení → Odolnost.

# Vymazání uzamčení jednoho 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"}'

# Vymazání všech uzamčení
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

Úplný koncepční přehled a výchozí nastavení jističů: viz CLAUDE.md → „Stav běhu odolnosti“.

---

Dovednosti

Framework dovedností pro rozšíření OmniRoute o vlastní spustitelné obslužné rutiny a integrace s tržišti.

Metoda	Cesta	Popis
GET	/api/skills	Výpis nainstalovaných dovedností — lze filtrovat pomocí ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, stránkováno
GET	/api/skills/[id]	Načtení jedné dovednosti
PUT	/api/skills/[id]	Aktualizace dovednosti (název, popis, režim, schéma, obslužná rutina, značky)
DELETE	/api/skills/[id]	Odinstalování dovednosti
POST	/api/skills/install	Instalace dovednosti z nezpracovaného manifestu — tělo: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	Výpis nedávných spuštění dovedností (auditní stopa se vstupy, výstupy a dobou trvání)
GET	/api/skills/marketplace?q=...	Vyhledávání / seznam oblíbených položek z tržiště SkillsMP (vyžaduje nastavení skillsmpApiKey)
POST	/api/skills/marketplace/install	Instalace dovednosti podle ID ze SkillsMP
GET	/api/skills/skillssh?q=&limit=	Vyhledávání v registru skills.sh
POST	/api/skills/skillssh/install	Instalace dovednosti podle ID ze skills.sh

Ověření: relace správy / klíč API. Trasy vyhledávání na tržišti přijímají ověření správy nebo klíč API typu Bearer (isAuthenticated).

---

Paměť

Trvalé úložiště konverzační/faktické paměti s rozsahem omezeným na klíč API / relaci.

Metoda	Cesta	Popis
GET	/api/memory	Výpis vzpomínek — ?apiKeyId=, ?type=, ?sessionId=, ?q=, se stránkováním pomocí offset/limit nebo page/limit
POST	/api/memory	Vytvoření vzpomínky — tělo validované pomocí Zod: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	Načtení jedné vzpomínky
DELETE	/api/memory/[id]	Odstranění vzpomínky
GET	/api/memory/health	Stav paměťového subsystému (připojení k DB, backend vektorových reprezentací, stav vektorového indexu)

Ověřování: relace pro správu / klíč API (requireManagementAuth). Výčet type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (viz MemoryType v src/lib/memory/types.ts).

---

Server MCP

OmniRoute obsahuje vestavěný server protokolu Model Context Protocol se 3 transporty (stdio, SSE, streamable-http) a nástroji s omezeným rozsahem oprávnění. Níže uvedené endpointy řídicího panelu načítají údaje o stavu/auditu a zprostředkovávají HTTP transporty.

Metoda	Cesta	Popis
GET	/api/mcp/status	Prezenční signál, transport, stav připojení, poslední volání, nejpoužívanější nástroje, míra úspěšnosti za 24 hodin
GET	/api/mcp/tools	Seznam nástrojů MCP s poli name, description, scopes, phase, auditLevel, sourceEndpoints
GET	/api/mcp/sse	Otevření streamu SSE pro transport SSE (vrací 503, pokud je MCP zakázáno nebo transport neodpovídá)
POST	/api/mcp/sse	Odeslání rámce JSON-RPC prostřednictvím transportu SSE
GET	/api/mcp/stream	Otevření strany SSE transportu Streamable HTTP (zprávy iniciované serverem)
POST	/api/mcp/stream	Odeslání rámce JSON-RPC prostřednictvím transportu Streamable HTTP
DELETE	/api/mcp/stream	Ukončení relace Streamable HTTP
GET	/api/mcp/audit	Dotaz na protokol auditu — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	Agregované statistiky auditu (celkové počty, míra úspěšnosti, průměrná doba trvání, nejpoužívanější nástroje)

Ověřování: transporty sse/stream respektují ověřování specifické pro MCP (klíč API typu Bearer s rozsahem mcp); trasy status/tools/audit* jsou čitelné z řídicího panelu (kromě přístupu k hostiteli řídicího panelu není vyžadováno žádné další ověření).

Oba HTTP transporty jsou řízeny nastaveními settings.mcpEnabled a settings.mcpTransport — neshoda transportu vrací 400, zakázaný stav MCP vrací 503.

---

Server A2A

OmniRoute zpřístupňuje koncový bod A2A (Agent-to-Agent) JSON-RPC 2.0 a také REST obálku pro účely kontroly a řídicího panelu.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # volitelné, pokud není nastavena proměnná 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"}]
  }
}

Podporované metody (všechny jsou podmíněny nastavením settings.a2aEnabled):

Metoda	Popis
message/send	Synchronní spuštění dovednosti; vrací {task, artifacts, metadata}
message/stream	Streamované spuštění stejné sady dovedností pomocí SSE
tasks/get	Načtení úlohy podle taskId
tasks/cancel	Zrušení úlohy podle taskId

Vestavěné dovednosti: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Karta agenta

GET /.well-known/agent.json

Vrací veřejnou kartu agenta A2A (název, popis, schopnosti, katalog dovedností, schéma ověřování) — je veřejně ukládána do mezipaměti na 1 hodinu. Ověření není vyžadováno.

Pomocné koncové body REST

Metoda	Cesta	Popis
GET	/api/a2a/status	Stav povolení A2A + statistiky úloh + souhrn karty agenta uložené v mezipaměti
GET	/api/a2a/tasks	Výpis úloh — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST	/api/a2a/tasks	(Není implementováno jako pomocný koncový bod REST — vytvořte prostřednictvím JSON-RPC message/send)
GET	/api/a2a/tasks/[id]	Načtení jedné úlohy
POST	/api/a2a/tasks/[id]/cancel	Zrušení úlohy

Ověřování: pomocné koncové body REST fungují bez ověření pro správu (jsou čitelné z řídicího panelu); trasa JSON-RPC /a2a používá Bearer OMNIROUTE_API_KEY, pokud je nakonfigurován.

---

Cloud, vyhodnocení a posouzení

Metoda	Cesta	Popis
POST	/api/cloud/auth	Ověří klíč Bearer a vrátí maskovaná připojení poskytovatelů + aliasy modelů pro klienty cloudové synchronizace
POST	/api/cloud/credentials/update	Aktualizuje šifrované přihlašovací údaje poskytovatele synchronizovaného s cloudem
POST	/api/cloud/model/resolve	Převede logické ID modelu na konkrétního poskytovatele/model pomocí místní směrovací tabulky
GET	/api/cloud/models/alias	Vypíše aliasy modelů zpřístupněné cloudové synchronizaci
GET	/api/assess	Načte nejnovější kategorizace posouzení (podle poskytovatele/modelu)
POST	/api/assess	Spustí posouzení — tělo: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	Vypíše vestavěné sady vyhodnocení + nejnovější běhy
POST	/api/evals	Spustí běh vyhodnocení
POST	/api/evals/suites	Vytvoří vlastní sadu vyhodnocení — tělo ověřuje evalSuiteSaveSchema
GET	/api/evals/suites/[id]	Načte vlastní sadu vyhodnocení

Ověřování: /api/cloud/auth ověřuje klíč Bearer přímo; ostatní trasy /api/cloud/*, /api/evals/* a /api/assess vyžadují relaci pro správu nebo klíč API. Požadavek POST na /api/assess používá validateBody se schématem rozsahu typu discriminated union.

---

Správa ACP (Agent Client Protocol)

jako podřízené procesy. Tyto koncové body spravují detekci agentů ACP a registraci vlastních agentů.

Metoda	Cesta	Popis
GET	/api/acp/agents	Vypíše všechny známé agenty CLI (vestavěné i vlastní) se stavem instalace, verzí a binárním souborem
POST	/api/acp/agents	Zaregistruje vlastního agenta ACP nebo aktualizuje mezipaměť — tělo: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} nebo {action: "refresh"}
DELETE	/api/acp/agents	Odebere vlastního agenta ACP — parametr dotazu: ?id=<agentId>

Příklad odpovědi (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
}

Autorizace: Vyžaduje relaci pro správu (soubor cookie auth_token řídicího panelu) nebo klíč API s rozsahem oprávnění pro správu.

Úplné podrobnosti najdete v dokumentu Framework ACP.

---

Analytika a pozorovatelnost

Koncové body analytiky v reálném čase pro monitorování směrování, komprese a diverzity poskytovatelů. Tyto koncové body zajišťují data pro stránky /dashboard/analytics/*.

Analytika automatického směrování

Metoda	Cesta	Popis
GET	/api/analytics/auto-routing	Agregované statistiky automatického směrování: celkový počet volání, rozdělení strategií, úrovní a hlavní poskytovatelé
GET	/api/analytics/auto-routing?days=7	Statistiky za časové období (výchozí hodnota je 24 h)

Příklad odpovědi:

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

Metoda	Cesta	Popis
GET	/api/analytics/compression	Agregované statistiky komprese: ušetřené tokeny, procento úspory, rozdělení režimů, využití enginů

Příklad odpovědi:

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

Sledování diverzity poskytovatelů

Metoda	Cesta	Popis
GET	/api/analytics/diversity	Sledování diverzity založené na Shannonově entropii: měřením rozložení poskytovatelů předchází jediným bodům selhání

Příklad odpovědi:

{
  "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 zajišťuje 40 % provozu — zvažte větší diverzifikaci"]
}

Autorizace: Vyžaduje relaci pro správu nebo klíč API s rozsahem oprávnění pro správu.

---

Operace správce

Koncové body určené pouze pro správce k provozní správě.

Metoda	Cesta	Popis
GET	/api/admin/concurrency	Načtení aktuálních limitů souběžnosti (globálních + pro jednotlivé poskytovatele)
POST	/api/admin/concurrency	Aktualizace limitů souběžnosti — tělo: {global?: number, perProvider?: Record<string, number>}

Ověření: Vyžaduje relaci pro správu s oprávněním správce.

---

Správa nástrojů CLI

Správa nástrojů CLI, které se integrují s OmniRoute (antigravity, chipotle, commandCode, devin-cli atd.). Úplný seznam naleznete v referenční příručce poskytovatelů.

Metoda	Cesta	Popis
GET	/api/cli-tools/all-statuses	Stav všech nástrojů CLI (instalace, verze, poslední zaznamenané použití)
GET	/api/cli-tools/status	Podrobnosti o stavu jednoho nástroje CLI (dotaz ?tool=)
POST	/api/cli-tools/apply	Zápis vygenerované konfigurace nástroje (dryRun zobrazí náhled; při běhu v kontejneru vrátí 422 + containerEphemeralTarget; migration upozorní na starší YAML konfiguraci Codex)
GET	/api/cli-tools/backups	Výpis záloh konfigurace nástrojů CLI
POST	/api/cli-tools/backups	Vytvoření zálohy konfigurací všech nástrojů CLI
POST	/api/cli-tools/backups	Obnovení: stejný koncový bod s {tool, backupId} v těle obnoví danou zálohu
GET	/api/cli-tools/antigravity-mitm	Stav proxy MITM Antigravity (nástroj CLI „antigravity-mitm“)
POST	/api/cli-tools/antigravity-mitm/alias	Konfigurace aliasů antigravity-mitm

Ověření: Vyžaduje relaci pro správu.

---

Dovednosti agentů

Správa dovedností agentů AI (podobných vlastním GPT od OpenAI, ale určených pro agenty).

Metoda	Cesta	Popis
GET	/api/agent-skills	Výpis všech dovedností agentů (vestavěných + vlastních)
GET	/api/agent-skills/[id]	Načtení konkrétní dovednosti agenta
POST	/api/agent-skills	Vytvoření vlastní dovednosti agenta — tělo: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	Aktualizace vlastní dovednosti agenta
DELETE	/api/agent-skills/[id]	Odstranění vlastní dovednosti agenta
GET	/api/agent-skills/[id]/raw	Načtení nezpracovaného promptu + metadat (bez spuštění)
POST	/api/agent-skills/generate	Vygenerování nové dovednosti pomocí AI z popisu v přirozeném jazyce

Ověření: Vyžaduje relaci pro správu nebo klíč API s oprávněním pro správu.

---

Správa mezipaměti

Správa sémantické mezipaměti a mezipaměti uvažování.

Metoda	Cesta	Popis
GET	/api/cache	Přehled mezipaměti: celkový počet záznamů, míra zásahů, velikost na disku
GET	/api/cache/entries	Seznam záznamů v mezipaměti (se stránkováním)
DELETE	/api/cache/entries	Odstranění záznamů z mezipaměti (filtrování podle parametrů dotazu)
GET	/api/cache/stats	Podrobné statistiky mezipaměti (podle poskytovatele a modelu)
GET	/api/cache/reasoning	Stav mezipaměti uvažování (pro opakované přehrání uvažování)
DELETE	/api/cache/reasoning	Vymazání mezipaměti uvažování — parametry dotazu: ?toolCallId=<id> (jeden), ?provider=<p> nebo žádné (vše)

Ověření: Vyžaduje relaci pro správu.

---

Systém paměti

Správa trvalé paměti (FTS5 + vektorová vnoření).

Metoda	Cesta	Popis
GET	/api/memory	Seznam záznamů v paměti (filtrování podle rozsahu, typu a vyhledávacího dotazu)
POST	/api/memory	Vytvoření nového záznamu v paměti — tělo: {scope, type, content, metadata?}
GET	/api/memory/[id]	Získání konkrétního záznamu v paměti
PUT	/api/memory/[id]	Aktualizace záznamu v paměti
DELETE	/api/memory/[id]	Odstranění záznamu z paměti
GET	/api/memory?q=	Vyhledávání v paměti (FTS5 + vektory) — statistiky jsou součástí stejné odpovědi

Ověření: Vyžaduje relaci pro správu nebo klíč API s rozsahem pro správu.

---

Webhooky

Správa odběrů událostí prostřednictvím webhooků.

Metoda	Cesta	Popis
GET	/api/webhooks	Seznam všech odběrů webhooků
POST	/api/webhooks	Vytvoření odběru webhooku — tělo: {url, events[], secret?, active?}
GET	/api/webhooks/[id]	Získání konkrétního odběru webhooku
PUT	/api/webhooks/[id]	Aktualizace odběru webhooku
DELETE	/api/webhooks/[id]	Odstranění odběru webhooku
GET	/api/webhooks/[id]/deliveries	Seznam historie doručení webhooku (protokol úspěšných/neúspěšných doručení)
POST	/api/webhooks/[id]/test	Odeslání testovací události webhooku

Ověření: Vyžaduje relaci pro správu.

Úplný seznam typů událostí naleznete v dokumentu Framework webhooků.

---

Framework dovedností

Správa dovedností (frameworku agentních rozšíření).

Metoda	Cesta	Popis
GET	/api/skills	Vypíše všechny nainstalované dovednosti (vestavěné i vlastní)
POST	/api/skills/install	Nainstaluje dovednost z místní cesty nebo URL
DELETE	/api/skills/[id]	Odinstaluje dovednost
PUT	/api/skills/[id]	Povolí nebo zakáže dovednost — tělo: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST	/api/skills/executions	Spustí dovednost — tělo: {skillName, apiKeyId, input?, sessionId?}
GET	/api/skills/executions	Vypíše historii spuštění všech dovedností (filtrování pomocí ?apiKeyId=)

Ověření: Vyžaduje relaci pro správu nebo klíč API s oprávněními pro správu.

Úplné podrobnosti naleznete v dokumentaci Framework dovedností.

---

Pluginy

Správa pluginů OmniRoute (rozšíření třetích stran).

Metoda	Cesta	Popis
GET	/api/plugins	Vypíše nainstalované pluginy
POST	/api/plugins/marketplace/install	Nainstaluje plugin z tržiště
DELETE	/api/plugins/[name]	Odinstaluje plugin
POST	/api/plugins/[name]/activate	Aktivuje plugin
POST	/api/plugins/[name]/deactivate	Deaktivuje plugin
GET	/api/plugins/[name]/config	Získá konfiguraci pluginu
PUT	/api/plugins/[name]/config	Aktualizuje konfiguraci pluginu

Ověření: Vyžaduje relaci pro správu.

Úplné podrobnosti naleznete v dokumentaci Framework pluginů.

---

Stínové směrování

Stínové porovnávání poskytovatelů / porovnávání A-B není samostatné rozhraní REST — konfiguruje se prostřednictvím kombinovaného směrování (viz Automatická kombinace). Metriky porovnání pro jednotlivé kombinace poskytuje GET /api/combos/metrics.

---

Ochranná opatření

Kontrola běhových ochranných opatření (detekce osobních údajů, detekce vložení instrukcí, přemostění obrazového vstupu). Ochranná opatření se spouštějí při každém požadavku; jejich vynechání pro jednotlivá volání se provádí prostřednictvím hlavičky požadavku x-omniroute-disabled-guardrails — trvalé rozhraní pro jejich povolení či zakázání neexistuje.

Metoda	Cesta	Popis
GET	/api/guardrails	Vypíše registrovaná ochranná opatření a jejich stav (název / povoleno / priorita)
POST	/api/guardrails/test	Provede zkušební běh předvolacího kanálu nad vzorovým vstupem — tělo: {input, disabledGuardrails?}

Ověření: Vyžaduje relaci pro správu.

Úplné podrobnosti naleznete v dokumentaci Zabezpečení > Ochranná opatření.

---

---

Autentizace

Informace o čtyřech typech přihlašovacích údajů (relace řídicího panelu, místní token CLI, přístupový token oma_live_…, klíč API s oprávněním ke správě) a o tom, jak se liší od klíčů pro inferenci, najdete v dokumentu Autentizace správy.

• Trasy řídicího panelu (/dashboard/*) používají soubor cookie auth_token
• Přihlášení používá uložený hash hesla; jako záložní možnost používá INITIAL_PASSWORD
• Nastavení requireLogin lze přepínat prostřednictvím /api/settings/require-login
• Trasy /v1/* mohou volitelně vyžadovat klíč API typu Bearer, pokud platí REQUIRE_API_KEY=true
• Pojmy „token pro správu“ / „klíč API s oprávněním ke správě“ v této referenční příručce označují jeden z typů uvedených v daném průvodci — nikoli další nedefinovaný typ tajného údaje

Zpětně nekompatibilní změna (v3.8.0) — /api/v1/agents/tasks/* a koncové body pro správu intervalů cooldown nyní vyžadují autentizaci správy (soubor cookie auth_token řídicího panelu nebo klíč API s oprávněním ke správě). Klienti, kteří dříve volali tyto trasy bez autentizace, obdrží odpověď 401 Unauthorized. Viz commit 588a0333 (fix(auth): require management auth for agent and cooldown APIs).