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

API Reference (Malti)

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

---

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

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 u s-siġra tar-rotot taħt src/app/api/ huma s-sorsi eżawrjenti.

---

Werrej

• Tkomplijiet taċ-Chat
• Kirjiet Esklussivi ta' Sessjonijiet Immaniġġjati
• Inkorporazzjonijiet
• Ġenerazzjoni ta' Immaġnijiet
• OCR tad-Dokumenti
• Lista tal-Mudelli
• Manifest tal-Plugin tal-Fornitur
• Endpoints tal-Kompatibbiltà
• API tal-Fajls
• API tal-Lottijiet
• API tat-Tiftix
• Streaming permezz ta' WebSocket
• Kwoti u Rappurtar ta' Problemi
• Cache Semantika
• Dashboard u Ġestjoni
• Ġestjoni tal-Kombinazzjonijiet
• Webhooks
• Ċwievet Irreġistrati (Ġestjoni Awtomatika)
• Protokoll tal-Aġenti
• Proxies tal-Ġestjoni
• Reżiljenza (estiża)
• Ħiliet
• Memorja
• Server MCP
• Server A2A
• Cloud, Evalwazzjonijiet u Valutazzjoni
• Ipproċessar tat-Talbiet
• Awtentikazzjoni

---

Tkomplijiet taċ-Chat

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=<name>; provider=<alias>; latency_ms=<n> (<name> 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.

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

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

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:

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

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

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

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

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:

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:

{
  "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:<id>	Magna waħda meta tkun attivata, eż. engine:rtk.
<combo>	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: <mode>; source=<source>

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

---

Inkorporazzjonijiet

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:

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

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

# Elenka l-mudelli kollha tal-inkorporazzjonijiet
GET /v1/embeddings

---

Ġenerazzjoni tal-Immaġnijiet

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

# Elenka l-mudelli kollha tal-immaġnijiet
GET /v1/images/generations

---

OCR tad-Dokumenti

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:

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

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:

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.

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/<provider>/<model>

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-<provider>/<model> 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

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.

# 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

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

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)

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

# 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/<group>/codex/<model>". 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):

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)

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.

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

# Format strutturat — dak li tuża UI
curl -H "Authorization: Bearer <your-api-key>" \
  "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:

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

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

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

Eżempju ta’ rispons:

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

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

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

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:

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

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:

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:

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

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

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

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

# Ikseb sommarju tat-telemetrija tal-latenza (p50/p95/p99 għal kull fornitur)
GET /api/telemetry/summary

Risposta:

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

---

Baġit

# 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 globalment fuq iċ-ċavetta kollha; meta diversi limiti jaqblu ma' talba, japplika l-aktar wieħed restrittiv.

# 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

---

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

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

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

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

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=<agentId>

Eżempju ta’ rispons (GET /api/acp/agents):

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

Awtentikazzjoni: Teħtieġ sessjoni ta’ ġestjoni (cookie auth_token tad-dashboard) jew ċavetta API b’ambitu ta’ ġestjoni.

Ara Il-Qafas ACP 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:

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

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

{
  "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<string, number>}

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, commandCode, devin-cli, eċċ.). Ara Referenza tal-Fornituri għal-lista sħiħa.

Metodu	Mogħdija	Deskrizzjoni
GET	/api/cli-tools/all-statuses	L-istatus 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	Jikteb il-konfigurazzjoni ġġenerata ta’ għodda (dryRun juri previżjoni; 422 + containerEphemeralTarget meta tkun f’container; migration jinnota YAML legacy ta’ Codex)
GET	/api/cli-tools/backups	Jelenka l-backups tal-konfigurazzjonijiet tal-għodod CLI
POST	/api/cli-tools/backups	Joħloq backup tal-konfigurazzjonijiet kollha tal-għodod CLI
POST	/api/cli-tools/backups	Restawr: l-istess endpoint b’{tool, backupId} fil-body jirrestawra dak il-backup
GET	/api/cli-tools/antigravity-mitm	L-istatus tal-proxy MITM ta’ Antigravity (l-għodda CLI "antigravity-mitm")
POST	/api/cli-tools/antigravity-mitm/alias	Jikkonfigura 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=<id> (wieħed) jew ?provider=<p> 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 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 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 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). 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 għad-dettalji kollha.

---

---

Awtentikazzjoni

Ara Awtentikazzjoni tal-Ġestjoni 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).