# API Reference (Malti) 🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md) --- 🌐 **Lingwi:** 🇺🇸 [Ingliż](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md) Referenza ewlenija għall-API ta’ OmniRoute. Din tkopri l-interfaċċa pubblika `/v1` u l-endpoints ta’ ġestjoni l-aktar użati; il-fajl li jista’ jinqara mill-magni [`docs/openapi.yaml`](../openapi.yaml) u s-siġra tar-rotot taħt `src/app/api/` huma s-sorsi eżawrjenti. --- ## Werrej - [Tkomplijiet taċ-Chat](#chat-completions) - [Kirjiet Esklussivi ta' Sessjonijiet Immaniġġjati](#exclusive-managed-session-leases) - [Inkorporazzjonijiet](#embeddings) - [Ġenerazzjoni ta' Immaġnijiet](#image-generation) - [OCR tad-Dokumenti](#document-ocr) - [Lista tal-Mudelli](#list-models) - [Manifest tal-Plugin tal-Fornitur](#provider-plugin-manifest) - [Endpoints tal-Kompatibbiltà](#compatibility-endpoints) - [API tal-Fajls](#files-api) - [API tal-Lottijiet](#batches-api) - [API tat-Tiftix](#search-api) - [Streaming permezz ta' WebSocket](#websocket-streaming) - [Kwoti u Rappurtar ta' Problemi](#quotas--issues-reporting) - [Cache Semantika](#semantic-cache) - [Dashboard u Ġestjoni](#dashboard--management) - [Ġestjoni tal-Kombinazzjonijiet](#combo-management) - [Webhooks](#webhooks) - [Ċwievet Irreġistrati (Ġestjoni Awtomatika)](#registered-keys-auto-management) - [Protokoll tal-Aġenti](#agents-protocol) - [Proxies tal-Ġestjoni](#management-proxies) - [Reżiljenza (estiża)](#resilience-extended) - [Ħiliet](#skills) - [Memorja](#memory) - [Server MCP](#mcp-server) - [Server A2A](#a2a-server) - [Cloud, Evalwazzjonijiet u Valutazzjoni](#cloud-evals--assess) - [Ipproċessar tat-Talbiet](#request-processing) - [Awtentikazzjoni](#authentication) --- ## Tkomplijiet taċ-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": "Ikteb funzjoni biex..."} ], "stream": true } ``` ### Headers Personalizzati | Header | Direzzjoni | Deskrizzjoni | | ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `X-OmniRoute-No-Cache` | Talba | Issettjah għal `true` biex taqbeż il-cache | | `x-omniroute-no-memory` | Talba | Issettjah għal `true` biex taqbeż l-injezzjoni tal-memorja u tal-ħiliet għal din it-talba (jirrifletti no-cache; jevita l-ispiża addizzjonali tat-tokens/tal-kost għal kull sejħa) | | `X-OmniRoute-Progress` | Talba | Issettjah għal `true` għal avvenimenti tal-progress | | `X-Session-Id` | Talba | Ċavetta persistenti tas-sessjoni għall-affinità ma' sessjoni esterna | | `x_session_id` | Talba | Il-varjant b'linja taħt huwa aċċettat ukoll (HTTP dirett) | | `X-OmniRoute-Session-Id` | Talba | Tag tas-sessjoni/konverżazzjoni pprovdut minn min jagħmel is-sejħa (jintuża wkoll mill-memorja). Meta jkun preżenti, jinżamm verbatim f'`call_logs.session_tag` għall-attribuzzjoni tal-kost għal kull sessjoni (#8249) — qatt ma jiġi ġġenerat meta jkun nieqes | | `Idempotency-Key` | Talba | Ċavetta għat-tneħħija tad-duplikati (tieqa ta' 5s) | | `X-Request-Id` | Talba | Ċavetta alternattiva għat-tneħħija tad-duplikati | | `X-OmniRoute-Cache` | Tweġiba | `HIT` jew `MISS` (mingħajr streaming) | | `X-OmniRoute-Idempotent` | Tweġiba | `true` jekk tneħħa d-duplikat | | `X-OmniRoute-Progress` | Tweġiba | `enabled` jekk it-traċċar tal-progress ikun attiv | | `X-OmniRoute-Session-Id` | Tweġiba | L-ID effettiva tas-sessjoni użata minn OmniRoute | | `X-OmniRoute-Request-Id` | Tweġiba | ID ta' korrelazzjoni tat-talba (meta tkun magħrufa) | | `X-OmniRoute-Version` | Tweġiba | Verżjoni tal-build ta' OmniRoute (dejjem preżenti) | | `X-OmniRoute-Cost-Saved` | Tweġiba | L-ammont f'USD li l-cache evitat fuq `HIT` (għal hits tal-cache biss) | | `X-OmniRoute-Decision` | Tweġiba | Traċċa tar-routing: `strategy=; provider=; latency_ms=` (`` hija l-istrateġija tal-kombinazzjoni, jew `single` għal talba li mhijiex kombinazzjoni) — dejjem preżenti fit-tweġibiet tat-tlestija | > Nota dwar Nginx: jekk tiddependi fuq headers b'linji taħt (pereżempju `x_session_id`), attiva `underscores_in_headers on;`. > **Headers tat-telemetrija tal-ispejjeż:** it-tweġibiet ta’ suċċess mhux streaming iġorru wkoll is-sett tat-telemetrija tal-ispejjeż `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, fiss għal 10 postijiet deċimali; `0.0000000000` għal servizzi bla ħlas/mingħajr prezz), `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 taċ-chat, `/v1/responses`, `/v1/messages`, **u l-endpoints 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 bi spiża ta’ `0`). L-ispiża tal-midja tiġi kkalkolata skont il-modalità (għal kull immaġni, għal kull sekonda, għal kull karattru, għal kull unità ta’ tfittxija) meta l-ipprezzar ikun disponibbli; inkella tkun `0` (fail-open). > **Semantika tal-ispiża ta’ cache hit:** meta jkun hemm HIT fil-cache semantika (`X-OmniRoute-Cache-Hit: true`), ma ssir ebda sejħa upstream, għalhekk `X-OmniRoute-Response-Cost` ikun `0.0000000000` (l-ispiża **inkrementali** biex jiġi pprovdut il-hit). L-ispiża oriġinali/li kieku kienet tiġġarrab tiġi rrappurtata separatament f’`X-OmniRoute-Cost-Saved`. Il-konsumaturi tad-dejta tal-kontijiet għandhom jgħoddu s-somma ta’ `X-OmniRoute-Response-Cost` (il-hits ma jiswew xejn); l-analitika tal-cache tista’ taggrega `X-OmniRoute-Cost-Saved`. ## Kirjiet Esklussivi ta’ Sessjonijiet Ġestiti Il-kiri esklussiv ta’ sessjonijiet ġestiti huwa kuntratt ta’ routing fakultattiv u newtrali għall-klijent: sid attiv wieħed iżomm konnessjoni OmniRoute eliġibbli waħda. Dan ma jikrix mudell, ma jeħtieġx OAuth, ma jidentifikax klijent partikolari, u ma jeħtieġx fornitur partikolari. Iċ-ċavetta API li twettaq l-awtentikazzjoni jrid ikollha l-ambitu `lease:exclusive` u lista espliċita mhux vojta `allowedConnections`. Il-konfini tal-mutazzjoni tad-database jinforzaw iż-żewġ kampijiet flimkien waqt il-ħolqien taċ-ċavetta u l-aġġornamenti parzjali. ```http POST /api/v1/session-leases Authorization: Bearer Content-Type: application/json X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> {"action":"acquire","model":"glm/glm-4.6"} ``` It-tweġibiet ta’ akkwist, tiġdid u rilaxx li jirnexxu jesponu timestamps, `state`, u l-valur pożittiv eżatt ta’ `generation`, iżda qatt il-konnessjoni magħżula jew il-kredenzjali. It-tiġdid u r-rilaxx jipprovdu l-ġenerazzjoni fil-body JSON: ```json { "action": "renew", "generation": 1 } ``` ```json { "action": "release", "generation": 1, "reason": "OWNER_EXIT" } ``` Sid attiv tal-kiri jista’ jitlob b’mod espliċitu metadata tal-wiri li tipproteġi l-privatezza għall-assoċjazzjoni 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" } } ``` Din l-azzjoni fakultattiva tal-istatus hija protetta mis-sid opak, miċ-ċavetta API ġestita u awtentikata, u mill- ġenerazzjoni attiva eżatta fi tranżazzjoni waħda tad-database. `displayName` huwa biss l-isem ikkonfigurat u mirqum tal-konnessjoni; ikun `null` meta ma jkun jeżisti ebda isem ikkonfigurat sikur. OmniRoute qatt ma jissostitwixxi email jew identità tal-kont iġġenerata. Il-valur tal-fornitur huwa tikketta tal-wiri mhux sensittiva u qatt identifikatur iġġenerat ta’ fornitur kompatibbli. Il-kredenzjali, it-tokens, il-cookies, l-identifikaturi mhux ipproċessati tal-konnessjoni jew taċ-ċavetta API, il-hashes tas-sid, is-sigrieti tal-fencing, u d-data interna tar-routing huma esklużi. It-tfittxijiet b’ċavetta ħażina, sid ħażin, ġenerazzjoni skaduta, kiri nieqes, skadut, rilaxxat jew invalidat kollha jirritornaw l-istess żball `409 LEASE_FENCE_STALE` mingħajr metadata tal-konnessjoni. Klijent li rċieva t-tweġiba ta’ stennija għall-kapaċità ma għandu l-ebda assoċjazzjoni attiva x’jispezzjona. Meta r-routing jittrasferixxi kiri attiv, l-istess ġenerazzjoni tibqa’ valida u l-istatus jirritorna atomikament l-assoċjazzjoni l-ġdida, u qatt dik il-qadima. Il-klijenti eżistenti jibqgħu l-istess għax it-tweġibiet ta’ akkwist, tiġdid, rilaxx u stennija jżommu l-forom preċedenti tagħhom. Dan il-kuntratt tas-server ma jibdilx `/status` standard ta’ OpenAI Codex. Bħalissa, Codex standard jirrapporta l- fornitur tal-mudell u l-istat integrat tal-awtentikazzjoni/kont tiegħu, iżda ma jirrendix metadata arbitrarja ta’ kont ta’ fornitur personalizzat; integrazzjoni futura tal-klijent trid issejjaħ din l-azzjoni u tiddeċiedi kif turi `connection.displayName`. Kull talba ta’ inferenza ġestita mbagħad tipprovdi ż-żewġ headers ta’ kontroll: ```http X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> X-OmniRoute-Lease-Generation: 1 ``` Is-sid eżatt, il-ġenerazzjoni, il-konnessjoni attiva, u ċ-ċavetta API awtentikata jiġu vverifikati minnufih qabel kull tentattiv upstream appoġġjat. Ir-ripetizzjoni tas-sid u l-ġenerazzjoni b’ċavetta oħra tfalli anki meta dik iċ-ċavetta tippermetti l-istess konnessjoni. Is-sidien mhux ipproċessati ma jiġux ippersistiti, irreġistrati fil-logs, miżmuma fl- istantanja tat-talba, jew mgħoddija 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 } ``` Din it-tweġiba tfisser biss li s-sett eliġibbli ordinarju ma kienx vojt u kull kandidat liberu kien miżmum minn kiri attiv barrani. Mudelli/fornituri mhux appoġġjati, nuqqas ta’ qbil mal-politika, cooldown, kwota, saħħa, u fallimenti ordinarji oħra tal-eliġibbiltà jżommu t-tweġibiet OmniRoute eżistenti tagħhom. ### `x-omniroute-compression` Sovrascrittura għal kull talba tal-pjan tal-kompressjoni. L-ogħla preċedenza — tieħu prijorità fuq is-sovrascrittura tal-kombinazzjoni tar-routing, il-profil attiv, l-attivazzjoni awtomatika, u d-Default tal-pannell. Valuri: | Valur | Effett | | ------------- | ------------------------------------------------------------------------------------------------------------- | | `off` | Ebda kompressjoni għal din it-talba. | | `default` | Il-profil Default derivat mill-pannell (jinjora l-profil attiv). | | `engine:` | Magna waħda meta tkun attivata, eż. `engine:rtk`. | | `` | Kombinazzjoni msemmija, imqabbla l-ewwel skont l-isem (mingħajr sensittività għall-każ), imbagħad skont l-id. | Noti: - Valuri mhux magħrufa jiġu injorati (it-talba qatt ma tiġi rrifjutata); ir-riżoluzzjoni tkompli skont il-preċedenza normali tal-operaturi. - Jekk diversi kombinazzjonijiet ikollhom l-istess isem, għaddi l-**id** tal-kombinazzjoni għal tqabbil deterministiku. - Kombinazzjoni li isimha huwa `off` jew `default` ma tistax tintgħażel bl-isem (dawk il-kliem ewlieni jiġu interpretati l-ewwel); irreferi għal tali kombinazzjoni bl-id tagħha. - Is-swiċċ prinċipali tal-kompressjoni huwa kontroll assolut: meta l-kompressjoni tkun diżattivata globalment, dan il-header ma jistax jattivaha. Il-pjan applikat jintbagħat lura fil-header tat-tweġiba: ``` X-OmniRoute-Compression: ; source= ``` fejn `` huwa wieħed minn `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, jew `off`. --- ## Inkorporazzjonijiet ```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 tal-mudelli Jina mingħajr prefiss li jidhru fir-reġistru (pereżempju `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) jiġu riżolti wkoll. Il-funzjonijiet embed/rerank/classify/segment ta’ Jina jużaw l-ewwel il-kredenzjali `jina-ai` tad-dashboard; `JINA_AI_API_KEY` jintuża bħala alternattiva biss meta ma teżisti l-ebda kjavi fid-dashboard. Il-kard `jina-reader` hija biss għal Reader / `r.jina.ai` (`POST /v1/web/fetch`) u qatt ma tipprovdi embeddings jew rerank. Il-mudelli fir-reġistru li jiddikjaraw appoġġ multimodali jaċċettaw ukoll sa 32 element strutturat newtrali għall-fornitur. It-tipi ta’ elementi tal-midja huma `text`, `image`, `audio`, `video`, u `document`. Is-`source` tal-midja 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-alias tal-familja `jina-ai/jina-embeddings-v5-omni` → omni-small) jaċċetta wkoll id-dokumenti nattivi EmbeddingsV5Request ta’ Jina u **jgħaddihom intatti** lil `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,..." }] } ] } ``` Il-valuri nattivi `{ image | audio | video | pdf }` jistgħu jkunu URL HTTPS pubbliku, URI `data:`, jew base64 mhux ipproċessat. OmniRoute ma jikkonvertix dawk l-oġġetti għal strings u lanqas ma jġib URLs nattivi tal-immaġnijiet — Jina jġib il-midja pubblika huwa stess. Oqsma addizzjonali ta’ Jina (`task`, `normalized`, `truncate`, `embedding_type`) jiġu mgħoddija. L-SKUs ta’ Jina li jaċċettaw test biss xorta jirrifjutaw dokumenti mhux testwali. Limiti tas-sigurtà u tat-trasport: - L-URLs tal-midja remota jridu jkunu HTTPS pubbliċi. Elementi kanoniċi `{type,source:url}` jinġiebu min-naħa tas-server (b’validazzjoni mill-ġdid tar-ridirezzjonijiet, timeout, limiti tad-daqs, DNS pubbliku, u ffissar tal-konnessjoni) u jiddaħħlu inline qabel is-sejħa lill-fornitur. Elementi nattivi ta’ Jina `{image:"https://..."}` jiġu mgħoddija kif inhuma wara l-istess verifika ta’ HTTPS pubbliku; Jina jġib il-URL. - Midja base64 inline hija limitata għal 8 MiB dekodifikati għal kull element u 16 MiB dekodifikati fit-talba kollha. Traduzzjoni għall-fornitur (l-elementi kanoniċi qatt ma jiġu mgħoddija mingħajr tibdil): - Mudelli multimodali ta’ Jina: kull element tal-ogħla livell isir oġġett wieħed b’kjavi skont il-modalità (`text` / `image` / `audio` / `video` / `pdf`), bl-użu ta’ URIs tad-data għall-midja inline; vettur wieħed għal kull element tal-ogħla livell. - Familja Gemini Embedding 2: array wieħed tal-ogħla livell isir talba nattiva waħda `models/{model}:embedContent` b’`content.parts` (`text` jew `inline_data`). - Mudelli mhux magħrufa/dinamiċi mingħajr metadata espliċita tal-modalità 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 ta’ mudell/modalità jirritornaw HTTP 400 minflok jikkonvertu l-element bil-forza. Oqsma ta’ estensjoni li mhumiex tal-input f’talbiet legacy ta’ strings/tokens ikomplu jiġu mgħoddija mingħajr tibdil. ```bash # Elenka l-mudelli kollha tal-inkorporazzjonijiet GET /v1/embeddings ``` --- ## Ġenerazzjoni tal-Immaġnijiet ```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 # Elenka l-mudelli kollha tal-immaġnijiet GET /v1/images/generations ``` --- ## OCR tad-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` jagħżel il-fornitur tal-OCR permezz ta' prefiss `provider/model`; id tal-mudell waħdu (eż. `mistral-ocr-latest`) jiġi riżolt għall-fornitur irreġistrat tiegħu, u jekk `model` jitħalla barra, il-valur predefinit ikun Mistral (`mistral-ocr-latest`). Fornituri rreġistrati (`open-sse/config/ocrRegistry.ts`): | Id tal-fornitur | Id tal-mudell | Valur ta' `model` | Noti | | ----------------------------- | -------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (jew `mistral-ocr-latest` waħdu) | Sinkroniku — ir-rispons jintbagħat lura direttament mis-sejħa unika upstream. | | `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Upstream asinkroniku (`analyze` + poll) — ara hawn taħt. | | `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Sinkroniku, permezz tal-endpoint sieħeb `openapi/chat/completions` ta' Vertex AI — ara hawn taħt għall-awtentikazzjoni/URL. | It-tliet fornituri kollha jirrispondu bl-istess korp iffurmat bħal dak ta' Mistral: ```json { "pages": [{ "index": 0, "markdown": "# Extracted text..." }], "model": "mistral-ocr-latest", "usage_info": { "pages_processed": 1 } } ``` ### Fluss ta' polling ta' Azure Document Intelligence L-API `analyze` ta' Azure Document Intelligence hija asinkronika: it-talba inizjali tirritorna header `Operation-Location` minflok korp, u r-riżultat irid jiġi ċċekkjat permezz ta' polling. Il-handler (`open-sse/handlers/ocr.ts`) jagħmel polling ta' dak il-URL kull sekonda sa 30 tentattiv, jieqaf immedjatament (ma jkomplix jagħmel polling) jekk rispons tal-poll ma jkunx `ok` jew jekk l-istatus ikun `"failed"`, u jirritorna `504` jekk l- operazzjoni tkun għadha għaddejja wara li jiġi eżawrit il-limitu tat-tentattivi. Ir-rispons finali ta' Azure jiġi normalizzat fl-istess format `pages`/`markdown` użat minn Mistral qabel jintbagħat lura lil min għamel it- talba, għalhekk il-kodiċi tal-klijent ma għandux għalfejn jittratta lill-fornitur bħala każ speċjali. ### Awtentikazzjoni u riżoluzzjoni tal-endpoint għal Vertex AI DeepSeek OCR `vertex-deepseek-ocr` jerġa' juża l-istess awtentikazzjoni ta' Vertex AI li OmniRoute diġà jappoġġja għat- traffiku taċ-chat/tal-immaġnijiet (`open-sse/executors/vertex.ts`): iċ-ċavetta tal-API tal-konnessjoni tkun jew kredenzjali JSON ta' Service Account (skambjata ma' token ta' aċċess OAuth għal żmien qasir permezz tal-fluss JWT-bearer) jew token ta' aċċess OAuth diġà maħruġ li jintuża kif inhu. Il-URL tal-endpoint upstream huwa l- endpoint sieħeb ġeneriku `openapi/chat/completions` ta' Vertex, mibni mill-proġett u r-reġjun tal-konnessjoni — `providerSpecificData.project`/`providerSpecificData.region` espliċitu dejjem jieħu preċedenza; inkella l-proġett jiġi derivat minn `project_id` tal-JSON tas-Service Account u r-reġjun jieħu l-valur predefinit `us-central1`. Iż-żewġ riżoluzzjonijiet iseħħu f'`open-sse/handlers/ocr.ts` (`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`), u jintużaw minn `src/app/api/v1/ocr/route.ts` qabel ma jintbagħtu lil `handleOcr`. --- ## Elenka tal-Mudelli ```bash GET /v1/models Authorization: Bearer your-api-key → Jirritorna l-mudelli kollha taċ-chat, tal-inkorporazzjoni u tal-immaġnijiet + il-kombinazzjonijiet fil-format ta’ OpenAI ``` ### Prefissi tal-id tal-mudell (`?prefix=`) Il-biċċa l-kbira tal-mudelli jiġu ppubblikati taħt **prefiss tal-fornitur**. Il-prefiss li tikseb huwa kkontrollat mill-feature flag `MODELS_CATALOG_PREFIX_MODE`, u jista’ jiġi sostitwit **għal kull talba** permezz ta’ parametru tal-query — utli għal klijent li jrid lista nadifa mingħajr ma jibdel l-issettjar ġenerali tas-server għal kulħadd: ```bash GET /v1/models?prefix=alias # id wieħed għal kull mudell — il-prefiss qasir tal-alias GET /v1/models?prefix=dual # iż-żewġ forom (il-valur predefinit tas-server) GET /v1/models?prefix=canonical # il-prefiss sħiħ tal-id tal-fornitur biss ``` | Modalità | Joħroġ | Noti | | ----------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `dual` | `cc/claude-sonnet-4-6` **u** `claude/claude-sonnet-4-6` | **Predefinita.** Iż-żewġ ids jiġu diretti lejn l-istess mudell; dan jinżamm sabiex il-konfigurazzjonijiet tal-klijenti li għandhom waħda miż-żewġ forom miktuba direttament jibqgħu jaħdmu. Bejn wieħed u ieħor jirdoppja l-katalgu. | | `alias` | `cc/claude-sonnet-4-6` | Entrata waħda għal kull mudell. Il-fornituri mingħajr alias distint xorta joħorġu l-entrata tagħhom, għalhekk ma jintilef xejn. | | `canonical` | `claude/claude-sonnet-4-6` | Entrata waħda għal kull mudell taħt il-prefiss sħiħ tal-id tal-fornitur. Il-fornituri mingħajr alias distint (eż. `antigravity/…`, `agy/…`) joħorġu l-id uniku tagħhom hawn ukoll, għalhekk ma jintilef xejn. | Mera fil-modalità `dual` tista’ tiġi rikonoxxuta wkoll mingħajr il-parametru tal-query: ikollha field `parent` li jindika l-id primarju. Il-klijenti li jirrendu selettur tal-mudelli għandhom jitolbu `?prefix=alias` — dan huwa dak li tagħmel l-[estensjoni OmniCopilot għal VS Code](../guides/VSCODE-COPILOT.md). ### Varjanti tal-mudelli mingħajr ħsieb Għall-mudelli Claude li għandhom il-kapaċità tal-ħsieb, `/v1/models` jirreklama wkoll varjant **mingħajr ħsieb** li l-id tiegħu jkollu l-prefiss `claude-3-omniroute-no-thinking/`: ``` claude-3-omniroute-no-thinking// ``` Meta jintgħażel dan l-id (eż. f’konfigurazzjoni ta’ Claude Code li dejjem tehmeż blokk `thinking`), dan jiġi riżolt lura għall-`/` reali bir-raġunament imrażżan — `thinking:{type:"disabled"}` fuq il-passaġġ `/v1/messages`, jew bil-fields `reasoning`/`reasoning_effort` imneħħija fuq il-passaġġ `/v1/chat/completions`. Il-varjant jiġi elenkat biss għal mudelli tal-familja Claude li jappoġġjaw il-ħsieb **u** jirrispettaw `disabled` (għalhekk, eż., mudelli adaptive-only li jirrifjutaw `disabled` huma esklużi). L-operaturi jistgħu jimponu li l-varjant ikun attivat jew diżattivat għal kull mudell permezz ta’ `ModelSpec.noThinkingAlias`. --- ## Manifest tal-Plugin tal-Fornitur ```bash GET /api/v1/provider-plugin-manifest ``` Jirritorna l-manifest tal-plugin tal-fornitur, sikur għall-JSON, li jintuża minn Bifrost, CLIProxyAPI, u routers sidecar futuri. Ir-rispons jiġi ġġenerat mir-reġistru tal-fornituri ta’ TypeScript u intenzjonalment jeskludi s-sigrieti tal-klijenti OAuth, ir-riżoluzzjoni tal-ambjent waqt l-eżekuzzjoni, il-funzjonijiet tal-eżekutur, l-headers tat-talbiet, u d-data tal-kontijiet. Uża dan l-endpoint meta sidecar jaħdem barra mill-proċess u ma jkunx jista’ jimporta `open-sse/config/providerPluginManifestRegistry.ts` direttament. --- ## Endpoints tal-Kompatibbiltà | Metodu | Path | Format | | ------ | ----------------------------------------- | ----------------------------------------- | | POST | `/v1/chat/completions` | OpenAI | | POST | `/v1/messages` | Anthropic | | POST | `/v1/responses` | Risponsi OpenAI | | POST | `/v1/embeddings` | OpenAI | | POST | `/v1/images/generations` | Immaġnijiet OpenAI | | POST | `/v1/images/edits` | Immaġnijiet OpenAI (editjar/inpaint) | | POST | `/v1/videos/generations` | Ġenerazzjoni ta’ vidjow bl-istil OpenAI | | POST | `/v1/music/generations` | Ġenerazzjoni ta’ mużika bl-istil OpenAI | | POST | `/v1/audio/transcriptions` | Awdjo OpenAI (STT) | | POST | `/v1/audio/speech` | OpenAI TTS (jirritorna l-korp tal-awdjo) | | POST | `/v1/rerank` | Riklassifikazzjoni bl-istil Cohere/Voyage | | POST | `/v1/classify` | Klassifikazzjoni 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}` | Gemini generateContent | | POST | `/v1/api/chat` | Ollama | | GET | `/api/v1/vscode/{token}/` | Alias tal-katalgu OpenAI | | GET | `/api/v1/vscode/{token}/models` | Alias tal-mudelli OpenAI | | POST | `/api/v1/vscode/{token}/chat/completions` | Alias tokenizzat OpenAI | | POST | `/api/v1/vscode/{token}/responses` | Alias tokenizzat tar-Risponsi OpenAI | | POST | `/api/v1/vscode/{token}/api/chat` | Alias tokenizzat Ollama | | GET | `/api/v1/vscode/{token}/api/tags` | Alias tokenizzat tat-tags Ollama | Ir-rotot POST kollha jsegwu l-istess struttura: `Bearer your-api-key` + korp JSON ivvalidat minn Zod (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, eċċ., ara `src/shared/validation/schemas.ts`). Jiġi rritornat 4xx jekk l-iskema tfalli. Għal klijenti li ma jistgħux jehmżu `Authorization: Bearer ...`, OmniRoute jaċċetta wkoll API keys fil-URL, jew permezz ta’ kompatibbiltà fil-query string (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) jew permezz tal-endpoints dedikati `/api/v1/vscode/{token}/...` dokumentati hawn taħt. ```bash # Riklassifikazzjoni POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] } # Klassifikazzjoni Jina (kredenzjali tal-Foundation API) POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] } # Segmentatur Jina POST /v1/segment { "content": "...", "return_chunks": true } # Tfittxija 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 korp audio/mpeg (jew il-format mitlub) POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" } # Editjar tal-immaġni (multipart) POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png # Ġenerazzjoni ta’ vidjow / mużika (ID tal-mudell bil-prefiss tal-fornitur) POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." } POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." } ``` ### Rotot Dedikati tal-Fornitur ```bash POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` Il-prefiss tal-fornitur jiżdied awtomatikament jekk ikun nieqes. Mudelli li ma jaqblux jirritornaw `400`. --- ## API tal-Fajls Endpoint kompatibbli ma’ OpenAI għall-fajls għall-input/output f’lottijiet u għat-tlugħ ta’ fajls bi skop speċifiku. | Metodu | Mogħdija | Deskrizzjoni | | ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------- | | POST | `/v1/files` | Tella’ fajl (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — massimu ta’ 512 MiB | | GET | `/v1/files` | Elenka l-fajls għaċ-ċavetta tal-API awtentikata | | GET | `/v1/files/[id]` | Ikseb il-metadata ta’ fajl | | DELETE | `/v1/files/[id]` | Ħassar fajl | | GET | `/v1/files/[id]/content` | Ibgħat lura l-korp mhux ipproċessat tal-fajl bħala stream | **Awtentikazzjoni:** Ċavetta tal-API tat-tip Bearer — il-fajls huma limitati għal kull ċavetta tal-API permezz ta’ `getApiKeyRequestScope`. Ċavetta tara, tniżżel u tħassar il-fajls tagħha biss; sessjoni tad-dashboard mingħajr ċavetta taqra l-istanza kollha; fajl mingħajr sid (upload anonimu jew minn sessjoni tad-dashboard) jiġi miċħud lil kull min jagħmel talba mingħajr sessjoni. `GET /v1/files` jiċħad lil min jagħmel talba b’mod anonimu — u ċavetta ppreżentata li ma tiġix riżolta — b’`401` anke meta `REQUIRE_API_KEY=false`, minflok jelenka l-fajls tat-tenant kollha (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523). --- ## API tal-Lottijiet Ipproċessar f’lottijiet kompatibbli ma’ OpenAI. | Metodu | Mogħdija | Deskrizzjoni | | ------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------- | | POST | `/v1/batches` | Oħloq lott — il-korp jiġi vvalidat minn `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) | | GET | `/v1/batches` | Elenka l-lottijiet | | GET | `/v1/batches/[id]` | Ikseb l-istatus tal-lott + `request_counts` | | DELETE | `/v1/batches/[id]` | Ħassar lott li jkun tlesta/falla | | POST | `/v1/batches/[id]/cancel` | Ikkanċella lott li jkun għadu għaddej | **Awtentikazzjoni:** Ċavetta tal-API tat-tip Bearer. Il-lottijiet huma limitati għal kull ċavetta tal-API skont l-istess regola bi tliet każijiet bħall- fajls: iċ-ċavetta proprja biss, sessjoni tad-dashboard għall-istanza kollha, u rekords mingħajr sid miċħuda lil kull min jagħmel talba mingħajr sessjoni (meta jikseb, iħassar, jikkanċella, u fil-verifika ta’ `input_file_id` waqt il-ħolqien). `GET /v1/batches` jiċħad lil min jagħmel talba b’mod anonimu b’`401` anke meta `REQUIRE_API_KEY=false`. --- ## API tat-Tiftix Astrazzjoni tal-fornitur tal-web/tiftix (Tavily, Brave, Exa, Serper, eċċ.). | Metodu | Mogħdija | Deskrizzjoni | | ------ | ---------------------- | ----------------------------------------------------------------------------------------------------------- | | GET | `/v1/search` | Elenka l-fornituri tat-tiftix ikkonfigurati + il-kapaċitajiet tagħhom | | POST | `/v1/search` | Esegwixxi mistoqsija ta’ tiftix — il-body jiġi vvalidat minn `v1SearchSchema`, jappoġġja caching/coalescing | | GET | `/v1/search/analytics` | Statistika għal kull fornitur dwar hits/latency/cache | **Awtentikazzjoni:** Ċavetta API Bearer (`extractApiKey` + `isValidApiKey`). Il-politika tat-tiftix tiġi infurzata permezz ta’ `enforceApiKeyPolicy`. --- ## API tal-Ġbir mill-Web Estratta kontenut minn URL permezz ta’ fornitur ikkonfigurat għall-ġbir mill-web (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract). | Metodu | Mogħdija | Deskrizzjoni | | ------ | --------------- | ---------------------------------------------------------------- | | POST | `/v1/web/fetch` | Ġib/estratta URL — il-body jiġi vvalidat minn `v1WebFetchSchema` | **Awtentikazzjoni:** Ċavetta API Bearer (`extractApiKey` + `isValidApiKey`). Il-politika tiġi infurzata permezz ta’ `enforceApiKeyPolicy`. **Fallback konxju tal-kwota (#8297):** meta ma jingħata l-ebda `provider` espliċitu, il-pool (`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) jiġi segwit f’ordni ta’ prijorità fissa (fill-first) — fornitur ikkonfigurat iżda limitat fir-rata jinqabeż minflok ma titwaqqaf it-talba minnufih, u falliment upstream li jista’ jerġa’ jiġi ppruvat/relatat mal-kwota (HTTP 429 dejjem; 402/403 għal-livelli bla ħlas ta’ Firecrawl/Tavily/TinyFish relatati mal-kwota — mhux għal Jina Reader, u qatt għal talba ħażina sempliċi 400) jgħaddi għall- fornitur li jmiss b’kredenzjali li għadu ma ġiex ippruvat fil-ħin tat-talba. Meta kull fornitur fil- pool ikun eżawrit, l-endpoint jirritorna `429` wieħed (b’header `Retry-After`) minflok il-`400` ġeneriku preċedenti. Meta jintalab `provider` espliċitu, **ma jkun hemm l-ebda** fallback sieket — fornitur espliċitu limitat fir-rata jew li qed ifalli juri l-iżball tiegħu stess (`429` jekk ikun limitat fir-rata, inkella l-istatus upstream). --- ## Streaming bil-WebSocket ```bash GET /v1/ws?handshake=1 ``` Jivvalida handshake ta’ upgrade tal-WebSocket u jirritorna l-messaġġi ta’ eżempju tal-protokoll fuq il-wire (`request`, `cancel`). Il-frames WS attwali jiġu ġestiti mis-server WS inkluż, barra mit-tabella tar-rotot ta’ Next.js. **Awtentikazzjoni:** Ċavetta API Bearer waqt il-handshake. ### Responses API fuq WebSocket (codex biss) ```bash # L-istess host:port bħall-API HTTP (default 20128); aġġorna l-konnessjoni: wscat -c "ws://localhost:20128/v1/responses?api_key=" # (jew: -H "Authorization: Bearer ") # L-ewwel frame GĦANDU jkun response.create: { "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] } ``` Proxy ta’ Responses-API-over-WebSocket huwa mqabbad **esklussivament ma’ `codex`** (backend ta’ ChatGPT). Jisma’ fuq l-istess port bħall-API/dashboard fil-mogħdijiet `/v1/responses`, `/responses`, u `/api/v1/responses`. Mal-ewwel frame `response.create`, dan jawtentika + jipprepara permezz tal-bridge intern `codex-responses-ws`, jagħżel konnessjoni OAuth ta’ codex, u joħloq mina lejn `wss://chatgpt.com/backend-api/codex/responses` permezz tat-transport `wreq-js`. **Mudelli mhux codex jiġu rrifjutati** (`codex_ws_provider_required`). Għar-routing bil-qsim tal-kwota uża `model: "qtSd//codex/"`. Implimentat fi `app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`. **Awtentikazzjoni:** Ċavetta API Bearer waqt il-handshake. Is-server HTTP inkluż (`server-ws.mjs`) irid ikun l-entrypoint attiv (u hekk ikun, b’mod awtomatiku, meta jeżisti `app/server-ws.mjs`). #### ID tal-mudell: uża l-ID sempliċi ta’ ChatGPT (mingħajr il-prefiss `codex/`) L-OpenAI **Codex CLI** jivvalida l-isem tal-mudell fuq in-naħa tal-klijent meta `supports_websockets = true` u **jirrifjuta IDs bi prefiss tal-fornitur** bħal `codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account`). Ibgħat l-ID **sempliċi** (eż. `gpt-5.5`). Il-bridge ta’ OmniRoute huwa għal codex biss, għalhekk jerġa’ jirriżolvi ID sempliċi bħala mudell codex (`resolveCodexWsModelInfo`) qabel joħloq mina upstream — minkejja li `gpt-5.5` sempliċi normalment jiġi dirett lejn fornitur ieħor permezz ta’ HTTP. #### Konfigurazzjoni tal-OpenAI Codex CLI Idderieġi l-Codex CLI lejn OmniRoute billi żżid fornitur personalizzat b’appoġġ għal WebSocket ma’ `~/.codex/config.toml` (uża `CODEX_HOME` separat biex tevita li tibdel konfigurazzjoni eżistenti): ```toml model = "gpt-5.5" # ID sempliċi — MHUX "codex/gpt-5.5" model_provider = "omniroute" [model_providers.omniroute] name = "OmniRoute (WS)" base_url = "http://localhost:20128/v1" # mingħajr slash fl-aħħar; il-URL WS jiġi derivat (uża https/wss fil-produzzjoni) wire_api = "responses" # l-uniku valur appoġġjat minn Frar 2026 supports_websockets = true # jippermetti t-transport Responses-over-WS env_key = "OMNIROUTE_API_KEY" # iżomm iċ-ċavetta API ta’ OmniRoute (Bearer) ``` ```bash export OMNIROUTE_API_KEY=sk-... # ċavetta API ta’ OmniRoute (kwalunkwe ċavetta jekk REQUIRE_API_KEY=false) codex exec "Responda apenas: PONG" ``` Il-CLI jaġġorna `base_url + /responses` għal WebSocket u OmniRoute joħloq mina lejn il-konnessjoni OAuth ta’ codex magħżula. Ivvalidat minn tarf sa tarf mas-server lokali: ChatGPT jirritorna `codex.rate_limits` + `response.created` u jixxandar il-kompletament. --- ## Kwoti u Rappurtar ta’ Problemi | Metodu | Mogħdija | Deskrizzjoni | | ------ | ------------------- | ------------------------------------------------------------------------------------------------- | | GET | `/v1/quotas/check` | Ivvalida minn qabel il-kwota għal `provider` + `accountId` qabel ma tinħareġ ċavetta rreġistrata | | POST | `/v1/issues/report` | Irrapporta falliment fil-kwota/ħruġ taċ-ċavetta lil GitHub (jeħtieġ `GITHUB_ISSUES_REPO` + token) | **Awtentikazzjoni:** Ċavetta API Bearer (`isAuthenticated`). --- ## Użu self-service (`/api/usage/om-usage`) Kwalunkwe ċavetta API tista’ taqra l-użu u l-kwoti **tagħha stess** — mingħajr awtentikazzjoni tal-ġestjoni. Dan huwa l-endpoint li klijent (CLI, il-pannell OmniCopilot) juża biex juri lid-detentur taċ-ċavetta l-infiq tiegħu. ```bash # Format ta’ test (il-kuntratt storiku — test sempliċi għal terminal) curl -H "Authorization: Bearer " \ http://localhost:20128/api/usage/om-usage # Format strutturat — dak li tuża UI curl -H "Authorization: Bearer " \ "http://localhost:20128/api/usage/om-usage?format=json" ``` Iċ-ċavetta jrid ikollha **`allowUsageCommand`** attivat (diżattivat b’mod awtomatiku — il-maniġer taċ-ċwievet API tad-dashboard jaqilbu għal kull ċavetta). Mingħajru, l-endpoint iwieġeb `403`. `?format=json` jirritorna struttura diskriminata sabiex min isejjaħ qatt ma jaqra kamp tad-data minn rifjut. F’każ ta’ suċċess: ```jsonc { "allowed": true, // preżenti biss meta ċ-ċavetta tkun għażlet limiti tal-użu għal kull ċavetta (USD kuljum/kull ġimgħa): "personal": { "dailySpentUsd": 1.25, "dailyLimitUsd": 5, "dailyResetAtIso": "…", "weeklySpentUsd": 8, "weeklyLimitUsd": 20, "weeklyResetAtIso": "…" /* … */, }, // stampa tal-kwota tal-fornitur magħżul, jew null meta għad m’hemm xejn fil-cache: "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */}, }, // stampa ta’ kull konnessjoni, sabiex UI tkun tista’ tirrendi diversi fornituri maġenb xulxin: "providers": [ { "connectionId": "…", "provider": "claude" /* … */ }, { "provider": "codex" /* … */ }, ], } ``` F’każ ta’ rifjut (`401` ċavetta ħażina / `403` mhux permess), l-istess rotta tirritorna `{ "allowed": false, "error": { "message": "…" } }` — `personal`/`provider` preżenti iżda vojt (iċ-ċavetta permessa, iżda għadu ma nkiseb xejn) huwa stat differenti minn rifjut, u l-format JSON biss jiddistingwihom. **Awtentikazzjoni:** iċ-ċavetta API Bearer ta’ min isejjaħ stess, ivvalidata b’`isValidApiKey` — din _mhijiex_ l-interfaċċa tal-ġestjoni (`/api/keys/…`), li tibqa’ protetta minn `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 fil-cache semantiku jipprovdi r-rispons mill-cache **mingħajr sejħa upstream**, għalhekk il-`X-OmniRoute-Response-Latency` irrappurtat ikun qrib iż-żero (irrispettivament mil-latenza upstream oriġinali). Klijenti sensittivi għal-latenza (benchmarking, monitoraġġ p50/p99) għandhom jiċċekkjaw il-header tar-rispons `X-OmniRoute-Cache-Latency`: | Valur | Tifsira | | ----------- | ------------------------------------------------------------------- | | `synthetic` | Rispons ipprovdut mill-cache; il-latenza mhijiex ħin upstream reali | | _(assenti)_ | Rispons minn sejħa upstream reali | ### Qbiż tal-cache għal kull ċavetta Iċ-ċwievet API jistgħu jagħżlu li ma jużawx qari mill-cache semantiku permezz ta’ `cacheDefaultMode`: | Valur | Imġiba | | -------- | ------------------------------------------------------------- | | `legacy` | Imġiba normali tal-cache (awtomatika) | | `bypass` | Aqbeż kompletament it-tiftix fil-cache; dejjem uża l-upstream | Issettjah waqt il-ħolqien taċ-ċavetta (`POST /api/keys`) jew waqt aġġornament (`PATCH /api/keys/[id]`): ```json { "cacheDefaultMode": "bypass" } ``` ### Qbiż għal kull talba Kwalunkwe talba tista’ taqbeż il-cache irrispettivament mis-settings taċ-ċavetta: ``` X-OmniRoute-No-Cache: true ``` --- ## Dashboard u Ġestjoni Ir-rotot tal-ġestjoni (`/api/*` ħlief l-awtentikazzjoni/pubbliku u l-login) **mhumiex** awtorizzati permezz taċ-ċwievet API ordinarji tal-inferenza. Familji ta’ kredenzjali, ambiti, u eżempji ta’ curl: [Awtentikazzjoni tal-Ġestjoni](../guides/MANAGEMENT-AUTH.md). ### Awtentikazzjoni | Punt finali | Metodu | Deskrizzjoni | | ----------------------------- | ------- | ------------------------------------ | | `/api/auth/login` | POST | Idħol | | `/api/auth/logout` | POST | Oħroġ | | `/api/settings/require-login` | GET/PUT | Ixgħel jew itfi l-login obbligatorju | ### Ġestjoni tal-Fornituri | Punt finali | Metodu | Deskrizzjoni | | ---------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `/api/providers` | GET/POST | Elenka / oħloq fornituri | | `/api/providers/[id]` | GET/PUT/DELETE | Immaniġġja fornitur | | `/api/providers/[id]/test` | POST | Ittestja l-konnessjoni tal-fornitur | | `/api/providers/[id]/models` | GET | Elenka l-mudelli tal-fornitur | | `/api/providers/validate` | POST | Ivvalida l-konfigurazzjoni tal-fornitur | | `/api/providers/bulk` | POST | Żid bil-massa ċ-ċwievet API għal fornitur WIEĦED | | `/api/providers/import` | POST | Importa LISTA eteroġenja ta’ fornituri minn fajl CSV/JSON analizzat (#6836); riżultati ta’ falliment parzjali għal kull ringiela | | `/api/provider-nodes*` | Diversi | Ġestjoni tan-nodi tal-fornituri | | `/api/provider-models` | GET/POST/PATCH/DELETE | Mudelli personalizzati (żid, aġġorna, aħbi/uri, ħassar) | ### Flussi OAuth | Punt finali | Metodu | Deskrizzjoni | | -------------------------------- | ------- | ------------------------------ | | `/api/oauth/[provider]/[action]` | Diversi | OAuth speċifiku għall-fornitur | ### Rotot u Konfigurazzjoni | Punt finali | Metodu | Deskrizzjoni | | --------------------- | -------- | -------------------------------------------- | | `/api/models/alias` | GET/POST | Psewdonimi tal-mudelli | | `/api/models/catalog` | GET | Il-mudelli kollha skont il-fornitur + it-tip | | `/api/combos*` | Diversi | Ġestjoni tal-kombinazzjonijiet | | `/api/keys*` | Diversi | Ġestjoni taċ-ċwievet API | | `/api/pricing` | GET | Ipprezzar tal-mudelli | ### Użu u Analitika | Punt tat-tmiem | Metodu | Deskrizzjoni | | -------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/usage/history` | GET | Storja tal-użu | | `/api/usage/logs` | GET | Reġistri tal-użu | | `/api/usage/request-logs` | GET | Reġistri fil-livell tat-talba | | `/api/usage/[connectionId]` | GET | Użu għal kull konnessjoni | | `/api/usage/token-limits` | GET/POST/DELETE | Baġits tal-limitu ta’ tokens għal kull ċavetta tal-API | | `/api/usage/model-latency-stats` | GET | Aggregat kontinwu tal-latenza għal kull fornitur/mudell (medja/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 kitba/qari, distribuzzjoni p50/p90/p99 tad-daqs tal-kitba, konċentrazzjoni ta’ kitbiet intensivi, tqassim għal kull mudell, u verdett `healthy`/`degraded`/`thrash`/`no-data`; parametri tal-mistoqsija `range` (`1h`\|`24h`\|`7d`\|`30d`, valur predefinit `24h`) u `model` fakultattiv (#8827) | ### Settings | Punt tat-tmiem | Metodu | Deskrizzjoni | | ------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/settings` | GET/PUT/PATCH | Settings ġenerali | | `/api/settings/proxy` | GET/PUT | Konfigurazzjoni tal-proxy tan-network | | `/api/settings/proxy/test` | POST | Ittestja l-konnessjoni tal-proxy | | `/api/settings/ip-filter` | GET/PUT | Lista ta’ permessi/lista ta’ mblukkar tal-IP | | `/api/settings/thinking-budget` | GET/PUT | Modalità ta’ kitba mill-ġdid tat-**talba** għall-baġit tal-ħsieb/raġunament (mgħoddi kif inhu / tneħħija awtomatika / personalizzat / adattiv). Indipendenti mill-kompressjoni. Ara [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). | | `/api/settings/system-prompt` | GET/PUT | Prompt globali tas-sistema | | `/api/settings/compression` | GET/PUT | Konfigurazzjoni globali tal-kompressjoni | | `/api/settings/purge-request-history` | POST | Ħassar ir-ringieli tar-reġistru tat-talbiet u l-artifatti lokali tar-reġistru tas-sejħiet | ### Kuntest u Kompressjoni | Endpoint | Metodu | Deskrizzjoni | | -------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------ | | `/api/compression/preview` | POST | Previżjoni tal-kompressjoni off/lite/standard/aggressive/ultra/RTK/stacked | | `/api/compression/language-packs` | GET | Elenka l-pakketti lingwistiċi Caveman disponibbli | | `/api/compression/rules` | GET | Elenka l-metadejta 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 tal-output mhux ipproċessat | | `/api/context/rtk/filters` | GET | Katalgu tal-filtri RTK u dijanjostika tal-filtri personalizzati | | `/api/context/rtk/test` | POST | Ħaddem previżjoni/test RTK fuq payload ta’ test | | `/api/context/rtk/raw-output/[id]` | GET | Aqra l-output mhux ipproċessat u redatt miżmum permezz tal-id tal-pointer | | `/api/context/combos` | GET/POST | Elenka/oħloq kombinazzjonijiet tal-kompressjoni | | `/api/context/combos/[id]` | GET/PUT/DELETE | Dettalji/aġġornament/tħassir ta’ kombinazzjoni tal-kompressjoni | | `/api/context/combos/[id]/assignments` | GET/PUT | Assenja kombinazzjonijiet tal-kompressjoni lil kombinazzjonijiet tar-routing | | `/api/context/analytics` | GET | Alias tal-analitika tal-kompressjoni | ### Monitoraġġ | Endpoint | Metodu | Deskrizzjoni | | ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/sessions` | GET | Traċċar tas-sessjonijiet attivi | | `/api/rate-limits` | GET | Limiti tar-rata għal kull kont | | `/api/monitoring/health` | GET | Kontroll tas-saħħa + sommarju tal-fornitur (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Il-veduta tal-ġestjoni tinkludi `credentialHealth`: valuri skalari tal-cache tal-probes, `failedConnections` meta `failed>0`, u `staleDbNonOkCount` (`test_status` persistenti ta’ SQLite, mhux il-gauge). Ara [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). | | `/api/cache/stats` | GET/DELETE | Statistika tal-cache / neħħi l-cache | | `/api/modality-bridge/stats` | GET | `attempts` fil-memorja, suċċessi/`bridged`, fallimenti, hits tal-cache, `totalLatencyMs`, `latencySamples`, `averageLatencyMs` ibbażat fuq id-denominatur tal-kampjuni, u l-ħin tal-aħħar użu (jiġi ssettjat mill-ġdid meta jerġa’ jibda; awtentikazzjoni tal-ġestjoni) | | `/api/modality-bridge/video/runtime` | GET | Kontroll strett ta’ loopback fdat qabel l-awtentikazzjoni/probe tal-ġestjoni; disponibbiltà u verżjonijiet sanitizzati ta’ FFmpeg/ffprobe (no-store) | | `/api/modality-bridge/video/extract` | POST | Broker intern awtentikat tal-bytes permezz ta’ loopback fdat; input ta’ 50 MiB, kju limitat/output ta’ 32 MiB, kapaċità `503`, skonnessjoni `499`, skadenza `504`; mhix API pubblika għat-tlugħ ta’ fajls | ### Backup u Esportazzjoni/Importazzjoni | Endpoint | Metodu | Deskrizzjoni | | --------------------------- | ------ | -------------------------------------------------- | | `/api/db-backups` | GET | Elenka l-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 id-database bħala fajl .sqlite | | `/api/db-backups/import` | POST | Tella' fajl .sqlite biex tissostitwixxi d-database | | `/api/db-backups/exportAll` | GET | Niżżel backup sħiħ bħala arkivju .tar.gz | ### Sinkronizzazzjoni mal-Cloud | Endpoint | Metodu | Deskrizzjoni | | ---------------------- | ------- | ----------------------------------------------- | | `/api/sync/cloud` | Diversi | Operazzjonijiet ta' sinkronizzazzjoni mal-cloud | | `/api/sync/initialize` | POST | Inizjalizza s-sinkronizzazzjoni | | `/api/cloud/*` | Diversi | Ġestjoni tal-cloud | ### Tunnels | Endpoint | Metodu | Deskrizzjoni | | -------------------------- | ------ | ---------------------------------------------------------------------------------------- | | `/api/tunnels/cloudflared` | GET | Aqra l-istatus tal-installazzjoni/eżekuzzjoni ta' Cloudflare Quick Tunnel għad-dashboard | | `/api/tunnels/cloudflared` | POST | Ippermetti jew iddiżattiva Cloudflare Quick Tunnel (`action=enable/disable`) | | `/api/tunnels/ngrok` | GET | Aqra l-istatus tal-eżekuzzjoni ta' ngrok Tunnel għad-dashboard | | `/api/tunnels/ngrok` | POST | Ippermetti jew iddiżattiva ngrok Tunnel (`action=enable/disable`) | ### Għodod tas-CLI | Endpoint | Metodu | Deskrizzjoni | | ---------------------------------- | ------ | ---------------------------------------- | | `/api/cli-tools/claude-settings` | GET | Status tas-CLI ta' Claude | | `/api/cli-tools/codex-settings` | GET | Status tas-CLI ta' Codex | | `/api/cli-tools/droid-settings` | GET | Status tas-CLI ta' Droid | | `/api/cli-tools/openclaw-settings` | GET | Status tas-CLI ta' OpenClaw | | `/api/cli-tools/runtime/[toolId]` | GET | Ambjent ta' eżekuzzjoni ġeneriku tas-CLI | It-tweġibiet tas-CLI jinkludu: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. ### Aġenti ACP | Endpoint | Metodu | Deskrizzjoni | | ----------------- | ------ | ----------------------------------------------------------------------------------- | | `/api/acp/agents` | GET | Elenka l-aġenti kollha identifikati (integrati + personalizzati) bl-istatus tagħhom | | `/api/acp/agents` | POST | Żid aġent personalizzat jew aġġorna l-cache tal-identifikazzjoni | | `/api/acp/agents` | DELETE | Neħħi aġent personalizzat permezz tal-parametru tal-query `id` | It-tweġiba GET tinkludi `agents[]` (id, name, binary, version, installed, protocol, isCustom) u `summary` (total, installed, notFound, builtIn, custom). ### Reżiljenza u Limiti tar-Rata | Endpoint | Metodu | Deskrizzjoni | | --------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------- | | `/api/resilience` | GET/PATCH | Ikseb/aġġorna l-kju tat-talbiet, il-perjodu ta' stennija tal-konnessjoni, il-breaker tal-fornitur u s-settings tal-istennija | | `/api/resilience/reset` | POST | Irrisettja s-circuit breakers tal-fornituri | | `/api/resilience/model-cooldowns` | GET | Elenka l-lockouts attivi għal kull (fornitur, konnessjoni, mudell), magħżula skont il-ħin li fadal | | `/api/resilience/model-cooldowns` | DELETE | Neħħi lockout ta' mudell — body `{provider, model}` jew `{all: true}` biex tħassar kollox | | `/api/rate-limits` | GET | Status tal-limitu tar-rata għal kull kont | | `/api/rate-limit` | GET | Konfigurazzjoni globali tal-limitu tar-rata | > L-erba' rotot `/api/resilience/*` kollha jeħtieġu **awtentikazzjoni tal-ġestjoni** (`requireManagementAuth`). Ara [Reżiljenza (estiża)](#resilience-extended) għal analiżi sħiħa tad-differenza bejn il-breaker tal-fornitur, il-perjodu ta' stennija tal-konnessjoni u l-lockout tal-mudell. ### Evalwazzjonijiet | Endpoint | Metodu | Deskrizzjoni | | ------------ | -------- | --------------------------------------------------------- | | `/api/evals` | GET/POST | Elenka s-settijiet ta' evalwazzjoni / wettaq evalwazzjoni | ### Politiki | Endpoint | Metodu | Deskrizzjoni | | --------------- | --------------- | --------------------------------- | | `/api/policies` | GET/POST/DELETE | Immaniġġja l-politiki tar-routing | ### Konformità | Endpoint | Metodu | Deskrizzjoni | | --------------------------- | ------ | ------------------------------------------------ | | `/api/compliance/audit-log` | GET | Reġistru tal-awditjar tal-konformità (l-aħħar N) | ### v1beta (Kompatibbli ma' Gemini) | Endpoint | Metodu | Deskrizzjoni | | -------------------------- | ------ | -------------------------------------- | | `/v1beta/models` | GET | Elenka l-mudelli fil-format ta' Gemini | | `/v1beta/models/{...path}` | POST | Endpoint `generateContent` ta' Gemini | Dawn l-endpoints jirriflettu l-format tal-API ta' Gemini għall-klijenti li jistennew kompatibbiltà nattiva mal-SDK ta' Gemini. ### APIs Interni / tas-Sistema | Endpoint | Metodu | Deskrizzjoni | | ------------------------ | ------ | ------------------------------------------------------------------------- | | `/api/init` | GET | Verifika tal-inizjalizzazzjoni tal-applikazzjoni (użata fl-ewwel tħaddim) | | `/api/tags` | GET | Tikketti tal-mudelli kompatibbli ma’ Ollama (għall-klijenti Ollama) | | `/api/restart` | POST | Jiskatta ristartjar gradwali tas-server | | `/api/shutdown` | POST | Jiskatta għeluq gradwali tas-server | | `/api/system/env/repair` | POST | Isewwi l-varjabbli tal-ambjent tal-fornitur OAuth | > **Nota:** Dawn l-endpoints jintużaw internament mis-sistema jew għall-kompatibbiltà mal-klijenti Ollama. Normalment ma jissejħux mill-utenti finali. ### Tiswija tal-Ambjent OAuth _(v3.6.1+)_ ```bash POST /api/system/env/repair Content-Type: application/json { "provider": "claude-code" } ``` Isewwi varjabbli tal-ambjent OAuth neqsin jew korrotti għal fornitur speċifiku. Jirritorna: ```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 ``` Ittraskrivi fajls tal-awdjo billi tuża kwalunkwe fornitur STT ikkonfigurat. L-ewwel segment tal-mogħdija jagħżel il-fornitur nattiv (`openai/…`, `deepgram/…`). Gateways li jerġgħu jesponu l-mudell ta’ fornitur ieħor jużaw 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" ``` **Risposta:** ```json { "text": "Bonġu, dan huwa l-kontenut tal-awdjo traskritt.", "task": "transcribe", "language": "en", "duration": 12.5 } ``` **Eżempji ta’ ids tal-mudelli:** `openai/whisper-1` (jeħtieġ ċavetta ta’ OpenAI), `openrouter/deepgram/nova-3` (jeħtieġ ċavetta ta’ OpenRouter), `deepgram/nova-3` (jeħtieġ ċavetta nattiva ta’ Deepgram). Talba sempliċi għal `deepgram/nova-3` **ma** tużax OpenRouter. **Formati appoġġjati:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- ## Kompatibbiltà ma’ Ollama Għal klijenti li jużaw il-format tal-API ta’ Ollama: ```bash # Endpoint taċ-chat (format ta’ Ollama) POST /v1/api/chat # Elenkar tal-mudelli (format ta’ Ollama) GET /api/tags ``` It-talbiet jiġu tradotti awtomatikament bejn il-formati ta’ Ollama u dawk interni. ## Aliases Tokenizzati għal VS Code / Mingħajr Header Uża dawn l-aliases meta integrazzjoni ma tkunx tista’ ddaħħal header `Authorization` u jkollha bżonn li ċ-ċavetta tal-API tkun inkorporata fil-URL bażi. ```bash # Alias tal-katalgu bl-istil ta’ OpenAI GET /api/v1/vscode/{token}/ GET /api/v1/vscode/{token}/models # Aliases taċ-chat bl-istil ta’ OpenAI POST /api/v1/vscode/{token}/chat/completions POST /api/v1/vscode/{token}/responses # Aliases bl-istil ta’ 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-aliases tokenizzati jerġgħu jużaw l-istess handlers bħal `/v1/*` u `/api/tags`; il-forom tar-risposti jibqgħu identiċi. - Ippreferi `Authorization: Bearer ...` kull meta l-klijent jappoġġja headers personalizzati. - Tokens ibbażati fuq URL jistgħu jidhru fil-logs tar-reverse proxy, fl-istorja tal-brawżer u fit-telemetrija barra OmniRoute. Ittrattahom bħala għażla ta’ kompatibbiltà, mhux bħala l-modalità ta’ awtentikazzjoni predefinita. --- ## Telemetrija ```bash # Ikseb sommarju tat-telemetrija tal-latenza (p50/p95/p99 għal kull fornitur) GET /api/telemetry/summary ``` **Risposta:** ```json { "providers": { "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } } } ``` --- ## Baġit ```bash # Ikseb l-istatus tal-baġit għaċ-ċwievet kollha tal-API GET /api/usage/budget # Issettja 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 dwar l-iskema** (`setBudgetSchema`): `apiKeyId` huwa meħtieġ; mill-inqas wieħed minn `dailyLimitUsd`, `weeklyLimitUsd`, jew `monthlyLimitUsd` irid ikun akbar minn żero. Oqsma fakultattivi: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Il-format l-antik `{keyId, limit, period}` jirritorna `400 Bad Request`. ## Limiti tat-Tokens Baġits ta' **tokens** għal kull ċavetta API (distinti mill-Baġit ibbażat fuq USD imsemmi hawn fuq). Dawn jiġu infurzati direttament fil-perkors tat-talba: meta l-użu tat-tieqa attwali ta' ċavetta jilħaq il-limitu tagħha, it-talbiet jiġu miċħuda b'`429 Too Many Requests`. Il-limiti jistgħu jiġu ristretti għal `model` speċifiku, għal `provider`, jew jiġu applikati `global`ment fuq iċ-ċavetta kollha; meta diversi limiti jaqblu ma' talba, japplika l-aktar wieħed restrittiv. ```bash # Elenka l-limiti tat-tokens ta' ċavetta (jinkludi l-użu attwali tat-tieqa) GET /api/usage/token-limits?apiKeyId=key-123 # Oħloq jew aġġorna limitu tat-tokens POST /api/usage/token-limits Content-Type: application/json { "apiKeyId": "key-123", "scopeType": "model", "scopeValue": "openai/gpt-4o", "tokenLimit": 1000000, "resetInterval": "monthly", "enabled": true } # Ħassar limitu tat-tokens skont l-id DELETE /api/usage/token-limits?id=tl-abc ``` > **Noti dwar l-iskema** (`setTokenLimitSchema`): `apiKeyId` u `scopeType` (`model` | `provider` | `global`) huma obbligatorji. `scopeValue` huwa obbligatorju sakemm `scopeType` ma jkunx `global` (eż. id ta' mudell għall-ambitu `model`, jew id ta' fornitur għall-ambitu `provider`). `tokenLimit` irid ikun numru sħiħ pożittiv (ikkonvertit minn string). Fakultattivi: `id` (ħallih barra biex toħloq, inkludih biex taġġorna), `resetInterval` (`daily` | `weekly` | `monthly`, valur predefinit `monthly`), `resetTime` (`HH:MM`), `enabled` (valur predefinit `true`). It-tweġibiet `GET` jarrikkixxu kull limitu b'`tokensUsed`, `remaining`, `windowStart`, `periodStartAt`, u `nextResetAt`. Dan huwa endpoint tal-klassi ta' ġestjoni (l-awtentikazzjoni tiġi infurzata ċentralment mill-pipeline tal-awtorizzazzjoni). ## Ipproċessar tat-Talbiet 1. Il-klijent jibgħat talba lil `/v1/*` 2. Il-handler tar-rotta jsejjaħ `handleChat`, `handleEmbedding`, `handleAudioTranscription`, jew `handleImageGeneration` 3. Il-mudell jiġi riżolt (fornitur/mudell dirett jew alias/combo) 4. Il-kredenzjali jintgħażlu mid-DB lokali b'filtrazzjoni skont id-disponibbiltà tal-kont 5. Għaċ-chat: `handleChatCore` jiċċekkja l-cache semantika/tal-firma u jirriżolvi s-settings tal-kompressjoni tal-combo 6. Il-kompressjoni proattiva titħaddem qabel it-traduzzjoni tal-fornitur meta tkun attivata (`lite`, Caveman, RTK, jew f'saffi) 7. L-eżekutur tal-fornitur jibgħat it-talba upstream 8. It-tweġiba tiġi tradotta lura għall-format tal-klijent (chat) jew tintbagħat kif inhi (embeddings/immaġnijiet/awdjo) 9. L-użu, l-analitika tal-kompressjoni, u l-logs tat-talbiet jiġu rreġistrati 10. Il-fallback japplika f'każ ta' żbalji skont ir-regoli tal-combo Referenza sħiħa tal-arkitettura: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md) --- ## Ġestjoni tal-Combos Combos ta' routing ta' livell ogħla (diġà miġbura fil-qosor taħt `/api/combos*`) jistgħu wkoll jiġu mmappjati 1:1 minn mudell ta' id tal-mudell, biex b'hekk tkun possibbli direzzjoni mill-ġdid trasparenti ta' id ta' mudell bi stil OpenAI lejn combo. | Metodu | Perkors | Deskrizzjoni | | ------ | -------------------------------- | ------------------------------------------------------------------------------- | | GET | `/api/model-combo-mappings` | Elenka l-immappjar kollu minn mudell għal combo | | POST | `/api/model-combo-mappings` | Oħloq immappjar — body: `{pattern, comboId, priority?, enabled?, description?}` | | GET | `/api/model-combo-mappings/[id]` | Irċievi immappjar wieħed | | PUT | `/api/model-combo-mappings/[id]` | Aġġorna l-fields ta' immappjar eżistenti | | DELETE | `/api/model-combo-mappings/[id]` | Neħħi immappjar | **Awtentikazzjoni:** sessjoni/ċavetta API ta' ġestjoni (`requireManagementAuth`). --- ## Webhooks Abbonamenti għal webhooks ħerġin għal avvenimenti ta’ OmniRoute (tlestija ta’ talba, eżawriment tal-kwota, rotazzjoni taċ-ċwievet, eċċ.). | Metodu | Mogħdija | Deskrizzjoni | | ------ | ------------------------- | ------------------------------------------------------------------------------ | | GET | `/api/webhooks` | Elenka l-webhooks (is-sigrieti jiġu moħbija bħala `...`) | | POST | `/api/webhooks` | Oħloq webhook — body: `{url, events?: ["*"], secret?, description?}` | | GET | `/api/webhooks/[id]` | Irċievi webhook | | PUT | `/api/webhooks/[id]` | Aġġorna url/events/secret/description | | DELETE | `/api/webhooks/[id]` | Neħħi webhook | | POST | `/api/webhooks/[id]/test` | Ibgħat payload tat-test lill-URL tal-webhook u rritorna l-istatus tal-konsenja | **Awtentikazzjoni:** sessjoni ta’ ġestjoni/ċavetta tal-API (`requireManagementAuth`). --- ## Ċwievet Irreġistrati (Ġestjoni Awtomatika) Użati mis-subsistema tal-ġestjoni awtomatika taċ-ċwievet biex toħroġ u ddawwar ċwievet tal-API ma’ fornitur/kont sottostanti, bi kwoti ta’ kuljum/kull siegħa. | Metodu | Mogħdija | Deskrizzjoni | | ------ | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/registered-keys` | Elenka ċ-ċwievet irreġistrati (il-prefiss moħbi biss) | | POST | `/api/v1/registered-keys` | Oħroġ ċavetta rreġistrata ġdida — body: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Jirritorna ċ-ċavetta mhux moħbija **darba biss**. Jirritorna `429` jekk il-kwota tirrifjuta t-talba. | | GET | `/api/v1/registered-keys/[id]` | Irċievi l-metadata ta’ ċavetta rreġistrata (mingħajr materjal mhux moħbi) | | DELETE | `/api/v1/registered-keys/[id]` | Irrevoka ċavetta rreġistrata | | POST | `/api/v1/registered-keys/[id]/revoke` | Endpoint espliċitu għar-revoka (l-istess effett bħal DELETE) | **Awtentikazzjoni:** ċavetta tal-API Bearer (`isAuthenticated`). Ara wkoll `/v1/quotas/check` u `/v1/issues/report`. --- ## Protokoll tal-Aġenti Kompiti tal-aġenti tal-cloud (Claude Code, Codex Cloud, OpenHands, eċċ.) eżegwiti mill-bogħod f’isem l-utenti ta’ OmniRoute. | Metodu | Mogħdija | Deskrizzjoni | | ------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/agents/tasks` | Elenka l-kompiti — `?provider=`, `?status=`, `?limit=` fakultattivi (1–500, valur predefinit 50) | | POST | `/api/v1/agents/tasks` | Oħloq kompitu — il-korp jiġi vvalidat minn `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Jirritorna `201` bl-envelop tal-kompitu | | DELETE | `/api/v1/agents/tasks?id=...` | Ħassar kompitu | | GET | `/api/v1/agents/tasks/[id]` | Aqra kompitu — jaġġorna b’mod sinkroniku l-istatus mill-aġent tal-cloud upstream meta jkun issettjat `external_id` | | POST | `/api/v1/agents/tasks/[id]` | Azzjoni diskriminata: `{action: "approve"}`, `{action: "message", message}`, jew `{action: "cancel"}` | | DELETE | `/api/v1/agents/tasks/[id]` | Ħassar kompitu speċifiku skont l-id | > **Awtentikazzjoni:** hija meħtieġa awtentikazzjoni tal-ġestjoni għal kull metodu (`requireCloudAgentManagementAuth`). Qabel v3.8.0 dawn ma kinux jeħtieġu awtentikazzjoni — ara l-commit `588a0333` għall-bidla inkompatibbli. ```bash # Oħloq kompitu tal-cloud ta’ 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 HTTP(S)/SOCKS ħerġin li jistgħu jiġu assenjati lil providers, kontijiet, jew globalment. | Metodu | Mogħdija | Deskrizzjoni | | ------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/management/proxies` | Elenka l-proxies (b’`?id=` jirritorna wieħed; b’`?id=&where_used=1` jirritorna l-graff tal-assenjamenti) | | POST | `/api/v1/management/proxies` | Oħloq proxy — il-korp jiġi vvalidat minn `createProxyRegistrySchema` | | PATCH | `/api/v1/management/proxies` | Aġġorna proxy — il-korp jiġi vvalidat minn `updateProxyRegistrySchema` (jeħtieġ `id`) | | DELETE | `/api/v1/management/proxies?id=...&force=1` | Ħassar proxy (uża `force=1` biex tneħħi l-assenjamenti) | | GET | `/api/v1/management/proxies/assignments` | Elenka l-assenjamenti — jistgħu jiġu ffiltrati skont `proxy_id`, `scope`, `scope_id`; għaddi `resolve_connection_id=` biex tiddetermina l-proxy attiv għal konnessjoni | | PUT | `/api/v1/management/proxies/assignments` | Assenja — il-korp jiġi vvalidat minn `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Inaddaf il-cache tad-dispatcher | | PUT | `/api/v1/management/proxies/bulk-assign` | Assenja bil-massa — il-korp jiġi vvalidat minn `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) | | GET | `/api/v1/management/proxies/health?hours=24` | Stat aggregat tas-saħħa tal-proxy (għadd ta’ suċċessi/fallimenti, latenza) fuq perjodu ta’ żmien | **Awtentikazzjoni:** sessjoni tal-ġestjoni/ċavetta API fuq kull rotta (`requireManagementAuth`). > Id-deskrizzjoni tal-kompitu ssemmi `POST /api/v1/management/proxies/[id]/assignments` u `POST /api/v1/management/proxies/[id]/health`, iżda dawn huma moqdija mir-rotot ċatti `/assignments` u `/health` murija hawn fuq — fil-codebase ma hemm l-ebda subrotta għal kull id. --- ## Reżiljenza (estiża) OmniRoute jesponi tliet mekkaniżmi indipendenti għal ħsarat temporanji; l-endpoints ta’ ġestjoni hawn taħt jippermettu lill-operaturi jaqrawhom u jissovrascrivuhom: | Ambitu | Ħażna tal-istat | Qari | Irrisettjar / tneħħija | | ------------------------------------ | ------------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------- | | Interruttur tal-fornitur | `domain_circuit_breakers` + fil-memorja | `/api/monitoring/health` | `POST /api/resilience/reset` | | Perjodu ta’ stennija tal-konnessjoni | `rateLimitedUntil` fuq il-konnessjonijiet tal-fornitur | `/api/rate-limits`, `/api/providers/[id]` | (jerġa’ jiġi attivat b’mod differit; neħħih permezz ta’ PUT tal-fornitur) | | Imblukkar tal-mudell | Reġistru fil-memorja tad-disponibbiltà tal-mudelli | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` | `PATCH /api/resilience` jaċċetta sovrascrizzjonijiet tal-interruttur tal-fornitur taħt `providerBreaker.oauth` u `providerBreaker.apikey`. Kull profil jappoġġja `degradationThreshold`, `failureThreshold`, u `resetTimeoutMs`; l-istess oqsma huma disponibbli f’Dashboard → Settings → Resilience. ```bash # Neħħi mblukkar ta’ mudell wieħed 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"}' # Neħħi l-imblukkar kollu curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \ -H "Cookie: auth_token=..." \ -d '{"all":true}' ``` Għar-referenza kunċettwali sħiħa u l-valuri awtomatiċi tal-interruttur: ara [`CLAUDE.md`](../../CLAUDE.md) → "Resilience Runtime State". --- ## Ħiliet Qafas ta’ ħiliet għall-estensjoni ta’ OmniRoute b’handlers eżegwibbli personalizzati, flimkien ma’ integrazzjonijiet ma’ swieq. | Metodu | Mogħdija | Deskrizzjoni | | ------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/skills` | Elenka l-ħiliet installati — jistgħu jiġu ffiltrati permezz ta’ `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, b’paġinazzjoni | | GET | `/api/skills/[id]` | Irkupra ħila waħda | | PUT | `/api/skills/[id]` | Aġġorna ħila (isem, deskrizzjoni, modalità, skema, handler, tikketti) | | DELETE | `/api/skills/[id]` | Iddiżinstalla ħila | | POST | `/api/skills/install` | Installa ħila minn manifest mhux ipproċessat — body: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` | | GET | `/api/skills/executions` | Elenka l-eżekuzzjonijiet reċenti tal-ħiliet (rekord tal-awditjar b’inputs/outputs/tul ta’ żmien) | | GET | `/api/skills/marketplace?q=...` | Fittex/lista popolari mis-suq SkillsMP (teħtieġ l-issettjar `skillsmpApiKey`) | | POST | `/api/skills/marketplace/install` | Installa ħila skont l-id minn SkillsMP | | GET | `/api/skills/skillssh?q=&limit=` | Fittex fir-reġistru skills.sh | | POST | `/api/skills/skillssh/install` | Installa ħila skont l-id minn skills.sh | **Awtentikazzjoni:** sessjoni ta’ ġestjoni/API key. Ir-rotot tat-tiftix fis-suq jaċċettaw jew awtentikazzjoni ta’ ġestjoni jew Bearer API key (`isAuthenticated`). --- ## Memorja Ħażna persistenti ta’ memorja konverżazzjonali/fattwali, limitata għal kull ċavetta tal-API / sessjoni. | Metodu | Mogħdija | Deskrizzjoni | | ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/memory` | Elenka l-memorji — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, b’paġinazzjoni permezz ta’ `offset/limit` jew `page/limit` | | POST | `/api/memory` | Oħloq memorja — il-body jiġi vvalidat minn Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` | | GET | `/api/memory/[id]` | Irkupra memorja waħda | | DELETE | `/api/memory/[id]` | Ħassar memorja | | GET | `/api/memory/health` | Stat tas-sottosistema tal-memorja (konnettività mad-DB, backend tal-embeddings, stat tal-indiċi vettorjali) | **Awtentikazzjoni:** sessjoni ta’ ġestjoni/ċavetta tal-API (`requireManagementAuth`). Enum `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (ara `MemoryType` f’`src/lib/memory/types.ts`). --- ## Server MCP OmniRoute jinkludi server inkorporat tal-Model Context Protocol bi 3 mezzi ta’ trasport (stdio, SSE, streamable-http) u għodod b’ambitu definit. L-endpoints tad-dashboard hawn taħt jaqraw id-data tal-istat/awditjar u jagħmlu proxy tat-trasporti HTTP. | Metodu | Mogħdija | Deskrizzjoni | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- | | GET | `/api/mcp/status` | Heartbeat, trasport, stat online, l-aħħar sejħa, l-aktar għodod użati, rata ta’ suċċess fuq 24 siegħa | | GET | `/api/mcp/tools` | Lista ta’ għodod MCP b’`name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` | | GET | `/api/mcp/sse` | Iftaħ fluss SSE għat-trasport SSE (jirritorna `503` jekk MCP ikun diżattivat jew jekk it-trasport ma jaqbilx) | | POST | `/api/mcp/sse` | Ibgħat frame JSON-RPC fuq it-trasport SSE | | GET | `/api/mcp/stream` | Iftaħ in-naħa SSE tat-trasport Streamable HTTP (messaġġi mibdija mis-server) | | POST | `/api/mcp/stream` | Ibgħat frame JSON-RPC fuq it-trasport Streamable HTTP | | DELETE | `/api/mcp/stream` | Temm sessjoni Streamable HTTP | | GET | `/api/mcp/audit` | Fittex fir-reġistru tal-awditjar — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` | | GET | `/api/mcp/audit/stats` | Statistika aggregata tal-awditjar (totali, rata ta’ suċċess, durata medja, l-aktar għodod użati) | **Awtentikazzjoni:** it-trasporti `sse`/`stream` jirrispettaw is-superfiċje ta’ awtentikazzjoni speċifika għall-MCP (ċavetta tal-API Bearer bl-ambitu `mcp`); ir-rotot `status`/`tools`/`audit*` jistgħu jinqraw mid-dashboard (ma hija meħtieġa ebda awtentikazzjoni addizzjonali lil hinn mill-aċċess għall-host tad-dashboard). > Iż-żewġ trasporti HTTP huma kkontrollati minn `settings.mcpEnabled` u `settings.mcpTransport` — nuqqas ta’ qbil fit-trasport jirritorna `400`, filwaqt li stat fejn MCP ikun diżattivat jirritorna `503`. --- ## Server A2A OmniRoute jesponi endpoint A2A (Minn Aġent għal Aġent) JSON-RPC 2.0 flimkien ma’ saff REST għall-ispezzjoni/użu fid-dashboard. ### JSON-RPC ```bash POST /a2a Authorization: Bearer your-api-key # fakultattiv sakemm OMNIROUTE_API_KEY ma jkunx issettjat Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "method": "message/send", "params": { "skill": "smart-routing", "messages": [{"role": "user", "content": "Idderieġi dan il-kompitu tal-ipprogrammar"}] } } ``` Metodi appoġġjati (kollha kkontrollati minn `settings.a2aEnabled`): | Metodu | Deskrizzjoni | | ---------------- | ------------------------------------------------------------------------- | | `message/send` | Eżekuzzjoni sinkronika tal-ħila; tirritorna `{task, artifacts, metadata}` | | `message/stream` | Eżekuzzjoni SSE bi streaming tal-istess sett ta’ ħiliet | | `tasks/get` | Iġib kompitu permezz ta’ `taskId` | | `tasks/cancel` | Jikkanċella kompitu permezz ta’ `taskId` | Ħiliet integrati: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`. ### Kard tal-Aġent ```bash GET /.well-known/agent.json ``` Jirritorna l-kard pubblika tal-aġent A2A (isem, deskrizzjoni, kapaċitajiet, katalgu tal-ħiliet, skema tal-awtentikazzjoni) — maħżuna pubblikament fil-cache għal siegħa. Ma hija meħtieġa l-ebda awtentikazzjoni. ### Għodod ta’ għajnuna REST | Metodu | Mogħdija | Deskrizzjoni | | ------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- | | GET | `/api/a2a/status` | A2A attivat + statistika tal-kompiti + sommarju tal-kard tal-aġent maħżuna fil-cache | | GET | `/api/a2a/tasks` | Elenka l-kompiti — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` | | POST | `/api/a2a/tasks` | (Mhux implimentat bħala għodda ta’ għajnuna REST — oħloq permezz ta’ JSON-RPC `message/send`) | | GET | `/api/a2a/tasks/[id]` | Irkupra kompitu wieħed | | POST | `/api/a2a/tasks/[id]/cancel` | Ikkanċella kompitu | **Awtentikazzjoni:** l-għodod ta’ għajnuna REST jaħdmu mingħajr awtentikazzjoni tal-ġestjoni (jistgħu jinqraw mid-dashboard); ir-rotta JSON-RPC `/a2a` tuża Bearer `OMNIROUTE_API_KEY` jekk din tkun ikkonfigurata. --- ## Cloud, Evalwazzjonijiet u Valutazzjoni | Metodu | Mogħdija | Deskrizzjoni | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- | | POST | `/api/cloud/auth` | Jivverifika ċavetta Bearer u jirritorna konnessjonijiet moħbija tal-fornituri + psewdonimi tal-mudelli għall-klijenti tas-sinkronizzazzjoni mal-cloud | | POST | `/api/cloud/credentials/update` | Jaġġorna l-kredenzjali kriptati għal fornitur sinkronizzat mal-cloud | | POST | `/api/cloud/model/resolve` | Jikkonverti id loġiku ta’ mudell għal fornitur/mudell konkret permezz tat-tabella tar-rotot lokali | | GET | `/api/cloud/models/alias` | Jelenka l-psewdonimi tal-mudelli kif esposti għas-sinkronizzazzjoni mal-cloud | | GET | `/api/assess` | Jaqra l-aħħar kategorizzazzjonijiet tal-valutazzjoni (għal kull fornitur/mudell) | | POST | `/api/assess` | Iħaddem valutazzjoni — korp: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` | | GET | `/api/evals` | Jelenka s-suites ta’ evalwazzjoni integrati + l-aktar eżekuzzjonijiet reċenti | | POST | `/api/evals` | Jiskatta eżekuzzjoni ta’ evalwazzjoni | | POST | `/api/evals/suites` | Joħloq suite ta’ evalwazzjoni personalizzata — il-korp jiġi vvalidat minn `evalSuiteSaveSchema` | | GET | `/api/evals/suites/[id]` | Jirkupra suite ta’ evalwazzjoni personalizzata | **Awtentikazzjoni:** `/api/cloud/auth` jivvalida ċavetta Bearer direttament; ir-rotot l-oħra `/api/cloud/*`, `/api/evals/*`, u `/api/assess` jeħtieġu sessjoni/ċavetta API tal-ġestjoni. POST għal `/api/assess` juża `validateBody` bi skema tal-kamp ta’ applikazzjoni tat-tip unjoni diskriminata. --- ## Ġestjoni tal-ACP (Agent Client Protocol) bħala proċessi sekondarji. Dawn l-endpoints jimmaniġġjaw l-iskoperta tal-aġenti ACP u r-reġistrazzjoni ta’ aġenti personalizzati. | Metodu | Mogħdija | Deskrizzjoni | | ------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/acp/agents` | Elenka l-aġenti CLI magħrufa kollha (inkorporati + personalizzati), flimkien mal-istat tal-installazzjoni, il-verżjoni u l-binarju | | POST | `/api/acp/agents` | Irreġistra aġent ACP personalizzat jew aġġorna l-cache — korp: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` jew `{action: "refresh"}` | | DELETE | `/api/acp/agents` | Neħħi aġent ACP personalizzat — parametru tal-query: `?id=` | **Eżempju ta’ rispons** (`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 } ``` **Awtentikazzjoni:** Teħtieġ sessjoni ta’ ġestjoni (cookie `auth_token` tad-dashboard) jew ċavetta API b’ambitu ta’ ġestjoni. Ara [Il-Qafas ACP](../frameworks/ACP.md) għad-dettalji kollha. --- ## Analitika u Osservabbiltà Endpoints tal-analitika f’ħin reali għall-monitoraġġ tar-routing, il-kompressjoni u d-diversità tal-fornituri. Dawn iħaddmu l-paġni `/dashboard/analytics/*`. ### Analitika tar-routing awtomatiku | Metodu | Mogħdija | Deskrizzjoni | | ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/analytics/auto-routing` | Statistika aggregata tar-routing awtomatiku: sejħiet totali, distribuzzjoni tal-istrateġiji, distribuzzjoni tal-livelli, l-aktar fornituri użati | | GET | `/api/analytics/auto-routing?days=7` | Statistika għal perjodu ta’ żmien speċifikat (24 siegħa b’mod predefinit) | **Eżempju ta’ rispons**: ```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 } ] } ``` ### Analitika tal-kompressjoni | Metodu | Mogħdija | Deskrizzjoni | | ------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/compression` | Statistika aggregata tal-kompressjoni: tokens iffrankati, % ta’ ffrankar, distribuzzjoni tal-modi, użu tal-magna | **Eżempju ta’ rispons**: ```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 tad-diversità tal-fornituri | Metodu | Mogħdija | Deskrizzjoni | | ------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/analytics/diversity` | Traċċar tad-diversità bbażat fuq l-entropija ta’ Shannon: jipprevjeni punti uniċi ta’ falliment billi jkejjel il-firxa tal-fornituri | **Eżempju ta’ rispons**: ```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"] } ``` **Awtentikazzjoni:** Teħtieġ sessjoni ta’ ġestjoni jew ċavetta API b’ambitu ta’ ġestjoni. --- ## Operazzjonijiet tal-Amministratur Endpoints għall-amministraturi biss għall-ġestjoni operazzjonali. | Metodu | Mogħdija | Deskrizzjoni | | ------ | ------------------------ | -------------------------------------------------------------------------------------------------- | | GET | `/api/admin/concurrency` | Aqra l-limiti attwali tal-konkorrenza (globali + għal kull fornitur) | | POST | `/api/admin/concurrency` | Aġġorna l-limiti tal-konkorrenza — body: `{global?: number, perProvider?: Record}` | **Awtentikazzjoni:** Teħtieġ sessjoni ta’ ġestjoni b’ambitu ta’ amministratur. --- ## Ġestjoni tal-Għodod CLI Immaniġġja l-għodod CLI li jintegraw ma’ OmniRoute (antigravity, chipotle, commandCode, devin-cli, eċċ.). Ara r-[Referenza tal-Fornituri](./PROVIDER_REFERENCE.md) għal-lista sħiħa. | Metodu | Mogħdija | Deskrizzjoni | | ------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/cli-tools/all-statuses` | Status tal-għodod CLI kollha (installati, verżjoni, l-aħħar darba li dehru) | | GET | `/api/cli-tools/status` | Dettalji tal-istatus għal għodda CLI waħda (query `?tool=`) | | POST | `/api/cli-tools/apply` | Ikteb il-konfigurazzjoni ġġenerata ta’ għodda (`dryRun` juri previżjoni; `422` + `containerEphemeralTarget` meta tkun f’container; `migration` jinnota Codex YAML antik) | | GET | `/api/cli-tools/backups` | Elenka l-backups tal-konfigurazzjonijiet tal-għodod CLI | | POST | `/api/cli-tools/backups` | Oħloq backup tal-konfigurazzjonijiet kollha tal-għodod CLI | | POST | `/api/cli-tools/backups` | Irrestawra: l-istess endpoint b’`{tool, backupId}` fil-body jirrestawra dak il-backup | | GET | `/api/cli-tools/antigravity-mitm` | Status tal-proxy MITM ta’ Antigravity (l-għodda CLI "antigravity-mitm") | | POST | `/api/cli-tools/antigravity-mitm/alias` | Ikkonfigura l-aliases ta’ antigravity-mitm | **Awtentikazzjoni:** Teħtieġ sessjoni ta’ ġestjoni. --- ## Ħiliet tal-Aġent Immaniġġja l-ħiliet tal-aġenti tal-IA (simili għall-GPTs personalizzati ta’ OpenAI, iżda għall-aġenti). | Metodu | Mogħdija | Deskrizzjoni | | ------ | ---------------------------- | ----------------------------------------------------------------------------------------------- | | GET | `/api/agent-skills` | Elenka l-ħiliet kollha tal-aġenti (inklużi + personalizzati) | | GET | `/api/agent-skills/[id]` | Ikseb ħila speċifika ta’ aġent | | POST | `/api/agent-skills` | Oħloq ħila personalizzata ta’ aġent — body: `{name, description, prompt, model?, temperature?}` | | PUT | `/api/agent-skills/[id]` | Aġġorna ħila personalizzata ta’ aġent | | DELETE | `/api/agent-skills/[id]` | Ħassar ħila personalizzata ta’ aġent | | GET | `/api/agent-skills/[id]/raw` | Ikseb l-istruzzjoni mhux ipproċessata + il-metadejta (mingħajr eżekuzzjoni) | | POST | `/api/agent-skills/generate` | Iġġenera ħila ġdida bl-IA minn deskrizzjoni b’lingwa naturali | **Awtentikazzjoni:** Teħtieġ sessjoni ta’ ġestjoni jew ċavetta API b’ambitu ta’ ġestjoni. --- ## Ġestjoni tal-Cache Immaniġġja l-cache semantika u l-cache tar-raġunament. | Metodu | Mogħdija | Deskrizzjoni | | ------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/cache` | Ħarsa ġenerali lejn il-cache: entrati totali, rata ta' suċċess, daqs fuq id-diska | | GET | `/api/cache/entries` | Elenka l-entrati fil-cache (bil-paġinazzjoni) | | DELETE | `/api/cache/entries` | Ħassar entrati mill-cache (iffiltra skont il-parametri tal-query) | | GET | `/api/cache/stats` | Statistika dettaljata tal-cache (għal kull fornitur, għal kull mudell) | | GET | `/api/cache/reasoning` | Status tal-cache tar-raġunament (għar-riproduzzjoni tar-raġunament) | | DELETE | `/api/cache/reasoning` | Battal il-cache tar-raġunament — parametri tal-query: `?toolCallId=` (wieħed) jew `?provider=

` jew ebda parametru (kollha) | **Awtentikazzjoni:** Teħtieġ sessjoni ta' ġestjoni. --- ## Sistema tal-Memorja Immaniġġja l-memorja persistenti (FTS5 + embeddings vettorjali). | Metodu | Mogħdija | Deskrizzjoni | | ------ | ------------------ | ----------------------------------------------------------------------------------- | | GET | `/api/memory` | Elenka l-entrati tal-memorja (iffiltra skont l-ambitu, it-tip, il-query tat-tiftix) | | POST | `/api/memory` | Oħloq entrata ġdida fil-memorja — body: `{scope, type, content, metadata?}` | | GET | `/api/memory/[id]` | Ikseb entrata speċifika tal-memorja | | PUT | `/api/memory/[id]` | Aġġorna entrata tal-memorja | | DELETE | `/api/memory/[id]` | Ħassar entrata tal-memorja | | GET | `/api/memory?q=` | Fittex fil-memorja (FTS5 + vettur) — l-istatistika hija inkluża fl-istess risposta | **Awtentikazzjoni:** Teħtieġ sessjoni ta' ġestjoni jew API key b'ambitu ta' ġestjoni. --- ## Webhooks Immaniġġja l-abbonamenti tal-webhook għall-avvenimenti. | Metodu | Mogħdija | Deskrizzjoni | | ------ | ------------------------------- | ----------------------------------------------------------------------------- | | GET | `/api/webhooks` | Elenka l-abbonamenti kollha tal-webhook | | POST | `/api/webhooks` | Oħloq abbonament tal-webhook — body: `{url, events[], secret?, active?}` | | GET | `/api/webhooks/[id]` | Ikseb abbonament speċifiku tal-webhook | | PUT | `/api/webhooks/[id]` | Aġġorna abbonament tal-webhook | | DELETE | `/api/webhooks/[id]` | Ħassar abbonament tal-webhook | | GET | `/api/webhooks/[id]/deliveries` | Elenka l-istorja tal-konsenji għal webhook (reġistru ta' suċċessi/fallimenti) | | POST | `/api/webhooks/[id]/test` | Ibgħat avveniment tat-test lil webhook | **Awtentikazzjoni:** Teħtieġ sessjoni ta' ġestjoni. Ara [Qafas tal-Webhooks](../frameworks/WEBHOOKS.md) għat-tipi kollha ta' avvenimenti. --- ## Qafas tax-Xogħol tal-Ħiliet Immaniġġja l-Ħiliet (il-qafas tal-estensjonijiet aġentiċi). | Metodu | Mogħdija | Deskrizzjoni | | ------ | ------------------------ | ------------------------------------------------------------------------------------------ | | GET | `/api/skills` | Elenka l-ħiliet installati kollha (integrati + personalizzati) | | POST | `/api/skills/install` | Installa ħila minn mogħdija lokali jew URL | | DELETE | `/api/skills/[id]` | Iddiżinstalla ħila | | PUT | `/api/skills/[id]` | Attiva jew iddiżattiva ħila — body: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` | | POST | `/api/skills/executions` | Eżegwixxi ħila — body: `{skillName, apiKeyId, input?, sessionId?}` | | GET | `/api/skills/executions` | Elenka l-kronoloġija tal-eżekuzzjonijiet għall-ħiliet kollha (iffiltra skont `?apiKeyId=`) | **Awtentikazzjoni:** Teħtieġ sessjoni ta’ ġestjoni jew API key b’ambitu ta’ ġestjoni. Ara [Qafas tax-Xogħol tal-Ħiliet](../frameworks/SKILLS.md) għad-dettalji kollha. --- ## Plugins Immaniġġja l-plugins ta’ OmniRoute (estensjonijiet ta’ partijiet terzi). | Metodu | Mogħdija | Deskrizzjoni | | ------ | ---------------------------------- | ------------------------------------ | | GET | `/api/plugins` | Elenka l-plugins installati | | POST | `/api/plugins/marketplace/install` | Installa plugin mis-suq | | DELETE | `/api/plugins/[name]` | Iddiżinstalla plugin | | POST | `/api/plugins/[name]/activate` | Attiva plugin | | POST | `/api/plugins/[name]/deactivate` | Iddiżattiva plugin | | GET | `/api/plugins/[name]/config` | Ikseb il-konfigurazzjoni tal-plugin | | PUT | `/api/plugins/[name]/config` | Aġġorna l-konfigurazzjoni tal-plugin | **Awtentikazzjoni:** Teħtieġ sessjoni ta’ ġestjoni. Ara [Qafas tax-Xogħol tal-Plugins](../frameworks/PLUGIN_SDK.md) għad-dettalji kollha. --- ## Rotot Paralelli It-tqabbil parallel / A-B tal-fornituri **mhuwiex interfaċċa REST awtonoma** — jiġi kkonfigurat permezz ta’ rotot ikkombinati (ara [Kombinazzjoni Awtomatika](../routing/AUTO-COMBO.md)). Il-metriċi tat-tqabbil għal kull kombinazzjoni jiġu pprovduti minn `GET /api/combos/metrics`. --- ## Salvagwardji Spezzjona s-salvagwardji waqt it-tħaddim (detezzjoni ta’ PII, detezzjoni ta’ injezzjoni fil-prompt, u konnessjoni tal-viżjoni). Is-salvagwardji jitħaddmu ma’ kull talba; l-esklużjoni għal sejħa individwali ssir permezz tal-header tat-talba `x-omniroute-disabled-guardrails` — m’hemm l-ebda interfaċċa persistenti għall-attivazzjoni jew id-diżattivazzjoni. | Metodu | Mogħdija | Deskrizzjoni | | ------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | | GET | `/api/guardrails` | Elenka s-salvagwardji rreġistrati u l-istatus tagħhom (isem / attivat / prijorità) | | POST | `/api/guardrails/test` | Wettaq prova mingħajr effetti tal-pipeline ta’ qabel is-sejħa fuq input kampjun — body: `{input, disabledGuardrails?}` | **Awtentikazzjoni:** Teħtieġ sessjoni ta’ ġestjoni. Ara [Sigurtà > Salvagwardji](../security/GUARDRAILS.md) għad-dettalji kollha. --- --- ## Awtentikazzjoni Ara [Awtentikazzjoni tal-Ġestjoni](../guides/MANAGEMENT-AUTH.md) għall-erba’ familji ta’ kredenzjali (sessjoni tad-dashboard, token lokali tas-CLI, Token ta’ Aċċess `oma_live_…`, API key b’ambitu ta’ ġestjoni) u kif dawn huma differenti mill-keys tal-inferenza. - Ir-rotot tad-dashboard (`/dashboard/*`) jużaw il-cookie `auth_token` - Il-login juża l-hash tal-password issejvjat; bħala alternattiva juża `INITIAL_PASSWORD` - `requireLogin` jista’ jinxtegħel jew jintefa permezz ta’ `/api/settings/require-login` - Ir-rotot `/v1/*` jistgħu jeħtieġu Bearer API key meta `REQUIRE_API_KEY=true` - “token tal-ġestjoni” / “API key b’ambitu ta’ ġestjoni” f’din ir-referenza tfisser waħda mill-familji f’dik il-gwida — mhux tip addizzjonali mhux definit ta’ sigriet > **Bidla inkompatibbli (v3.8.0)** — `/api/v1/agents/tasks/*` u l-endpoints tal-ġestjoni tal-perjodu ta’ stennija issa jeħtieġu **awtentikazzjoni tal-ġestjoni** (cookie `auth_token` tad-dashboard jew API key b’ambitu ta’ ġestjoni). Il-klijenti li qabel kienu jsejħu dawn ir-rotot mingħajr awtentikazzjoni se jirċievu `401 Unauthorized`. Ara l-commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).