# API_REFERENCE (Malti)

🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/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) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/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) · 🇸🇰 [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) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)

---

---

title: "Referenza tal-API"
version: 3.8.51
lastUpdated: 2026-08-31
---

# Referenza tal-API

🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/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) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/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) · 🇸🇰 [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) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)

Referenza bażtarja għall-API tal-OmnirRoute. Tinklodi s-superfiċi pubblika `/v1` u l-endpoints tal-ġestjona l-aktar użati; il-[`docs/openapi.yaml`](../openapi.yaml) li jista' jitqara mill-magni u t-taqsima tar-rotot taħt `src/app/api/` huma s-sorsi kompli.

---

## Indiċi tal-Kontenut

- [Kompletamenti tal-Chat](#chat-completions)
- [Lesti tal-Isessjoni Maniġjata Eżklussiva](#exclusive-managed-session-leases)
- [Embs](#embeddings)
- [Ġenerazzjoni tal-Immaġni](#image-generation)
- [OCR tal-Dokumenti](#document-ocr)
- [Turi l-Mudelli](#list-models)
- [Maniġer tal-Plugin tal-Fornitur](#provider-plugin-manifest)
- [Għanijiet tal-Kompatibbiltà](#compatibility-endpoints)
- [API tal-Fajls](#files-api)
- [API tal-Batches](#batches-api)
- [API tat-Tiftix](#search-api)
- [Streaming permezz ta' WebSocket](#websocket-streaming)
- [Kwoti u Rapportar tal-Problemi](#quotas--issues-reporting)
- [Cache Semantika](#semantic-cache)
- [Dashboard u Ġestjoni](#dashboard--management)
- [Ġestjoni tal-Kombo](#combo-management)
- [Webhooks](#webhooks)
- [ĊavverteReġistrati (Ġestjoni Awtomatika)](#registered-keys-auto-management)
- [Protokoll tal-Aġenti](#agents-protocol)
- [Proxys tal-Ġestjoni](#management-proxies)
- [Reżiljenza (estiża)](#resilience-extended)
- [Ħiliet](#skills)
- [Memorja](#memory)
- [Server MCP](#mcp-server)
- [Server A2A](#a2a-server)
- [Sħab, Evalwazzjonijiet u Valutazzjoni](#cloud-evals--assess)
- [Proċessar tal-Ħarsa](#request-processing)
- [Awtentikazzjoni](#authentication)

---

## Kompletamenti tal-Chat

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

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Iktar funzjoni għal..."}
  ],
  "stream": true
}
```

### Intestaturi Personaliżżati

| Intestatura              | Direzzjoni  | Deskrizzjoni                                                                                                                                                                                                                       |
| ------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache`   | Tal-Ħarsa   | Ibbuttaha għal `true` biex tevita l-cache                                                                                                                                                                                          |
| `x-omniroute-no-memory`  | Tal-Ħarsa   | Ibbuttaha għal `true` biex taħbi l-memorja + l-injezzjoni tal-ħiliet għal din il-ħarsa (tirrifletti no-cache; tevita l-ispiża tal-token/kull ċempela)                                                                              |
| `X-OmniRoute-Progress`   | Tal-Ħarsa   | Ibbuttaha għal `true` għall-avvenimenti tal-progress                                                                                                                                                                               |
| `X-Session-Id`           | Tal-Ħarsa   | Ċavviera tal-isessjoni stikky għall-affinità tal-isessjoni esterna                                                                                                                                                                 |
| `x_session_id`           | Tal-Ħarsa   | Varjazzjoni b'ankra aċċettata wkoll (HTTP dirett)                                                                                                                                                                                  |
| `X-OmniRoute-Session-Id` | Tal-Ħarsa   | Ċippa ta' konverżazzjoni/isessjoni pprovduta mill-appell (tagħti wkoll memorja). Meta preżenti, tistaħżen verbatim fi `call_logs.session_tag` għall-attribuzzjoni tal-ispiża ta' kull isessjoni (#8249) — qatt ma ssir meta nieqes |
| `Idempotency-Key`        | Tal-Ħarsa   | Ċavviera dedup (finestra ta' 5s)                                                                                                                                                                                                   |
| `X-Request-Id`           | Tal-Ħarsa   | Ċavviera dedup alternattiva                                                                                                                                                                                                        |
| `X-OmniRoute-Cache`      | Tar-Rispons | `HIT` jew `MISS` (mhux streaming)                                                                                                                                                                                                  |
| `X-OmniRoute-Idempotent` | Tar-Rispons | `true` jekk iddeduplikat                                                                                                                                                                                                           |
| `X-OmniRoute-Progress`   | Tar-Rispons | `enabled` jekk it-traċċar tal-progress ikun mixgħul                                                                                                                                                                                |
| `X-OmniRoute-Session-Id` | Tar-Rispons | ID tal-isessjoni effettiva użata minn OmniRoute                                                                                                                                                                                    |
| `X-OmniRoute-Request-Id` | Tar-Rispons | ID tal-korrelazzjoni tal-ħarsa (meta magħrufa)                                                                                                                                                                                     |
| `X-OmniRoute-Version`    | Tar-Rispons | Verżjoni tal-bini ta' OmniRoute (dejjem preżenti)                                                                                                                                                                                  |
| `X-OmniRoute-Cost-Saved` | Tar-Rispons | USD li l-cache ħlset fuq HIT ( HITs tal-cache biss)                                                                                                                                                                                |
| `X-OmniRoute-Decision`   | Tar-Rispons | Traċċar ir-routing: `strategy=<isem>; provider=<alias>; latency_ms=<n>` (`<isem>` hija l-istrateġija tal-kombo, jew `single` għal ħarsa mhux kombo) — dejjem preżenti fir-risponsijiet tat-tmiem                                   |

> Nota ta' Nginx: jekk tista' sserraħ fuq l-intestaturi b'ankra (eż. `x_session_id`), attiva `underscores_in_headers on;`.

> **Intestaturi tat-telemetija tal-ispiża:** ir-risponsijiet ta' suċċess mhux streaming iġorru wkoll l-intestaturi tal-grupp `X-OmniRoute-*` tal-ispiża — `X-OmniRoute-Response-Cost` (USD, 10 deċimali fissi; `0.0000000000` għal mingħajr spiża/mhux ittakkjar), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit`, u `X-OmniRoute-Fallback-Attempts` (biss meta > 0), flimkien ma' `X-OmniRoute-Request-Id` u `X-OmniRoute-Version`. Dawn jiġu emessi mill-kompletamenti tal-chat, `/v1/responses`, `/v1/messages`, **u l-għanijiet tal-midja** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations`, u `/v1/moderations` (dejjem spiża `0`). L-ispiża tal-midja tintlibes skont il-modalità (kull immaġni, kull sekonda, kull karattru, kull unità ta' tiftix) meta l-prezzijiet huma disponibbli, inkella `0` (ħlas falz).

> **Semantika tal-ispiża ta' HIT tal-cache:** fuq HIT tal-cache semantika (`X-OmniRoute-Cache-Hit: true`) ma ssir l-ebda sejħa upstream, għalhekk `X-OmniRoute-Response-Cost` hija `0.0000000000` (l-ispiża **inkrementalment** tas-servizz tal-HIT). L-ispiża oriġinali/tal-possibbiltà titwettaq f'rapport separat fi `X-OmniRoute-Cost-Saved`. L-konsumaturi tal-fattur għandhom jisummaw `X-OmniRoute-Response-Cost` (HITs jiswew xejn); l-analitika tal-cache tista' tiggruppa `X-OmniRoute-Cost-Saved`.

## Sessjonijiet ta’ Kirja Eżklużivi ta’ Ġestjoni

Il-kiri ta’ sessjonijiet ta’ ġestjoni eżklużivi huwa kuntrat ta’ routing appoġġat u newtrali għall-klijent: wieħed proprjetarju attiv iżomm konnessjoni ta’ OmniRoute waħda eliġibbli. Mhuwiex jagħmel kiri ta’ mudell, ma jeħtieġx OAuth, ma jidentifikax klijent partikolari, u lanqas jeħtieġi fornitur partikolari.

Il-mewt API tal-awtentikazzjoni trid ikollha skop `lease:exclusive` u lista li ma hijiex vojta `allowedConnections` espliċita. Il-limitu tal-mutazzjoni tal-bażi tad-dejta jinfurza iż-żewġ qasam flimkien meta jinħoloq il-mewt u waqt il-aġġornamenti parzjali.

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

Il-responsi ta’ akkwist, taġdid, u rilaxx successfully juru timestamps, `state`, u l-positiv eżatt `generation`, iżda qatt il-konnessjoni magħżula jew l-credentials. It-tġdid u r-rilaxx jipprovdu l-ġenerazzjon fil-body JSON:

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

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

Proprjetarju ta’ kiri attiv jista’ jitolb b’mod espliċitu metadata ta’ wiri sigura għall-privacy għal qafas attwali tiegħu:

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

L-azzjoni ta’ stat appoġġata ġġib protezzjoni permezz tal-proprjetarju opaq, il-mewt API awtentikata, u l-ġenerazzjoni attiva eżatt f’transazzjoni waħda tal-bażi tad-dejta. `displayName` huwa biss l-isem tal-konnessjoni kkonfigurat li ntilef; huwa `null` meta m’hemmx isem sigur kkonfigurat. OmniRoute ma jissostitwixxi qatt email jew identità tal-kont generata. Il-valur tal-fornitur huwa etiketta ta’ wiri mhux sensittiva u qatt mhux identifikatur ta’ fornitur kompatibbli magħmul. Credentials, tokens, cookies, IDs ta’ konnessjoni ġodda jew tal-mewt, hashes tal-proprjetarju, ficing secrets, u data interna ta’ routing huma esklużi.

Tfittxijiet b’mewt ħażin, proprjetarju ħażin, ġenerazzjoni skaduta, nieqsa, skaduta, rilaxxata, u invalidata kollha jirritornaw l-istess ħata `409 LEASE_FENCE_STALE` mingħajr metadata ta’ konnessjoni. Klijent li rċieva r-rispons ta’ stennija tal-kapaċità m’għandux qafas attiv x’jispezzjona. Meta r-routing jibdel kiri attiv, l-istess ġenerazzjoni tibqa’ valida u l-stat atomikament jirritorna l-qafas ġdid, qatt l-ieħor. Klijenti eżistenti jibqgħu l-istess għax l-akkwist, tġdid, rilaxx, u risponsi ta’ stenni żżomm l-istqarrijiet preċedenti tagħhom.

Dan il-kuntrat tas-servizz ma jibdlilx statut l-OpenAI Codex `/status`. L-iStatut tal-Cex kurrentment jirrapporta l-mudell tal-fornitur u l-istat awtentikazzjoni/kont integrat iżda ma juri metadata ta’ kont tal-fornitur personalizzat arbitrarja; integrazzjoni tal-klijent wara trid tieħu din l-azzjoni u tiddeċiedi kif turi `connection.displayName`.

Kull talba ta’ inferenza ta’ ġestjoni mbagħad jipprovdi iż-żewġ headers ta’ kontroll:

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

Il-proprjetarju eżatt, ġenerazzjoni, konnessjoni attiva, u mewt API awtentikata ġew imfissra mal-eqqel qabel kull tentattiv upstream appoġġat. Il-logħob mill-ġdid tal-proprjetarju u tal-ġenerazzjoni b’mewt ieħor fallas anki jekk dik il-mewt tippermetti l-istess konnessjoni. Proprjetarji ġodda mhumiex permanenti, irreġistrati, iżżomm fl-snapshot tat-talba, jew imgħadda upstream.

Kontenzjoni temporanja tirritorna HTTP `429` b'`Retry-After` u:

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

Dan ir-rispons ifisser biss li l-grupp normali eliġibbli kien mhux vojt u kull kandidat ħieles kien miżmum minn kiri attiv barrani. Mudelli/fornituri mhumiex appoġġati, in-nuqqas tal-politika, tas-sħana, kwota, saħħa, u fallimenti normali oħra ta’ eliġibbilta jżommu l-ispezzjonijiet preċedenti ta’ OmniRoute tagħhom.

### `x-omniroute-compression`

Override għal kull talba tal-pjan tal-kompressjoni. Preċedenza l-ogħla — jegħlba l-override ta’ routing-combo, il-profil attiv, l-awto-triger, u l-Default tal-pannell. Valuri:

| Valur         | Effett                                                                      |
| ------------- | --------------------------------------------------------------------------- |
| `off`         | Ebda kompressjoni għal din it-talba.                                        |
| `default`     | Il-profil Default (jinjora l-profil attiv).                                 |
| `engine:<id>` | Magna waħda meta tkun attiva, pereż. `engine:rtk`.                          |
| `<combo>`     | Combo magħżuwa, imqaqqsa bl-isem (kas-insensittiv) l-ewwel, imbagħad bl-id. |

Noti:

- Valuri magħrufa huma injorati (it-talba qatt ma tiġi rifjutata); ir-risoluzzjoni taqa’ fil-prijorità normali tal-operatur.
- Jekk aktar kombo jaqsmu l-isem, għaddi l-**id** tal-combo għal tqabbil deterministiku.
- Kombo li għandu isem `off` jew `default` ma jintgħażilx bl-isem (dawk il-kelma jinterpretaw l-ewwel); irreferi b’tali kombo bl-id tiegħu.
- Il-master switch tal-kompressjoni huwa bieb iebes: meta l-kompressjoni tkun diżattivata globalment, dan il-headers ma jistax iħallaha.

Il-pjan applikata jittella’ lura fil-header tar-rispons:

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

fejn `<source>` huwa wieħed minn `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, jew `off`.

---

## Embrijodings

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

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

Fornituri disponibbli: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.

L-IDs tal-katalgu huma `provider/model` (eżempju: `jina-ai/jina-embeddings-v5-omni-small`). L-IDs ċerti tal-mudelli Jina li dehru fir-reġistru (per eżempju `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) jistgħu jsiru wkoll. Il-prodotti Jina embed/rerank/classify/segment jużaw l-kredenzjali tal-dashboard `jina-ai` l-ewwel; `JINA_AI_API_KEY` huwa fallback biss meta ma hemm l-ebda ċavetta tal-dashboard. Il-karta `jina-reader` hija Reader / `r.jina.ai` biss (`POST /v1/web/fetch`) u qatt ma sservi embrijodings jew rerank.

Il-mudelli tar-reġistru li jirriklamaw multimedja bħala appoġġ jassenu ukoll sa 32 oġġett strutturat newtrali għal-fornitur. It-tipi ta' medja huma `text`, `image`, `audio`, `video`, u `document`. Is-source tagħhom huwa jew `{"type":"url","url":"https://..."}` jew
`{"type":"base64","data":"...","media_type":"..."}`.

Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`,
u l-isem tal-familja `jina-ai/jina-embeddings-v5-omni` → omni-small) jaċċetta wkoll id-dokumenti nattivi EmbeddingsV5Request ta' Jina u **jibgħathom intatti** lejn `https://api.jina.ai/v1/embeddings`:

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

Valuri nattivi `{ image | audio | video | pdf }` jistgħu jkunu URL HTTPS pubbliku, URI `data:`, jew base64 dirett. OmniRoute ma jħaddanx dawn l-oġġetti jew ifittex URLs tal-istampi nattivi — Jina ifittex il-medja pubbliku nnifsu. Ġiti estiżi ta' Jina (`task`, `normalized`, `truncate`, `typing_type`) jibqgħu jgħaddu. Is- SKUJ ta' Jina b'tekst biss għadhom jirrifjutaw dokumenti mhux test.

Limiti ta' sigurtà u trasport:

- URLs tal-medja remoti għandhom ikun HTTPS pubbliku. L-oġġetti standard `{type,source:url}` jiġu mibrin liv server (ridirezzjonar tal-validazzjoni, ħin massiku, limiti ta' daqs, DNS pubbliku, ullimm tal-konnessjoni) u jintegraw qabel l-sejħa tal-fornitur. L-oġġetti Jina-nattivi `{image:"https://..."}` jiġu mibgħuthom kif inhu wara l-istess tassigurar HTTPS pubbliku; Jina ifittex l-URL.

- Il-medja inline base64 huwa limitat għal 8 MiB dekodifikat kull oġġett u 16 MiB dekodifikat fil-ġisem tal-ġisem.

Talsar tal-fornitur (l-oġġetti standard qatt jiġu mibgħuthom mhux imbandalati):

- Mudelli multimodal ta' Jina: kull oġġett liv tlieta jsir wieħed ċavtat b'modalità
  (`text` / `image` / `audio` / `video` / `pdf`) juża data URIs għal-medja inline; vettur wieħed għal
  oġġett liv tlieta.
- Gemina Embedding 2 family: array wieħed liv tlieta jsir sejħa nattiva waħda
  `models/{model}:embedContent` b'`content.parts` (`text` jew `inline_data`).
- Mudelli magħrufa/dinamiċi mingħajr metadata ta' modalità speċifika jirrifjutaw input strutturat b'HTTP 400.

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

Kombinazzjonijiet mhux appoġġjati tal-mudell/modalità jirritornaw HTTP 400 minflok jibilbu l-oġġett. L-estensjonijiet mhux ta' input f'taljenti antik tal-kords/jetons jibqgħu jgħaddu mingħajr tibdil.

```bash
#Lista ta' kollha mudelli embed
GET /v1/embeddings
```

## Ġenerazzjoni tal-Immaġni

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

Fornituri disponibbli: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (lokali), ComfyUI (lokali).

```bash
# Lista l-mudelli kollha tal-immaġni
GET /v1/images/generations
```

---

## OCR tal-Dokumenti

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

`model` tagħżel il-fornitur OCR permezz tal-k蒈ttix `provider/model`; model bla prefiss (p.e.
`mistral-ocr-latest`) jiġi risolut għal fornitur irreġistrat tiegħu, u meta `model` jitħalla barra
huwa jħallas għal Mistral (`mistral-ocr-latest`). Fornituri irreġistrati (`open-sse/config/ocrRegistry.ts`):

| ID tal-Fornitur               | ID tal-Mudell        | Valur `tal-model`                                                          | Noti                                                                                                                    |
| ----------------------------- | -------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `mistral`                     | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (jew wieħed bla prefiss `mistral-ocr-latest`) | Sinċron — ir-risposta tiġi rritornata direttament mill-unika sejħa ta' fuq.                                             |
| `azure-document-intelligence` | `prebuilt-read`      | `azure-document-intelligence/prebuilt-read`                                | Asinkron ta' fuq (`analyze` + poll) — ara t'hawn taħt.                                                                  |
| `vertex-deepseek-ocr`         | `deepseek-ocr-maas`  | `vertex-deepseek-ocr/deepseek-ocr-maas`                                    | Sinċron, permezz tal-punt tal-assi tal-`openapi/chat/completions` ta' Vertex AI — ara t'hawn taħt għal awtentiċità/URL. |

It-tliet fornituri kollha jirrispondu bl-istess ġisem rranġat skont Mistral:

```json
{
  "pages": [{ "index": 0, "markdown": "# Text estratt..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}
```

### Il-Fluss tal-Poll għal Azure Document Intelligence

L-API tal-`analyze` ta' Azure Document Intelligence hija asinkron: ir-rikjest inizjali jirritorna
rider `Operation-Location` minflok ġisem, u r-rizultat irid jiġi pпроlljat. Il-maniger
(`open-sse/handlers/ocr`) jiproja dik l-URL kull sekonda għal massimu ta' 30 attent, jonqos malajr
(jagħmel pollx aktar) meta r-risposta tal-poll mhix `ok` jew meta l-statut ikun `"failed"`, u
jirritorna `504` jekk l-operazzjoni għadha qed issuq wara li l-budget tal-attentx jeħlas.
Ir-risposta finali ta' Azure tiġi normalizzata fl-istess forma `pages`/`markdown` li tintuża
minn Mistral qabel ma tiġi rritornata lill-sejjaħ, għalhekk il-kodiċi tal-klijent m'għandux
jagħmel xi ħaġa speċjali għal dan il-fornitur.

### L-Awtentiċità u r-Riżoluzzjoni tal-Punt għal Vertex AI DeepSeek OCR

`vertex-deepseek-ocr` jerġa' juża l-istess awtentiċità ta' Vertex AI li OmniRoute juża diġà għal
traffiku tal-konversazzjoni/immaġni (`open-sse/executors/vertex.ts`): iċ-ċavetta API tal-konnessjoni
tista' tkun kredenzjali JSON ta' Account tas-Servizz (eskambjata għal token OAuth ta' ħajja qasira permezz
tal-fluss tal-JWT-bearer) jew token OAuth diġà maħruq u jużatha kif hi. L-URL tal-punt ta' fuq
huwa l-punt ġeneriku tal-`openapi/chat/completions` ta' Vertex, mibni mill-proġett u r-reġjun
tal-konnessjoni — valur espliċitu `providerSpecificData.project`/`providerSpecificData.region`
dejjem jirbaħ; inkella l-proġett jingħata mill-`project_id` tal-Kredenzjali JSON tal-Account
tas-Servizz u r-reġjun jin默认 għal `us-central1`. Iż-żewġ riżoluzzjonijiet isiru f
`open-sse/handlers/ocr.ts` (`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`),
u jintwerew minn `src/app/api/v1/ocr/route.ts` qabel ma jitwassal għal `handleOcr`.

---

## Lestiellijiet tal-Mudelli

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

→ Jirritorna l-mudelli kollha tal-chat, embedding, u stampa + kumbinazzjonijiet f'format OpenAI
```

### Prefissi tal-ID tal-Mudell (`?prefix=`)

Il-biċċa l-kbira tal-mudelli huma rreklamati taħt **prefiss tal-fornitur**. Liema prefiss tirċievi huwa kkontrollat minn
il-feature flag `MODELS_CATALOG_PREFIX_MODE`, u jista' jinqabeż **għal kull talba** permezz ta'
parametru tal-mistoqsija — utli għal klijent li jrid lista nadif mingħajr ma jibdel is-settings globali tal-server għal l-oħrajn:

```bash
GET /v1/models?prefix=alias        # ID wieħed għal kull mudell — il-prefiss alias qasir
GET /v1/models?prefix=dual         # iż-żewġ forom (predefinit tal-server)
GET /v1/models?prefix=canonical    # il-prefiss provider-id sħiħ biss
```

| L-Modalità  | Joħroġ                                                  | Noti                                                                                                                                                                                                    |
| ----------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual`      | `cc/claude-sonnet-4-6` **u** `claude/claude-sonnet-4-6` | **Predefinit.** Iż-żewġ IDs jwasslu għall-相同 mudell; żżommhom sabiex il-konfigurazzjonijiet tal-kliets li kien qed jagħtu wieħed minn dawn il-forom ikomplu jaħdmu. T Ittabilax daqs l-katalgu.       |
| `alias`     | `cc/claude-sonnet-4-6`                                  | Entrata waħda għal kull mudell. Il-fornituri li m'għandhomx alias distintu x'aktarx joħorġu l-entrata tagħhom, sabiex xejn titlef.                                                                      |
| `canonical` | `claude/claude-sonnet-4-6`                              | Entrata waħda għal kull mudell taħt il-prefiss provider-id sħiħ. Il-fornituri li m'għandhomx alias distintu (e.g. `antigravity/…`, `agy/…`) joħorġu l-ID wieħed tagħhom hawn ukoll, sabiex xejn titlef. |

Anke mirror tal-`dual`-modalità jista' jingħaraf mingħajr il-parametru tal-mistoqsija: jġorr il-qasam `parent`
li jindika l-ID primarju.

Il-kliets li juru għażla tal-mudell għandhom jitolbu `?prefix=alias` — dan huwa dak li jagħmel
[Estensjoni OmniCopilot għal VS Code](../guides/VSCODE-COPILOT.md).

### Varjanti tal-mudell mingħajr ħsieb

Għal mudelli tal-Claude kapaċi bi ħsieb, `/v1/models` jirreklama ukoll varjanti **mingħajr ħsieb** li l-ID tagħhom huwa b'bord ma' `claude-3-omniroute-no-thinking/`:

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

L-għażla ta' dan l-ID (e.g. f'konfigurazzjoni ta' Claude Code li dejjem tattacha blokka `thinking`) tassigura lura lejn il-`<provider>/<model>` reali bil-konsiderazzjoni fis-sikketta — `thinking:{type:"disabled"` fuq it-triq `/v1/messages`, jew il-qasam `reasoning`/`reasoning_effort` jitneħħa fuq it-triq `/v1/chat/completions`. Il-varjanti huwa mliesta biss għal mudelli tal-familja Claude li jappoġġaw ħsieb **u** jirrispettaw `disabled` (għal e.g. mudelli biss adattivi li jerġgħu jkunu `disabled` huma esklużi). L-operaturi jistgħu iġiegħlu l-varjanti fuq jew off għal kull mudell permezz ta' `ModelSpec.noThinkingAlias`.

## Manifist tal-Plugin tal-Fornitur

```bash
GET /api/v1/provider-plugin-manifest
```

Irritorna l-manifist tal-Plugin tal-Fornitur sigur għall-JSON li jużaw Bifrost, CLIProxyAPI, u routers sidecar futuri. Ir-risposta ġġenerata mir-reġistru tal-fornitur TypeScript u deliberatament teskludi l-isigri tal-klijent OAuth, ir-risoluzzjoni tal-ambjent tax-xogħol, il-funzjonijiet tal-eżekutur, l-intestaturi tal-ħtiġijiet, u d-data tal-kont.

Uża dan il-punt ta' aċċess meta sidecar joper barra mill-proċess u ma jistax jimporta direttament `open-sse/config/providerPluginManifestRegistry.ts`.

---

## Punti ta' Aċċess tal-Kompatibbiltà

| Metodu | Triq                                      | Format                               |
| ------ | ----------------------------------------- | ------------------------------------ |
| POST   | `/v1/chat/completions`                    | OpenAI                               |
| POST   | `/v1/messages`                            | Anthropic                            |
| POST   | `/v1/responses`                           | Risponsi OpenAI                      |
| POST   | `/v1/embeddings`                          | OpenAI                               |
| POST   | `/v1/images/generations`                  | Stampi OpenAI                        |
| POST   | `/v1/images/edits`                        | Stampi OpenAI (edit/inpaint)         |
| POST   | `/v1/videos/generations`                  | Ġenerazzjoni vidjo stil OpenAI       |
| POST   | `/v1/music/generations`                   | Ġenerazzjoni mużika stil OpenAI      |
| POST   | `/v1/audio/transcriptions`                | Awdio OpenAI (STT)                   |
| POST   | `/v1/audio/speech`                        | TTS OpenAI (jirritorna bodi awdjo)   |
| POST   | `/v1/rerank`                              | Rerank stil Cohere/Voyage            |
| POST   | `/v1/classify`                            | Klassifika Jina (`api.jina.ai`)      |
| POST   | `/v1/segment`                             | Segmentatur Jina (`segment.jina.ai`) |
| POST   | `/v1/moderations`                         | Moderazzjonijiet OpenAI              |
| GET    | `/v1/models`                              | OpenAI                               |
| POST   | `/v1/messages/count_tokens`               | Anthropic                            |
| GET    | `/v1beta/models`                          | Gemini                               |
| POST   | `/v1beta/models/{...path}`                | generateContent Gemini               |
| POST   | `/v1/api/chat`                            | Ollama                               |
| GET    | `/api/v1/vscode/{token}/`                 | Alias katalgu OpenAI                 |
| GET    | `/api/v1/vscode/{token}/models`           | Alias mudelli OpenAI                 |
| POST   | `/api/v1/vscode/{token}/chat/completions` | Alias tokenized OpenAI               |
| POST   | `/api/v1/vscode/{token}/responses`        | Alias Risponsi OpenAI tokenized      |
| POST   | `/api/v1/vscode/{token}/api/chat`         | Alias tokenized Ollama               |
| GET    | `/api/v1/vscode/{token}/api/tags`         | Alias tagijiet Ollama tokenized      |

Il-ħatrie kollha POST jsegwu l-istess forma: `Bearer your-api-key` + bodi JSON validat minn Zod (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, eċċ., ara `src/shared/validation/schemas.ts`). 4xx jirritorna meta skema falliet.

Għal klijenti li ma jistgħu jwaħħlu `Authorization: Bearer ...`, OmniRoute jaqbad ukoll ċavetar API fl-URL permezz ta' kompatibbiltà b'query-string (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) jew il-punti ta' aċċess dedikati `/api/v1/vscode/{token}/...` dokumentati hawn taħt.

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

# Klassifika Jina (ċredenzjali Foundation API)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Segmentatur Jina
POST /v1/segment     { "content": "...", "return_chunks": true }

# Tiftixa Jina (s.jina.ai; aliases tal-fornitur: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

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

# TTS — jirritorna bodi audio/mpeg (jew format mitlub)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Edit tal-istampa (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Ġenerazzjoni vidjo / mużika (id mudell b'prefiss tal-fornitur)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }
```

### Ħatrie tal-Fornitur Dedikati

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

Il-prefiss tal-fornitur miżjud awtomatikament jekk nieqas. Mudelli b'disponibbiltà ħażina jirritornaw `400`.

---

## API tal-Fajls

Punt tat-twaħħil tal-fajls kompatibbli ma' OpenAI għal dħul/ħruġ ta' lott u għal għanijiet ta' ttagħbija ta' fajls.

| Metodu | Sinsla                   | Deskrizzjoni                                                                                                        |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/files`              | Tella' fajl (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — massimu ta' 512 MiB |
| GET    | `/v1/files`              | Urif lista tal-fajls għal ċavetta API awtentikata                                                                   |
| GET    | `/v1/files/[id]`         | Ikseb metadata tal-fajl                                                                                             |
| DELETE | `/v1/files/[id]`         | Ħassar fajl                                                                                                         |
| GET    | `/v1/files/[id]/content` | 几次Aħdem streamed tal-korp tal-fajl fil-forma primitive lura                                                       |

**Awtentikazzjoni:** Ċavetta API Bearer — il-fajls huma limitati għal kull ċavetta API permezz ta' `getApiKeyRequestScope`.

---

## API tal-Lottijiet

Proċessar tal-lottijiet kompatibbli ma' OpenAI.

| Metodu | Sinsla                    | Deskrizzjoni                                                                                                    |
| ------ | ------------------------- | --------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/batches`             | Oħloq lott — il-korp jiġi validat minn `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) |
| GET    | `/v1/batches`             | Urif lista tal-lottijiet                                                                                        |
| GET    | `/v1/batches/[id]`        | Ikseb status tal-lott + `request_counts`                                                                        |
| DELETE | `/v1/batches/[id]`        | Ħassar lott terminat/ Falliet                                                                                   |
| POST   | `/v1/batches/[id]/cancel` | Ikkanċella lott li għadu qed isir                                                                               |

**Awtentikazzjoni:** Ċavetta API Bearer. Il-lottijiet huma limitati għal kull ċavetta API.

---

## API tat-Tiftix

Astrazzjoni tal-fornitur tal-web/tiftix (Tavily, Brave, Exa, Serper, eċċ.).

| Metodu | Sinsla                 | Deskrizzjoni                                                                                        |
| ------ | ---------------------- | --------------------------------------------------------------------------------------------------- |
| GET    | `/v1/search`           | Urif il-fornituri tat-tiftix inkonfigurati + il-kapaċitajiet                                        |
| POST   | `/v1/search`           | ejbija kwejri tat-tiftix — il-korp jiġi validat minn `v1SearchSchema`, jappoġġa ċ-ċaching/jitwaħħal |
| GET    | `/v1/search/analytics` | Statistika ta' tħabbat/ latentzza/ ċaching għal kull fornitur                                       |

**Awtentikazzjoni:** Ċavetta API Bearer (`extractApiKey` + `isValidApiKey`). Politika tat-tiftix infurzata permezz ta' `enforceApiKeyPolicy`.

---

## Web Fetch API

Hodu ġabra ta' kontenuti minn URL permezz ta' fornitur web-fetch ikkonfigurat (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

| Metodu | Triq            | Deskrizzjoni                                                  |
| ------ | --------------- | ------------------------------------------------------------- |
| POST   | `/v1/web/fetch` | Ħodu skrejjja URL — il-ġisem vvalidat minn `v1WebFetchSchema` |

**Awtentikazzjoni:** Ċavetta API Bearer (`extractApiKey` + `isValidApiKey`). Politika infurzata permezz ta`enforceApiKeyPolicy`.

**Fallback kkonxju tal-kwota (#8297):** meta ma jingħatax `provider` espliċit, il-pul (`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) jimxi
f'ordni prijorità fiss (l-ewwel mill-bqija) — fornitur limitat ir-rata imma kkunfigurat jitiġbid minfloc jissaffar ir-r界west, u falliment上游 li jerġa jipprova/kwota (HTTP 429 dejjem; 402/403 għal Firecrawl/Tavily/TinyFish kwota-tip ta' tier b'xejn —
mhux għal Jina Reader, u qatt għal talba ħażina 400 sempliċi) jaqa' għall-fornitur kredenzjat li għadu ma tprovaħx meta ssir ir-r界west. Meta kull fornitur fil-pul jiġi eżawrit, il-punt terġa' lura `429` waħda (b'intestatura `Retry-After`)
minfloc il-`400` ġenerika ta' qabel. Meta jingħata `provider` espliċit, m'hemm l-ebda fallback bil-ħeffa — fornitur limitat ir-rata jew li falla jurri l-errori tiegħu stess (`429` jekk limitat ir-rata, inkella l-istatus tal-foreached).

---

## Streaming WebSocket

```bash
GET /v1/ws?handshake=1
```

Jivvalida hand shake WebSocket u jirritorna l-eżempji ta' messaġġi tal-protokol wire (`request`, `cancel`). Frames WS attwali huma mħaddma mis-server WS inklużx barra l-linka tal-roti Next.js.

**Awtentikazzjoni:** Ċavetta API Bearer matul il-handshake.

### Responses API permezz ta WebSocket (codex biss)

```bash
# L-istess host:port bħall-API HTTP (default 20128); ittella' il-konnessjoni:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (jew: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# L-ewwel frame IRID JKUN response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```

Proxu Responses-API-over-WebSocket huwa mwaħħal **esklussivament ma `codex`** (il-backend
ChatGPT). Jisma' fl-istess port bħall-API/dashboared fi triqat `/v1/responses`,
`/responses`, u `/api/v1/responses`. Fuq l-ewwel frame `response.create` jwettaq
awtentikazzjoni + tħejjija permezz tal-pont intern `codex-responses-ws`, jagħżel
konnessjoni codex OAuth, u jgħaddi lejn `wss://chatgpt.com/backend-api/codex/responses`
permezz tal- trasport `wreq-js`. **Mudelli li mhumiex codex jitrefgħu** (`codex_ws_provider_required`).
Għal rotjatura ta' kwota ta' qsim użu `model: "qtSd/<group>/codex/<model>"`. Implimentat f'
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.

**Awtentikazzjoni:** Ċavetta API Bearer matul il-handshake. Is-server HTTP inkluż (`server-ws.mjs`)
iridu jkunu l-punt attiv (hekk huwa, b'mod default, meta `app/server-ws.mjs` jeżisti).

#### ID tal-mudell: użu l-ID ħafna ta ChatGPT (bla prefiss `codex/`)

Il-**Codex CLI** tal-OpenAI jivvalida l-isem tal-mudell fil-klient meta
`supports_websockets = true` u **jirrifjuta ID bil-prefiss tal-fornitur** bħal
`codex/gpt-5.5` (`Il-mudell 'codex/gpt-5.5' mhuwiex appoġġjat meta tuża Codex
b'kont ChatGPT`). Bagħat l-ID **ħafna** (e.g. `gpt-5.5`). Il-pont ta' OmniRoute huwa
biss-codex, għalhekk terġa' tissolva ID ħafna bħala mudell codex
(`resolveCodexWsModelInfo`) qabel tibgħatha fuq il-foreached — anki jekk `gpt-5.5`
ħafna oħra rotterebtbfornitur ieħor permezz HTTP.

#### Kif tikkonfigura l-OpenAI Codex CLI

Indika lill-Codex CLI lejn OmniRoute billi żżid fornitur personalizzat ma' appoġġ
WebSocket f' `~/.codex/config.toml` (użu `CODEX_HOME` separat biex tevita li tmiss
konfigurazzjoni eżistenti):

```toml
model = "gpt-5.5"                 # ID ěafna — MHUX "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # ebda slash tal-aħħar; l-URL WS jiġi dderivat (uża https/wss fil-produzzjoni)
wire_api = "responses"                    # l-uniku valur appoġġjat minn Frar 2026
supports_websockets = true                # jippermetti t-trasport Responses-over-WS
env_key = "OMNIROUTE_API_KEY"             iżomm iċ-ċavetta API OmniRoute (Bearer)
```

```bash
export OMNIROUTE_API_KEY=sk-...           # ċavetta API OmniRoute (kull ċavetta jekk REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```

Il-CLI ittella' `base_url + /responses` għal WebSocket u OmniRoute tgħaddiha
għal-konnessjoni codex OAuth magħżula. Vvalida tmiem għal tmiem kontra s-server lokali: ChatGPT terġa' `codex.rate_limits` + `response.created` u tista mill-kompluzzjoni.

---

## Kwoti u Rapportar ta' Kwistjonijiet

| Metodu | Path                | Deskrizzjoni                                                                                      |
| ------ | ------------------- | ------------------------------------------------------------------------------------------------- |
| GET    | `/v1/quotas/check`  | Ivvalida minn qabel il-kwota għal `provider` + `accountId` qabel ma toħroġ ċavetta rreġistrata    |
| POST   | `/v1/issues/report` | Irrapporta falliment ta' kwota/ħruġ ta' ċavetta lil GitHub (jeħtieġ `GITHUB_ISSUES_REPO` + token) |

**Awtorizzazzjoni:** Ċavetta API Bearer (`isAuthenticated`).

---

## Użu self-service (`/api/usage/om-usage`)

Kwalunkwe ċavetta API tista' taqra **l-użu tagħha stess** u l-kwoti — l-ebda awtorizzazzjoni ta' ġestjoni. Dan huwa l-endpoint li
klijent (CLI, il-panel OmniCopilot) juża biex juri lil min għandu ċ-ċavetta l-infiq tiegħu.

```bash
# Forma ta' test (il-kuntratt storiku — test sempliċi għal terminal)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Forma strutturata — dak li jikkonsma UI
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"
```

Iċ-ċavetta trid ikollha **`allowUsageCommand`** attivat (mitfija b'mod awtomatiku — il-maniġer tal-ċwievet API tad-dashboard
jibdilha għal kull ċavetta). Mingħajrha l-endpoint iwieġeb `403`.

`?format=json` jirritorna forma diskriminata sabiex min jsejjaħ qatt ma jaqra qasam ta' dejta minn
rifjut. Fuq suċċess:

```jsonc
{
  "allowed": true,
  // preżenti biss meta ċ-ċavetta għażlet limiti ta' użu għal kull ċavetta (USD ta' kuljum/ġimgħa):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // il-ħarsa tal-kwota tal-provider magħżul, jew null meta għadu ma hemmx cache:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // il-ħarsa ta' kull konnessjoni, sabiex UI tkun tista' turi diversi providers ħdejn xulxin:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}
```

Fuq rifjut (`401` ċavetta ħażina / `403` mhux permess) l-istess rotta tirritorna
`{ "allowed": false, "error": { "message": "…" } }` — `personal`/`provider` preżenti iżda vojta
(ċavetta permessa, għadha ma tgħallmet xejn) hija stat differenti minn rifjut, u biss il-forma JSON
tiddistingwihom.

**Awtorizzazzjoni:** iċ-ċavetta API Bearer tal-min jsejjaħ, ivvalidata b'`isValidApiKey` — din _mhijiex_ il-wiċċ ta'
ġestjoni (`/api/keys/…`), li tibqa' wara `requireManagementAuth`.

---

## Cache Semantiku

```bash
# Ikseb l-istatistika tal-cache
GET /api/cache/stats

# Ħassar il-caches kollha
DELETE /api/cache/stats
```

Eżempju ta' rispons:

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

### Impatt fuq il-latenza

HIT tal-cache semantiku jservi r-rispons mill-cache **mingħajr sejħa
upstream**, għalhekk il-`X-OmniRoute-Response-Latency` rrappurtata hija kważi żero
(irrispettivament mil-latenza upstream oriġinali). Klijenti sensittivi għal-latenza
(benchmarking, monitoraġġ p50/p99) għandhom jiċċekkjaw l-header tar-rispons
`X-OmniRoute-Cache-Latency`:

| Valur       | Tifsira                                                          |
| ----------- | ---------------------------------------------------------------- |
| `synthetic` | Rispons servut mill-cache; il-latenza mhijiex ħin upstream reali |
| _(assenti)_ | Rispons minn sejħa upstream reali                                |

### Bypass tal-cache għal kull ċavetta

Il-ċwievet API jistgħu jagħżlu li ma jaqrawx il-cache semantiku permezz ta' `cacheDefaultMode`:

| Valur    | Imġiba                                                        |
| -------- | ------------------------------------------------------------- |
| `legacy` | Imġiba normali tal-cache (default)                            |
| `bypass` | Aqbeż il-lookup tal-cache kompletament; dejjem laqat upstream |

Issettjat fil-ħolqien taċ-ċavetta (`POST /api/keys`) jew fl-aġġornament (`PATCH /api/keys/[id]`):

```json
{ "cacheDefaultMode": "bypass" }
```

### Bypass għal kull talba

Kwalunkwe talba tista' taqbeż il-cache irrispettivament mis-settings taċ-ċavetta:

```
X-OmniRoute-No-Cache: true
```

---

## Dashboard u Ġestjoni

Ir-rotti ta' ġestjoni (`/api/*` ħlief auth/login pubbliku) **mhumiex** awtorizzati minn
ċwievet API ta' inferenza ordinarji. Familji ta' kredenzjali, ambitu, u eżempji ta' curl:
[Awtorizzazzjoni ta' Ġestjoni](../guides/MANAGEMENT-AUTH.md).

### Awtorizzazzjoni

| Endpoint                      | Metodu  | Deskrizzjoni         |
| ----------------------------- | ------- | -------------------- |
| `/api/auth/login`             | POST    | Login                |
| `/api/auth/logout`            | POST    | Logout               |
| `/api/settings/require-login` | GET/PUT | Toggle login meħtieġ |

### Ġestjoni tal-Providers

| Endpoint                     | Metodu                | Deskrizzjoni                                                                                                                     |
| ---------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `/api/providers`             | GET/POST              | Lista / toħloq providers                                                                                                         |
| `/api/providers/[id]`        | GET/PUT/DELETE        | Immaniġġja provider                                                                                                              |
| `/api/providers/[id]/test`   | POST                  | Ittestja konnessjoni tal-provider                                                                                                |
| `/api/providers/[id]/models` | GET                   | Lista mudelli tal-provider                                                                                                       |
| `/api/providers/validate`    | POST                  | Ivvalida konfigurazzjoni tal-provider                                                                                            |
| `/api/providers/bulk`        | POST                  | Żid bil-massa ċwievet API għal provider WIEĦED                                                                                   |
| `/api/providers/import`      | POST                  | Importa lista ta' providers eteroġenji minn fajl CSV/JSON analizzat (#6836); riżultati ta' falliment parzjali għal kull ringiela |
| `/api/provider-nodes*`       | Varji                 | Ġestjoni tan-nodi tal-provider                                                                                                   |
| `/api/provider-models`       | GET/POST/PATCH/DELETE | Mudelli personalizzati (żid, aġġorna, aħbi/uri, ħassar)                                                                          |

### Flussi OAuth

| Endpoint                         | Metodu | Deskrizzjoni                   |
| -------------------------------- | ------ | ------------------------------ |
| `/api/oauth/[provider]/[action]` | Varji  | OAuth speċifiku għall-provider |

### Routing u Konfigurazzjoni

| Endpoint              | Metodu   | Deskrizzjoni                           |
| --------------------- | -------- | -------------------------------------- |
| `/api/models/alias`   | GET/POST | Alias tal-mudelli                      |
| `/api/models/catalog` | GET      | Il-mudelli kollha skont provider + tip |
| `/api/combos*`        | Varji    | Ġestjoni tal-combos                    |
| `/api/keys*`          | Varji    | Ġestjoni taċ-ċwievet API               |
| `/api/pricing`        | GET      | Ipprezzar tal-mudelli                  |

### Użu u Analitiċi

| Endpoint                         | Metodu          | Deskrizzjoni                                                                                                                                                                                                                                                                                                                                             |
| -------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history`             | GET             | Storja tal-użu                                                                                                                                                                                                                                                                                                                                           |
| `/api/usage/logs`                | GET             | Logs tal-użu                                                                                                                                                                                                                                                                                                                                             |
| `/api/usage/request-logs`        | GET             | Logs fil-livell ta' talbiet                                                                                                                                                                                                                                                                                                                              |
| `/api/usage/[connectionId]`      | GET             | Użu għal kull konnessjoni                                                                                                                                                                                                                                                                                                                                |
| `/api/usage/token-limits`        | GET/POST/DELETE | Baġits ta' limiti ta' tokens għal kull ċavetta API                                                                                                                                                                                                                                                                                                       |
| `/api/usage/model-latency-stats` | GET             | Aggregat ta' latenza li jdur għal kull provider/mudell (avg/p50/p95/p99, rata ta' suċċess); filtri: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873)                                                                                                                                                                                      |
| `/api/usage/cache-health`        | GET             | Sommarju tas-saħħa tal-cache tal-prompt fuq `call_logs` — proporzjon ta' kitba/qari, distribuzzjoni tad-daqs tal-kitba p50/p90/p99, konċentrazzjoni ta' kitba tqila, qasma għal kull mudell, u verdett `healthy`/`degraded`/`thrash`/`no-data`; parametri tal-mistoqsija `range` (`1h`\|`24h`\|`7d`\|`30d`, default `24h`) u `model` fakultattiv (#8827) |

### Settings

| Endpoint                              | Metodu        | Deskrizzjoni                                                                                                                                                                                              |
| ------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings`                       | GET/PUT/PATCH | Settings ġenerali                                                                                                                                                                                         |
| `/api/settings/proxy`                 | GET/PUT       | Konfigurazzjoni tal-proxy tan-netwerk                                                                                                                                                                     |
| `/api/settings/proxy/test`            | POST          | Ittestja konnessjoni tal-proxy                                                                                                                                                                            |
| `/api/settings/ip-filter`             | GET/PUT       | Allowlist/blocklist tal-IP                                                                                                                                                                                |
| `/api/settings/thinking-budget`       | GET/PUT       | Modalità ta' kitba mill-ġdid ta' **talbiet** ta' ħsieb/raġunament (passthrough / auto-strip / custom / adaptive). Indipendenti mill-kompressjoni. Ara [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). |
| `/api/settings/system-prompt`         | GET/PUT       | Prompt tas-sistema globali                                                                                                                                                                                |
| `/api/settings/compression`           | GET/PUT       | Konfigurazzjoni tal-kompressjoni globali                                                                                                                                                                  |
| `/api/settings/purge-request-history` | POST          | Ċara ringieli tal-log tat-talbiet u artifatti lokali tal-log tas-sejħiet                                                                                                                                  |

### Kuntest u Kompressjoni

| Endpoint                               | Metodu         | Deskrizzjoni                                                                                   |
| -------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------- |
| `/api/compression/preview`             | POST           | Preview tal-kompressjoni off/lite/standard/aggressive/ultra/RTK/stacked                        |
| `/api/compression/language-packs`      | GET            | Lista pakketti tal-lingwa Caveman disponibbli                                                  |
| `/api/compression/rules`               | GET            | Lista metadata tar-regoli Caveman                                                              |
| `/api/context/caveman/config`          | GET/PUT        | Alias tas-settings speċifiċi għal Caveman                                                      |
| `/api/context/rtk/config`              | GET/PUT        | Settings speċifiċi għal RTK, inklużi filtri personalizzati u żamma ta' output mhux ipproċessat |
| `/api/context/rtk/filters`             | GET            | Katalgu tal-filtri RTK u dijanjostiċi tal-filtri personalizzati                                |
| `/api/context/rtk/test`                | POST           | Mexxi preview/test RTK kontra payload ta' test                                                 |
| `/api/context/rtk/raw-output/[id]`     | GET            | Aqra output mhux ipproċessat redatt miżmum bl-id tal-pointer                                   |
| `/api/context/combos`                  | GET/POST       | Lista/toħloq combos tal-kompressjoni                                                           |
| `/api/context/combos/[id]`             | GET/PUT/DELETE | Dettalji/aġġornament/tħassir tal-combo tal-kompressjoni                                        |
| `/api/context/combos/[id]/assignments` | GET/PUT        | Assenja combos tal-kompressjoni lil combos tar-routing                                         |
| `/api/context/analytics`               | GET            | Alias tal-analitiċi tal-kompressjoni                                                           |

### Monitoraġġ

| Endpoint                             | Metodu     | Deskrizzjoni                                                                                                                                                                                                                         |
| ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/sessions`                      | GET        | Traċċar ta' sessjonijiet attivi                                                                                                                                                                                                      |
| `/api/rate-limits`                   | GET        | Limiti tar-rata għal kull kont                                                                                                                                                                                                       |
| `/api/monitoring/health`             | GET        | Kontroll tas-saħħa + sommarju tal-provider (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`)                                                                                                                      |
| `/api/cache/stats`                   | GET/DELETE | Stats tal-cache / ċar                                                                                                                                                                                                                |
| `/api/modality-bridge/stats`         | GET        | Fil-memorja `attempts`, suċċessi/`bridged`, fallimenti, hits tal-cache, `totalLatencyMs`, `latencySamples`, `averageLatencyMs` denominat mill-kampjuni, u ħin tal-aħħar użu (reset mal-bidu mill-ġdid; awtorizzazzjoni ta' ġestjoni) |
| `/api/modality-bridge/video/runtime` | GET        | Kontroll strett ta' trusted-loopback qabel awtorizzazzjoni/probe ta' ġestjoni; disponibbiltà u verżjonijiet sanitizzati ta' FFmpeg/ffprobe (no-store)                                                                                |
| `/api/modality-bridge/video/extract` | POST       | Broker ta' bytes trusted-loopback awtentikat intern; input ta' 50 MiB, kju b'limitu/output ta' 32 MiB, `503` kapaċità, `499` skonnessjoni, `504` skadenza; mhux API pubblika ta' upload                                              |

### Backup u Esportazzjoni/Importazzjoni

| Endpoint                    | Metodu | Deskrizzjoni                                         |
| --------------------------- | ------ | ---------------------------------------------------- |
| `/api/db-backups`           | GET    | Lista backups disponibbli                            |
| `/api/db-backups`           | PUT    | Oħloq backup manwali                                 |
| `/api/db-backups`           | POST   | Irrestawra minn backup speċifiku                     |
| `/api/db-backups/export`    | GET    | Niżżel database bħala fajl .sqlite                   |
| `/api/db-backups/import`    | POST   | Ittella' fajl .sqlite biex tissostitwixxi d-database |
| `/api/db-backups/exportAll` | GET    | Niżżel backup sħiħ bħala arkivju .tar.gz             |

### Sinkronizzazzjoni tal-Cloud

| Endpoint               | Metodu | Deskrizzjoni                                    |
| ---------------------- | ------ | ----------------------------------------------- |
| `/api/sync/cloud`      | Varji  | Operazzjonijiet ta' sinkronizzazzjoni tal-cloud |
| `/api/sync/initialize` | POST   | Inizjalizza sinkronizzazzjoni                   |
| `/api/cloud/*`         | Varji  | Ġestjoni tal-cloud                              |

### Mini (Tunnels)

| Endpoint                   | Metodu | Deskrizzjoni                                                                                  |
| -------------------------- | ------ | --------------------------------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET    | Aqra status ta' installazzjoni/ħin ta' eżekuzzjoni tal-Cloudflare Quick Tunnel għad-dashboard |
| `/api/tunnels/cloudflared` | POST   | Attiva jew iddiżattiva l-Cloudflare Quick Tunnel (`action=enable/disable`)                    |
| `/api/tunnels/ngrok`       | GET    | Aqra status ta' ħin ta' eżekuzzjoni tal-ngrok Tunnel għad-dashboard                           |
| `/api/tunnels/ngrok`       | POST   | Attiva jew iddiżattiva l-ngrok Tunnel (`action=enable/disable`)                               |

### Għodod CLI

| Endpoint                           | Metodu | Deskrizzjoni                     |
| ---------------------------------- | ------ | -------------------------------- |
| `/api/cli-tools/claude-settings`   | GET    | Status tal-Claude CLI            |
| `/api/cli-tools/codex-settings`    | GET    | Status tal-Codex CLI             |
| `/api/cli-tools/droid-settings`    | GET    | Status tal-Droid CLI             |
| `/api/cli-tools/openclaw-settings` | GET    | Status tal-OpenClaw CLI          |
| `/api/cli-tools/runtime/[toolId]`  | GET    | Ħin ta' eżekuzzjoni CLI ġeneriku |

Ir-risposti tal-CLI jinkludu: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.

### Aġenti ACP

| Endpoint          | Metodu | Deskrizzjoni                                                           |
| ----------------- | ------ | ---------------------------------------------------------------------- |
| `/api/acp/agents` | GET    | Lista l-aġenti kollha skoperti (integrati + personalizzati) bl-istatus |
| `/api/acp/agents` | POST   | Żid aġent personalizzat jew aġġorna l-cache ta' skoperta               |
| `/api/acp/agents` | DELETE | Neħħi aġent personalizzat bil-parametru tal-mistoqsija `id`            |

Ir-risposta GET tinkludi `agents[]` (id, isem, binarju, verżjoni, installat, protokoll, isCustom) u `summary` (total, installat, notFound, builtIn, custom).

### Reżiljenza u Limiti tar-Rata

| Endpoint                          | Metodu    | Deskrizzjoni                                                                                           |
| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------ |
| `/api/resilience`                 | GET/PATCH | Ikseb/aġġorna kju ta' talbiet, cooldown tal-konnessjoni, breaker tal-provider, u settings ta' stennija |
| `/api/resilience/reset`           | POST      | Irrisettja circuit breakers tal-provider                                                               |
| `/api/resilience/model-cooldowns` | GET       | Lista lockouts attivi għal kull (provider, konnessjoni, mudell), issortjati bil-ħin li jifdal          |
| `/api/resilience/model-cooldowns` | DELETE    | Ċara lockout ta' mudell — body `{provider, model}` jew `{all: true}` biex tħassar kollox               |
| `/api/rate-limits`                | GET       | Status tal-limiti tar-rata għal kull kont                                                              |
| `/api/rate-limit`                 | GET       | Konfigurazzjoni globali tal-limitu tar-rata                                                            |

> Ir-rotti kollha `/api/resilience/*` jeħtieġu **awtorizzazzjoni ta' ġestjoni** (`requireManagementAuth`). Ara [Reżiljenza (estensjoni)](#resilience-extended) għal tqassim sħiħ ta' breaker tal-provider vs cooldown tal-konnessjoni vs lockout tal-mudell.

### Evals

| Endpoint     | Metodu   | Deskrizzjoni                                |
| ------------ | -------- | ------------------------------------------- |
| `/api/evals` | GET/POST | Lista suites tal-evals / mexxi evalwazzjoni |

### Policies

| Endpoint        | Metodu          | Deskrizzjoni                    |
| --------------- | --------------- | ------------------------------- |
| `/api/policies` | GET/POST/DELETE | Immaniġġja policies tar-routing |

### Konformità

| Endpoint                    | Metodu | Deskrizzjoni                                |
| --------------------------- | ------ | ------------------------------------------- |
| `/api/compliance/audit-log` | GET    | Log tal-awditjar tal-konformità (l-aħħar N) |

### v1beta (Kompatibbli mal-Gemini)

| Endpoint                   | Metodu | Deskrizzjoni                      |
| -------------------------- | ------ | --------------------------------- |
| `/v1beta/models`           | GET    | Lista mudelli fil-format Gemini   |
| `/v1beta/models/{...path}` | POST   | Endpoint Gemini `generateContent` |

Dawn l-endpoints jirriflettu l-format tal-API ta' Gemini għal klijenti li jistennew kompatibbiltà nattiva mal-SDK tal-Gemini.

### APIs Interni / tas-Sistema

| Endpoint                 | Metodu | Deskrizzjoni                                                         |
| ------------------------ | ------ | -------------------------------------------------------------------- |
| `/api/init`              | GET    | Kontroll ta' inizjalizzazzjoni tal-applikazzjoni (użat fl-ewwel ħin) |
| `/api/tags`              | GET    | Tags tal-mudelli kompatibbli mal-Ollama (għal klijenti Ollama)       |
| `/api/restart`           | POST   | Attiva restart grazzjuż tas-server                                   |
| `/api/shutdown`          | POST   | Attiva għeluq grazzjuż tas-server                                    |
| `/api/system/env/repair` | POST   | Tiswija ta' varjabbli tal-ambjent OAuth tal-provider                 |

> **Nota:** Dawn l-endpoints jintużaw internament mis-sistema jew għal kompatibbiltà mal-klijenti Ollama. Normalment ma jintsejħux mill-utenti finali.

### Tiswija tal-Ambjent OAuth _(v3.6.1+)_

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

{
  "provider": "claude-code"
}
```

Tissewwa varjabbli tal-ambjent OAuth nieqsa jew korrotti għal provider speċifiku. Tirritorna:

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

---

## Traskrizzjoni tal-Awdjo

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

Traskrivi fajls awdjo bl-użu ta' kwalunkwe fornitur STT ikkonfigurat. L-ewwel segment tal-pass jiġbed il-furnitur nattiv (`openai/…`, `deepgram/…`). Il-portal li jerġa' jistenna mudell ta' fornitur ieħor juża' ID kwalifikat
(`openrouter/deepgram/nova-3`).

**Talba:**

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

**Rispons:**

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

**Eżempji ta' ID tal-mudell:** `openai/whisper-1` (jirrikjedi chiave OpenAI),
`openrouter/deepgram/nova-3` (jirrikjedi chiave OpenRouter),
`deepgram/nova-3` (jirrikjedi chiave Deepgram nattiva). Talba ċċara
`deepgram/nova-3` **ma tużax** OpenRouter.

**Formati appoġġjati:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.

---

## Kompatibilità Ollama

Għal klijenti li jużaw il-format API tal-Ollama:

```bash
# Pont tat-Tkellim (format Ollama)
POST /v1/api/chat

# Lesti tal-Mudelli (format Ollama)
GET /api/tags
```

It-talbiet jittradawwlew awtomatikament bejn il-formati tal-Ollama u interni.

## Alias Tokenizzati VS Code / Bla Tieni Raxx

Uża dawn l-alias meta integrazzjoni ma tistax tinject header `Authorization` u teħtieġ il-chiave tal-API inkorporata fil-URL bażi.

```bash
# Alias tal-Katalgu stili OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Alias tat-Tkellim stili OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Alias stili Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```

Eżempju:

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

Noti:

- L-alias tokenizzati jerġgħu jużaw l-istess handlers bħal `/v1/*` u `/api/tags`; ix-xhur tal-rispons jibqgħu identiċi.
- Agħżel `Authorization: Bearer ...` meta l-klijent jappoġġja custom headers.
- Ix-xhur tal-URL jistgħu jidhru fil-logħob tal-proxi magħluf, fl-istorja tal-browser, u fit-telemetrija barra OmniRoute. Trattahom bħala għażla ta' kompatibilità, mhux il-modalità ta' awtentikazzjoni predefinita.

---

## Telemetrija

```bash
# Ħu sommarju tal-telemetrija tal-kurrent (p50/p95/p99 għal kull fornitur)
GET /api/telemetry/summary
```

**Rispons:**

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

---

## Baġit

```bash
# Ħu l-istat tal-baġit għal dawk il-ħafna chiavi tal-API
GET /api/usage/budget

# Joqgħod jew aġġorna baġit
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"
}
```

> **Noti tal-Iskema** (`setBudgetSchema`): `apiKeyId` huwa meħtieġ; mill-inqas waħda minn `dailyLimitUsd`, `weeklyLimitUsd`, jew `monthlyLimitUsd` għandha tkun akbar minn żero. Oħroġ: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). L-isforza ta' qabel `{keyId, limit, period}` tirritorna `400 Talba Ħażina`.

## Limiti ta' Token

Figoli tal-baġit għal **token** għal kull API-key (differenti mill-Baġit bbażat fuq USD hawn fuq). Imponut dirett fil-via tat-talba: meta l-użu tal-finiema attwali ta' ċavetta jilħaq il-limitu tiegħu, it-talbiet jiġu refiżi b'`429 Too Many Requests`. Il-limiti jistgħu jiġu skopati għal `model` partikolari, `provider`, jew applikati `global`ment madwar iċ-ċavetta; meta diversi limiti jikkorrispondu ma' talba, dak l-aktar restrittiv jirbaħ.

```bash
# Tfisser il-limiti ta' token ta' ċavetta (jinkludu l-użu attwali tal-finiema)
GET /api/usage/token-limits?apiKeyId=key-123

# Joħloq jew jġedded limit ta' token
POST /api/usage/token-limits
Content-Type: application/json

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

# Jħassar limit ta' token permezz ta' id
DELETE /api/usage/token-limits?id=tl-abc
```

> **Noti ta' l-i schema** (`setTokenLimitSchema`): `apiKeyId` u `scopeType` (`model` | `provider` | `global`) huma meħtieġa. `scopeValue` huwa meħtieġ sakemm `scopeType` mhuwiex `global` (pereżempju ID ta' model għal skop ta' `model`, ID ta' provider għal skop ta' `provider`). `tokenLimit` għandu jkun numru pożittiv (imħawwad minn stringa). Opzjonali: `id` (neħħih biex toħloq, ipprovdih biex taġġorna), `resetInterval` (`daily` | `weekly` | `monthly`, default `monthly`), `resetTime` (`HH:MM`), `enabled` (default `true`). Risposti `GET` jirranġaw kull limit b'`tokensUsed`, `remaining`, `windowStart`, `periodStartAt`, u `nextResetAt`. Dan huwa punt tat-tmiem tal-klassi tal-ġestjoni (awtentikazzjoni infurzata ċentralment mill-pipeline tal-awtorizzazzjoni).

## It-Trattament tat-Talbiet

1. Il-klijent jibgħat talba għal `/v1/*`
2. Il-maniġer tar-rotta jsejjaħ `handleChat`, `handleEmbedding`, `handleAudioTranscription`, jew `handleImageGeneration`
3. Il-mudell jiġi solvut (provider/mudell dirett jew alias/kombinazzjoni)
4. L-iskunzjonijiet jintgħażlu mill-DB lokali b'filtru ta' disponibbiltà tal-kont
5. Għal chat: `handleChatCore` jivverifika l-cache semantika/firma u jsolvi l-issettjar tal-kompressjoni tal-kombinazzjoni
6. Kompressjoni proattiva taħdem qabel it-traduzzjoni tal-provider meta tkun attiva (`lite`, Caveman, RTK, jew impiljata)
7. L-eżekutur tal-provider jibgħat talba 'l fuq
8. Ir-risposta tiġi tradotta lura lejn il-format tal-klijent (chat) jew terġa' kif inhi (embeddings/immaġni/awdjo)
9. L-użu, l-analiżi tal-kompressjoni, u t-talbiet tal-logaritmu jinnotaw
10. Riżervat japplika fuq l-għanijiet skond ir-regoli tal-kombinazzjoni

Riferenza sħiha tal-arkitettura: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)

---

## Ġestjoni tal-Kombinazzjonijiet

Kombinazzjonijiet tar-rotta ta' livell ogħla (diġà sommarizzati taħt `/api/combos*`) jistgħu wkoll jimmappjaw 1:1 minn mudell ID pattern, li jippermetti rdirezzjoni trasparenti ta' mudell ID ta' stili OpenAI lejn kombinazzjoni.

| Metodu | Pass                             | Deskrizzjoni                                                                   |
| ------ | -------------------------------- | ------------------------------------------------------------------------------ |
| GET    | `/api/model-combo-mappings`      | Tfisser il-mappings kollha ta' mudell→kombinazzjoni                            |
| POST   | `/api/model-combo-mappings`      | Joħloq mapping — body: `{pattern, comboId, priority?, enabled?, description?}` |
| GET    | `/api/model-combo-mappings/[id]` | Jikseb mapping wieħed                                                          |
| PUT    | `/api/model-combo-mappings/[id]` | Jagġorna oqsma ta' mapping eżistenti                                           |
| DELETE | `/api/model-combo-mappings/[id]` | Neħħi mapping                                                                  |

**Awtentikazzjoni:** Sessjoni tal-ġestjoni/API key (`requireManagementAuth`).

## Webhooks

Abbonamenti tal-webhooks li ħierjin għal avvenimenti tal-OmniRoute (tlestija tal-ħtiġijiet, għebien tal-kwota, rotazzjonal tal-ħdd, eċċ.).

| Metodu | Triq                      | Deskrizzjoni                                                                   |
| ------ | ------------------------- | ------------------------------------------------------------------------------ |
| GET    | `/api/webhooks`           | Turi l-webhooks (is-sigrietti huma maskrati bħala `<prefix>...`)               |
| POST   | `/api/webhooks`           | Oħloq webhook — ġisem: `{url, events?: ["*"], secret?, description?}`          |
| GET    | `/api/webhooks/[id]`      | Retrieva webhook                                                               |
| PUT    | `/api/webhooks/[id]`      | Ġdid id/events/secret/description                                              |
| DELETE | `/api/webhooks/[id]`      | Neħħi webhook                                                                  |
| POST   | `/api/webhooks/[id]/test` | Ibqa' piż prova lejn l-URL tal-webhook u irreġistra l-kundizzjoni tal-konsenja |

**Awti:** Sessjoni tal-ġestjoni / API key (`requireManagementAuth`).

---

## Reġistrati Ħdd (Ġestjoni Awtomatika)

Użat mis-sottosustem għall-ġestjoni awtomatika tal-ħdd biex joħroġ u jdur API keys kontra fornitur/kont ta' appoġġ, bi kwota ta' kuljum/siegħa.

| Metodu | Triq                                  | Deskrizzjoni                                                                                                                                                                                                |
| ------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/registered-keys`             | Turi l-ħdd reġistrati (prefiss maskrat biss)                                                                                                                                                                |
| POST   | `/api/v1/registered-keys`             | Ħruġ ħdd reġistrat ġdid — ġisem: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Irreġistra l-ħdd ġdid **darba**. Irreġistra `429` meta tiġi rrifjutata l-kwota. |
| GET    | `/api/v1/registered-keys/[id]`        | Retrieva metadati ta' ħdd reġistrat (ebda materjal iRaw)                                                                                                                                                    |
| DELETE | `/api/v1/registered-keys/[id]`        | Illimita ħdd reġistrat                                                                                                                                                                                      |
| POST   | `/api/v1/registered-keys/[id]/revoke` | Punt ta' limitazzjoni espliċita (l-istess effett bħal DELETE)                                                                                                                                               |

**Awti:** Bearer API key (`isAuthenticated`). Ara wkoll `/v1/quotas/check` u `/v1/issues/report`.

---

## Protokoll tal-Aġenti

Direzzjonijiet għax-xogħol tal-Aġenti tal-Cloud (Claude Code, Codex Cloud, OpenHands, eċċ.) ejekutati mill-bogħod f'isem l-utenti tal-OmniRoute.

| Metodu | Triq                          | Deskrizzjoni                                                                                                                                           |
| ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/v1/agents/tasks`        | Sejjaħ il-lista tax-xogħlijiet — `?provider=`, `?status=`, `?limit=` (1–500, default 50) għażliet                                                      |
| POST   | `/api/v1/agents/tasks`        | ħloq xogħol — il-ġisem validat minn `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Jirritorna `201` ma' benni tax-xogħol |
| DELETE | `/api/v1/agents/tasks?id=...` | ħassar xogħol                                                                                                                                          |
| GET    | `/api/v1/agents/tasks/[id]`   | Qara xogħol — isaħħaħ l-istat b'mod sinċroni mill-Aġent tal-Cloud meta `external_id` huwa maħluq                                                       |
| POST   | `/api/v1/agents/tasks/[id]`   | Azzjoni diskriminata: `{action: "approve"}`, `{action: "message", message}`, jew `{action: "cancel"}`                                                  |
| DELETE | `/api/v1/agents/tasks/[id]`   | ħassar xogħol speċifiku b'id                                                                                                                           |

> **Awtentikazzjoni:** jeħtieġ awtentikazzjoni tal-ġestjoni fuq kull metodu (`requireCloudAgentManagementImmuni`). Qabel v3.8.0 dawn kienu bla awtentikazzjoni — ara l-impust `588a0333` għal il-bidla li tkisser kompatibilità.

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

---

## Proxies tal-Ġestjoni

Proxies tal-outbound HTTP(S)/SOCKS li jistgħu jiġu assenjati lill-fornituri, lill-kontijiet, jew globalment.

| Metodu | Triq                                         | Deskrizzjoni                                                                                                                                                      |
| ------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/management/proxies`                 | Sejjaħ il-lista tal-proxies (b'`?id=` jirritorna wieħed; b'`?id=&where_used=1` jirritorna l-graf tal-assenjazzjoni)                                               |
| POST   | `/api/v1/management/proxies`                 | ħloq proxy — il-ġisem validat minn `createProxyRegistrySchema`                                                                                                    |
| PATCH  | `/api/v1/management/proxies`                 | Aġġorna proxy — il-ġisem validat minn `updateProxyRegistrySchema` (jeħtieġ `id`)                                                                                  |
| DELETE | `/api/v1/management/proxies?id=...&force=1`  | ħassar proxy (uża `force=1` biex tiddetaxxi l-assenjazzjonijiet)                                                                                                  |
| GET    | `/api/v1/management/proxies/assignments`     | Sejjaħ l-assenjazzjonijiet — tista' tfiltrahom b'`proxy_id`, `scope`, `scope_id`; għaddi `resolve_connection_id=<id>` biex issolvi l-proxy attiv għal konnissjoni |
| PUT    | `/api/v1management/proxies/assignments`      | Assenja — il-ġisem validat minn `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Jnaddaf il-cache tal-dispatcher                                          |
| PUT    | `/api/v1/management/proxies/bulk-assign`     | Assenja bi volum — il-ġisem validat minn `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`)                                                            |
| GET    | `/api/v1/management/proxies/health?hours=24` | Aggregat il-kondizzjoni tas-saħħa tal-proxy (kontijiet ta' suċċess/falliment, latentija) f'finestra ta' ħin                                                       |

**Awtentikazzjoni:** sessjoni/API key tal-ġestjoni fuq kull rotta (`requireManagementAuth`).

> L-deskrizzjoni tax-xogħol `POST /api/v1/management/proxies/[id]/assignments` u `POST /api/v1/management/proxies/[id]/health` huma mheddija mir-rotta ċatta `/assignments` u `/health` murija hawn fuq — mhemm l-ebda rotta taħt id fil-bażi tal-kodiċi.

## Reżiljenza (estiża)

OmniRoute jur昕 xi ħaġa ta' falliment temporanju indipendenti; il-punti tal-immaniġġar t'hawn taħt jippermettu lill-operaturi jrawwlu u jirraddjhom:

| Ambitu                  | Ħażna tal-istat                                      | Qari                                      | Tindif / ħasil                              |
| ----------------------- | ---------------------------------------------------- | ----------------------------------------- | ------------------------------------------- |
| Provider breaker        | `domain_circuit_breakers` + fil-memorja              | `/api/monitoring/`                        | `POST /api/resilience/reset`                |
| Tnemmis tal-konnessjoni | `rateLimitedUntil` fil-konnessjonijiet tal-providers | `/api/rate-limits`, `/api/providers/[id]` | (jimbamm hekk kif; tindif via provider PUT) |
| Tinsib tal-mudell       | Reġistru tal-disponibbiltà tal-mudell fil-memorja    | `GET /api/resilience/model-cooldowns`     | `DELETE /api/resilience/model-cooldowns`    |

`PATCH /api/resilience` jikseb l-iradd ta' l-interruttur tal-provider taħt `providerBreaker.oauth` u `providerBreaker.apikey`. Kull profil jappoġġa `degradationThreshold`, `failureThreshold`, u `resetTimeoutMs`; l-istess oqsma huma esposti fil-Settings → Resilience.

```bash
# Ħassar Blokko Uniku tal-Mudell
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"}'

# Ħassar il-Blokki Kollha
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'
```

Referenza ġenerika u defaults tal-interruttur: ara [`CLAUDE.md`](../../CLAUDE.md) → "Reżiljenza Stat Runtime".

---

## Ħiliet

Qafas ta' ħiliet għat-tiswir ta' OmniRoute b'maniġġari eżegwibbli personalizzati, flimkien mal-integrazzjonijiet tal-marketplace.

| Metodu | Triq                              | Deskrizzjoni                                                                                                                        |
| ------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`                     | Lit lill-ħiliet installati — tista' tittella' b'`?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, bil-paginazzjoni |
| GET    | `/api/skills/[id]`                | Ħaġar ħila waħda                                                                                                                    |
| PUT    | `/api/skills/[id]`                | Ġdid ħila (ism, deskrizzjoni, mod, schema, maniġġar, tags)                                                                          |
| DELETE | `/api/skills/[id]`                | Neħħi ħila                                                                                                                          |
| POST   | `/api/skills/install`             | Installa ħila minn manifest moħġor — ġisem: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}`          |
| GET    | `/api/skills/executions`          | Lit eżekuzzjonijiet riċenti tal-ħiliet (traċċa tal-awdit bl-inputs/outputs/durata)                                                  |
| GET    | `/api/skills/marketplace?q=...`   | Fittex/roster popolari mill-marketplace tal-SkillsMP (jħtieġa settings `skillsmpApiKey`)                                            |
| POST   | `/api/skills/marketplace/install` | Installa ħila b'ID mill-SkillsMP                                                                                                    |
| GET    | `/api/skills/skillssh?q=&limit=`  | Fittex il-reġistru tal-skills.sh                                                                                                    |
| POST   | `/api/skills/skillssh/install`    | Installa ħila b'ID mill-skills.sh                                                                                                   |

**Awtentikazzjoni:** sessjoni/chi API tal-immaniġġar. Triqot tal-fittxija tal-marketplace jaċċettaw jew awtentikazzjoni tal-immaniggjar jew Bearer API key (`isAuthenticated`).

## Memorja

Ħażna memorja ġejjiena tal-konversazzjoni/fatti, skedata skont API key / sessjoni.

| Metodu | Triq                 | Deskrizzjoni                                                                                                  |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/memory`        | Nota memorji — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, bi paginazzjoni `offset/limit` jew `page/limit`  |
| POST   | `/api/memory`        | Oħloq memorja — ġisem validat minn Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET    | `/api/memory/[id]`   | Retrievi memorja waħda                                                                                        |
| DELETE | `/api/memory/[id]`   | Fassal memorja                                                                                                |
| GET    | `/api/memory/health` | Saħħa s-sottosistema tal-memorja (konnettività DB, backend ta' embeddings, stat tal-investi vetturi)          |

**Autentikazzjoni:** sessjoni/ API key tal-ġestjoni (`requireManagementAuth`). Enum `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (ara `MemoryType` f'`src/lib/memory/types.ts`).

---

## Server MCP

OmniRoute jipprovdi server tal-Model Context Protocol integrat b'3 trasporti (stdio, SSE, streamable-http) u strumenti skedati. It-tmiem tas-sinks hawn taħt jaqraw data tal-stat/awdit u jipprokssjany it-trasporti HTTP.

| Metodu | Triq                   | Deskrizzjoni                                                                                          |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------------- |
| GET    | `/api/mcp/status`      | Heartbeat, trasport, stat onlajn, sejħa l-aħħar, l-istrumenti ewlenin, rata ta' suċċess ta' 24 siegħa |
| GET    | `/api/mcp/tools`       | Lista tal-istrumenti MCP b'`name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints`  |
| GET    | `/api/mcp/sse`         | Stream SSE miftuħ għat-trasport SSE (jirritorna `503` jekk MCP diżabilitat jew trasport ma jaqbilx)   |
| POST   | `/api/mcp/sse`         | Bagħat qafas JSON-RPC fuq it-trasport SSE                                                             |
| GET    | `/api/mcp/stream`      | Stream tal-latt SSE tal-Streamable HTTP transport (messaġġi mtellgħin mis-server)                     |
| POST   | `/api/mcp/stream`      | Bagħat qafas JSON-RPC fuq it-trasport Streamable HTTP                                                 |
| DELETE | `/api/mcp/stream`      | Tisfiq tas-sessjoni Streamable HTTP                                                                   |
| GET    | `/api/mcp/audit`       | Staqsija log tal-awdit — `?limit=`, `?offset=`, `?tool=`, `?success=true                              | false`, `?apiKeyId=` |
| GET    | `/api/mcp/audit/stats` | Statistika tal-awdit aggregate (totali, rata ta' suċċess, durata medja, l-istrumenti ewlenin)         |

**Autentikazzjoni:** it-trasporti `sse`/`stream` jirrikonoxxu l-wiċċ ta' autentikazzjoni speċifiku tal-MCP (API key Bearer b'xiħ `mcp`); it-toroq `status`/`tools`/`audit*` jinqraw mis-dashboard (mhux hemm bżonn autentikazzjoni addizzjonali lil hinn milli tilħaq il-host tal-dashboard).

> Iż-żewġ trasporti HTTP huma mħarsa minn `settings.mcpEnabled` u `settings.mcpTransport` — jekk it-trasport ma jaqbilx jirritorna `400`, stat diżabilitat tal-MCP jirritorna `503`.

## Server tal-A2A

OmniRoute juri punt ta' titjiba A2A (Agent-to-Agent) JSON-RPC 2.0 flimkien ma' wrapper REST għal użu ta' spezzjoni/dashboard.

### JSON-RPC

```bash
POST /a2a
Authorization: Bearer your-api-key   # optional unless OMNIROUTE_API_KEY is set
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Route this coding task"}]
  }
}
```

Metodi appoġġjati (kollha ġesti minn `settings.a2aEnabled`):

| Metodu           | Deskrizzjoni                                                              |
| ---------------- | ------------------------------------------------------------------------- |
| `message/send`   | Eżekuzzjoni sinċrona tal-ħiliet; jirritorna `{task, artifacts, metadata}` |
| `message/stream` | Eżekuzzjoni SSE f'ħin reali tal-istess sett ta' ħiliet                    |
| `tasks/get`      | Tniġġil ta' xogħol permezz ta' `taskId`                                   |
| `tasks/cancel`   | Tħassir ta' xogħol permezz ta' `taskId`                                   |

Ħiliet integrati: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.

### Karta tal-Aġent

```bash
GET /.well-known/agent.json
```

Jirritorna il-karta pubblika tal-aġent A2A (isem, deskrizzjoni, kapaċitajiet, katalgu tal-ħiliet, skema ta' awtentikazzjoni) — maħżuna b'mod pubbliku għal 1h. M'hemmx bżonn awtentikazzjoni.

### Għajnuniet REST

| Metodu | Triq                         | Deskrizzjoni                                                                                                          |
| ------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/a2a/status`            | A2A attiv + statistika tax-xogħol + sommarju tal-karta tal-aġent maħżuna                                              |
| GET    | `/api/a2a/tasks`             | Lista tax-xogħol — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST   | `/api/a2a/tasks`             | (Mhuwiex implimentat bħala għajnuna REST — joħloq permezz ta' JSON-RPC `message/send`)                                |
| GET    | `/api/a2a/tasks/[id]`        | Retrieves wieħed mill-xogħol                                                                                          |
| POST   | `/api/a2a/tasks/[id]/cancel` | Iħassar xogħol                                                                                                        |

**Awtentikazzjoni:** il-għajnuniet REST jaħdmu mingħajr awtentikazzjoni ta' ġestjoni (readable mill-dashboard); il-rotta JSON-RPC `/a2a` tuża Bearer `OMNIROUTE_API_KEY` jekk ikun konfigurat.

---

## Nniflu, Evalwazzjonijiet u Valutazzjonijiet

| Metodu | Triq | Deskrizzjoni |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Jivverifika Bearer key u jirritorna konnessjonijiet tal-fornitur maski + aliased tal-mudelli għal klijenti li jsinkronizzaw mal-cloud |
| POST | `/api/cloud/credentials/update` | Jaġġorna kredenzjali ċċifrat għal fornitur li jissinkronizza mal-cloud |
| POST | `/api/cloud/model/resolve` | Jissolvi ID ta' mudell loġiku għal fornitur/mudell konkret billi juża t-tabella lokali ta' rotot |
| GET | `/api/cloud/models/alias` | Jilista aliaji tal-modell kif ukoll fil-cloud sync |
| GET | `/api/assess` | Aqra l-aħħar klassifikazzjonijiet tal-valutazzjoni (għal kull fornitur/mudell) |
| POST | `/api/assess` | Mexxi valutazzjoni — ġisem: `{scope: {type:"all"}                                                   | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Jilista l-suite evalwazzjonijiet integrati + l-aħħar ġirjiet |
| POST | `/api/evals` | Trigerja ġirja ta' evalwazzjoni |
| POST | `/api/evals/suites` | Oħloq suite evalwazzjonijiet custom — ġisem validat minn `evalSuiteSaveSchema` |
| GET | `/api/evals/suites/[id]` | Retrieves suite evalwazzjonijiet custom |

**Awtentikazzjoni:** `/api/cloud/auth` jivverifika Bearer key direttament; ir-rutti l-oħra `/api/cloud/*`, `/api/evals/*`, u `/api/assess` jitolbu taħdita jew API key ta' ġestjoni. `/api/assess` POST juża `validateBody` b'skema ta' scope ta' unjoni diskriminata.

## Ġestjoni tal-ACP (Agent Client Protocol)

bħala proċessi ul-irqajjem. Dawn il-punti tal-aċċess jiġġestixxu l-għarfien tal-aġenti ACP u r-reġistrazzjoni ta' aġenti personalizzati.

| Metodu | Triq              | Deskrizzjoni                                                                                                                                                             |
| ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/acp/agents` | Juri l-ġ_list kollha ta' aġenti CLI magħrufa (integrati + personalizzati) mal-istat tal-installazzjoni, verżjoni, binarju                                                |
| POST   | `/api/acp/agents` | Jirreġistra aġent ACP personalizzati jew jirriġenera l-cache — ġisem: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` jew `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Jneħħi aġent ACP personalizzati — parametru tal-mistoqsija: `?id=<agentId>`                                                                                              |

**Eżempju ta' risposta** (`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
}
```

**Awtorizzazzjoni:** Teħtieġ sessjoni ta' ġestjoni (cookie `auth_token` tal-dashboard) jew chiave API ta' skop ta' ġestjoni.

Ara [Qafas ACP](../frameworks/ACP.md) għad-dettalji sħaħ.

---

## Analiżi u Osservabilità

Punti tal-aċċess għall-analiżi real-time għas-sorveljanza tal-ir Routing, il-kompressjoni, u d-diversità tal-fornituri. Dawn jitilgħu l-paġni `/dashboard/analytics/*`.

### Analiżi tar-routing awtomatiku

| Metodu | Triq                                 | Deskrizzjoni                                                                                                                              |
| ------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/analytics/auto-routing`        | Statistika aggregata tar-routing awtomatiku: sejħiet totali, distribuzzjoni tal-istrateġija, distribuzzjoni tal-livell, l-aktar fornituri |
| GET    | `/api/analytics/auto-routing?days=7` | Statistika b'finestra ta' żmien (default 24h)                                                                                             |

**Eżempju ta' risposta**:

```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 }
  ]
}
```

### Analiżi tal-kompressjoni

| Metodu | Triq                         | Deskrizzjoni                                                                                               |
| ------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
| GET    | `/api/analytics/compression` | Statistika aggregata tal-kompressjoni: token salvati, % tiffrankar, distribuzzjoni tal-modu, użu tal-magna |

**Eżempju ta' risposta**:

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

### Traċċar tal-diversità tal-fornituri

| Metodu | Triq                        | Deskrizzjoni                                                                                              |
| ------ | --------------------------- | --------------------------------------------------------------------------------------------------------- |
| GET    | `/api/analytics/diversity`  | Traċċar tal-diversità bbażat fuq l-entropija ta' Shannon: jipprevjeni punti waħdieni ta' falliment billi jkejjel il-kaluma tal-fornituri |

**Eżempju ta' risposta**:

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

**Awtorizzazzjoni:** Teħtieġ sessjoni ta' ġestjoni jew chiave API ta' skop ta' ġestjoni.

---

## Operazzjonijiet tal-Administrat Endpoints biss għall-Administratur għall-ġestjoni operazzjonali.

| Metodu | Triq                     | Deskrizzjoni                                                                                        |
| ------ | ------------------------ | --------------------------------------------------------------------------------------------------- |
| GET    | `/api/admin/concurrency` | Qara l-limiti tal-kunċurrenta attwali (globali + għal kull fornitur)                                |
| POST   | `/api/admin/concurrency` | Aġġorna l-limiti tal-kunċurrenta — ġisem: `{global?: number, perProvider?: Record<string, number>}` |

**Awtentikazzjoni:** Teħtieġ sessjoni tal-ġestjoni b'terren tal-awditur.

---

## Ġestjoni tal-Għodod CLI

Ħaddem għodod CLI li jintegraw mal-OmniRoute (antigravity, chipitol, commandCode,
devin-cli, eċċ.). Aħseb [Riferenza tal-Fornitur](./PROVIDER_REFERENCE.md) għall-lista sħiħa.

| Metodu | Triq                                    | Deskrizzjoni                                                                                                                                                               |
| ------ | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cli-tools/all-statuses`           | Statut ta' kull għodda CLI (installat, verżjoni, deher l-aħħar)                                                                                                            |
| GET    | `/api/cli-tools/status`                 | Dettagli tal-statut għal għodda CLI waħda (`?tool=` kwestjoni)                                                                                                             |
| POST   | `/api/cli-tools/apply`                  | Ikteb il-konfigurazzjoni ġenerata ta' għodda (`dryRun` previews; `422` + `containerEphemeralTarget` meta tkun f'kuntenitur; `migration` jinnota YAML tal-Kodiċi tal-qedem) |
| GET    | `/api/cli-tools/backups`                | Ipprova l-konfigurazzjonijiet ta' backup tal-għodod CLI                                                                                                                    |
| POST   | `/api/cli-tools/backups`                | Ħloq backup tal-konfigurazzjonijiet kollha tal-għodod CLI                                                                                                                  |
| POST   | `/api/cli-tools/backups`                | Irrestawra: l-istess endpoint bil-`{tool, backupId}` fil-ġisem jirrestawra dawk il-backup                                                                                  |
| GET    | `/api/cli-tools/antigravity-mitm`       | Statut tal-prokju tal-antigravity MITM (l-għodda CLI "antigravity-mitm")                                                                                                   |
| POST   | `/api/cli-tools/antigravity-mitm/alias` | Ikkonfigura l-alja tal-antigravity-mitm                                                                                                                                    |

**Awtentikazzjoni:** Teħtieġ sessjoni tal-ġestjoni.

---

## Ħiliet tal-Aġent

Ħaddem ħiliet tal-aġent AI (bħal il-GPTs personalizzat ta' OpenAI iżda għall-aġenti).

| Metodu | Triq                         | Deskrizzjoni                                                                                     |
| ------ | ---------------------------- | ------------------------------------------------------------------------------------------------ |
| GET    | `/api/agent-skills`          | Ipprova l-ħiliet kollha tal-aġent (interna + personalizzata)                                     |
| GET    | `/api/agent-skills/[id]`     | Ikseb ħila speċifika tal-aġent                                                                   |
| POST   | `/api/agent-skills`          | Oħroġ ħila tal-aġent personalizzata — ġisem: `{name, description, prompt, model?, temperature?}` |
| PUT    | `/api/agent-skills/[id]`     | Aġġorna ħila tal-aġent personalizzata                                                            |
| DELETE | `/api/agent-skills/[id]`     | Ħassar ħila tal-aġent personalizzata                                                             |
| GET    | `/api/agent-skills/[id]/raw` | Ikseb prompt raw + metadati (bla ekzekuzzjoni)                                                   |
| POST   | `/api/agent-skills/generate` | Ġġenera ħila ġdida mill-IA minn deskrizzjoni bil-lingwa naturali                                 |

**Awtentikazzjoni:** Teħtieġ sessjoni tal-ġestjoni jewAPI key bis-skop tal-ġestjoni.

---

## Ġestjoni tal-Kaxxa

Ħares il-kaxxa semantika u l-kaxxa tar-raġunament.

| Metodu | Triq                   | Deskrizzjoni                                                                                                                           |
| ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cache`           | Ħarsa ġenerali tal-kaxxa: numru ta' dħul, rata ta' qabda, daqs fuq il-disk                                                             |
| GET    | `/api/cache/entries`   | List ta' dħul magħżu fil-kaxxa (b'paginazzjoni)                                                                                        |
| DELETE | `/api/cache/entries`   | Ħassar dħul fil-kaxxa (filtr bl-parametri tal-mistoqsija)                                                                              |
| GET    | `/api/cache/stats`     | Statistiki dettaljati tal-kaxxa (per-fornitur, per-mudell)                                                                             |
| GET    | `/api/cache/reasoning` | Statu tal-kaxxa tar-raġunament (għal riproduzzjoni tar-raġunament)                                                                     |
| DELETE | `/api/cache/reasoning` | Ħassar il-kaxxa tar-raġunament — parametri tal-mistoqsija: `?toolCallId=<id>` (wieħed) jew `?provider=<p>` jew ebda parametri (kollha) |

**Awtentikazzjoni:** Teħtieġ sessjoni ta' ġestjoni.

---

## Sistema tal-Memorja

Ħares il-morja permanenti (FTS5 + embendingi vettorjali).

| Metodu | Triq               | Deskrizzjoni                                                                |
| ------ | ------------------ | --------------------------------------------------------------------------- |
| GET    | `/api/memory`      | List ta' dħul fil-memorja (filtr b'skop, tip, query tat-tiftixa)            |
| POST   | `/api/memory`      | Oħloq dħul ġdid fil-memorja — bodi: `{scope, type, content, metadata?}`     |
| GET    | `/api/memory/[id]` | Ħu dħul speċifiku fil-memorja                                               |
| PUT    | `/api/memory/[id]` | Aġġorna dħul fil-memorja                                                    |
| DELETE | `/api/memory/[id]` | Ħassar dħul fil-memorja                                                     |
| GET    | `/api/memory?q=`   | Fittix fil-memorja (FTS5 + vettorja) — statistika inkluża fl-istess rispons |

**Awtentikazzjoni:** Teħtieġ sessjoni ta' ġestjoni jew chiav API ta' skop ta' ġestjoni.

---

## Webhooks

Ħares l-abbonamenti għal events.

| Metodu | Triq                            | Deskrizzjoni                                                         |
| ------ | ------------------------------- | -------------------------------------------------------------------- |
| GET    | `/api/webhooks`                 | List ta' abbonamenti kollha tal-webhook                              |
| POST   | `/api/webhooks`                 | Oħloq abbonament webhook — bodi: `{url, events[], secret?, active?}` |
| GET    | `/api/webhooks/[id]`            | Ħu abbonament speċifiku webhook                                      |
| PUT    | `/api/webhooks/[id]`            | Aġġorna abbonament webhook                                           |
| DELETE | `/api/webhooks/[id]`            | Ħassar abbonament webhook                                            |
| GET    | `/api/webhooks/[id]/deliveries` | List tal-istorja tal-konsenja għal webhook (logg ta' suċċess/telf)   |
| POST   | `/api/webhooks/[id]/test`       | Ibda event tal-prova lejn webhook                                    |

**Awtentikazzjoni:** Teħtieġ sessjoni ta' ġestjoni.

Ara [Framework tal-Webhooks](../frameworks/WEBHOOKS.md) għat-tipi kollha tal-events.

---

## Qafas tal-Ħiliet

Immaniġġja l-Ħiliet (il-qafas ta 'estensjonijiet agentic).

| Metodu | Triq                     | Deskrizzjoni                                                                                |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`            | Ipprovdil lista tal-ħiliet kollha installed (bil-ħruq + custom)                             |
| POST   | `/api/skills/install`    | Installa ħila minn triq lokali jew URL                                                      |
| DELETE | `/api/skills/[id]`       | Neħħi installazzjoni ta' ħila                                                               |
| PUT    | `/api/skills/[id]`       | Tirejja jew tiddiżattiva ħila — body: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST   | `/api/skills/executions` | Esegwixxi ħila — body: `{skillName, apiKeyId, input?, sessionId?}`                          |
| GET    | `/api/skills/executions` | Ipprovdil lista tal-istorja tal-ezekuzzjoni għall-ħiliet kollha (filtrat b'`?apiKeyId=`)    |

**AWTENTIKAZZJONI:** Teħtieġ session ta' ġestjoni jew API key b'ambitu ta' ġestjoni.

Ara [Qafas tal-Ħiliet](../frameworks/SKILLS.md) għad-dettalji sħaħ.

---

## Plugins

Immaniġġja plugins OmniRoute (estensjonijiet terzi).

| Metodu | Triq                               | Deskrizzjoni                          |
| ------ | ---------------------------------- | ------------------------------------- |
| GET    | `/api/plugins`                     | Ipprovdil lista tal-plugins installed |
| POST   | `/api/plugins/marketplace/install` | Installa plugin mill-marketplace      |
| DELETE | `/api/plugins/[name]`              | Neħħi installazzjoni ta' plugin       |
| POST   | `/api/plugins/[name]/activate`     | Attiva plugin                         |
| POST   | `/api/plugins/[name]/deactivate`   | Diżattiva plugin                      |
| GET    | `/api/plugins/[name]/config`       | Ħu configurazzjoni tal-plugin         |
| PUT    | `/api/plugins/[name]/config`       | Aġġorna configurazzjoni tal-plugin    |

**AWTENTIKAZZJONI:** Teħtieġ session ta' ġestjoni.

Ara [Qafas Plugins](../frameworks/PLUGIN_SDK.md) għad-dettalji sħaħ.

---

## Għoti tal-Shadow

L-iskurjar / paragun A-B tal-fornituri **mhux żifna tal-wiċċ REST** — huwa kkunfigurat permezz tal-għoti kombo (ara [Auto-Combo](../routing/AUTO-COMBO.md)). Il-miżuri tal-paragun għal kull kombo jinbiegħu b'`GET /api/combos/metrics`.

---

## Safe-guards

Iskenni l-safe-guards runtime (rilevament PII, rilevament ta' għoti ta' prompt, għanċjar ta' viżjoni). Is-safe-gwards jimxu fuq kull talba; il-għażla ta' barra għal kull sejħa hija permezz tal-header tal-talba `x-omniroute-disabled-guardrails` — m'hemmx wifqa preservata biex tiddiżattiva/tiġġedded.

| Metodu | Triq                   | Deskrizzjoni                                                                                          |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------------- |
| GET    | `/api/guardrails`      | Ipprovdil lista tal-safe-gwards irreġistrati u l-istatus tagħhom (isem / mixghul / priorita')         |
| POST   | `/api/guardrails/test` | Test b'xejn tal-pipeline ta' qabel is-sejħa fuq input provvija — body: `{input, disabledGuardrails?}` |

**AWTENTIKAZZJONI:** Teħtieġ session ta' ġestjoni.

Ara [Sigurtà > Safe-guards](../security/GUARDRAILS.md) għad-dettalji sħaħ.

---

---

## Ġdid tal-Identità

Ara [Għaddissa tal-Ħlas](../guides/MANAGEMENT-AUTH.md) għall-erba' familji ta' kredenzjali (seduta tad-dashbord, token CLI lokali, token tal-Aċċess `oma_live_…`, u ċ-ċavetta API tal-iskop ta' ġestjoni) u kif dawn jidhru mal-muftieħ ta' inferenza.

- It-toroq tad-dashbord (`/dashboard/*`) jużaw il-cookies `auth_token`
- Il-login juża l-kontroll tal-password salvata; riżorsa għal `INITIAL_PASSWORD`
- `requireLogin` jista' jiġi mibdul permezz ta' `/api/settings/require-login`
- It-toroq `/v1/*` jistgħu jeħtieġu ċ-ċavetta tal-API Bearer meta `REQUIRE_API_KEY=true`
- "token tal-ġestjoni" / "ċavetta API tal-iskop ta' ġestjoni" f'din ir-riferenza jfissru waħda mill-familji f'dik il-gwida — mhux tip ta' sigriet żejjed mhux definit

> **Bidla li tinqasam (v3.8.0)** — `/api/v1/agents/tasks/*` u t-toroq tal-kaptan tal-kura issa jeħtieġu **autentiċità tal-ġestjoni** (cookie `auth_token` tad-dashbord jew ċavetta API tal-iskop ta' ġestjoni). Il-klijenti li qabel kienu sejħin għal dawn it-toroq bla tawrira se jirċievu `401 Unauthorized`. Ara l-kommit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).