# API Reference (Magyar)

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

---

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

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`](../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](#chat-completions)
- [Exkluzív felügyelt munkamenet-bérletek](#exclusive-managed-session-leases)
- [Beágyazások](#embeddings)
- [Képgenerálás](#image-generation)
- [Dokumentum-OCR](#document-ocr)
- [Modellek listázása](#list-models)
- [Szolgáltatói bővítmény jegyzéke](#provider-plugin-manifest)
- [Kompatibilitási végpontok](#compatibility-endpoints)
- [Fájlok API](#files-api)
- [Kötegek API](#batches-api)
- [Keresési API](#search-api)
- [WebSocket-adatfolyam](#websocket-streaming)
- [Kvóták és problémák jelentése](#quotas--issues-reporting)
- [Szemantikai gyorsítótár](#semantic-cache)
- [Irányítópult és felügyelet](#dashboard--management)
- [Kombinációk kezelése](#combo-management)
- [Webhookok](#webhooks)
- [Regisztrált kulcsok (automatikus kezelés)](#registered-keys-auto-management)
- [Ügynökprotokoll](#agents-protocol)
- [Felügyeleti proxyk](#management-proxies)
- [Hibatűrés (kibővített)](#resilience-extended)
- [Készségek](#skills)
- [Memória](#memory)
- [MCP-kiszolgáló](#mcp-server)
- [A2A-kiszolgáló](#a2a-server)
- [Felhő, kiértékelések és értékelés](#cloud-evals--assess)
- [Kérések feldolgozása](#request-processing)
- [Hitelesítés](#authentication)

---

## Csevegési kiegészítések

```bash
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 menedzselt munkamenet-bérletek

Az exkluzív menedzselt munkamenet-bérlet 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-ot, nem azonosít konkrét klienst, és nem igényel konkrét szolgáltatót.

Az autentikáló API kulcsnak rendelkeznie kell `lease:exclusive` hatókörrel és egy explicit, nem üres `allowedConnections` listával. Az adatbázis-módosítási határ mindkét mezőt érvényesíti a kulcs létrehozásakor és a részleges frissítéseknél.

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

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

A sikeres megszerzési, megújítási és felszabadítási válaszok időbélyegeket, `state`-et és az pontos pozitív `generation`-t tesznek közzé, de soha nem a kiválasztott kapcsolatot vagy hitelesítő adatokat. A megújítás és a felszabadítás a generációt a JSON törzsben adja meg:

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

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

Egy aktív bérlet tulajdonos explicit módon kérhet adatvédelmi szempontból biztonságos megjelenítési metaadatokat az aktuális kötéséhez:

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

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

Ez az opcionális állapotművelet az átlátszatlan tulajdonos, az autentikált menedzselt API kulcs és az pontos aktív generáció által van védve egy adatbázis tranzakcióban. A `displayName` csak a levágott konfigurált kapcsolatnév; `null`, ha nincs biztonságos konfigurált név. Az OmniRoute soha nem helyettesít e-mailt vagy generált fiókazonosítót. A szolgáltató értéke egy nem érzékeny megjelenítési címke, és soha nem egy generált kompatibilis szolgáltató azonosító. A hitelesítő adatok, tokenek, sütik, nyers kapcsolat- vagy API kulcs azonosítók, tulajdonos hash-ek, védelmi titkok és belső útválasztási adatok kizárásra kerülnek.

Helytelen kulcs, helytelen tulajdonos, elavult generáció, hiányzó, lejárt, felszabadított és érvénytelenített keresések mind ugyanazt a `409 LEASE_FENCE_STALE` hibát adják vissza kapcsolat metaadatok nélkül. Egy kliens, amely kapacitás-várakozási választ kapott, nem rendelkezik aktív kötéssel, amelyet ellenőrizhetne. Amikor az útválasztás átvisz egy aktív bérletet, ugyanaz a generáció érvényes marad, és az állapot atomi módon adja vissza az új kötést, soha nem a régit. A meglévő kliensek változatlanok maradnak, mert a megszerzési, megújítási, felszabadítási és várakozási válaszok megőrzik korábbi formájukat.

Ez a szerver szerződés nem változtatja meg a standard OpenAI Codex `/status` működését. A standard Codex jelenleg jelenti a modell szolgáltatóját és a beépített hitelesítési/fiók állapotát, de nem jelenít meg tetszőleges egyedi szolgáltatói fiók metaadatokat; egy későbbi kliens integrációnak kell meghívnia ezt a műveletet, és el kell döntenie, hogyan jelenítse meg a `connection.displayName`-t.

Minden menedzselt következtetési kérés ezután mindkét vezérlőfejlécet tartalmazza:

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

Az pontos tulajdonos, generáció, aktív kapcsolat és autentikált API kulcs azonnal védve van minden támogatott upstream kísérlet előtt. A tulajdonos és a generáció újrajátszása egy másik kulccsal meghiúsul, még akkor is, ha az a kulcs ugyanazt a kapcsolatot engedélyezi. A nyers tulajdonosok nem kerülnek tárolásra, naplózásra, megőrzésre a kérés pillanatképében, vagy továbbításra upstream.

Az ideiglenes versengés HTTP `429` választ ad vissza `Retry-After` fejléccel és:

```json
{
  "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 tartott. 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 megőrzik meglévő OmniRoute válaszaikat.

### `x-omniroute-compression`

Kérésenkénti felülbírálás a tömörítési tervre. Legmagasabb prioritás – felülírja az útválasztási-kombináció felülbírálását, az aktív profilt, az automatikus indítást és a panel alapértelmezett beállítását. Értékek:

| Érték         | Hatás                                                                                                                             |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `off`         | Nincs tömörítés ehhez a kéréshez.                                                                                                 |
| `default`     | A panelből származó alapértelmezett profil (figyelmen kívül hagyja az aktív profilt). A veszteséges motorok kikapcsolva maradnak. |
| `safe`        | Csak duplikáció eltávolítás és szóközösszevonás.                                                                                  |
| `allow-lossy` | Tartsa meg az operátor tervét ehhez a kéréshez, beleértve az összefoglalókat és a stílus újraírásokat.                            |
| `engine:<id>` | Egyetlen motor, ha engedélyezve van, pl. `engine:rtk`. Kérésenkénti bekapcsolás az adott motorhoz.                                |
| `<combo>`     | Egy elnevezett kombináció, először név (kis- és nagybetű érzéketlen) alapján, majd azonosító alapján egyezik.                     |

Megjegyzések:

- Az ismeretlen értékek figyelmen kívül maradnak (a kérés soha nem kerül elutasításra); a feloldás a normál operátori prioritás szerint történik.
- Ha több kombináció osztozik egy néven, adja meg a kombináció **azonosítóját** a determinisztikus egyezéshez.
- Az `off` vagy `default` nevű kombináció nem választható ki név alapján (ezeket a kulcsszavakat először értelmezik); hivatkozzon az ilyen kombinációra az azonosítója alapján.
- A fő tömörítési kapcsoló egy kemény kapu: ha a tömörítés globálisan le van tiltva, ez a fejléc nem tudja engedélyezni.

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

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

ahol `<source>` a `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` vagy `off` egyikét jelenti.

---

## Beágyazások

```bash
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:

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

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.

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

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.

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

---

## Képgenerálás

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

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

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).

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

---

## Dokumentum-OCR

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

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

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:

```json
{
  "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

```bash
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:

```bash
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](../guides/VSCODE-COPILOT.md) 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

```bash
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 | Útvonal                                   | Formátum                             |
| ------- | ----------------------------------------- | ------------------------------------ |
| POST    | `/v1/chat/completions`                    | OpenAI                               |
| POST    | `/v1/messages`                            | Anthropic                            |
| POST    | `/v1/responses`                           | OpenAI válaszok                      |
| POST    | `/v1/embeddings`                          | OpenAI                               |
| POST    | `/v1/images/generations`                  | OpenAI képek                         |
| POST    | `/v1/images/edits`                        | OpenAI képek (szerkesztés/kitöltés)  |
| POST    | `/v1/videos/generations`                  | OpenAI-stílusú videógenerálás        |
| POST    | `/v1/music/generations`                   | OpenAI-stílusú zene generálás        |
| POST    | `/v1/audio/transcriptions`                | OpenAI hang (STT)                    |
| POST    | `/v1/audio/speech`                        | OpenAI TTS (hanganyagot ad vissza)   |
| POST    | `/v1/rerank`                              | Cohere/Voyage-stílusú újrarendezés   |
| POST    | `/v1/classify`                            | Jina osztályozás (`api.jina.ai`)     |
| POST    | `/v1/segment`                             | Jina szegmentáló (`segment.jina.ai`) |
| POST    | `/v1/moderations`                         | OpenAI moderációk                    |
| 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 alias               |
| GET     | `/api/v1/vscode/{token}/models`           | OpenAI modellek alias                |
| POST    | `/api/v1/vscode/{token}/chat/completions` | OpenAI tokenizált alias              |
| POST    | `/api/v1/vscode/{token}/responses`        | OpenAI válaszok tokenizált alias     |
| POST    | `/api/v1/vscode/{token}/api/chat`         | Ollama tokenizált alias              |
| GET     | `/api/v1/vscode/{token}/api/tags`         | Ollama címkék tokenizált alias       |

Minden POST útvonal azonos formátumot követ: `Bearer your-api-key` + Zod-validált JSON törzs (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, stb., lásd `src/shared/validation/schemas.ts`). Sémahiba esetén 4xx-es válasz kerül visszaadásra.

Azoknak az ügyfeleknek, amelyek nem tudnak `Authorization: Bearer ...` fejlécet csatolni, az OmniRoute az API kulcsokat az URL-ben is elfogadja, akár lekérdezési sztring kompatibilitás (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) révén, akár az alább dokumentált dedikált `/api/v1/vscode/{token}/...` végpontokon keresztül.

```bash
# Újrarendezés (felhőalapú regisztrációs szolgáltató, vagy OpenAI-kompatibilis szolgáltatói csomópont "<előtag>/<modell>" formában)
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ációk
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — audio/mpeg (vagy 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ó / zene generálás (szolgáltató-előtaggal ellátott modell azonosító)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }
```

> **Újrarendezési szolgáltatói csomópontok:** A `POST /v1/rerank` útvonal OpenAI-kompatibilis szolgáltatói csomópontokhoz is irányít (oMLX, vLLM, Infinity, TEI egy átjáró mögött, …), amelyek `<csomópont-előtag>/<modell>` formában vannak címezve. A loopback csomópontok (`localhost`, `127.0.0.1`, `172.16.0.0/12`) mindig jogosultak. Bármely más gazdagépen — egy LAN-dobozon vagy Tailscale-társgépen — lévő csomópontok csak akkor jogosultak, ha az operátor engedélyezi a `RERANK_REMOTE_PROVIDER_NODES` funkciójelzőt **és** a csomópont alap URL-je megfelel a szolgáltató kimenő URL-szabályzatának (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`); a felhő-metaadat gazdagépekhez soha nem történik útválasztás. A memóriakezelő újrarendezési lépése ezen az útvonalon keresztül hívja meg a loopbacket, így ugyanez a szabály vonatkozik a `rerankProviderModel`-re a Memória beállításokban.
>
> **Helyi szerver formák:** A csomópontot a `<base>/v1/rerank` címen hívják meg, és 404 esetén a `<base>/rerank` címen (Infinity, TEI). A felsőbb rétegbeli törzs tartalmazza a Cohere/OpenAI írásmódot (`documents`, `return_documents`) és a TEI írásmódot (`texts`, `return_text`) is, és a felsőbb rétegbeli válasz a Cohere borítékhoz van normalizálva: A TEI csupasz `[{index, score, text}]` formátuma, a vékony átjárókból származó `{results: [{index, score}]}` és a Voyage-stílusú `{data: [...]}` mind `{results: [{index, relevance_score, document?}]}` formában térnek vissza az ügyfélhez, pontszám szerint rendezve és `top_n`-nél korlátozva.

> **Szolgáltatói csomópont felfedezés:** Az OpenAI-kompatibilis szolgáltatói csomóponton lévő modellek a `GET /v1/models` alatt jelennek meg a csomópont előtaggal. Azok a sorok, amelyek nem tartalmaznak végpont metaadatokat (jellemző a helyi `/v1/models` listázásokra), öröklik a csomópont `apiType`-ját, így egy beágyazási csomópont modelljei `type: "embedding"` típusúak, és egy újrarendezési csomópont modelljei `type: "rerank"` típusúak lesznek a chat alapértelmezett helyett; egy szinkronizált vagy manuálisan hozzáadott soron lévő explicit `supportedEndpoints` továbbra is elsőbbséget élvez.

### Dedikált szolgáltatói útvonalak

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

A szolgáltató előtagja automatikusan hozzáadódik, ha hiányzik. Az illesztetlen modellek `400`-as hibakódot adnak vissza.

---

## 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

```bash
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)

```bash
# 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):

```toml
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)
```

```bash
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.

```bash
# 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:

```jsonc
{
  "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

```bash
# 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:

```json
{
  "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]`):

```json
{ "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](../guides/MANAGEMENT-AUTH.md).

### 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](../guides/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](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). |
| `/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)](#resilience-extended).

### 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+)_

```bash
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:

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

---

## Hangátirat

```bash
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:**

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

**Válasz:**

```json
{
  "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:

```bash
# 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.

```bash
# 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:

```bash
curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'
```

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

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

**Válasz:**

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

---

## Költségkeret

```bash
# 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.

```bash
# 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`](../architecture/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.

```bash
# 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.

```bash
# 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`](../../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

```bash
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

```bash
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`):

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

**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](../frameworks/ACP.md) 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**:

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

### 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**:

```json
{
  "window": "24h",
  "totalOriginalTokens": 5000000,
  "totalCompressedTokens": 3500000,
  "totalSavings": 1500000,
  "savingsPct": 30.0,
  "modeBreakdown": {
    "lite": 400,
    "standard": 600,
    "aggressive": 100,
    "ultra": 50,
    "rtk": 84
  },
  "engineBreakdown": {
    "caveman": 800,
    "rtk": 434
  }
}
```

### 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**:

```json
{
  "window": "24h",
  "shannonEntropy": 2.45,
  "maxEntropy": 3.17,
  "diversityRatio": 0.77,
  "providerUsage": {
    "openai": 0.4,
    "anthropic": 0.25,
    "google": 0.2,
    "kiro": 0.15
  },
  "warnings": ["OpenAI accounts for 40% of traffic — consider diversifying"]
}
```

**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](./PROVIDER_REFERENCE.md).

| 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](../frameworks/WEBHOOKS.md) 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](../frameworks/SKILLS.md).

---

## 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](../frameworks/PLUGIN_SDK.md).

---

## Á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ó](../routing/AUTO-COMBO.md)). 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](../security/GUARDRAILS.md).

---

---

## 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](../guides/MANAGEMENT-AUTH.md) 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`).