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

API Reference (Magyar)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇦🇲 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

---

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇦🇲 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

Az OmniRoute API alapvető referenciája. Bemutatja a nyilvános /v1 felületet és a leggyakrabban használt felügyeleti végpontokat; a géppel olvasható docs/openapi.yaml és a src/app/api/ alatti útvonalfa szolgál teljes körű forrásként.

---

Tartalomjegyzék

• Csevegési kiegészítések
• Exkluzív felügyelt munkamenet-bérletek
• Beágyazások
• Képgenerálás
• Dokumentum-OCR
• Modellek listázása
• Szolgáltatói bővítmény jegyzéke
• Kompatibilitási végpontok
• Fájlok API
• Kötegek API
• Keresési API
• WebSocket-adatfolyam
• Kvóták és problémák jelentése
• Szemantikai gyorsítótár
• Irányítópult és felügyelet
• Kombinációk kezelése
• Webhookok
• Regisztrált kulcsok (automatikus kezelés)
• Ügynökprotokoll
• Felügyeleti proxyk
• Hibatűrés (kibővített)
• Készségek
• Memória
• MCP-kiszolgáló
• A2A-kiszolgáló
• Felhő, kiértékelések és értékelés
• Kérések feldolgozása
• Hitelesítés

---

Csevegési kiegészítések

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

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Írj egy függvényt, amely..."}
  ],
  "stream": true
}

Egyéni fejlécek

Fejléc	Irány	Leírás
X-OmniRoute-No-Cache	Kérés	Állítsa true értékre a gyorsítótár megkerüléséhez
x-omniroute-no-memory	Kérés	Állítsa true értékre a memória és a készségek befecskendezésének kihagyásához ennél a kérésnél (a gyorsítótár megkerüléséhez hasonlóan; elkerüli a hívásonkénti token-/költségtöbbletet)
X-OmniRoute-Progress	Kérés	Állítsa true értékre az előrehaladási eseményekhez
X-Session-Id	Kérés	Rögzített munkamenetkulcs külső munkamenet-affinitáshoz
x_session_id	Kérés	Az aláhúzásjeles változat is elfogadott (közvetlen HTTP)
X-OmniRoute-Session-Id	Kérés	A hívó által megadott munkamenet-/beszélgetéscímke (a memóriát is táplálja). Ha jelen van, változtatás nélkül kerül a call_logs.session_tag mezőbe a munkamenetenkénti költség-hozzárendeléshez (#8249) — hiányában soha nem jön létre automatikusan
Idempotency-Key	Kérés	Deduplikációs kulcs (5 másodperces időablak)
X-Request-Id	Kérés	Alternatív deduplikációs kulcs
X-OmniRoute-Cache	Válasz	HIT vagy MISS (nem adatfolyamos)
X-OmniRoute-Idempotent	Válasz	true, ha deduplikálva lett
X-OmniRoute-Progress	Válasz	enabled, ha az előrehaladás követése be van kapcsolva
X-OmniRoute-Session-Id	Válasz	Az OmniRoute által ténylegesen használt munkamenet-azonosító
X-OmniRoute-Request-Id	Válasz	Kéréskorrelációs azonosító (ha ismert)
X-OmniRoute-Version	Válasz	Az OmniRoute buildverziója (mindig jelen van)
X-OmniRoute-Cost-Saved	Válasz	A gyorsítótár által megtakarított USD-összeg HIT esetén (csak gyorsítótár-találatoknál)
X-OmniRoute-Decision	Válasz	Útválasztási nyomkövetés: strategy=<name>; provider=<alias>; latency_ms=<n> (a <name> a kombinációs stratégia, nem kombinált kérésnél pedig single) — a befejezési válaszokban mindig jelen van

Nginx-megjegyzés: ha aláhúzásjelet tartalmazó fejlécekre támaszkodik (például x_session_id), engedélyezze az underscores_in_headers on; beállítást.

Költségtelemetriai fejlécek: a nem streamelt sikeres válaszok az X-OmniRoute-* költségtelemetriai készletet is tartalmazzák — X-OmniRoute-Response-Cost (USD, fixen 10 tizedesjeggyel; ingyenes/nem árazott esetben 0.0000000000), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit és X-OmniRoute-Fallback-Attempts (csak ha > 0), továbbá X-OmniRoute-Request-Id és X-OmniRoute-Version. Ezeket a csevegésikiegészítés-, a /v1/responses- és a /v1/messages-végpontok, valamint a médiavégpontok bocsátják ki — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations és /v1/moderations (ennek költsége mindig 0). A médiaköltség modalitásonként kerül kiszámításra (képenként, másodpercenként, karakterenként, keresési egységenként), ha rendelkezésre állnak árazási adatok; ellenkező esetben 0 (fail-open).

Gyorsítótártalálat költségszemantikája: szemantikus gyorsítótártalálat (X-OmniRoute-Cache-Hit: true) esetén nem történik upstream hívás, ezért az X-OmniRoute-Response-Cost értéke 0.0000000000 (a találat kiszolgálásának járulékos költsége). Az eredeti/a gyorsítótár nélkül felmerült költséget külön, az X-OmniRoute-Cost-Saved fejléc jelenti. A számlázási fogyasztóknak az X-OmniRoute-Response-Cost értékeit kell összegezniük (a találatoknak nincs költségük); a gyorsítótár-analitika az X-OmniRoute-Cost-Saved értékeit összesítheti.

Exkluzív felügyelt munkamenet-bérletek

Az exkluzív felügyelt munkamenet-bérlés egy opcionális, klienssemleges útválasztási szerződés: egy aktív tulajdonos egy jogosult OmniRoute-kapcsolatot birtokol. Nem bérel modellt, nem igényel OAuth-hitelesítést, nem azonosít egy adott klienst, és nem követel meg egy adott szolgáltatót.

A hitelesítést végző API-kulcsnak rendelkeznie kell a lease:exclusive hatókörrel és egy explicit, nem üres allowedConnections listával. Az adatbázis-módosítási határvonal a kulcs létrehozásakor és részleges frissítésekor mindkét mező együttes meglétét kikényszeríti.

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

A sikeres megszerzési, megújítási és felszabadítási válaszok időbélyegeket, state értéket és a pontos pozitív generation értéket teszik elérhetővé, de soha nem fedik fel a kiválasztott kapcsolatot vagy a hitelesítő adatokat. A megújítás és a felszabadítás a generációt a JSON-törzsben adja meg:

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

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

Egy aktív bérlet tulajdonosa explicit módon kérheti az aktuális hozzárendelés adatvédelmi szempontból biztonságos megjelenítési metaadatait:

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

Ezt az opcionális állapotműveletet az átlátszatlan tulajdonos, a hitelesített felügyelt API-kulcs és a pontos aktív generáció egyetlen adatbázis-tranzakción belül védi. A displayName kizárólag a konfigurált kapcsolat szóközöktől megtisztított neve; értéke null, ha nem áll rendelkezésre biztonságosan használható konfigurált név. Az OmniRoute soha nem helyettesíti ezt e-mail-címmel vagy generált fiókazonosítóval. A szolgáltató értéke nem érzékeny megjelenítési címke, és soha nem generált kompatibilisszolgáltató-azonosító. A hitelesítő adatok, tokenek, cookie-k, nyers kapcsolat- vagy API- kulcsazonosítók, tulajdonoskivonatok, elkerítési titkok és belső útválasztási adatok ki vannak zárva.

A helytelen kulccsal, helytelen tulajdonossal, elavult generációval végzett, illetve a hiányzó, lejárt, felszabadított vagy érvénytelenített bérletre irányuló lekérdezések mind ugyanazt a 409 LEASE_FENCE_STALE hibát adják vissza kapcsolatmetaadatok nélkül. A kapacitásra várakozást jelző választ kapott kliensnek nincs megvizsgálható aktív hozzárendelése. Amikor az útválasztás átállít egy aktív bérletet, ugyanaz a generáció marad érvényben, és az állapotművelet atomi módon az új hozzárendelést adja vissza, soha nem a régit. A meglévő kliensek változatlanok maradnak, mivel a megszerzési, megújítási, felszabadítási és várakozási válaszok megőrzik korábbi formájukat.

Ez a kiszolgálói szerződés nem módosítja az alapértelmezett OpenAI Codex /status végpontját. Az alapértelmezett Codex jelenleg jelentést ad a modellszolgáltatójáról és a beépített hitelesítési-/fiókállapotról, de nem jelenít meg tetszőleges egyéni szolgáltatói fiókmetaadatokat; egy későbbi kliensintegrációnak meg kell hívnia ezt a műveletet, és el kell döntenie, hogyan jelenítse meg a connection.displayName értékét.

Ezután minden felügyelt következtetési kérés megadja mindkét vezérlőfejlécet:

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

A pontos tulajdonos, generáció, aktív kapcsolat és hitelesített API-kulcs ellenőrzése közvetlenül minden támogatott upstream-próbálkozás előtt történik. A tulajdonos és a generáció másik kulccsal történő újbóli felhasználása akkor is sikertelen, ha az a kulcs ugyanazt a kapcsolatot engedélyezi. A nyers tulajdonosértékeket a rendszer nem tárolja, nem naplózza, nem őrzi meg a kérés pillanatképében, és nem továbbítja upstream irányba.

Az ideiglenes erőforrás-ütközés HTTP 429 választ ad vissza Retry-After fejléccel és a következő tartalommal:

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

Ez a válasz csak azt jelenti, hogy a szokásos jogosult halmaz nem volt üres, és minden szabad jelöltet egy idegen aktív bérlet foglalt. A nem támogatott modellek/szolgáltatók, a házirend-eltérés, a lehűlési idő, a kvóta, az állapot és más szokásos jogosultsági hibák megtartják a meglévő OmniRoute-válaszaikat.

x-omniroute-compression

A tömörítési terv kérésenkénti felülbírálása. A legmagasabb prioritású — felülírja az útválasztási kombináció felülbírálását, az aktív profilt, az automatikus aktiválást és a panel alapértelmezését. Értékek:

Érték	Hatás
off	Ennél a kérésnél nincs tömörítés.
default	A panelből származtatott alapértelmezett profil (figyelmen kívül hagyja az aktív profilt).
engine:<id>	Egyetlen motor, ha engedélyezve van, például engine:rtk.
<combo>	Egy névvel ellátott kombináció; először név alapján történik az egyezés (kis- és nagybetűktől függetlenül), majd azonosító alapján.

Megjegyzések:

• Az ismeretlen értékeket a rendszer figyelmen kívül hagyja (a kérést soha nem utasítja el); a feloldás a normál operátori precedencia szerint folytatódik.
• Ha több kombinációnak ugyanaz a neve, a determinisztikus egyezéshez a kombináció id értékét adja meg.
• Az off vagy default nevű kombinációk nem választhatók ki név alapján (ezeket a kulcsszavakat értelmezi először a rendszer); az ilyen kombinációkra az azonosítójukkal hivatkozzon.
• A fő tömörítési kapcsoló kötelező korlát: ha a tömörítés globálisan le van tiltva, ez a fejléc nem engedélyezheti.

Az alkalmazott terv megjelenik a válasz fejlécében:

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

ahol a <source> értéke a következők egyike: request-header, routing-override, active-profile, auto-trigger, default vagy off.

---

Beágyazások

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

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

Elérhető szolgáltatók: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.

A katalógusazonosítók formátuma provider/model (például: jina-ai/jina-embeddings-v5-omni-small). A nyilvántartásban szereplő, szolgáltatónév nélküli Jina-modellazonosítók (például jina-embeddings-v5-text-small, jina-reranker-v3.5) szintén feloldhatók. A Jina embed/rerank/classify/segment műveletek először az irányítópulton megadott jina-ai hitelesítő adatokat használják; a JINA_AI_API_KEY csak akkor szolgál tartalékként, ha nincs irányítópulton megadott kulcs. A jina-reader kártya kizárólag a Reader / r.jina.ai szolgáltatáshoz használható (POST /v1/web/fetch), és soha nem szolgál ki beágyazási vagy újrarangsorolási kéréseket.

A nyilvántartás multimodális támogatást jelző modelljei legfeljebb 32, szolgáltatófüggetlen strukturált elemet is elfogadnak. A médiaelemek típusai: text, image, audio, video és document. A média source értéke vagy {"type":"url","url":"https://..."}, vagy {"type":"base64","data":"...","media_type":"..."}.

A Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano, valamint a jina-ai/jina-embeddings-v5-omni → omni-small családálnév) a Jina natív EmbeddingsV5Request dokumentumait is elfogadja, és változtatás nélkül továbbítja őket a https://api.jina.ai/v1/embeddings címre:

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

A natív { image | audio | video | pdf } értékek lehetnek nyilvános HTTPS URL-ek, data: URI-k vagy nyers base64-adatok. Az OmniRoute ezeket az objektumokat nem alakítja karakterlánccá, és nem tölti le a natív kép-URL-eket — a nyilvános médiát maga a Jina tölti le. A további Jina-mezők (task, normalized, truncate, embedding_type) továbbításra kerülnek. A csak szöveges Jina SKU-k továbbra is elutasítják a nem szöveges dokumentumokat.

Biztonsági és átviteli korlátok:

• A távoli média-URL-eknek nyilvános HTTPS-címeknek kell lenniük. A kanonikus {type,source:url} elemeket a rendszer szerveroldalon tölti le (átirányítások újbóli ellenőrzése, időtúllépés, méretkorlátok, nyilvános DNS, kapcsolatrögzítés), majd beágyazza őket a szolgáltató meghívása előtt. A Jina natív {image:"https://..."} elemei változatlanul kerülnek továbbításra ugyanazon nyilvános HTTPS-ellenőrzést követően; az URL-t a Jina tölti le.
• A beágyazott base64-média dekódolt mérete elemenként legfeljebb 8 MiB, a teljes kérésben pedig összesen legfeljebb 16 MiB lehet.

Szolgáltatói átalakítás (a kanonikus elemek soha nem kerülnek változatlanul továbbításra):

• Jina multimodális modellek: minden felső szintű elemből egy modalitáskulccsal rendelkező objektum lesz (text / image / audio / video / pdf), amely a beágyazott médiához adat-URI-kat használ; felső szintű elemenként egy vektor.
• Gemini Embedding 2 család: egy felső szintű tömbből egyetlen natív models/{model}:embedContent kérés lesz content.parts elemekkel (text vagy inline_data).
• A kifejezett modalitási metaadatok nélküli ismeretlen/dinamikus modellek HTTP 400-as hibával utasítják el a strukturált bemenetet.

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

A nem támogatott modell/modalitás-kombinációk az elem kényszerített átalakítása helyett HTTP 400-as hibát adnak vissza. A régi karakterlánc-/tokenkérések bemeneten kívüli kiegészítő mezői továbbra is változatlanul kerülnek továbbításra.

# Az összes beágyazási modell listázása
GET /v1/embeddings

---

Képgenerálás

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

{
  "model": "openai/gpt-image-2",
  "prompt": "A beautiful sunset over mountains",
  "size": "1024x1024"
}

Elérhető szolgáltatók: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (helyi), ComfyUI (helyi).

# Az összes képmodell listázása
GET /v1/images/generations

---

Dokumentum-OCR

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

A model egy provider/model előtag segítségével választja ki az OCR-szolgáltatót; az előtag nélküli modellazonosító (pl. mistral-ocr-latest) a regisztrált szolgáltatójára oldódik fel, a model elhagyása esetén pedig az alapértelmezett a Mistral (mistral-ocr-latest). Regisztrált szolgáltatók (open-sse/config/ocrRegistry.ts):

Szolgáltatóazonosító	Modellazonosító	model értéke	Megjegyzések
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest (vagy előtag nélkül: mistral-ocr-latest)	Szinkron — a válasz közvetlenül az egyetlen felsőbb szintű hívásból érkezik vissza.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	Aszinkron felsőbb szintű szolgáltatás (analyze + lekérdezés) — lásd alább.
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	Szinkron, a Vertex AI openapi/chat/completions partneri végpontján keresztül — a hitelesítést/URL-t lásd alább.

Mindhárom szolgáltató ugyanabban a Mistral-formátumú törzsben válaszol:

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

Az Azure Document Intelligence lekérdezési folyamata

Az Azure Document Intelligence analyze API-ja aszinkron: a kezdeti kérés törzs helyett egy Operation-Location fejlécet ad vissza, és az eredményt ismételt lekérdezésekkel kell lekérni. A kezelő (open-sse/handlers/ocr.ts) másodpercenként lekérdezi ezt az URL-t, legfeljebb 30 alkalommal; sikertelen, nem ok állapotú lekérdezési válasz vagy "failed" állapot esetén azonnal hibával leáll (nem folytatja a lekérdezést), és 504 választ ad vissza, ha a művelet a próbálkozási keret kimerülése után is folyamatban van. A végső Azure-választ a visszaküldés előtt ugyanarra a Mistral által használt pages/markdown formátumra alakítja át, így az ügyfélkódban nem szükséges szolgáltatóspecifikus esetkezelés.

A Vertex AI DeepSeek OCR hitelesítése és végpontfeloldása

A vertex-deepseek-ocr ugyanazt a Vertex AI-hitelesítést használja újra, amelyet az OmniRoute már támogat a csevegési/képforgalomhoz (open-sse/executors/vertex.ts): a kapcsolat API-kulcsa vagy egy Service Account JSON hitelesítő adat (amelyet a JWT bearer folyamat rövid élettartamú OAuth hozzáférési tokenre cserél), vagy egy már kiállított, változtatás nélkül használt OAuth hozzáférési token. A felsőbb szintű végpont URL-je a Vertex általános openapi/chat/completions partneri végpontja, amelyet a kapcsolat projektjéből és régiójából állít össze — az explicit providerSpecificData.project/providerSpecificData.region mindig elsőbbséget élvez; ellenkező esetben a projektet a Service Account JSON project_id mezőjéből származtatja, a régió alapértelmezett értéke pedig us-central1. Mindkét feloldás az open-sse/handlers/ocr.ts fájlban történik (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl), és ezeket az src/app/api/v1/ocr/route.ts használja fel a handleOcr meghívása előtt.

---

Modellek listázása

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

→ Visszaadja az összes csevegési, beágyazási és képmodellt, valamint ezek kombinációit OpenAI-formátumban

Modellazonosító-előtagok (?prefix=)

A legtöbb modell egy szolgáltatói előtag alatt jelenik meg. A használt előtagot a MODELS_CATALOG_PREFIX_MODE funkciójelző szabályozza, és egy lekérdezési paraméterrel kérésenként felülbírálható — ez olyan kliensek számára hasznos, amelyek letisztult listát szeretnének anélkül, hogy mindenki más számára módosítanák a kiszolgálószintű beállítást:

GET /v1/models?prefix=alias        # modellenként egy azonosító — a rövid aliaselőtag
GET /v1/models?prefix=dual         # mindkét forma (a kiszolgáló alapértelmezése)
GET /v1/models?prefix=canonical    # csak a teljes szolgáltatóazonosító-előtag

Mód	Kibocsátott érték	Megjegyzések
dual	cc/claude-sonnet-4-6 és claude/claude-sonnet-4-6	Alapértelmezett. Mindkét azonosító ugyanahhoz a modellhez irányít; így az egyik formát rögzítetten használó klienskonfigurációk továbbra is működnek. Nagyjából megduplázza a katalógust.
alias	cc/claude-sonnet-4-6	Modellenként egy bejegyzés. A külön aliassal nem rendelkező szolgáltatók bejegyzése is megjelenik, így semmi sem vész el.
canonical	claude/claude-sonnet-4-6	Modellenként egy bejegyzés a teljes szolgáltatóazonosító-előtag alatt. A külön aliassal nem rendelkező szolgáltatók (pl. antigravity/…, agy/…) egyetlen azonosítója itt is megjelenik, így semmi sem vész el.

A dual módú tükrözött bejegyzés a lekérdezési paraméter nélkül is felismerhető: rendelkezik egy parent mezővel, amely az elsődleges azonosítóra mutat.

A modellválasztót megjelenítő klienseknek a ?prefix=alias paramétert kell használniuk — ezt teszi az OmniCopilot VS Code-bővítmény is.

Gondolkodás nélküli modellváltozatok

A gondolkodásra képes Claude-modellek esetében a /v1/models egy gondolkodás nélküli változatot is meghirdet, amelynek azonosítója a claude-3-omniroute-no-thinking/ előtaggal kezdődik:

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

Ennek az azonosítónak a kiválasztása (pl. egy olyan Claude Code-konfigurációban, amely mindig csatol egy thinking blokkot) visszaalakítja azt a valódi <provider>/<model> modellre, letiltott következtetéssel — a /v1/messages útvonalon thinking:{type:"disabled"} beállítással, illetve a /v1/chat/completions útvonalon a reasoning/reasoning_effort mezők elhagyásával. A változat csak olyan Claude-családba tartozó modelleknél jelenik meg, amelyek támogatják a gondolkodást és figyelembe veszik a disabled értéket (így például a disabled értéket elutasító, kizárólag adaptív modellek nem szerepelnek). Az üzemeltetők modellenként kényszeríthetik a változat be- vagy kikapcsolását a ModelSpec.noThinkingAlias segítségével.

---

Szolgáltatói bővítmény manifesztje

GET /api/v1/provider-plugin-manifest

Visszaadja a Bifrost, a CLIProxyAPI és a jövőbeli sidecar útválasztók által használt, JSON-biztos szolgáltatói bővítménymanifesztet. A válasz a TypeScript szolgáltatói regiszterből jön létre, és szándékosan nem tartalmaz OAuth-kliens-titkokat, futásidejű környezetfeloldást, végrehajtó függvényeket, kérésfejléceket és fiókadatokat.

Ezt a végpontot akkor használja, ha egy sidecar folyamaton kívül fut, és nem tudja közvetlenül importálni az open-sse/config/providerPluginManifestRegistry.ts fájlt.

---

Kompatibilitási végpontok

Metódus	Elérési út	Formátum
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 (szerkesztés/inpaint)
POST	/v1/videos/generations	OpenAI-stílusú videógenerálás
POST	/v1/music/generations	OpenAI-stílusú zenegenerálás
POST	/v1/audio/transcriptions	OpenAI Audio (STT)
POST	/v1/audio/speech	OpenAI TTS (hangtörzset ad vissza)
POST	/v1/rerank	Cohere/Voyage-stílusú újrarangsorolás
POST	/v1/classify	Jina osztályozás (api.jina.ai)
POST	/v1/segment	Jina szegmentáló (segment.jina.ai)
POST	/v1/moderations	OpenAI Moderations
GET	/v1/models	OpenAI
POST	/v1/messages/count_tokens	Anthropic
GET	/v1beta/models	Gemini
POST	/v1beta/models/{...path}	Gemini generateContent
POST	/v1/api/chat	Ollama
GET	/api/v1/vscode/{token}/	OpenAI-katalógus aliasa
GET	/api/v1/vscode/{token}/models	OpenAI-modellek aliasa
POST	/api/v1/vscode/{token}/chat/completions	OpenAI tokenizált aliasa
POST	/api/v1/vscode/{token}/responses	OpenAI Responses tokenizált aliasa
POST	/api/v1/vscode/{token}/api/chat	Ollama tokenizált aliasa
GET	/api/v1/vscode/{token}/api/tags	Ollama-címkék tokenizált aliasa

Minden POST-útvonal ugyanazt a formát követi: Bearer your-api-key + Zod által ellenőrzött JSON-törzs (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema stb.; lásd: src/shared/validation/schemas.ts). Sémahiba esetén 4xx válasz érkezik.

Azon kliensek számára, amelyek nem tudják csatolni az Authorization: Bearer ... fejlécet, az OmniRoute az API-kulcsokat az URL-ben is elfogadja, akár lekérdezési karakterláncon alapuló kompatibilitással (?token=..., ?apiKey=..., ?api_key=..., ?key=...), akár az alább dokumentált, dedikált /api/v1/vscode/{token}/... végpontokon keresztül.

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

# Jina-osztályozás (Foundation API hitelesítő adatok)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Jina-szegmentáló
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina-keresés (s.jina.ai; szolgáltatói aliasok: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# Moderálás
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — audio/mpeg (vagy a kért formátumú) törzset ad vissza
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Képszerkesztés (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Videó- és zenegenerálás (szolgáltatói előtaggal ellátott modellazonosító)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Dedikált szolgáltatói útvonalak

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

A rendszer automatikusan hozzáadja a szolgáltatói előtagot, ha az hiányzik. A nem egyező modellek 400 választ eredményeznek.

---

Files API

OpenAI-kompatibilis fájlvégpont kötegelt bemenethez/kimenethez és fájlcél szerinti feltöltésekhez.

Metódus	Elérési út	Leírás
POST	/v1/files	Fájl feltöltése (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — legfeljebb 512 MiB
GET	/v1/files	A hitelesített API-kulcshoz tartozó fájlok listázása
GET	/v1/files/[id]	Egy fájl metaadatainak lekérése
DELETE	/v1/files/[id]	Egy fájl törlése
GET	/v1/files/[id]/content	A fájl nyers tartalmának streamelése

Hitelesítés: Bearer API-kulcs — a fájlok API-kulcsonként vannak elkülönítve a getApiKeyRequestScope segítségével. Egy kulcs csak a saját fájljait látja, töltheti le és törölheti; egy kulcs nélküli irányítópult-munkamenet a teljes példányt olvashatja; a tulajdonos nélküli fájlokhoz (névtelen vagy irányítópult-munkamenetből történő feltöltés) minden nem munkamenet-alapú hívó hozzáférése meg van tagadva. A GET /v1/files a névtelen hívót — és a megadott, de nem feloldható kulcsot — 401 válasszal utasítja el még akkor is, ha REQUIRE_API_KEY=false, ahelyett, hogy minden bérlő fájljait listázná (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

Batches API

OpenAI-kompatibilis kötegelt feldolgozás.

Metódus	Elérési út	Leírás
POST	/v1/batches	Köteg létrehozása — a törzset a v1BatchCreateSchema validálja (input_file_id, endpoint, completion_window)
GET	/v1/batches	Kötegek listázása
GET	/v1/batches/[id]	A köteg állapotának és a request_counts értékének lekérése
DELETE	/v1/batches/[id]	Befejezett/meghiúsult köteg törlése
POST	/v1/batches/[id]/cancel	Folyamatban lévő köteg megszakítása

Hitelesítés: Bearer API-kulcs. A kötegek API-kulcsonként vannak elkülönítve, ugyanazon háromágú szabály szerint, mint a fájlok: csak a saját kulcshoz tartozók érhetők el, az irányítópult-munkamenet a teljes példányhoz hozzáfér, a null tulajdonosú rekordok pedig minden nem munkamenet-alapú hívó számára tiltottak (lekérés, törlés, megszakítás, valamint létrehozáskor az input_file_id ellenőrzése). A GET /v1/batches a névtelen hívót 401 válasszal utasítja el még akkor is, ha REQUIRE_API_KEY=false.

---

Search API

Webes/keresési szolgáltatók absztrakciója (Tavily, Brave, Exa, Serper stb.).

Metódus	Útvonal	Leírás
GET	/v1/search	A konfigurált keresési szolgáltatók és képességeik listázása
POST	/v1/search	Keresési lekérdezés futtatása — a törzset a v1SearchSchema validálja; támogatja a gyorsítótárazást és az összevonást
GET	/v1/search/analytics	Szolgáltatónkénti találati, késleltetési és gyorsítótár-statisztikák

Hitelesítés: Bearer API-kulcs (extractApiKey + isValidApiKey). A keresési szabályzatot az enforceApiKeyPolicy kényszeríti ki.

---

Web Fetch API

Tartalom kinyerése egy URL-ről egy konfigurált webes lekérési szolgáltatón keresztül (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

Metódus	Útvonal	Leírás
POST	/v1/web/fetch	URL lekérése/kinyerése — a törzset a v1WebFetchSchema validálja

Hitelesítés: Bearer API-kulcs (extractApiKey + isValidApiKey). A szabályzatot az enforceApiKeyPolicy kényszeríti ki.

Kvótafigyelő tartalékmechanizmus (#8297): ha nincs explicit provider megadva, a rendszer a készletet (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) rögzített prioritási sorrendben járja be (az elsőt tölti fel először) — a sebességkorlátozott, de konfigurált szolgáltatót kihagyja ahelyett, hogy azonnal megszakítaná a kérést, és egy újrapróbálható/kvótával kapcsolatos felsőbb szintű hiba (HTTP 429 minden esetben; 402/403 a Firecrawl/Tavily/TinyFish kvótaalapú ingyenes csomagjainál — de nem a Jina Reader esetén, és soha nem egyszerű 400 hibás kérésnél) futásidőben a következő, még nem próbált, hitelesítő adatokkal rendelkező szolgáltatóra vált. Ha a készlet minden szolgáltatója kimerült, a végpont az előző általános 400 helyett egyetlen 429 választ ad vissza (Retry-After fejléccel). Ha explicit provider van megadva, nincs automatikus tartalékra váltás — a sebességkorlátozott vagy hibát adó explicit szolgáltató saját hibája jut el a klienshez (sebességkorlátozás esetén 429, egyébként a felsőbb szintű állapotkód).

---

WebSocket-streamelés

GET /v1/ws?handshake=1

Validálja a WebSocket-frissítési kézfogást, és visszaadja a vezetékes protokoll példaüzeneteit (request, cancel). A tényleges WS-kereteket a csomagban található WS-kiszolgáló kezeli a Next.js útvonaltábláján kívül.

Hitelesítés: Bearer API-kulcs a kézfogás során.

Responses API WebSocketen keresztül (csak codex)

# Ugyanaz a gazdagép:port, mint a HTTP API esetén (alapértelmezés szerint 20128); a kapcsolat frissítése:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (vagy: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Az első keretnek KÖTELEZŐEN response.create típusúnak kell lennie:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

A Responses API WebSocketen keresztüli proxyja kizárólag a codex szolgáltatóhoz van bekötve (ChatGPT- háttérrendszer). Ugyanazon a porton figyel, mint az API/irányítópult, a /v1/responses, /responses és /api/v1/responses útvonalakon. Az első response.create keretnél hitelesítést és előkészítést végez a belső codex-responses-ws hídon keresztül, kiválaszt egy codex OAuth-kapcsolatot, majd alagutat hoz létre a wss://chatgpt.com/backend-api/codex/responses címhez a wreq-js átviteli rétegen keresztül. A nem codex modelleket elutasítja (codex_ws_provider_required). A kvótamegosztásos útválasztáshoz használja a következőt: model: "qtSd/<group>/codex/<model>". Megvalósítás: app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.

Hitelesítés: Bearer API-kulcs a kézfogás során. A csomagban található HTTP-kiszolgálónak (server-ws.mjs) kell lennie az aktív belépési pontnak (ez az alapértelmezés, ha az app/server-ws.mjs létezik).

Modellazonosító: használja a nyers ChatGPT-azonosítót (codex/ előtag nélkül)

Az OpenAI Codex CLI kliensoldalon validálja a modell nevét, amikor a supports_websockets = true, és elutasítja a szolgáltató-előtaggal ellátott azonosítókat, például a codex/gpt-5.5 értéket (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Küldje a nyers azonosítót (például gpt-5.5). Az OmniRoute hídja kizárólag codex modelleket kezel, ezért egy nyers azonosítót újra codex modellként old fel (resolveCodexWsModelInfo), mielőtt továbbítaná a felsőbb szintű szolgáltatónak — még akkor is, ha egy nyers gpt-5.5 HTTP-n keresztül egyébként másik szolgáltatóhoz lenne irányítva.

Az OpenAI Codex CLI konfigurálása

Irányítsa a Codex CLI-t az OmniRoute-hoz úgy, hogy WebSocket-támogatással rendelkező egyéni szolgáltatót ad hozzá a ~/.codex/config.toml fájlhoz (használjon külön CODEX_HOME értéket, hogy ne módosítson egy meglévő konfigurációt):

model = "gpt-5.5"                 # nyers azonosító — NEM "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # nincs záró perjel; a WS URL ebből származik (éles környezetben használjon https/wss protokollt)
wire_api = "responses"                    # 2026 februárja óta az egyetlen támogatott érték
supports_websockets = true                # engedélyezi a Responses-over-WS átvitelt
env_key = "OMNIROUTE_API_KEY"             # az OmniRoute API-kulcsot tartalmazza (Bearer)

export OMNIROUTE_API_KEY=sk-...           # egy OmniRoute API-kulcs (bármely kulcs, ha REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

A CLI a base_url + /responses címet WebSocket-kapcsolatra frissíti, az OmniRoute pedig a kiválasztott codex OAuth-kapcsolathoz továbbítja. Végponttól végpontig validálva a helyi kiszolgálóval: a ChatGPT codex.rate_limits + response.created eseményeket ad vissza, és streameli a befejezést.

---

Kvóták és hibák jelentése

Metódus	Útvonal	Leírás
GET	/v1/quotas/check	Egy provider + accountId kvótájának előzetes ellenőrzése regisztrált kulcs kiadása előtt
POST	/v1/issues/report	Kvóta- vagy kulcskiadási hiba jelentése a GitHubon (GITHUB_ISSUES_REPO + token szükséges)

Hitelesítés: Bearer API-kulcs (isAuthenticated).

---

Önkiszolgáló használati adatok (/api/usage/om-usage)

Bármely API-kulcs lekérdezheti a saját használati adatait és kvótáit — kezelői hitelesítés nélkül. Ezt a végpontot használja egy kliens (CLI, az OmniCopilot panel), hogy megjelenítse a kulcs tulajdonosának költését.

# Szöveges forma (a korábbi szerződés — egyszerű szöveg terminálhoz)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Strukturált forma — ezt használja fel egy felhasználói felület
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

A kulcshoz engedélyezni kell az allowUsageCommand beállítást (alapértelmezés szerint ki van kapcsolva — az irányítópult API-kulcs- kezelője kulcsonként kapcsolja be). Enélkül a végpont 403 választ ad.

A ?format=json megkülönböztetett struktúrát ad vissza, így a hívó soha nem olvas adatmezőt elutasító válaszból. Siker esetén:

{
  "allowed": true,
  // csak akkor van jelen, ha a kulcshoz kulcsonkénti használati korlátokat állítottak be (napi/heti USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // a kiválasztott szolgáltató kvótájának pillanatképe, vagy null, ha még semmi sincs gyorsítótárazva:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // minden kapcsolat pillanatképe, hogy a felhasználói felület több szolgáltatót is egymás mellett jeleníthessen meg:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

Elutasítás esetén (401 hibás kulcs / 403 nincs engedélyezve) ugyanez az útvonal { "allowed": false, "error": { "message": "…" } } választ ad — a jelen lévő, de üres personal/provider (a kulcs engedélyezett, de még nincs begyűjtött adat) eltér az elutasítástól, és csak a JSON-forma különbözteti meg őket.

Hitelesítés: a hívó saját Bearer API-kulcsa, az isValidApiKey segítségével ellenőrizve — ez nem a kezelői felület (/api/keys/…), amelyet továbbra is a requireManagementAuth véd.

---

Szemantikus gyorsítótár

# Gyorsítótár-statisztikák lekérése
GET /api/cache/stats

# Minden gyorsítótár törlése
DELETE /api/cache/stats

Példaválasz:

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

Késleltetési hatás

A szemantikus gyorsítótár TALÁLATA a választ a gyorsítótárból szolgálja ki külső szolgáltatáshívás nélkül, így a jelentett X-OmniRoute-Response-Latency közel nulla (az eredeti külső szolgáltatás késleltetésétől függetlenül). A késleltetésre érzékeny klienseknek (teljesítménymérés, p50/p99 monitorozás) ellenőrizniük kell az X-OmniRoute-Cache-Latency válaszfejlécet:

Érték	Jelentés
synthetic	A válasz a gyorsítótárból érkezett; a késleltetés nem valós külső válaszidő
(hiányzik)	A válasz valós külső szolgáltatáshívásból érkezett

Kulcsonkénti gyorsítótár-megkerülés

Az API-kulcsok a cacheDefaultMode segítségével letilthatják a szemantikus gyorsítótárból történő olvasást:

Érték	Viselkedés
legacy	Normál gyorsítótár-viselkedés (alapértelmezett)
bypass	A gyorsítótár teljes kihagyása; mindig a külső szolgáltatás hívása

Beállítás a kulcs létrehozásakor (POST /api/keys) vagy frissítésekor (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

Kérésenkénti megkerülés

Bármely kérés megkerülheti a gyorsítótárat a kulcs beállításaitól függetlenül:

X-OmniRoute-No-Cache: true

---

Irányítópult és kezelés

A kezelési útvonalak (/api/* a nyilvános hitelesítés/bejelentkezés kivételével) nem engedélyezhetők hagyományos következtetési API-kulcsokkal. A hitelesítőadat-típusok, hatókörök és curl-példák itt találhatók: Kezelési hitelesítés.

Hitelesítés

Végpont	Metódus	Leírás
/api/auth/login	POST	Bejelentkezés
/api/auth/logout	POST	Kijelentkezés
/api/settings/require-login	GET/PUT	Kötelező bejelentkezés váltása

Szolgáltatók kezelése

Végpont	Metódus	Leírás
/api/providers	GET/POST	Szolgáltatók listázása / létrehozása
/api/providers/[id]	GET/PUT/DELETE	Szolgáltató kezelése
/api/providers/[id]/test	POST	Szolgáltatói kapcsolat tesztelése
/api/providers/[id]/models	GET	A szolgáltató modelljeinek listázása
/api/providers/validate	POST	Szolgáltatói konfiguráció ellenőrzése
/api/providers/bulk	POST	API-kulcsok tömeges hozzáadása EGY szolgáltatóhoz
/api/providers/import	POST	Heterogén szolgáltatói LISTA importálása feldolgozott CSV/JSON-fájlból (#6836); soronkénti részleges sikertelenségi eredmények
/api/provider-nodes*	Különböző	Szolgáltatói csomópontok kezelése
/api/provider-models	GET/POST/PATCH/DELETE	Egyéni modellek (hozzáadás, frissítés, elrejtés/megjelenítés, törlés)

OAuth-folyamatok

Végpont	Metódus	Leírás
/api/oauth/[provider]/[action]	Különböző	Szolgáltatóspecifikus OAuth

Útválasztás és konfiguráció

Végpont	Metódus	Leírás
/api/models/alias	GET/POST	Modellálnevek
/api/models/catalog	GET	Minden modell szolgáltató és típus szerint
/api/combos*	Különböző	Kombinációk kezelése
/api/keys*	Különböző	API-kulcsok kezelése
/api/pricing	GET	Modellek árazása

Használat és analitika

Végpont	Metódus	Leírás
/api/usage/history	GET	Használati előzmények
/api/usage/logs	GET	Használati naplók
/api/usage/request-logs	GET	Kérésszintű naplók
/api/usage/[connectionId]	GET	Kapcsolatonkénti használat
/api/usage/token-limits	GET/POST/DELETE	API-kulcsonkénti tokenkorlát-keretek
/api/usage/model-latency-stats	GET	Szolgáltatónkénti/modellenkénti gördülő késleltetési összesítés (átlag/p50/p95/p99, sikerességi arány); szűrők: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health	GET	A prompt-gyorsítótár állapotának összegzése a call_logs alapján — írási/olvasási arány, az írásméret p50/p90/p99 eloszlása, a nagy írások koncentrációja, modellenkénti bontás, valamint healthy/degraded/thrash/no-data minősítés; lekérdezési paraméterek: range (1h|24h|7d|30d, alapértelmezett: 24h) és opcionálisan model (#8827)

Beállítások

Végpont	Metódus	Leírás
/api/settings	GET/PUT/PATCH	Általános beállítások
/api/settings/proxy	GET/PUT	Hálózati proxy konfigurációja
/api/settings/proxy/test	POST	A proxykapcsolat tesztelése
/api/settings/ip-filter	GET/PUT	IP-engedélyezési/tiltási lista
/api/settings/thinking-budget	GET/PUT	A gondolkodási/következtetési kérések átírási módja (változatlan továbbítás / automatikus eltávolítás / egyéni / adaptív). A tömörítéstől független. Lásd: THINKING_BUDGET.md.
/api/settings/system-prompt	GET/PUT	Globális rendszerprompt
/api/settings/compression	GET/PUT	Globális tömörítési konfiguráció
/api/settings/purge-request-history	POST	A kérésnapló sorainak és a helyi hívásnapló-összetevőknek a törlése

Kontextus és tömörítés

Végpont	Metódus	Leírás
/api/compression/preview	POST	Az off/lite/standard/aggressive/ultra/RTK/stacked tömörítés előnézete
/api/compression/language-packs	GET	Az elérhető Caveman nyelvi csomagok listázása
/api/compression/rules	GET	A Caveman-szabályok metaadatainak listázása
/api/context/caveman/config	GET/PUT	A Caveman-specifikus beállítások aliasa
/api/context/rtk/config	GET/PUT	RTK-specifikus beállítások, beleértve az egyéni szűrőket és a nyers kimenet megőrzését
/api/context/rtk/filters	GET	RTK-szűrőkatalógus és az egyéni szűrők diagnosztikája
/api/context/rtk/test	POST	RTK-előnézet/-teszt futtatása szöveges adatokon
/api/context/rtk/raw-output/[id]	GET	A megőrzött, kitakart nyers kimenet beolvasása mutatóazonosító alapján
/api/context/combos	GET/POST	Tömörítési kombinációk listázása/létrehozása
/api/context/combos/[id]	GET/PUT/DELETE	Tömörítési kombináció részletei/frissítése/törlése
/api/context/combos/[id]/assignments	GET/PUT	Tömörítési kombinációk hozzárendelése útválasztási kombinációkhoz
/api/context/analytics	GET	Tömörítési analitika aliasa

Monitorozás

Végpont	Metódus	Leírás
/api/sessions	GET	Aktív munkamenetek nyomon követése
/api/rate-limits	GET	Fiókonkénti sebességkorlátok
/api/monitoring/health	GET	Állapotellenőrzés és szolgáltatói összefoglaló (catalogCount, configuredCount, activeCount, monitoredCount). A felügyeleti nézet tartalmazza a credentialHealth adatot: a próbagyorsítótár skalárértékei, failedConnections, ha failed>0, valamint staleDbNonOkCount (SQLite-ban rögzült test_status, nem a mérőszám). Lásd: MONITORING_GUIDE.md.
/api/cache/stats	GET/DELETE	Gyorsítótár-statisztikák / ürítés
/api/modality-bridge/stats	GET	Memóriában tárolt attempts, sikeres műveletek/bridged, hibák, gyorsítótár-találatok, totalLatencyMs, latencySamples, mintaszám alapján számított averageLatencyMs, valamint az utolsó használat időpontja (újraindításkor alaphelyzetbe áll; felügyeleti hitelesítés szükséges)
/api/modality-bridge/video/runtime	GET	Szigorú, megbízható visszacsatolási címre vonatkozó ellenőrzés a felügyeleti hitelesítés/próba előtt; az FFmpeg/ffprobe elérhetősége és megtisztított verzióadatai (nincs tárolás)
/api/modality-bridge/video/extract	POST	Belső, hitelesített, megbízható visszacsatolási címre korlátozott bájtközvetítő; 50 MiB-os bemenet, korlátozott várólista/32 MiB-os kimenet, 503 kapacitáshiány, 499 kapcsolatbontás, 504 határidő-túllépés; nem nyilvános feltöltési API

Biztonsági mentés és exportálás/importálás

Végpont	Metódus	Leírás
/api/db-backups	GET	Az elérhető biztonsági mentések listázása
/api/db-backups	PUT	Kézi biztonsági mentés létrehozása
/api/db-backups	POST	Visszaállítás egy adott biztonsági mentésből
/api/db-backups/export	GET	Az adatbázis letöltése .sqlite-fájlként
/api/db-backups/import	POST	.sqlite-fájl feltöltése az adatbázis lecseréléséhez
/api/db-backups/exportAll	GET	Teljes biztonsági mentés letöltése .tar.gz-archívumként

Felhőszinkronizálás

Végpont	Metódus	Leírás
/api/sync/cloud	Különböző	Felhőszinkronizálási műveletek
/api/sync/initialize	POST	Szinkronizálás inicializálása
/api/cloud/*	Különböző	Felhőkezelés

Alagutak

Végpont	Metódus	Leírás
/api/tunnels/cloudflared	GET	A Cloudflare Quick Tunnel telepítési/futásidejű állapotának lekérdezése az irányítópulthoz
/api/tunnels/cloudflared	POST	A Cloudflare Quick Tunnel engedélyezése vagy letiltása (action=enable/disable)
/api/tunnels/ngrok	GET	Az ngrok Tunnel futásidejű állapotának lekérdezése az irányítópulthoz
/api/tunnels/ngrok	POST	Az ngrok Tunnel engedélyezése vagy letiltása (action=enable/disable)

CLI-eszközök

Végpont	Metódus	Leírás
/api/cli-tools/claude-settings	GET	A Claude CLI állapota
/api/cli-tools/codex-settings	GET	A Codex CLI állapota
/api/cli-tools/droid-settings	GET	A Droid CLI állapota
/api/cli-tools/openclaw-settings	GET	Az OpenClaw CLI állapota
/api/cli-tools/runtime/[toolId]	GET	Általános CLI-futási környezet

A CLI-válaszok a következőket tartalmazzák: installed, runnable, command, commandPath, runtimeMode, reason.

ACP-ügynökök

Végpont	Metódus	Leírás
/api/acp/agents	GET	Az összes észlelt ügynök (beépített és egyéni) listázása állapotukkal együtt
/api/acp/agents	POST	Egyéni ügynök hozzáadása vagy az észlelési gyorsítótár frissítése
/api/acp/agents	DELETE	Egyéni ügynök eltávolítása az id lekérdezési paraméter alapján

A GET-válasz tartalmazza az agents[] (id, name, binary, version, installed, protocol, isCustom) és a summary (total, installed, notFound, builtIn, custom) mezőket.

Hibatűrés és sebességkorlátok

Végpont	Metódus	Leírás
/api/resilience	GET/PATCH	A kérési sor, a kapcsolat-várakoztatás, a szolgáltatói megszakító és a várakozási beállítások lekérése/frissítése
/api/resilience/reset	POST	A szolgáltatói áramkör-megszakítók alaphelyzetbe állítása
/api/resilience/model-cooldowns	GET	Az aktív, (szolgáltató, kapcsolat, modell) szerinti zárolások listázása a hátralévő idő alapján rendezve
/api/resilience/model-cooldowns	DELETE	Modellzárolás törlése — törzs: {provider, model}, vagy minden törléséhez {all: true}
/api/rate-limits	GET	Fiókonkénti sebességkorlát-állapot
/api/rate-limit	GET	Globális sebességkorlát-konfiguráció

Mind a négy /api/resilience/* útvonalhoz kezelői hitelesítés (requireManagementAuth) szükséges. A szolgáltatói megszakító, a kapcsolat-várakoztatás és a modellzárolás teljes körű összehasonlításáért lásd: Hibatűrés (bővített).

Kiértékelések

Végpont	Metódus	Leírás
/api/evals	GET/POST	Kiértékelési csomagok listázása/kiértékelés futtatása

Házirendek

Végpont	Metódus	Leírás
/api/policies	GET/POST/DELETE	Útválasztási házirendek kezelése

Megfelelőség

Végpont	Metódus	Leírás
/api/compliance/audit-log	GET	Megfelelőségi auditnapló (utolsó N elem)

v1beta (Gemini-kompatibilis)

Végpont	Metódus	Leírás
/v1beta/models	GET	Modellek listázása Gemini-formátumban
/v1beta/models/{...path}	POST	Gemini generateContent végpont

Ezek a végpontok a Gemini API-formátumát tükrözik azon kliensek számára, amelyek natív Gemini SDK-kompatibilitást várnak el.

Belső/rendszer-API-k

Végpont	Metódus	Leírás
/api/init	GET	Alkalmazás-inicializálási ellenőrzés (az első indításkor használatos)
/api/tags	GET	Ollama-kompatibilis modellcímkék (Ollama-kliensekhez)
/api/restart	POST	A kiszolgáló szabályos újraindításának kezdeményezése
/api/shutdown	POST	A kiszolgáló szabályos leállításának kezdeményezése
/api/system/env/repair	POST	Az OAuth-szolgáltató környezeti változóinak javítása

Megjegyzés: Ezeket a végpontokat a rendszer belsőleg, illetve az Ollama-kliensekkel való kompatibilitás érdekében használja. A végfelhasználók általában nem hívják meg őket.

OAuth-környezeti változók javítása (v3.6.1+)

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

{
  "provider": "claude-code"
}

Kijavítja egy adott szolgáltató hiányzó vagy sérült OAuth-környezeti változóit. A visszaadott válasz:

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

---

Hangátirat

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

Hangfájlok átírása bármely konfigurált STT-szolgáltató használatával. Az elérési út első szegmense választja ki a natív szolgáltatót (openai/…, deepgram/…). A más gyártó modelljét újraexportáló átjárók minősített azonosítót használnak (openrouter/deepgram/nova-3).

Kérés:

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

Válasz:

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

Példa modellazonosítók: openai/whisper-1 (OpenAI-kulcsot igényel), openrouter/deepgram/nova-3 (OpenRouter-kulcsot igényel), deepgram/nova-3 (natív Deepgram-kulcsot igényel). Egy egyszerű deepgram/nova-3 kérés nem használja az OpenRoutert.

Támogatott formátumok: mp3, wav, m4a, flac, ogg, webm.

---

Ollama-kompatibilitás

Az Ollama API-formátumát használó kliensek számára:

# Csevegési végpont (Ollama-formátum)
POST /v1/api/chat

# Modelllista (Ollama-formátum)
GET /api/tags

A kérések automatikusan át lesznek alakítva az Ollama és a belső formátumok között.

Tokenizált VS Code-/fejléc nélküli aliasok

Ezeket az aliasokat akkor használja, ha egy integráció nem képes Authorization fejlécet beilleszteni, és az API-kulcsot az alap URL-be kell ágyazni.

# OpenAI-stílusú katalógusalias
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# OpenAI-stílusú csevegési aliasok
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Ollama-stílusú aliasok
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Példa:

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

Megjegyzések:

• A tokenizált aliasok ugyanazokat a kezelőket használják újra, mint a /v1/* és az /api/tags; a válaszok szerkezete változatlan marad.
• Amikor a kliens támogatja az egyéni fejléceket, részesítse előnyben az Authorization: Bearer ... használatát.
• Az URL-alapú tokenek megjelenhetnek a fordított proxy naplóiban, a böngészési előzményekben és az OmniRoute-on kívüli telemetriában. Kompatibilitási lehetőségként kezelje őket, ne alapértelmezett hitelesítési módként.

---

Telemetria

# Késleltetési telemetria összegzésének lekérése (p50/p95/p99 szolgáltatónként)
GET /api/telemetry/summary

Válasz:

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

---

Költségkeret

# Költségkeret állapotának lekérése az összes API-kulcshoz
GET /api/usage/budget

# Költségkeret beállítása vagy frissítése
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"
}

Sémával kapcsolatos megjegyzések (setBudgetSchema): az apiKeyId megadása kötelező; a dailyLimitUsd, a weeklyLimitUsd vagy a monthlyLimitUsd közül legalább egynek nullánál nagyobbnak kell lennie. Nem kötelező mezők: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). A korábbi {keyId, limit, period} struktúra 400 Bad Request választ eredményez.

Tokenkorlátok

API-kulcsonkénti tokenkeretek (a fenti, USD-alapú költségkerettől elkülönítve). Érvényesítésük közvetlenül a kérés feldolgozási útvonalán történik: amikor egy kulcs aktuális időablakbeli felhasználása eléri a korlátot, a rendszer 429 Too Many Requests válasszal elutasítja a kéréseket. A korlátok hatóköre beállítható egy adott model vagy provider értékre, illetve a teljes kulcsra global hatókörrel; ha egy kérésre több korlát is illeszkedik, a legszigorúbb érvényesül.

# Egy kulcs tokenkorlátainak listázása (az időablak aktuális felhasználását is tartalmazza)
GET /api/usage/token-limits?apiKeyId=key-123

# Tokenkorlát létrehozása vagy frissítése
POST /api/usage/token-limits
Content-Type: application/json

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

# Tokenkorlát törlése azonosító alapján
DELETE /api/usage/token-limits?id=tl-abc

Sémára vonatkozó megjegyzések (setTokenLimitSchema): az apiKeyId és a scopeType (model | provider | global) megadása kötelező. A scopeValue megadása kötelező, kivéve, ha a scopeType értéke global (például modellazonosító model hatókör esetén, illetve szolgáltatóazonosító provider hatókör esetén). A tokenLimit értékének pozitív egész számnak kell lennie (sztringből kényszerített típuskonverzióval). Nem kötelező mezők: id (létrehozáskor elhagyandó, frissítéskor megadandó), resetInterval (daily | weekly | monthly, alapértelmezett értéke monthly), resetTime (HH:MM), enabled (alapértelmezett értéke true). A GET-válaszok minden korlátot kiegészítenek a tokensUsed, remaining, windowStart, periodStartAt és nextResetAt mezőkkel. Ez egy felügyeleti osztályú végpont (a hitelesítést központilag az authz-folyamat érvényesíti).

Kérések feldolgozása

1. A kliens kérést küld a /v1/* címre
2. Az útvonalkezelő meghívja a handleChat, handleEmbedding, handleAudioTranscription vagy handleImageGeneration függvényt
3. A rendszer feloldja a modellt (közvetlen szolgáltató/modell vagy álnév/kombináció)
4. A hitelesítő adatokat a helyi adatbázisból választja ki, a fiókok elérhetősége szerinti szűréssel
5. Csevegés esetén: a handleChatCore ellenőrzi a szemantikai-/aláírás-gyorsítótárat, és feloldja a kombináció tömörítési beállításait
6. Ha engedélyezve van, a proaktív tömörítés a szolgáltatói formátumra való átalakítás előtt fut le (lite, Caveman, RTK vagy halmozott)
7. A szolgáltatói végrehajtó elküldi a kérést a felsőbb szintű szolgáltatásnak
8. A választ a rendszer visszaalakítja kliensformátumra (csevegés), vagy változatlanul adja vissza (beágyazások/képek/hang)
9. A felhasználási adatokat, a tömörítési analitikát és a kérésnaplókat rögzíti
10. Hiba esetén a kombináció szabályai szerint tartalékmechanizmust alkalmaz

Teljes architektúra-referencia: ARCHITECTURE.md

---

Kombinációk kezelése

A magasabb szintű útválasztási kombinációk (amelyeket a /api/combos* szakasz már összefoglalt) 1:1 arányban leképezhetők egy modellazonosító-mintából is, lehetővé téve egy OpenAI-stílusú modellazonosító átlátható átirányítását egy kombinációra.

Metódus	Útvonal	Leírás
GET	/api/model-combo-mappings	Az összes modell→kombináció leképezés listázása
POST	/api/model-combo-mappings	Leképezés létrehozása — törzs: {pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	Egyetlen leképezés lekérése
PUT	/api/model-combo-mappings/[id]	Egy meglévő leképezés mezőinek frissítése
DELETE	/api/model-combo-mappings/[id]	Leképezés eltávolítása

Hitelesítés: felügyeleti munkamenet/API-kulcs (requireManagementAuth).

---

Webhookok

Kimenő webhook-előfizetések az OmniRoute eseményeihez (kérések teljesítése, kvóta kimerülése, kulcsrotáció stb.).

Metódus	Útvonal	Leírás
GET	/api/webhooks	Webhookok listázása (a titkos kulcsok maszkolva jelennek meg: <prefix>...)
POST	/api/webhooks	Webhook létrehozása — törzs: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	Webhook lekérése
PUT	/api/webhooks/[id]	Az url/events/secret/description frissítése
DELETE	/api/webhooks/[id]	Webhook eltávolítása
POST	/api/webhooks/[id]/test	Tesztadatcsomag küldése a webhook URL-címére, majd a kézbesítési állapot visszaadása

Hitelesítés: kezelési munkamenet/API-kulcs (requireManagementAuth).

---

Regisztrált kulcsok (automatikus kezelés)

Az automatikus kulcskezelési alrendszer használja API-kulcsok kiadására és rotálására egy háttérszolgáltatónál/-fióknál, napi/óránkénti kvótákkal.

Metódus	Útvonal	Leírás
GET	/api/v1/registered-keys	Regisztrált kulcsok listázása (csak a maszkolt előtag)
POST	/api/v1/registered-keys	Új regisztrált kulcs kiadása — törzs: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. A nyers kulcsot egyszer adja vissza. A kvóta elutasítása esetén 429 értéket ad vissza.
GET	/api/v1/registered-keys/[id]	Egy regisztrált kulcs metaadatainak lekérése (a nyers kulcsanyag nélkül)
DELETE	/api/v1/registered-keys/[id]	Regisztrált kulcs visszavonása
POST	/api/v1/registered-keys/[id]/revoke	Explicit visszavonási végpont (ugyanaz a hatás, mint a DELETE esetén)

Hitelesítés: Bearer API-kulcs (isAuthenticated). Lásd még: /v1/quotas/check és /v1/issues/report.

---

Ügynökprotokoll

Az OmniRoute felhasználói nevében távolról végrehajtott felhőügynök-feladatok (Claude Code, Codex Cloud, OpenHands stb.).

Metódus	Útvonal	Leírás
GET	/api/v1/agents/tasks	Feladatok listázása — opcionális ?provider=, ?status=, ?limit= (1–500, alapértelmezés: 50)
POST	/api/v1/agents/tasks	Feladat létrehozása — a törzset a CreateCloudAgentTaskSchema validálja (providerId, prompt, source, options?). 201 választ ad vissza feladatburkolóval
DELETE	/api/v1/agents/tasks?id=...	Feladat törlése
GET	/api/v1/agents/tasks/[id]	Feladat lekérése — external_id beállítása esetén szinkron módon frissíti az állapotot a külső felhőügynöktől
POST	/api/v1/agents/tasks/[id]	Megkülönböztetett művelet: {action: "approve"}, {action: "message", message} vagy {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	Adott azonosítójú feladat törlése

Hitelesítés: minden metódushoz felügyeleti hitelesítés szükséges (requireCloudAgentManagementAuth). A v3.8.0 előtt ezek nem igényeltek hitelesítést — a kompatibilitást megszakító módosítást lásd a 588a0333 commitban.

# Claude Code-felhőfeladat létrehozása
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":"..."}}'

---

Felügyeleti proxyk

Kimenő HTTP(S)/SOCKS-proxyk, amelyek szolgáltatókhoz, fiókokhoz vagy globálisan rendelhetők hozzá.

Metódus	Útvonal	Leírás
GET	/api/v1/management/proxies	Proxyk listázása (a ?id= használatával egyet ad vissza; az ?id=&where_used=1 használatával a hozzárendelési gráfot adja vissza)
POST	/api/v1/management/proxies	Proxy létrehozása — a törzset a createProxyRegistrySchema validálja
PATCH	/api/v1/management/proxies	Proxy frissítése — a törzset az updateProxyRegistrySchema validálja (id szükséges)
DELETE	/api/v1/management/proxies?id=...&force=1	Proxy törlése (a hozzárendelések leválasztásához használja a force=1 értéket)
GET	/api/v1/management/proxies/assignments	Hozzárendelések listázása — szűrhető proxy_id, scope, scope_id szerint; egy kapcsolat aktív proxyjának feloldásához adja át a resolve_connection_id=<id> paramétert
PUT	/api/v1/management/proxies/assignments	Hozzárendelés — a törzset a proxyAssignmentSchema validálja ({scope, scopeId?, proxyId?}). Törli a diszpécser gyorsítótárát
PUT	/api/v1/management/proxies/bulk-assign	Tömeges hozzárendelés — a törzset a bulkProxyAssignmentSchema validálja ({scope, scopeIds[], proxyId?})
GET	/api/v1/management/proxies/health?hours=24	Összesített proxyállapot (sikeres/sikertelen műveletek száma, késleltetés) egy adott időablakban

Hitelesítés: minden útvonalon felügyeleti munkamenet/API-kulcs szükséges (requireManagementAuth).

A feladatleírásban szereplő POST /api/v1/management/proxies/[id]/assignments és POST /api/v1/management/proxies/[id]/health végpontokat a fent látható egyszerű /assignments és /health útvonalak szolgálják ki — a kódbázisban nincsenek azonosítónkénti alútvonalak.

---

Ellenálló képesség (bővített)

Az OmniRoute három egymástól független mechanizmust kínál az ideiglenes hibák kezelésére; az alábbi felügyeleti végpontok lehetővé teszik az üzemeltetők számára ezek állapotának lekérdezését és felülbírálását:

Hatókör	Állapottárolás	Lekérdezés	Visszaállítás / törlés
Szolgáltatói megszakító	domain_circuit_breakers + memóriában	/api/monitoring/health	POST /api/resilience/reset
Kapcsolati várakozási idő	rateLimitedUntil a szolgáltatói kapcsolatokon	/api/rate-limits, /api/providers/[id]	(késleltetetten engedélyezi újra; szolgáltatói PUT-tal törölhető)
Modellzárolás	Memóriában tárolt modell-elérhetőségi nyilvántartás	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

A PATCH /api/resilience szolgáltatói megszakító-felülbírálásokat fogad a providerBreaker.oauth és a providerBreaker.apikey alatt. Minden profil támogatja a degradationThreshold, failureThreshold és resetTimeoutMs mezőket; ugyanezek a mezők a Vezérlőpult → Beállítások → Ellenálló képesség felületen is elérhetők.

# Egyetlen modellzárolás törlése
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"}'

# Az összes zárolás törlése
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

A teljes fogalmi referencia és a megszakító alapértelmezett értékei: lásd CLAUDE.md → „Az ellenálló képesség futásidejű állapota”.

---

Képességek

Képesség-keretrendszer az OmniRoute egyéni végrehajtható kezelőkkel való kibővítéséhez, valamint piactéri integrációkhoz.

Metódus	Útvonal	Leírás
GET	/api/skills	A telepített képességek listázása — szűrhető a ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local paraméterekkel, lapozható
GET	/api/skills/[id]	Egy képesség lekérése
PUT	/api/skills/[id]	Képesség frissítése (név, leírás, mód, séma, kezelő, címkék)
DELETE	/api/skills/[id]	Képesség eltávolítása
POST	/api/skills/install	Képesség telepítése nyers manifesztből — törzs: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	A legutóbbi képesség-végrehajtások listázása (napló a bemenetekkel/kimenetekkel/időtartammal)
GET	/api/skills/marketplace?q=...	Keresés/népszerűségi lista a SkillsMP piactérről (a skillsmpApiKey beállítás szükséges)
POST	/api/skills/marketplace/install	Képesség telepítése azonosító alapján a SkillsMP-ről
GET	/api/skills/skillssh?q=&limit=	Keresés a skills.sh nyilvántartásban
POST	/api/skills/skillssh/install	Képesség telepítése azonosító alapján a skills.sh-ról

Hitelesítés: felügyeleti munkamenet/API-kulcs. A piactéri keresési útvonalak a felügyeleti hitelesítést vagy egy Bearer API-kulcsot (isAuthenticated) fogadnak el.

---

Memória

Állandó társalgási/tényalapú memóriatár, API-kulcsonként / munkamenetenként elkülönítve.

Metódus	Útvonal	Leírás
GET	/api/memory	Memóriák listázása — ?apiKeyId=, ?type=, ?sessionId=, ?q=, offset/limit vagy page/limit alapú lapozással
POST	/api/memory	Memória létrehozása — a törzset a Zod ellenőrzi: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	Egy memória lekérése
DELETE	/api/memory/[id]	Egy memória törlése
GET	/api/memory/health	A memória-alrendszer állapota (adatbázis-kapcsolat, beágyazási háttérrendszer, vektorindex állapota)

Hitelesítés: felügyeleti munkamenet/API-kulcs (requireManagementAuth). A type felsorolási típus értékei: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (lásd: MemoryType, src/lib/memory/types.ts).

---

MCP-kiszolgáló

Az OmniRoute egy beágyazott Model Context Protocol-kiszolgálót biztosít 3 átviteli móddal (stdio, SSE, streamable-http) és hatókörökhöz kötött eszközökkel. Az alábbi irányítópult-végpontok állapot- és auditadatokat olvasnak, valamint proxyzzák a HTTP-s átviteli módokat.

Metódus	Útvonal	Leírás
GET	/api/mcp/status	Életjelek, átviteli mód, online állapot, legutóbbi hívás, leggyakrabban használt eszközök, 24 órás sikerességi arány
GET	/api/mcp/tools	MCP-eszközök listája a következőkkel: name, description, scopes, phase, auditLevel, sourceEndpoints
GET	/api/mcp/sse	SSE-adatfolyam megnyitása az SSE átviteli módhoz (503 választ ad, ha az MCP le van tiltva, vagy az átviteli mód nem egyezik)
POST	/api/mcp/sse	JSON-RPC-keret küldése az SSE átviteli módon
GET	/api/mcp/stream	A Streamable HTTP átviteli mód SSE-oldalának megnyitása (kiszolgáló által kezdeményezett üzenetek)
POST	/api/mcp/stream	JSON-RPC-keret küldése a Streamable HTTP átviteli módon
DELETE	/api/mcp/stream	Streamable HTTP-munkamenet befejezése
GET	/api/mcp/audit	Az auditnapló lekérdezése — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	Összesített auditstatisztikák (összesítések, sikerességi arány, átlagos időtartam, leggyakrabban használt eszközök)

Hitelesítés: az sse/stream átviteli módok az MCP-specifikus hitelesítési felületet használják (mcp hatókörrel rendelkező Bearer API-kulcs); a status/tools/audit* útvonalak olvashatók az irányítópultról (az irányítópult gazdagépének elérésén túl nincs szükség további hitelesítésre).

Mindkét HTTP-s átviteli módot a settings.mcpEnabled és a settings.mcpTransport szabályozza — az átviteli mód eltérése 400, az MCP letiltott állapota pedig 503 választ eredményez.

---

A2A-kiszolgáló

Az OmniRoute egy A2A (ügynökök közötti) JSON-RPC 2.0-végpontot, valamint egy REST-burkolót biztosít ellenőrzési és vezérlőpultbeli használatra.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # opcionális, kivéve, ha az OMNIROUTE_API_KEY be van állítva
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Irányítsd ezt a programozási feladatot"}]
  }
}

Támogatott metódusok (mindegyik a settings.a2aEnabled beállítástól függ):

Metódus	Leírás
message/send	Szinkron képességvégrehajtás; eredménye: {task, artifacts, metadata}
message/stream	Ugyanazon képességkészlet streamelt SSE-végrehajtása
tasks/get	Feladat lekérése taskId alapján
tasks/cancel	Feladat megszakítása taskId alapján

Beépített képességek: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Ügynökkártya

GET /.well-known/agent.json

Visszaadja a nyilvános A2A-ügynökkártyát (név, leírás, képességek, képességkatalógus, hitelesítési séma) — nyilvánosan gyorsítótárazva 1 órán át. Nincs szükség hitelesítésre.

REST-segédfüggvények

Metódus	Útvonal	Leírás
GET	/api/a2a/status	A2A engedélyezési állapota + feladatstatisztikák + a gyorsítótárazott ügynökkártya összefoglalója
GET	/api/a2a/tasks	Feladatok listázása — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST	/api/a2a/tasks	(Nincs REST-segédfüggvényként megvalósítva — létrehozás JSON-RPC message/send segítségével)
GET	/api/a2a/tasks/[id]	Egy feladat lekérése
POST	/api/a2a/tasks/[id]/cancel	Feladat megszakítása

Hitelesítés: a REST-segédfüggvények kezelési hitelesítés nélkül futnak (a vezérlőpultról olvashatók); a JSON-RPC /a2a útvonal Bearer OMNIROUTE_API_KEY hitelesítést használ, ha az konfigurálva van.

---

Felhő, kiértékelések és felmérés

Metódus	Útvonal	Leírás
POST	/api/cloud/auth	Bearer-kulcs ellenőrzése, valamint maszkolt szolgáltatói kapcsolatok és modellálnevek visszaadása a felhőszinkronizálási kliensek számára
POST	/api/cloud/credentials/update	Egy felhővel szinkronizált szolgáltató titkosított hitelesítő adatainak frissítése
POST	/api/cloud/model/resolve	Logikai modellazonosító feloldása konkrét szolgáltatóra/modellre a helyi útválasztási táblázat használatával
GET	/api/cloud/models/alias	A felhőszinkronizálás számára elérhető modellálnevek listázása
GET	/api/assess	A legutóbbi felmérési kategorizálások beolvasása (szolgáltatónként/modellenként)
POST	/api/assess	Felmérés futtatása — törzs: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	Beépített kiértékelési csomagok és legutóbbi futtatásaik listázása
POST	/api/evals	Kiértékelési futtatás indítása
POST	/api/evals/suites	Egyéni kiértékelési csomag létrehozása — a törzset az evalSuiteSaveSchema ellenőrzi
GET	/api/evals/suites/[id]	Egyéni kiértékelési csomag lekérése

Hitelesítés: az /api/cloud/auth közvetlenül ellenőrzi a Bearer-kulcsot; a többi /api/cloud/*, /api/evals/* és /api/assess útvonal kezelési munkamenetet/API-kulcsot igényel. Az /api/assess POST a validateBody függvényt használja egy diszkriminált uniós hatókörsémával.

---

ACP (Agent Client Protocol) kezelése

gyermekfolyamatokként. Ezek a végpontok kezelik az ACP-ügynökök észlelését és az egyéni ügynökök regisztrációját.

Metódus	Útvonal	Leírás
GET	/api/acp/agents	Az összes ismert CLI-ügynök (beépített + egyéni) listázása a telepítési állapottal, verzióval és binárissal
POST	/api/acp/agents	Egyéni ACP-ügynök regisztrálása vagy a gyorsítótár frissítése — törzs: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} vagy {action: "refresh"}
DELETE	/api/acp/agents	Egyéni ACP-ügynök eltávolítása — lekérdezési paraméter: ?id=<agentId>

Példaválasz (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
}

Hitelesítés: Kezelési munkamenet (az irányítópult auth_token cookie-ja) vagy kezelési hatókörű API-kulcs szükséges.

A teljes részletekért lásd az ACP-keretrendszer dokumentációját.

---

Analitika és megfigyelhetőség

Valós idejű analitikai végpontok az útválasztás, a tömörítés és a szolgáltatói sokszínűség figyeléséhez. Ezek szolgálják ki a /dashboard/analytics/* oldalakat.

Automatikus útválasztási analitika

Metódus	Útvonal	Leírás
GET	/api/analytics/auto-routing	Összesített automatikus útválasztási statisztikák: összes hívás, stratégiák és szintek eloszlása, fő szolgáltatók
GET	/api/analytics/auto-routing?days=7	Időablakra korlátozott statisztikák (alapértelmezés szerint 24 óra)

Példaválasz:

{
  "window": "24h",
  "totalCalls": 1234,
  "strategyBreakdown": {
    "rules": 800,
    "cost": 200,
    "latency": 150,
    "sla-aware": 50,
    "lkgp": 34
  },
  "tierBreakdown": {
    "ultra": 100,
    "pro": 500,
    "standard": 400,
    "free": 234
  },
  "topProviders": [
    { "provider": "openai", "calls": 500, "avgLatencyMs": 850 },
    { "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 }
  ]
}

Tömörítési analitika

Metódus	Útvonal	Leírás
GET	/api/analytics/compression	Összesített tömörítési statisztikák: megtakarított tokenek, megtakarítási %, módok eloszlása, motorhasználat

Példaválasz:

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

Szolgáltatói sokszínűség nyomon követése

Metódus	Útvonal	Leírás
GET	/api/analytics/diversity	Shannon-entrópián alapuló sokszínűségkövetés: a szolgáltatók megoszlásának mérésével megelőzi az egyedi meghibásodási pontokat

Példaválasz:

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

Hitelesítés: Kezelési munkamenet vagy kezelési hatókörű API-kulcs szükséges.

---

Adminisztrátori műveletek

Kizárólag adminisztrátorok számára elérhető végpontok az üzemeltetési feladatok kezeléséhez.

Metódus	Útvonal	Leírás
GET	/api/admin/concurrency	Az aktuális párhuzamossági korlátok lekérése (globális és szolgáltatónkénti)
POST	/api/admin/concurrency	A párhuzamossági korlátok frissítése — törzs: {global?: number, perProvider?: Record<string, number>}

Hitelesítés: Adminisztrátori hatókörrel rendelkező felügyeleti munkamenet szükséges.

---

CLI-eszközök kezelése

Az OmniRoute-tal integrálható CLI-eszközök (antigravity, commandCode, devin-cli stb.) kezelése. A teljes listát lásd a szolgáltatói referenciában.

Metódus	Elérési út	Leírás
GET	/api/cli-tools/all-statuses	Az összes CLI-eszköz állapota (telepítve van-e, verzió, utolsó észlelés)
GET	/api/cli-tools/status	Egy CLI-eszköz részletes állapota (?tool= lekérdezési paraméter)
POST	/api/cli-tools/apply	Egy eszköz generált konfigurációjának írása (a dryRun előnézetet készít; konténeres futtatáskor 422 + containerEphemeralTarget; a migration örökölt Codex YAML-t jelez)
GET	/api/cli-tools/backups	A CLI-eszközök konfigurációs biztonsági mentéseinek listázása
POST	/api/cli-tools/backups	Biztonsági mentés létrehozása az összes CLI-eszköz konfigurációjáról
POST	/api/cli-tools/backups	Visszaállítás: ugyanez a végpont a törzsben megadott {tool, backupId} használatával visszaállítja az adott biztonsági mentést
GET	/api/cli-tools/antigravity-mitm	Az Antigravity MITM proxy állapota (az „antigravity-mitm” CLI-eszköz)
POST	/api/cli-tools/antigravity-mitm/alias	Az antigravity-mitm aliasainak konfigurálása

Hitelesítés: Kezelői munkamenetet igényel.

---

Ügynökképességek

MI-ügynökök képességeinek kezelése (hasonló az OpenAI egyéni GPT-ihez, de ügynökök számára).

Metódus	Útvonal	Leírás
GET	/api/agent-skills	Az összes ügynökképesség listázása (beépített és egyéni)
GET	/api/agent-skills/[id]	Egy adott ügynökképesség lekérése
POST	/api/agent-skills	Egyéni ügynökképesség létrehozása — törzs: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	Egyéni ügynökképesség frissítése
DELETE	/api/agent-skills/[id]	Egyéni ügynökképesség törlése
GET	/api/agent-skills/[id]/raw	A nyers prompt és a metaadatok lekérése (végrehajtás nélkül)
POST	/api/agent-skills/generate	Új képesség létrehozása MI segítségével, természetes nyelvű leírás alapján

Hitelesítés: Felügyeleti munkamenet vagy felügyeleti hatókörű API-kulcs szükséges.

---

Gyorsítótár-kezelés

A szemantikus gyorsítótár és a következtetési gyorsítótár kezelése.

Metódus	Útvonal	Leírás
GET	/api/cache	Gyorsítótár áttekintése: bejegyzések teljes száma, találati arány, lemezhasználat
GET	/api/cache/entries	Gyorsítótárazott bejegyzések listázása (lapozással)
DELETE	/api/cache/entries	Gyorsítótár-bejegyzések törlése (lekérdezési paraméterek szerinti szűréssel)
GET	/api/cache/stats	Részletes gyorsítótár-statisztikák (szolgáltatónként és modellenként)
GET	/api/cache/reasoning	A következtetési gyorsítótár állapota (a következtetések visszajátszásához)
DELETE	/api/cache/reasoning	A következtetési gyorsítótár törlése — lekérdezési paraméterek: ?toolCallId=<id> (egy), ?provider=<p> vagy nincs paraméter (mind)

Hitelesítés: Kezelői munkamenetet igényel.

---

Memóriarendszer

A tartós memória kezelése (FTS5 + vektoros beágyazások).

Metódus	Útvonal	Leírás
GET	/api/memory	Memóriabejegyzések listázása (hatókör, típus és keresési lekérdezés szerinti szűréssel)
POST	/api/memory	Új memóriabejegyzés létrehozása — törzs: {scope, type, content, metadata?}
GET	/api/memory/[id]	Egy adott memóriabejegyzés lekérése
PUT	/api/memory/[id]	Memóriabejegyzés frissítése
DELETE	/api/memory/[id]	Memóriabejegyzés törlése
GET	/api/memory?q=	Keresés a memóriában (FTS5 + vektor) — a statisztikákat ugyanaz a válasz tartalmazza

Hitelesítés: Kezelői munkamenetet vagy kezelési hatókörű API-kulcsot igényel.

---

Webhookok

Eseményekhez tartozó webhook-előfizetések kezelése.

Metódus	Útvonal	Leírás
GET	/api/webhooks	Az összes webhook-előfizetés listázása
POST	/api/webhooks	Webhook-előfizetés létrehozása — törzs: {url, events[], secret?, active?}
GET	/api/webhooks/[id]	Egy adott webhook-előfizetés lekérése
PUT	/api/webhooks/[id]	Webhook-előfizetés frissítése
DELETE	/api/webhooks/[id]	Webhook-előfizetés törlése
GET	/api/webhooks/[id]/deliveries	Egy webhook kézbesítési előzményeinek listázása (sikeres/sikertelen napló)
POST	/api/webhooks/[id]/test	Tesztesemény küldése egy webhooknak

Hitelesítés: Kezelői munkamenetet igényel.

Az eseménytípusok teljes listáját lásd a Webhook-keretrendszer dokumentumban.

---

Készségkeretrendszer

Készségek (az agentikus bővítmények keretrendszerének) kezelése.

Metódus	Útvonal	Leírás
GET	/api/skills	Az összes telepített készség listázása (beépített + egyéni)
POST	/api/skills/install	Készség telepítése helyi elérési útról vagy URL-ről
DELETE	/api/skills/[id]	Készség eltávolítása
PUT	/api/skills/[id]	Készség engedélyezése vagy letiltása — törzs: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST	/api/skills/executions	Készség végrehajtása — törzs: {skillName, apiKeyId, input?, sessionId?}
GET	/api/skills/executions	Az összes készség végrehajtási előzményeinek listázása (?apiKeyId= szerinti szűréssel)

Hitelesítés: Kezelési munkamenetet vagy kezelési hatókörű API-kulcsot igényel.

A teljes részletekért lásd: Készségkeretrendszer.

---

Bővítmények

OmniRoute-bővítmények (külső fejlesztésű kiegészítők) kezelése.

Metódus	Útvonal	Leírás
GET	/api/plugins	A telepített bővítmények listázása
POST	/api/plugins/marketplace/install	Bővítmény telepítése a piactérről
DELETE	/api/plugins/[name]	Bővítmény eltávolítása
POST	/api/plugins/[name]/activate	Bővítmény aktiválása
POST	/api/plugins/[name]/deactivate	Bővítmény deaktiválása
GET	/api/plugins/[name]/config	Bővítmény konfigurációjának lekérése
PUT	/api/plugins/[name]/config	Bővítmény konfigurációjának frissítése

Hitelesítés: Kezelési munkamenetet igényel.

A teljes részletekért lásd: Bővítmény-keretrendszer.

---

Árnyék-útválasztás

A szolgáltatók árnyék-/A-B összehasonlítása nem önálló REST-felület — kombinált útválasztással konfigurálható (lásd: Automatikus kombináció). A kombinációnkénti összehasonlítási metrikákat a GET /api/combos/metrics szolgálja ki.

---

Védőkorlátok

A futásidejű védőkorlátok (személyazonosításra alkalmas adatok észlelése, promptinjektálás észlelése, vizuális áthidalás) vizsgálata. A védőkorlátok minden kérésnél lefutnak; hívásonkénti kikapcsolásuk az x-omniroute-disabled-guardrails kérésfejléccel lehetséges — nincs tartós engedélyezési/letiltási felület.

Metódus	Útvonal	Leírás
GET	/api/guardrails	A regisztrált védőkorlátok és állapotuk listázása (név / engedélyezve / prioritás)
POST	/api/guardrails/test	A hívás előtti folyamat próbaüzemű futtatása egy mintabemeneten — törzs: {input, disabledGuardrails?}

Hitelesítés: Kezelési munkamenetet igényel.

A teljes részletekért lásd: Biztonság > Védőkorlátok.

---

---

Hitelesítés

A négy hitelesítőadat-családról (irányítópult-munkamenet, helyi CLI-token, oma_live_… hozzáférési token, kezelési hatókörű API-kulcs), valamint az inferenciakulcsoktól való eltéréseikről lásd a Kezelési hitelesítés című útmutatót.

• Az irányítópult útvonalai (/dashboard/*) az auth_token cookie-t használják
• A bejelentkezés a mentett jelszókivonatot használja; tartalék megoldásként az INITIAL_PASSWORD értéket
• A requireLogin a /api/settings/require-login útvonalon kapcsolható be vagy ki
• A /v1/* útvonalakhoz opcionálisan Bearer API-kulcs szükséges, ha REQUIRE_API_KEY=true
• Ebben a referenciában a „kezelési token” / „kezelési hatókörű API-kulcs” az útmutatóban ismertetett családok egyikét jelenti — nem pedig egy meghatározatlan, további titoktípust

Kompatibilitást megszakító változás (v3.8.0) — A /api/v1/agents/tasks/* és a várakozási idő kezelésére szolgáló végpontok mostantól kezelési hitelesítést igényelnek (az irányítópult auth_token cookie-ját vagy egy kezelési hatókörű API-kulcsot). Azok a kliensek, amelyek korábban hitelesítés nélkül hívták meg ezeket az útvonalakat, 401 Unauthorized választ kapnak. Lásd a 588a0333 commitot (fix(auth): require management auth for agent and cooldown APIs).