API Reference (Malti)

September 23, 2026 · View on GitHub

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 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 · 🇧🇦 bs · 🇨🇿 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

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

HeaderDirezzjoniDeskrizzjoni
X-OmniRoute-No-CacheTalbaIssettjah għal true biex taqbeż il-cache
x-omniroute-no-memoryTalbaIssettjah 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-ProgressTalbaIssettjah għal true għal avvenimenti tal-progress
X-Session-IdTalbaĊavetta persistenti tas-sessjoni għall-affinità ma' sessjoni esterna
x_session_idTalbaIl-varjant b'linja taħt huwa aċċettat ukoll (HTTP dirett)
X-OmniRoute-Session-IdTalbaTag 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-KeyTalbaĊavetta għat-tneħħija tad-duplikati (tieqa ta' 5s)
X-Request-IdTalbaĊavetta alternattiva għat-tneħħija tad-duplikati
X-OmniRoute-CacheTweġibaHIT jew MISS (mingħajr streaming)
X-OmniRoute-IdempotentTweġibatrue jekk tneħħa d-duplikat
X-OmniRoute-ProgressTweġibaenabled jekk it-traċċar tal-progress ikun attiv
X-OmniRoute-Session-IdTweġibaL-ID effettiva tas-sessjoni użata minn OmniRoute
X-OmniRoute-Request-IdTweġibaID ta' korrelazzjoni tat-talba (meta tkun magħrufa)
X-OmniRoute-VersionTweġibaVerżjoni tal-build ta' OmniRoute (dejjem preżenti)
X-OmniRoute-Cost-SavedTweġibaL-ammont f'USD li l-cache evitat fuq HIT (għal hits tal-cache biss)
X-OmniRoute-DecisionTweġibaTraċċ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 ta' Sessjonijiet Ġestiti Esklussivi

Il-kiri ta' sessjonijiet ġestiti esklussivi huwa kuntratt ta' rotta opt-in, newtrali għall-klijent: sid attiv wieħed iżomm konnessjoni OmniRoute waħda eliġibbli. Ma jikrix mudell, ma jeħtieġx OAuth, ma jidentifikax klijent partikolari, jew ma jeħtieġx fornitur partikolari.

Iċ-ċavetta tal-API tal-awtentikazzjoni għandu jkollha skop lease:exclusive u lista espliċita mhux vojta ta' allowedConnections. Il-konfini tal-mutazzjoni tad-database tinforza ż-żewġ oqsma flimkien mal-ħ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"}

Ir-risposti ta' akkwist, tiġdid, u rilaxx b'suċċess jesponu timestamps, state, u l-eżatt generation pożittiv, iżda qatt il-konnessjoni jew il-kredenzjali magħżula. It-tiġdid u r-rilaxx jipprovdu l-ġenerazzjoni fil-korp JSON:

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

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

Sid ta' kiri attiv jista' jitlob espliċitament metadata tal-wiri sigura għall-privatezza għall-binding kurrenti 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 ta' status opt-in hija magħluqa mis-sid opak, iċ-ċavetta tal-API ġestita awtentikata, u l-ġenerazzjoni attiva eżatta f'transazzjoni waħda tad-database. displayName huwa biss l-isem tal-konnessjoni kkonfigurat imqassar; huwa null meta ma jeżisti l-ebda isem konfigurat sigur. OmniRoute qatt ma jissostitwixxi email jew identità ta' kont ġenerata. Il-valur tal-fornitur huwa tikketta tal-wiri mhux sensittiva u qatt ma huwa identifikatur ta' fornitur kompatibbli ġenerat. Kredenzjali, tokens, cookies, IDs ta' konnessjoni jew API key mhux ipproċessati, hashes tas-sid, sigrieti ta' fencing, u data ta' rotta interna huma esklużi.

Tiftix b'ċavetta żbaljata, sid żbaljat, ġenerazzjoni skaduta, nieqsa, skaduta, rilaxxata, u invalidata kollha jirritornaw l-istess żball 409 LEASE_FENCE_STALE mingħajr metadata tal-konnessjoni. Klijent li rċieva r-risposta ta' stennija tal-kapaċità m'għandu l-ebda binding attiv biex jispezzjona. Meta r-rotta tittrasferixxi kiri attiv, l-istess ġenerazzjoni tibqa' valida u l-istatus jirritorna b'mod atomiku l-binding il-ġdid, qatt dak il-qadim. Il-klijenti eżistenti jibqgħu mhux mibdula minħabba li l-akkwist, it-tiġdid, ir-rilaxx, u r-risposti ta' stennija jżommu l-forom preċedenti tagħhom.

Dan il-kuntratt tas-server ma jbiddilx l-OpenAI Codex /status standard. Il-Codex standard bħalissa jirrapporta l-fornitur tal-mudell tiegħu u l-istat tal-awtentikazzjoni/kont inkorporat iżda ma jirrendix metadata tal-kont tal-fornitur personalizzata arbitrarja; integrazzjoni tal-klijent aktar tard 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 tal-API awtentikata huma magħluqa immedjatament qabel kull tentattiv upstream appoġġjat. Ir-replay tas-sid u l-ġenerazzjoni b'ċavetta oħra jfalli anke meta dik iċ-ċavetta tippermetti l-istess konnessjoni. Is-sidien mhux ipproċessati ma jiġux persistiti, illoggjati, miżmuma fl-snapshot tat-talba, jew mibgħuta 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 ir-risposta 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 tal-politika, cooldown, kwota, saħħa, u fallimenti oħra ta' eliġibilità ordinarja jżommu r-risposti OmniRoute eżistenti tagħhom.

x-omniroute-compression

Override għal kull talba tal-pjan ta' kompressjoni. L-ogħla preċedenza — tegħleb l-override tal-combo tar-rotta, il-profil attiv, l-awto-trigger, u l-Default tal-pannell. Valuri:

ValurEffett
offL-ebda kompressjoni għal din it-talba.
defaultIl-profil Default derivat mill-pannell (jinjora l-profil attiv). Il-magni lossy jitħallew mitfija.
safeDedup u tiwi tal-ispazji bojod biss.
allow-lossyŻomm il-pjan tal-operatur għal din it-talba, inklużi s-sommarji u r-rewrites tal-istil.
engine:<id>Magna waħda meta attivata, eż. engine:rtk. Opt-in għal kull talba għal dik il-magna.
<combo>Combo bl-isem, imqabbla bl-isem (mhux sensittiv għall-każ) l-ewwel, imbagħad bl-id.

Noti:

  • Valuri mhux magħrufa jiġu injorati (it-talba qatt ma tiġi rrifjutata); ir-riżoluzzjoni taqa' għall-preċedenza normali tal-operatur.
  • Jekk combos multipli jaqsmu isem, għaddi l-id tal-combo għal tqabbil deterministiku.
  • Combo li isimha huwa off jew default ma tistax tintgħażel bl-isem (dawk il-kliem kjavi jiġu interpretati l-ewwel); irreferi għal combo bħal din bl-id tagħha.
  • Is-swiċċ prinċipali tal-kompressjoni huwa gate iebes: meta l-kompressjoni tkun diżattivata globalment, dan l-header ma jistax jattivaha.

Il-pjan applikat jiġi rrepetut fl-header tar-risposta:

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-forniturId tal-mudellValur ta' modelNoti
mistralmistral-ocr-latestmistral/mistral-ocr-latest (jew mistral-ocr-latest waħdu)Sinkroniku — ir-rispons jintbagħat lura direttament mis-sejħa unika upstream.
azure-document-intelligenceprebuilt-readazure-document-intelligence/prebuilt-readUpstream asinkroniku (analyze + poll) — ara hawn taħt.
vertex-deepseek-ocrdeepseek-ocr-maasvertex-deepseek-ocr/deepseek-ocr-maasSinkroniku, 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
dualcc/claude-sonnet-4-6 u claude/claude-sonnet-4-6Predefinita. 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.
aliascc/claude-sonnet-4-6Entrata 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.
canonicalclaude/claude-sonnet-4-6Entrata 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 ta' Kompatibbiltà

MetoduMogħdijaFormat
POST/v1/chat/completionsOpenAI
POST/v1/messagesAnthropic
POST/v1/responsesOpenAI Responses
POST/v1/embeddingsOpenAI
POST/v1/images/generationsOpenAI Images
POST/v1/images/editsOpenAI Images (edit/inpaint)
POST/v1/videos/generationsĠenerazzjoni ta' vidjows fuq l-istil ta' OpenAI
POST/v1/music/generationsĠenerazzjoni ta' mużika fuq l-istil ta' OpenAI
POST/v1/audio/transcriptionsOpenAI Audio (STT)
POST/v1/audio/speechOpenAI TTS (jirritorna l-korp tal-awdjo)
POST/v1/rerankKlassifikazzjoni mill-ġdid fuq l-istil ta' Cohere/Voyage
POST/v1/classifyKlassifikazzjoni ta' Jina (api.jina.ai)
POST/v1/segmentSegmentatur ta' Jina (segment.jina.ai)
POST/v1/moderationsOpenAI Moderations
GET/v1/modelsOpenAI
POST/v1/messages/count_tokensAnthropic
GET/v1beta/modelsGemini
POST/v1beta/models/{...path}Gemini generateContent
POST/v1/api/chatOllama
GET/api/v1/vscode/{token}/Alias tal-katalgu ta' OpenAI
GET/api/v1/vscode/{token}/modelsAlias tal-mudelli ta' OpenAI
POST/api/v1/vscode/{token}/chat/completionsAlias tokenizzat ta' OpenAI
POST/api/v1/vscode/{token}/responsesAlias tokenizzat ta' OpenAI Responses
POST/api/v1/vscode/{token}/api/chatAlias tokenizzat ta' Ollama
GET/api/v1/vscode/{token}/api/tagsAlias tokenizzat tat-tags ta' Ollama

Ir-rotot POST kollha jsegwu l-istess struttura: Bearer your-api-key + korp JSON ivvalidat b'Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema, eċċ., ara src/shared/validation/schemas.ts). Jiġi rritornat 4xx meta l-validazzjoni tal-iskema tfalli.

Għall-klijenti li ma jistgħux jehmżu Authorization: Bearer ..., OmniRoute jaċċetta wkoll API keys fil-URL permezz jew ta' kompatibbiltà mal-query string (?token=..., ?apiKey=..., ?api_key=..., ?key=...) jew tal-endpoints iddedikati /api/v1/vscode/{token}/... dokumentati hawn taħt.

# Klassifikazzjoni mill-ġdid (fornitur mir-reġistru tal-cloud, jew node ta' fornitur kompatibbli ma' OpenAI bħala "<prefix>/<model>")
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Klassifikazzjoni ta' Jina (kredenzjali tal-Foundation API)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

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

# Tfittxija ta' 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 bil-format mitlub)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Editjar ta' 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 bi prefiss tal-fornitur)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Nodes tal-fornitur għall-klassifikazzjoni mill-ġdid: POST /v1/rerank jidderieġi wkoll lejn nodes ta' fornituri kompatibbli ma' OpenAI (oMLX, vLLM, Infinity, TEI wara gateway, …) indirizzati bħala <node-prefix>/<model>. Nodes loopback (localhost, 127.0.0.1, 172.16.0.0/12) huma dejjem eliġibbli. Nodes fuq kwalunkwe host ieħor — apparat fuq LAN jew peer ta' Tailscale — huma eliġibbli biss meta l-operatur jattiva l-feature flag RERANK_REMOTE_PROVIDER_NODES u l-URL bażi tan-node jgħaddi mill-politika tal-URLs 'il barra tal-fornitur (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS / OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS); hosts tal-metadata tal-cloud qatt ma jiġu diretti lejhom. Il-pass tal-klassifikazzjoni mill-ġdid tal-magna tal-memorja jsejjaħ din ir-rotta permezz ta' loopback, għalhekk l-istess regola tirregola rerankProviderModel fis-settings tal-Memorja.

Strutturi tas-server lokali: in-node jissejjaħ f'/v1/rerank u, f'każ ta' 404, f'<base>/rerank (Infinity, TEI). Il-korp upstream iġorr kemm l-ortografija ta' Cohere/OpenAI (documents, return_documents) kif ukoll dik ta' TEI (texts, return_text), u r-rispons upstream jiġi normalizzat għall-envelope ta' Cohere: l-array sempliċi ta' TEI [{index, score, text}], {results: [{index, score}]} minn gateways ħfief, u {data: [...]} fuq l-istil ta' Voyage kollha jaslu lura għand il-klijent bħala {results: [{index, relevance_score, document?}]}, magħżula skont il-punteġġ u limitati għal top_n.

Skoperta tan-nodes tal-fornitur: il-mudelli fuq node ta' fornitur kompatibbli ma' OpenAI jidhru f'GET /v1/models taħt il-prefiss tan-node. Ringieli li ma jkollhomx metadata tal-endpoint (tipiku għal listi lokali ta' /v1/models) jirtu l-apiType tan-node, għalhekk il-mudelli ta' node embeddings ikunu type: "embedding" u dawk ta' node rerank ikunu type: "rerank" minflok ma jaqgħu awtomatikament għal chat; supportedEndpoints espliċitu fuq ringiela sinkronizzata jew miżjuda manwalment xorta jieħu preċedenza.

Rotot Iddedikati għall-Fornituri

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.

MetoduMogħdijaDeskrizzjoni
POST/v1/filesTella’ fajl (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — massimu ta’ 512 MiB
GET/v1/filesElenka 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]/contentIbgħ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.

MetoduMogħdijaDeskrizzjoni
POST/v1/batchesOħloq lott — il-korp jiġi vvalidat minn v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET/v1/batchesElenka 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]/cancelIkkanċ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ċċ.).

MetoduMogħdijaDeskrizzjoni
GET/v1/searchElenka l-fornituri tat-tiftix ikkonfigurati + il-kapaċitajiet tagħhom
POST/v1/searchEsegwixxi mistoqsija ta’ tiftix — il-body jiġi vvalidat minn v1SearchSchema, jappoġġja caching/coalescing
GET/v1/search/analyticsStatistika 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).

MetoduMogħdijaDeskrizzjoni
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

MetoduMogħdijaDeskrizzjoni
GET/v1/quotas/checkIvvalida minn qabel il-kwota għal provider + accountId qabel ma tinħareġ ċavetta rreġistrata
POST/v1/issues/reportIrrapporta 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:

ValurTifsira
syntheticRispons 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:

ValurImġiba
legacyImġiba normali tal-cache (awtomatika)
bypassAqbeż 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 finaliMetoduDeskrizzjoni
/api/auth/loginPOSTIdħol
/api/auth/logoutPOSTOħroġ
/api/settings/require-loginGET/PUTIxgħel jew itfi l-login obbligatorju

Ġestjoni tal-Fornituri

Punt finaliMetoduDeskrizzjoni
/api/providersGET/POSTElenka / oħloq fornituri
/api/providers/[id]GET/PUT/DELETEImmaniġġja fornitur
/api/providers/[id]/testPOSTIttestja l-konnessjoni tal-fornitur
/api/providers/[id]/modelsGETElenka l-mudelli tal-fornitur
/api/providers/validatePOSTIvvalida l-konfigurazzjoni tal-fornitur
/api/providers/bulkPOSTŻid bil-massa ċ-ċwievet API għal fornitur WIEĦED
/api/providers/importPOSTImporta 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-modelsGET/POST/PATCH/DELETEMudelli personalizzati (żid, aġġorna, aħbi/uri, ħassar)

Flussi OAuth

Punt finaliMetoduDeskrizzjoni
/api/oauth/[provider]/[action]DiversiOAuth speċifiku għall-fornitur

Rotot u Konfigurazzjoni

Punt finaliMetoduDeskrizzjoni
/api/models/aliasGET/POSTPsewdonimi tal-mudelli
/api/models/catalogGETIl-mudelli kollha skont il-fornitur + it-tip
/api/combos*DiversiĠestjoni tal-kombinazzjonijiet
/api/keys*DiversiĠestjoni taċ-ċwievet API
/api/pricingGETIpprezzar tal-mudelli

Użu u Analitika

Punt tat-tmiemMetoduDeskrizzjoni
/api/usage/historyGETStorja tal-użu
/api/usage/logsGETReġistri tal-użu
/api/usage/request-logsGETReġistri fil-livell tat-talba
/api/usage/[connectionId]GETUżu għal kull konnessjoni
/api/usage/token-limitsGET/POST/DELETEBaġits tal-limitu ta’ tokens għal kull ċavetta tal-API
/api/usage/model-latency-statsGETAggregat 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-healthGETSommarju 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-tmiemMetoduDeskrizzjoni
/api/settingsGET/PUT/PATCHSettings ġenerali
/api/settings/proxyGET/PUTKonfigurazzjoni tal-proxy tan-network
/api/settings/proxy/testPOSTIttestja l-konnessjoni tal-proxy
/api/settings/ip-filterGET/PUTLista ta’ permessi/lista ta’ mblukkar tal-IP
/api/settings/thinking-budgetGET/PUTModalità 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-promptGET/PUTPrompt globali tas-sistema
/api/settings/compressionGET/PUTKonfigurazzjoni globali tal-kompressjoni
/api/settings/purge-request-historyPOSTĦassar ir-ringieli tar-reġistru tat-talbiet u l-artifatti lokali tar-reġistru tas-sejħiet

Kuntest u Kompressjoni

EndpointMetoduDeskrizzjoni
/api/compression/previewPOSTPreviżjoni tal-kompressjoni off/lite/standard/aggressive/ultra/RTK/stacked
/api/compression/language-packsGETElenka l-pakketti lingwistiċi Caveman disponibbli
/api/compression/rulesGETElenka l-metadejta tar-regoli Caveman
/api/context/caveman/configGET/PUTAlias tas-settings speċifiċi għal Caveman
/api/context/rtk/configGET/PUTSettings speċifiċi għal RTK, inklużi filtri personalizzati u ż-żamma tal-output mhux ipproċessat
/api/context/rtk/filtersGETKatalgu tal-filtri RTK u dijanjostika tal-filtri personalizzati
/api/context/rtk/testPOSTĦaddem previżjoni/test RTK fuq payload ta’ test
/api/context/rtk/raw-output/[id]GETAqra l-output mhux ipproċessat u redatt miżmum permezz tal-id tal-pointer
/api/context/combosGET/POSTElenka/oħloq kombinazzjonijiet tal-kompressjoni
/api/context/combos/[id]GET/PUT/DELETEDettalji/aġġornament/tħassir ta’ kombinazzjoni tal-kompressjoni
/api/context/combos/[id]/assignmentsGET/PUTAssenja kombinazzjonijiet tal-kompressjoni lil kombinazzjonijiet tar-routing
/api/context/analyticsGETAlias tal-analitika tal-kompressjoni

Monitoraġġ

EndpointMetoduDeskrizzjoni
/api/sessionsGETTraċċar tas-sessjonijiet attivi
/api/rate-limitsGETLimiti tar-rata għal kull kont
/api/monitoring/healthGETKontroll 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/statsGET/DELETEStatistika tal-cache / neħħi l-cache
/api/modality-bridge/statsGETattempts 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/runtimeGETKontroll strett ta’ loopback fdat qabel l-awtentikazzjoni/probe tal-ġestjoni; disponibbiltà u verżjonijiet sanitizzati ta’ FFmpeg/ffprobe (no-store)
/api/modality-bridge/video/extractPOSTBroker 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

EndpointMetoduDeskrizzjoni
/api/db-backupsGETElenka l-backups disponibbli
/api/db-backupsPUTOħloq backup manwali
/api/db-backupsPOSTIrrestawra minn backup speċifiku
/api/db-backups/exportGETNiżżel id-database bħala fajl .sqlite
/api/db-backups/importPOSTTella' fajl .sqlite biex tissostitwixxi d-database
/api/db-backups/exportAllGETNiżżel backup sħiħ bħala arkivju .tar.gz

Sinkronizzazzjoni mal-Cloud

EndpointMetoduDeskrizzjoni
/api/sync/cloudDiversiOperazzjonijiet ta' sinkronizzazzjoni mal-cloud
/api/sync/initializePOSTInizjalizza s-sinkronizzazzjoni
/api/cloud/*DiversiĠestjoni tal-cloud

Tunnels

EndpointMetoduDeskrizzjoni
/api/tunnels/cloudflaredGETAqra l-istatus tal-installazzjoni/eżekuzzjoni ta' Cloudflare Quick Tunnel għad-dashboard
/api/tunnels/cloudflaredPOSTIppermetti jew iddiżattiva Cloudflare Quick Tunnel (action=enable/disable)
/api/tunnels/ngrokGETAqra l-istatus tal-eżekuzzjoni ta' ngrok Tunnel għad-dashboard
/api/tunnels/ngrokPOSTIppermetti jew iddiżattiva ngrok Tunnel (action=enable/disable)

Għodod tas-CLI

EndpointMetoduDeskrizzjoni
/api/cli-tools/claude-settingsGETStatus tas-CLI ta' Claude
/api/cli-tools/codex-settingsGETStatus tas-CLI ta' Codex
/api/cli-tools/droid-settingsGETStatus tas-CLI ta' Droid
/api/cli-tools/openclaw-settingsGETStatus tas-CLI ta' OpenClaw
/api/cli-tools/runtime/[toolId]GETAmbjent ta' eżekuzzjoni ġeneriku tas-CLI

It-tweġibiet tas-CLI jinkludu: installed, runnable, command, commandPath, runtimeMode, reason.

Aġenti ACP

EndpointMetoduDeskrizzjoni
/api/acp/agentsGETElenka l-aġenti kollha identifikati (integrati + personalizzati) bl-istatus tagħhom
/api/acp/agentsPOSTŻid aġent personalizzat jew aġġorna l-cache tal-identifikazzjoni
/api/acp/agentsDELETENeħħ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

EndpointMetoduDeskrizzjoni
/api/resilienceGET/PATCHIkseb/aġġorna l-kju tat-talbiet, il-perjodu ta' stennija tal-konnessjoni, il-breaker tal-fornitur u s-settings tal-istennija
/api/resilience/resetPOSTIrrisettja s-circuit breakers tal-fornituri
/api/resilience/model-cooldownsGETElenka l-lockouts attivi għal kull (fornitur, konnessjoni, mudell), magħżula skont il-ħin li fadal
/api/resilience/model-cooldownsDELETENeħħi lockout ta' mudell — body {provider, model} jew {all: true} biex tħassar kollox
/api/rate-limitsGETStatus tal-limitu tar-rata għal kull kont
/api/rate-limitGETKonfigurazzjoni 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

EndpointMetoduDeskrizzjoni
/api/evalsGET/POSTElenka s-settijiet ta' evalwazzjoni / wettaq evalwazzjoni

Politiki

EndpointMetoduDeskrizzjoni
/api/policiesGET/POST/DELETEImmaniġġja l-politiki tar-routing

Konformità

EndpointMetoduDeskrizzjoni
/api/compliance/audit-logGETReġistru tal-awditjar tal-konformità (l-aħħar N)

v1beta (Kompatibbli ma' Gemini)

EndpointMetoduDeskrizzjoni
/v1beta/modelsGETElenka l-mudelli fil-format ta' Gemini
/v1beta/models/{...path}POSTEndpoint 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

EndpointMetoduDeskrizzjoni
/api/initGETVerifika tal-inizjalizzazzjoni tal-applikazzjoni (użata fl-ewwel tħaddim)
/api/tagsGETTikketti tal-mudelli kompatibbli ma’ Ollama (għall-klijenti Ollama)
/api/restartPOSTJiskatta ristartjar gradwali tas-server
/api/shutdownPOSTJiskatta għeluq gradwali tas-server
/api/system/env/repairPOSTIsewwi 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.

MetoduPerkorsDeskrizzjoni
GET/api/model-combo-mappingsElenka l-immappjar kollu minn mudell għal combo
POST/api/model-combo-mappingsOħ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ċċ.).

MetoduMogħdijaDeskrizzjoni
GET/api/webhooksElenka l-webhooks (is-sigrieti jiġu moħbija bħala <prefix>...)
POST/api/webhooksOħ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]/testIbgħ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.

MetoduMogħdijaDeskrizzjoni
GET/api/v1/registered-keysElenka ċ-ċwievet irreġistrati (il-prefiss moħbi biss)
POST/api/v1/registered-keysOħ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]/revokeEndpoint 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.

MetoduMogħdijaDeskrizzjoni
GET/api/v1/agents/tasksElenka l-kompiti — ?provider=, ?status=, ?limit= fakultattivi (1–500, valur predefinit 50)
POST/api/v1/agents/tasksOħ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.

MetoduMogħdijaDeskrizzjoni
GET/api/v1/management/proxiesElenka l-proxies (b’?id= jirritorna wieħed; b’?id=&where_used=1 jirritorna l-graff tal-assenjamenti)
POST/api/v1/management/proxiesOħloq proxy — il-korp jiġi vvalidat minn createProxyRegistrySchema
PATCH/api/v1/management/proxiesAġġ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/assignmentsElenka 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/assignmentsAssenja — il-korp jiġi vvalidat minn proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Inaddaf il-cache tad-dispatcher
PUT/api/v1/management/proxies/bulk-assignAssenja bil-massa — il-korp jiġi vvalidat minn bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?})
GET/api/v1/management/proxies/health?hours=24Stat 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-istatQariIrrisettjar / tneħħija
Interruttur tal-forniturdomain_circuit_breakers + fil-memorja/api/monitoring/healthPOST /api/resilience/reset
Perjodu ta’ stennija tal-konnessjonirateLimitedUntil 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-mudellReġistru fil-memorja tad-disponibbiltà tal-mudelliGET /api/resilience/model-cooldownsDELETE /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.

MetoduMogħdijaDeskrizzjoni
GET/api/skillsElenka 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/installInstalla ħila minn manifest mhux ipproċessat — body: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET/api/skills/executionsElenka 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/installInstalla ħila skont l-id minn SkillsMP
GET/api/skills/skillssh?q=&limit=Fittex fir-reġistru skills.sh
POST/api/skills/skillssh/installInstalla ħ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.

MetoduMogħdijaDeskrizzjoni
GET/api/memoryElenka l-memorji — ?apiKeyId=, ?type=, ?sessionId=, ?q=, b’paġinazzjoni permezz ta’ offset/limit jew page/limit
POST/api/memoryOħ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/healthStat 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):

MetoduDeskrizzjoni
message/sendEżekuzzjoni sinkronika tal-ħila; tirritorna {task, artifacts, metadata}
message/streamEżekuzzjoni SSE bi streaming tal-istess sett ta’ ħiliet
tasks/getIġib kompitu permezz ta’ taskId
tasks/cancelJikkanċ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

MetoduMogħdijaDeskrizzjoni
GET/api/a2a/statusA2A attivat + statistika tal-kompiti + sommarju tal-kard tal-aġent maħżuna fil-cache
GET/api/a2a/tasksElenka 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]/cancelIkkanċ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.

MetoduMogħdijaDeskrizzjoni
GET/api/acp/agentsElenka l-aġenti CLI magħrufa kollha (inkorporati + personalizzati), flimkien mal-istat tal-installazzjoni, il-verżjoni u l-binarju
POST/api/acp/agentsIrreġistra aġent ACP personalizzat jew aġġorna l-cache — korp: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} jew {action: "refresh"}
DELETE/api/acp/agentsNeħħ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

MetoduMogħdijaDeskrizzjoni
GET/api/analytics/auto-routingStatistika 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=7Statistika 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

MetoduMogħdijaDeskrizzjoni
GET/api/analytics/compressionStatistika 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

MetoduMogħdijaDeskrizzjoni
GET/api/analytics/diversityTraċċ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.

MetoduMogħdijaDeskrizzjoni
GET/api/admin/concurrencyAqra l-limiti attwali tal-konkorrenza (globali + għal kull fornitur)
POST/api/admin/concurrencyAġġ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.

MetoduMogħdijaDeskrizzjoni
GET/api/cli-tools/all-statusesL-istatus tal-għodod CLI kollha (installati, verżjoni, l-aħħar darba li dehru)
GET/api/cli-tools/statusDettalji tal-istatus għal għodda CLI waħda (query ?tool=)
POST/api/cli-tools/applyJikteb 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/backupsJelenka l-backups tal-konfigurazzjonijiet tal-għodod CLI
POST/api/cli-tools/backupsJoħloq backup tal-konfigurazzjonijiet kollha tal-għodod CLI
POST/api/cli-tools/backupsRestawr: l-istess endpoint b’{tool, backupId} fil-body jirrestawra dak il-backup
GET/api/cli-tools/antigravity-mitmL-istatus tal-proxy MITM ta’ Antigravity (l-għodda CLI "antigravity-mitm")
POST/api/cli-tools/antigravity-mitm/aliasJikkonfigura 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).

MetoduMogħdijaDeskrizzjoni
GET/api/agent-skillsElenka l-ħiliet kollha tal-aġenti (inklużi + personalizzati)
GET/api/agent-skills/[id]Ikseb ħila speċifika ta’ aġent
POST/api/agent-skillsOħ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]/rawIkseb l-istruzzjoni mhux ipproċessata + il-metadejta (mingħajr eżekuzzjoni)
POST/api/agent-skills/generateIġġ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.

MetoduMogħdijaDeskrizzjoni
GET/api/cacheĦarsa ġenerali lejn il-cache: entrati totali, rata ta' suċċess, daqs fuq id-diska
GET/api/cache/entriesElenka l-entrati fil-cache (bil-paġinazzjoni)
DELETE/api/cache/entriesĦassar entrati mill-cache (iffiltra skont il-parametri tal-query)
GET/api/cache/statsStatistika dettaljata tal-cache (għal kull fornitur, għal kull mudell)
GET/api/cache/reasoningStatus tal-cache tar-raġunament (għar-riproduzzjoni tar-raġunament)
DELETE/api/cache/reasoningBattal 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).

MetoduMogħdijaDeskrizzjoni
GET/api/memoryElenka l-entrati tal-memorja (iffiltra skont l-ambitu, it-tip, il-query tat-tiftix)
POST/api/memoryOħ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.

MetoduMogħdijaDeskrizzjoni
GET/api/webhooksElenka l-abbonamenti kollha tal-webhook
POST/api/webhooksOħ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]/deliveriesElenka l-istorja tal-konsenji għal webhook (reġistru ta' suċċessi/fallimenti)
POST/api/webhooks/[id]/testIbgħ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).

MetoduMogħdijaDeskrizzjoni
GET/api/skillsElenka l-ħiliet installati kollha (integrati + personalizzati)
POST/api/skills/installInstalla ħ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/executionsEżegwixxi ħila — body: {skillName, apiKeyId, input?, sessionId?}
GET/api/skills/executionsElenka 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).

MetoduMogħdijaDeskrizzjoni
GET/api/pluginsElenka l-plugins installati
POST/api/plugins/marketplace/installInstalla plugin mis-suq
DELETE/api/plugins/[name]Iddiżinstalla plugin
POST/api/plugins/[name]/activateAttiva plugin
POST/api/plugins/[name]/deactivateIddiżattiva plugin
GET/api/plugins/[name]/configIkseb il-konfigurazzjoni tal-plugin
PUT/api/plugins/[name]/configAġġ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.

MetoduMogħdijaDeskrizzjoni
GET/api/guardrailsElenka s-salvagwardji rreġistrati u l-istatus tagħhom (isem / attivat / prijorità)
POST/api/guardrails/testWettaq 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).