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

API Reference (Nederlands)

🌐 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 · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇴 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

---

🌐 Talen: 🇺🇸 English | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 Azərbaycan dili | 🇧🇬 Български | 🇧🇩 বাংলা | 🇨🇿 Čeština | 🇩🇰 Dansk | 🇩🇪 Deutsch | 🇬🇷 Ελληνικά | 🇪🇸 Español | 🇪🇪 Eesti | 🇮🇷 فارسی | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇪 Gaeilge | 🇮🇳 ગુજરાતી | 🇳🇬 Hausa | 🇮🇱 עברית | 🇮🇳 हिन्दी | 🇭🇷 Hrvatski | 🇭🇺 Magyar | 🇦🇲 Հայերեն | 🇮🇩 Bahasa Indonesia | 🇳🇬 Igbo | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇬🇪 ქართული | 🇰🇭 ខ្មែរ | 🇮🇳 ಕನ್ನಡ | 🇰🇷 한국어 | 🇱🇹 Lietuvių | 🇱🇻 Latviešu | 🇮🇳 മലയാളം | 🇮🇳 मराठी | 🇲🇾 Bahasa Melayu | 🇲🇹 Malti | 🇲🇲 မြန်မာ | 🇳🇵 नेपाली | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇮🇳 ଓଡ଼ିଆ | 🇮🇳 ਪੰਜਾਬੀ | 🇵🇭 Filipino | 🇵🇱 Polski | 🇵🇹 Português (Portugal) | 🇧🇷 Português (Brasil) | 🇷🇴 Română | 🇷🇺 Русский | 🇱🇰 සිංහල | 🇸🇰 Slovenčina | 🇸🇮 Slovenščina | 🇷🇸 Српски | 🇸🇪 Svenska | 🇰🇪 Kiswahili | 🇮🇳 தமிழ் | 🇮🇳 తెలుగు | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇵🇰 اردو | 🇺🇿 Oʻzbekcha | 🇻🇳 Tiếng Việt | 🇳🇬 Yorùbá | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

Kernreferentie voor de OmniRoute-API. Deze behandelt het openbare /v1-oppervlak en de meestgebruikte beheerendpoints; het machineleesbare docs/openapi.yaml en de routeboom onder src/app/api/ zijn de volledige bronnen.

---

Inhoudsopgave

• Chatvoltooiingen
• Exclusieve leases voor beheerde sessies
• Embeddings
• Afbeeldingen genereren
• OCR voor documenten
• Modellen weergeven
• Manifest voor providerplug-ins
• Compatibiliteitseindpunten
• Bestanden-API
• Batches-API
• Zoek-API
• WebSocket-streaming
• Quota- en probleemrapportage
• Semantische cache
• Dashboard en beheer
• Combobeheer
• Webhooks
• Geregistreerde sleutels (automatisch beheer)
• Agentprotocol
• Beheerproxy's
• Robuustheid (uitgebreid)
• Vaardigheden
• Geheugen
• MCP-server
• A2A-server
• Cloud, evaluaties en beoordeling
• Verwerking van verzoeken
• Authenticatie

---

Chatvoltooiingen

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

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Write a function to..."}
  ],
  "stream": true
}

Aangepaste headers

Header	Richting	Beschrijving
X-OmniRoute-No-Cache	Verzoek	Stel in op true om de cache te omzeilen
x-omniroute-no-memory	Verzoek	Stel in op true om de injectie van geheugen en vaardigheden voor dit verzoek over te slaan (analoog aan no-cache; voorkomt de overhead voor tokens/kosten per aanroep)
X-OmniRoute-Progress	Verzoek	Stel in op true voor voortgangsgebeurtenissen
X-Session-Id	Verzoek	Sticky-sessiesleutel voor externe sessieaffiniteit
x_session_id	Verzoek	Variant met onderstrepingstekens wordt ook geaccepteerd (rechtstreekse HTTP)
X-OmniRoute-Session-Id	Verzoek	Door de aanroeper opgegeven sessie-/conversatietag (wordt ook aan het geheugen doorgegeven). Indien aanwezig, wordt deze ongewijzigd opgeslagen in call_logs.session_tag voor kostentoewijzing per sessie (#8249) — wordt nooit gegenereerd indien afwezig
Idempotency-Key	Verzoek	Deduplicatiesleutel (venster van 5 s)
X-Request-Id	Verzoek	Alternatieve deduplicatiesleutel
X-OmniRoute-Cache	Antwoord	HIT of MISS (zonder streaming)
X-OmniRoute-Idempotent	Antwoord	true indien gededupliceerd
X-OmniRoute-Progress	Antwoord	enabled als voortgangsregistratie is ingeschakeld
X-OmniRoute-Session-Id	Antwoord	Effectieve sessie-ID die door OmniRoute wordt gebruikt
X-OmniRoute-Request-Id	Antwoord	Correlatie-ID van het verzoek (indien bekend)
X-OmniRoute-Version	Antwoord	Buildversie van OmniRoute (altijd aanwezig)
X-OmniRoute-Cost-Saved	Antwoord	Bedrag in USD dat dankzij de cache is bespaard bij een HIT (alleen cachetreffers)
X-OmniRoute-Decision	Antwoord	Routeringstracering: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> is de combostrategie, of single voor een verzoek zonder combo) — altijd aanwezig in voltooiingsantwoorden

Opmerking voor Nginx: als u afhankelijk bent van headers met onderstrepingstekens (bijvoorbeeld x_session_id), schakel dan underscores_in_headers on; in.

Headers voor kostentelemetrie: niet-streamende succesvolle responses bevatten ook de set X-OmniRoute-* voor kostentelemetrie — X-OmniRoute-Response-Cost (USD, vast 10 decimalen; 0.0000000000 voor gratis/niet-geprijsd), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit en X-OmniRoute-Fallback-Attempts (alleen wanneer > 0), plus X-OmniRoute-Request-Id en X-OmniRoute-Version. Deze worden uitgestuurd door chatvoltooiingen, /v1/responses, /v1/messages, en de media-endpoints — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations en /v1/moderations (kosten altijd 0). Mediakosten worden per modaliteit berekend (per afbeelding, per seconde, per teken, per zoekeenheid) wanneer prijsinformatie beschikbaar is; anders zijn ze 0 (fail-open).

Kostensemantiek bij cachetreffers: bij een HIT in de semantische cache (X-OmniRoute-Cache-Hit: true) wordt geen upstream-aanroep gedaan. Daarom is X-OmniRoute-Response-Cost gelijk aan 0.0000000000 (de incrementele kosten voor het afhandelen van de treffer). De oorspronkelijke kosten/kosten die anders zouden zijn gemaakt, worden afzonderlijk gerapporteerd in X-OmniRoute-Cost-Saved. Facturatieprocessen moeten X-OmniRoute-Response-Cost optellen (treffers kosten niets); voor cacheanalyses kan X-OmniRoute-Cost-Saved worden geaggregeerd.

Exclusieve beheerde sessieleases

Exclusieve leasing van beheerde sessies is een optioneel, clientneutraal routeringscontract: één actieve eigenaar houdt één geschikte OmniRoute-verbinding bezet. Hiermee wordt geen model geleaset, OAuth is niet vereist, er wordt geen specifieke client geïdentificeerd en er is geen specifieke provider vereist.

De API-sleutel die voor authenticatie wordt gebruikt, moet het bereik lease:exclusive en een expliciete, niet-lege allowedConnections-lijst hebben. De mutatiegrens van de database dwingt beide velden gezamenlijk af bij het aanmaken en gedeeltelijk bijwerken van sleutels.

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

Geslaagde antwoorden voor verwerving, verlenging en vrijgave bevatten tijdstempels, state en de exacte positieve generation, maar nooit de geselecteerde verbinding of referenties. Voor verlenging en vrijgave wordt de generatie in de JSON-body opgegeven:

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

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

Een actieve lease-eigenaar kan expliciet privacyveilige weergavemetadata opvragen voor de huidige koppeling:

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

Deze optionele statusactie wordt binnen één databasetransactie afgeschermd door de ondoorzichtige eigenaar, de geauthenticeerde beheerde API-sleutel en de exacte actieve generatie. displayName is uitsluitend de bijgesneden, geconfigureerde verbindingsnaam; deze is null wanneer er geen veilige geconfigureerde naam bestaat. OmniRoute gebruikt nooit ter vervanging een e-mailadres of gegenereerde accountidentiteit. De providerwaarde is een niet-gevoelig weergavelabel en nooit een gegenereerde identificatie voor een compatibele provider. Referenties, tokens, cookies, onbewerkte verbindings- of API- sleutel-id's, eigenaarshashes, afschermingsgeheimen en interne routeringsgegevens worden uitgesloten.

Opzoekacties met een verkeerde sleutel, verkeerde eigenaar, verouderde generatie, ontbrekende, verlopen, vrijgegeven of ongeldig gemaakte lease retourneren allemaal dezelfde fout 409 LEASE_FENCE_STALE, zonder verbindingsmetadata. Een client die het antwoord voor wachten op capaciteit heeft ontvangen, heeft geen actieve koppeling die kan worden geïnspecteerd. Wanneer bij het routeren een actieve lease naar een andere verbinding overgaat, blijft dezelfde generatie geldig en retourneert de status atomair de nieuwe koppeling, nooit de oude. Bestaande clients blijven ongewijzigd, omdat antwoorden voor verwerving, verlenging, vrijgave en wachten hun eerdere structuur behouden.

Dit servercontract wijzigt /status van de standaardversie van OpenAI Codex niet. De standaardversie van Codex rapporteert momenteel zijn modelprovider en ingebouwde authenticatie-/accountstatus, maar geeft geen willekeurige aangepaste provideraccountmetadata weer; een latere clientintegratie moet deze actie aanroepen en bepalen hoe connection.displayName wordt weergegeven.

Elk beheerd inferentieverzoek levert vervolgens beide besturingsheaders aan:

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

De exacte eigenaar, generatie, actieve verbinding en geauthenticeerde API-sleutel worden onmiddellijk vóór elke ondersteunde upstream-poging afgeschermd. Het opnieuw gebruiken van de eigenaar en generatie met een andere sleutel mislukt, zelfs wanneer die sleutel dezelfde verbinding toestaat. Onbewerkte eigenaren worden niet persistent opgeslagen, gelogd, in de verzoeksnapshot bewaard of upstream doorgestuurd.

Tijdelijke capaciteitsconcurrentie retourneert HTTP 429 met Retry-After en:

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

Dit antwoord betekent alleen dat de normale verzameling geschikte verbindingen niet leeg was en elke beschikbare kandidaat door een externe actieve lease bezet was. Niet-ondersteunde modellen/providers, niet-overeenkomend beleid, afkoelperiode, quota, status en andere normale geschiktheidsfouten behouden hun bestaande OmniRoute-antwoorden.

x-omniroute-compression

Overschrijving per verzoek van het compressieplan. Hoogste prioriteit — heeft voorrang op de overschrijving van de routeringscombinatie, het actieve profiel, de automatische trigger en de standaardinstelling van het paneel. Waarden:

Waarde	Effect
off	Geen compressie voor dit verzoek.
default	Het uit het paneel afgeleide standaardprofiel (negeert het actieve profiel).
engine:<id>	Eén engine wanneer deze is ingeschakeld, bijvoorbeeld engine:rtk.
<combo>	Een benoemde combinatie, eerst op naam vergeleken (hoofdletterongevoelig) en vervolgens op id.

Opmerkingen:

• Onbekende waarden worden genegeerd (het verzoek wordt nooit afgewezen); de bepaling valt terug op de normale prioriteitsvolgorde voor operatoren.
• Als meerdere combinaties dezelfde naam hebben, geeft u de id van de combinatie door voor een deterministische overeenkomst.
• Een combinatie met de naam off of default kan niet op naam worden geselecteerd (die trefwoorden worden eerst geïnterpreteerd); verwijs naar een dergelijke combinatie via de id.
• De hoofdschakelaar voor compressie vormt een harde blokkade: wanneer compressie globaal is uitgeschakeld, kan deze header deze niet inschakelen.

Het toegepaste plan wordt teruggestuurd in de responsheader:

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

waarbij <source> een van request-header, routing-override, active-profile, auto-trigger, default of off is.

---

Embeddings

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

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

Beschikbare providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.

Catalogus-id's hebben de vorm provider/model (voorbeeld: jina-ai/jina-embeddings-v5-omni-small). Losse Jina-model-id's die in het register voorkomen (bijvoorbeeld jina-embeddings-v5-text-small, jina-reranker-v3.5) worden ook herkend. Jina embed/rerank/classify/segment gebruikt eerst jina-ai-inloggegevens uit het dashboard; JINA_AI_API_KEY wordt alleen als terugvaloptie gebruikt wanneer er geen dashboardsleutel bestaat. De kaart jina-reader is uitsluitend voor Reader / r.jina.ai (POST /v1/web/fetch) en levert nooit embeddings of reranking.

Registermodellen die multimodale ondersteuning aangeven, accepteren ook maximaal 32 providersonafhankelijke gestructureerde items. Typen media-items zijn text, image, audio, video en document. Hun media-source is {"type":"url","url":"https://..."} of {"type":"base64","data":"...","media_type":"..."}.

Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano, en de familie-alias jina-ai/jina-embeddings-v5-omni → omni-small) accepteert ook de systeemeigen EmbeddingsV5Request-documenten van Jina en stuurt deze intact door naar 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,..." }]
    }
  ]
}

Systeemeigen { image | audio | video | pdf }-waarden mogen een openbare HTTPS-URL, een data:-URI of onbewerkte base64 zijn. OmniRoute converteert deze objecten niet naar tekenreeksen en haalt systeemeigen afbeeldings-URL's niet op — Jina haalt openbare media zelf op. Extra Jina-velden (task, normalized, truncate, embedding_type) worden doorgestuurd. Jina-SKU's die uitsluitend tekst ondersteunen, weigeren nog steeds documenten die geen tekst bevatten.

Beveiligings- en transportlimieten:

• Externe media-URL's moeten openbaar en via HTTPS bereikbaar zijn. Canonieke {type,source:url}-items worden aan de serverzijde opgehaald (hervalidatie van omleidingen, time-out, groottelimieten, openbare DNS, verbindingsvastlegging) en vóór de provideraanroep inline ingevoegd. Systeemeigen Jina-items van de vorm {image:"https://..."} worden ongewijzigd doorgestuurd na dezelfde controle op openbare HTTPS; Jina haalt de URL op.
• Inline base64-media zijn beperkt tot 8 MiB gedecodeerd per item en 16 MiB gedecodeerd voor het volledige verzoek.

Providervertaling (canonieke items worden nooit ongewijzigd doorgestuurd):

• Multimodale Jina-modellen: elk item op het hoogste niveau wordt één object met een modaliteitssleutel (text / image / audio / video / pdf), waarbij data-URI's worden gebruikt voor inline media; één vector per item op het hoogste niveau.
• Gemini Embedding 2-familie: één array op het hoogste niveau wordt één systeemeigen models/{model}:embedContent-verzoek met content.parts (text of inline_data).
• Onbekende/dynamische modellen zonder expliciete modaliteitsmetadata weigeren gestructureerde invoer met 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"
}

Niet-ondersteunde combinaties van model en modaliteit retourneren HTTP 400 in plaats van het item te converteren. Uitbreidingsvelden die geen invoervelden zijn, blijven bij verouderde tekenreeks-/tokenverzoeken ongewijzigd doorgegeven.

# Alle embeddingmodellen weergeven
GET /v1/embeddings

---

Afbeeldingen genereren

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

{
  "model": "openai/gpt-image-2",
  "prompt": "Een prachtige zonsondergang boven bergen",
  "size": "1024x1024"
}

Beschikbare providers: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (lokaal), ComfyUI (lokaal).

# Alle afbeeldingsmodellen weergeven
GET /v1/images/generations

---

OCR voor documenten

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 selecteert de OCR-provider via een voorvoegsel provider/model; een losse model-id (bijv. mistral-ocr-latest) wordt gekoppeld aan de geregistreerde provider ervan, en als model wordt weggelaten, wordt standaard Mistral (mistral-ocr-latest) gebruikt. Geregistreerde providers (open-sse/config/ocrRegistry.ts):

Provider-id	Model-id	model-waarde	Opmerkingen
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest (of alleen mistral-ocr-latest)	Synchroon — het antwoord wordt rechtstreeks door de enkele upstream-aanroep geretourneerd.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	Asynchrone upstream (analyze + polling) — zie hieronder.
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	Synchroon, via het openapi/chat/completions-partnerendpoint van Vertex AI — zie hieronder voor authenticatie/URL.

Alle drie providers antwoorden met dezelfde door Mistral gebruikte structuur:

{
  "pages": [{ "index": 0, "markdown": "# Geëxtraheerde tekst..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}

Pollingproces van Azure Document Intelligence

De analyze-API van Azure Document Intelligence is asynchroon: het initiële verzoek retourneert een Operation-Location-header in plaats van een berichttekst, waarna het resultaat via polling moet worden opgehaald. De handler (open-sse/handlers/ocr.ts) pollt die URL elke seconde, met maximaal 30 pogingen, stopt onmiddellijk (zonder door te gaan met pollen) bij een niet-ok-antwoord op een poll of bij de status "failed", en retourneert 504 als de bewerking nog steeds actief is nadat het maximale aantal pogingen is bereikt. Het uiteindelijke Azure-antwoord wordt genormaliseerd naar dezelfde pages/markdown-structuur die door Mistral wordt gebruikt voordat het aan de aanroeper wordt geretourneerd, zodat clientcode de provider niet als speciaal geval hoeft te behandelen.

Authenticatie en endpointresolutie voor Vertex AI DeepSeek OCR

vertex-deepseek-ocr gebruikt dezelfde Vertex AI-authenticatie die OmniRoute al ondersteunt voor chat-/afbeeldingsverkeer (open-sse/executors/vertex.ts): de API-sleutel van de verbinding is een Service Account JSON-referentie (die via de JWT-bearerflow wordt ingewisseld voor een kortlevend OAuth-toegangstoken) of een reeds uitgegeven OAuth-toegangstoken dat ongewijzigd wordt gebruikt. De upstream-endpoint-URL is het algemene openapi/chat/completions-partnerendpoint van Vertex en wordt opgebouwd uit het project en de regio van de verbinding — een expliciete providerSpecificData.project/providerSpecificData.region heeft altijd voorrang; anders wordt het project afgeleid van project_id uit de Service Account JSON en wordt voor de regio standaard us-central1 gebruikt. Beide resoluties vinden plaats in open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl) en worden gebruikt door src/app/api/v1/ocr/route.ts voordat de aanvraag naar handleOcr wordt doorgestuurd.

---

Modellen weergeven

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

→ Retourneert alle chat-, embedding- en afbeeldingsmodellen + combinaties in OpenAI-indeling

Model-id-prefixen (?prefix=)

De meeste modellen worden aangeboden onder een providerprefix. Welk prefix je krijgt, wordt bepaald door de featureflag MODELS_CATALOG_PREFIX_MODE en kan per verzoek worden overschreven met een queryparameter — handig voor een client die een overzichtelijke lijst wil zonder de serverbrede instelling voor alle anderen te wijzigen:

GET /v1/models?prefix=alias        # één id per model — het korte aliasprefix
GET /v1/models?prefix=dual         # beide vormen (standaardinstelling van de server)
GET /v1/models?prefix=canonical    # alleen het volledige provider-id-prefix

Modus	Geeft terug	Opmerkingen
dual	cc/claude-sonnet-4-6 en claude/claude-sonnet-4-6	Standaard. Beide id's worden naar hetzelfde model gerouteerd; dit blijft behouden zodat clientconfiguraties waarin een van beide vormen hardgecodeerd is, blijven werken. Verdubbelt de catalogus ongeveer.
alias	cc/claude-sonnet-4-6	Eén vermelding per model. Providers zonder afzonderlijke alias geven hun vermelding nog steeds terug, zodat er niets verloren gaat.
canonical	claude/claude-sonnet-4-6	Eén vermelding per model onder het volledige provider-id-prefix. Providers zonder afzonderlijke alias (bijv. antigravity/…, agy/…) geven hier ook hun enige id terug, zodat er niets verloren gaat.

Een mirror in de modus dual kan ook zonder de queryparameter worden herkend: deze bevat een veld parent dat naar het primaire id verwijst.

Clients die een modelkiezer weergeven, moeten ?prefix=alias aanvragen — dit is wat de OmniCopilot VS Code-extensie doet.

Modelvarianten zonder denkmodus

Voor Claude-modellen die denkfunctionaliteit ondersteunen, biedt /v1/models ook een variant zonder denkmodus aan, waarvan het id wordt voorafgegaan door claude-3-omniroute-no-thinking/:

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

Als dit id wordt geselecteerd (bijv. in een Claude Code-configuratie die altijd een thinking-blok toevoegt), wordt het terugverwezen naar het echte <provider>/<model>, waarbij redeneren wordt onderdrukt — thinking:{type:"disabled"} op het /v1/messages-pad, of waarbij de velden reasoning/reasoning_effort op het /v1/chat/completions-pad worden weggelaten. De variant wordt alleen vermeld voor modellen uit de Claude-familie die denkfunctionaliteit ondersteunen en disabled respecteren (dus bijvoorbeeld modellen die alleen adaptief werken en disabled afwijzen, worden uitgesloten). Beheerders kunnen de variant per model geforceerd in- of uitschakelen via ModelSpec.noThinkingAlias.

---

Manifest voor providerplug-ins

GET /api/v1/provider-plugin-manifest

Retourneert het JSON-veilige manifest voor providerplug-ins dat wordt gebruikt door Bifrost, CLIProxyAPI en toekomstige sidecarrouters. De respons wordt gegenereerd op basis van het TypeScript-providerregister en sluit OAuth-clientgeheimen, runtime-omgevingsresolutie, uitvoerfuncties, requestheaders en accountgegevens bewust uit.

Gebruik dit endpoint wanneer een sidecar buiten het proces wordt uitgevoerd en open-sse/config/providerPluginManifestRegistry.ts niet rechtstreeks kan importeren.

---

Compatibiliteitsendpoints

Methode	Pad	Indeling
POST	/v1/chat/completions	OpenAI
POST	/v1/messages	Anthropic
POST	/v1/responses	OpenAI Responses
POST	/v1/embeddings	OpenAI
POST	/v1/images/generations	OpenAI Images
POST	/v1/images/edits	OpenAI Images (bewerken/inpainten)
POST	/v1/videos/generations	Videogeneratie in OpenAI-stijl
POST	/v1/music/generations	Muziekgeneratie in OpenAI-stijl
POST	/v1/audio/transcriptions	OpenAI Audio (spraak-naar-tekst)
POST	/v1/audio/speech	OpenAI TTS (retourneert audiobody)
POST	/v1/rerank	Herrangschikking in Cohere/Voyage-stijl
POST	/v1/classify	Jina-classificatie (api.jina.ai)
POST	/v1/segment	Jina-segmenter (segment.jina.ai)
POST	/v1/moderations	OpenAI Moderations
GET	/v1/models	OpenAI
POST	/v1/messages/count_tokens	Anthropic
GET	/v1beta/models	Gemini
POST	/v1beta/models/{...path}	Gemini generateContent
POST	/v1/api/chat	Ollama
GET	/api/v1/vscode/{token}/	OpenAI-catalogusalias
GET	/api/v1/vscode/{token}/models	OpenAI-modellenalias
POST	/api/v1/vscode/{token}/chat/completions	OpenAI-alias met token
POST	/api/v1/vscode/{token}/responses	OpenAI Responses-alias met token
POST	/api/v1/vscode/{token}/api/chat	Ollama-alias met token
GET	/api/v1/vscode/{token}/api/tags	Ollama-tagsalias met token

Alle POST-routes volgen dezelfde structuur: Bearer your-api-key + een door Zod gevalideerde JSON-body (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema, enzovoort; zie src/shared/validation/schemas.ts). Bij een schemafout wordt 4xx geretourneerd.

Voor clients die Authorization: Bearer ... niet kunnen meesturen, accepteert OmniRoute ook API-sleutels in de URL via querystringcompatibiliteit (?token=..., ?apiKey=..., ?api_key=..., ?key=...) of via de speciale /api/v1/vscode/{token}/...-endpoints die hieronder worden beschreven.

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

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

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

# Jina-zoekopdracht (s.jina.ai; provideraliases: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

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

# TTS — retourneert een audio/mpeg-body (of de aangevraagde indeling)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

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

# Video-/muziekgeneratie (model-ID met providerprefix)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Speciale providerroutes

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

Het providerprefix wordt automatisch toegevoegd als het ontbreekt. Niet-overeenkomende modellen retourneren 400.

---

Files-API

OpenAI-compatibel bestandseindpunt voor batchinvoer/-uitvoer en uploads met een bestandsdoel.

Methode	Pad	Beschrijving
POST	/v1/files	Upload een bestand (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — max. 512 MiB
GET	/v1/files	Geef bestanden weer voor de geverifieerde API-sleutel
GET	/v1/files/[id]	Haal de metagegevens van een bestand op
DELETE	/v1/files/[id]	Verwijder een bestand
GET	/v1/files/[id]/content	Stream de onbewerkte bestandsinhoud terug

Authenticatie: Bearer-API-sleutel — bestanden zijn per API-sleutel afgeschermd via getApiKeyRequestScope. Een sleutel kan alleen zijn eigen bestanden zien, downloaden en verwijderen; een dashboardsessie zonder sleutel kan de hele instantie lezen; een bestand zonder eigenaar (anonieme upload of upload via een dashboardsessie) wordt voor elke aanroeper zonder sessie geweigerd. GET /v1/files weigert een anonieme aanroeper — en een opgegeven sleutel die niet kan worden gevonden — met 401, zelfs wanneer REQUIRE_API_KEY=false, in plaats van de bestanden van alle tenants weer te geven (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

Batches-API

OpenAI-compatibele batchverwerking.

Methode	Pad	Beschrijving
POST	/v1/batches	Maak een batch aan — body gevalideerd door v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET	/v1/batches	Geef batches weer
GET	/v1/batches/[id]	Haal de batchstatus + request_counts op
DELETE	/v1/batches/[id]	Verwijder een voltooide/mislukte batch
POST	/v1/batches/[id]/cancel	Annuleer een batch die wordt verwerkt

Authenticatie: Bearer-API-sleutel. Batches zijn per API-sleutel afgeschermd volgens dezelfde drievoudige regel als bestanden: alleen de eigen sleutel, een dashboardsessie voor de hele instantie, en records zonder eigenaar worden geweigerd voor elke aanroeper zonder sessie (ophalen, verwijderen, annuleren en de controle van input_file_id bij het aanmaken). GET /v1/batches weigert een anonieme aanroeper met 401, zelfs wanneer REQUIRE_API_KEY=false.

---

Search-API

Abstractielaag voor web-/zoekproviders (Tavily, Brave, Exa, Serper, enz.).

Methode	Pad	Beschrijving
GET	/v1/search	Geconfigureerde zoekproviders en mogelijkheden weergeven
POST	/v1/search	Een zoekopdracht uitvoeren — body gevalideerd door v1SearchSchema, ondersteunt caching/coalescing
GET	/v1/search/analytics	Statistieken per provider voor hits/latentie/cache

Authenticatie: Bearer-API-sleutel (extractApiKey + isValidApiKey). Zoekbeleid wordt afgedwongen via enforceApiKeyPolicy.

---

Web Fetch-API

Extraheer inhoud uit een URL via een geconfigureerde web-fetchprovider (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

Methode	Pad	Beschrijving
POST	/v1/web/fetch	Een URL ophalen/scrapen — body gevalideerd door v1WebFetchSchema

Authenticatie: Bearer-API-sleutel (extractApiKey + isValidApiKey). Beleid wordt afgedwongen via enforceApiKeyPolicy.

Quotabewuste fallback (#8297): wanneer geen expliciete provider is opgegeven, wordt de pool (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) in een vaste prioriteitsvolgorde doorlopen (fill-first) — een provider die is geconfigureerd maar waarvan de snelheidslimiet is bereikt, wordt overgeslagen in plaats van dat het verzoek direct wordt afgebroken, en een herhaalbare upstreamfout/quotafout (altijd HTTP 429; 402/403 voor quota-achtige gratis niveaus van Firecrawl/Tavily/TinyFish — niet voor Jina Reader en nooit voor een gewone 400-fout wegens een ongeldig verzoek) valt tijdens het verzoek terug op de volgende nog niet geprobeerde provider waarvoor referenties beschikbaar zijn. Wanneer elke provider in de pool is uitgeput, retourneert het endpoint één 429 (met een Retry-After-header) in plaats van de eerdere generieke 400. Wanneer expliciet een provider wordt aangevraagd, is er geen stille fallback — een expliciete provider waarvan de snelheidslimiet is bereikt of die faalt, geeft zijn eigen fout door (429 als de snelheidslimiet is bereikt, anders de upstreamstatus).

---

WebSocket-streaming

GET /v1/ws?handshake=1

Valideert een WebSocket-upgradehandshake en retourneert de voorbeeldberichten van het wire-protocol (request, cancel). Daadwerkelijke WS-frames worden afgehandeld door de meegeleverde WS-server buiten de Next.js-routetabel.

Authenticatie: Bearer-API-sleutel tijdens de handshake.

Responses-API via WebSocket (alleen codex)

# Dezelfde host:poort als de HTTP-API (standaard 20128); upgrade de verbinding:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (of: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Het eerste frame MOET response.create zijn:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Een Responses-API-over-WebSocket-proxy is uitsluitend met codex verbonden (ChatGPT- backend). Deze luistert op dezelfde poort als de API/het dashboard via de paden /v1/responses, /responses en /api/v1/responses. Bij het eerste response.create-frame wordt via de interne codex-responses-ws-bridge geauthenticeerd en voorbereid, een codex OAuth-verbinding geselecteerd en via het wreq-js-transport een tunnel opgezet naar wss://chatgpt.com/backend-api/codex/responses. Niet-codex-modellen worden geweigerd (codex_ws_provider_required). Gebruik voor routering op basis van quota-aandeel model: "qtSd/<group>/codex/<model>". Geïmplementeerd in app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.

Authenticatie: Bearer-API-sleutel tijdens de handshake. De meegeleverde HTTP-server (server-ws.mjs) moet het actieve toegangspunt zijn (wat standaard het geval is wanneer app/server-ws.mjs bestaat).

Model-id: gebruik de kale ChatGPT-id (zonder het voorvoegsel codex/)

De OpenAI Codex CLI valideert de modelnaam aan de clientzijde wanneer supports_websockets = true en weigert ids met een providervoorvoegsel, zoals codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Verstuur de kale id (bijvoorbeeld gpt-5.5). De bridge van OmniRoute is uitsluitend voor codex, waardoor deze een kale id opnieuw omzet naar een codex-model (resolveCodexWsModelInfo) voordat de tunnel naar upstream wordt opgezet — ook al zou een kale gpt-5.5 via HTTP anders naar een andere provider worden gerouteerd.

De OpenAI Codex CLI configureren

Laat de Codex CLI naar OmniRoute verwijzen door een aangepaste provider met WebSocket- ondersteuning toe te voegen aan ~/.codex/config.toml (gebruik een afzonderlijke CODEX_HOME om een bestaande configuratie niet te wijzigen):

model = "gpt-5.5"                 # kale id — NIET "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # geen afsluitende slash; de WS-URL wordt afgeleid (gebruik https/wss in productie)
wire_api = "responses"                    # enige ondersteunde waarde sinds feb 2026
supports_websockets = true                # schakelt het Responses-over-WS-transport in
env_key = "OMNIROUTE_API_KEY"             # bevat de OmniRoute-API-sleutel (Bearer)

export OMNIROUTE_API_KEY=sk-...           # een OmniRoute-API-sleutel (elke sleutel als REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

De CLI upgradet base_url + /responses naar een WebSocket en OmniRoute tunnelt deze naar de geselecteerde codex OAuth-verbinding. End-to-end gevalideerd met de lokale server: ChatGPT retourneert codex.rate_limits + response.created en streamt de voltooiing.

---

Quota's en probleemrapportage

Methode	Pad	Beschrijving
GET	/v1/quotas/check	Valideer vooraf het quotum voor een provider + accountId voordat een geregistreerde sleutel wordt uitgegeven
POST	/v1/issues/report	Rapporteer een fout bij het uitgeven van een quotum/sleutel aan GitHub (vereist GITHUB_ISSUES_REPO + token)

Authenticatie: Bearer-API-sleutel (isAuthenticated).

---

Zelfbedieningsgebruik (/api/usage/om-usage)

Elke API-sleutel kan het eigen gebruik en de eigen quota lezen — zonder beheerauthenticatie. Dit is het endpoint dat een client (CLI, het OmniCopilot-paneel) gebruikt om de uitgaven van een sleutelhouder weer te geven.

# Tekstvorm (het historische contract — platte tekst voor een terminal)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Gestructureerde vorm — wat een gebruikersinterface gebruikt
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

Voor de sleutel moet allowUsageCommand zijn ingeschakeld (standaard uitgeschakeld — het API-sleutelbeheer van het dashboard schakelt dit per sleutel in of uit). Zonder deze instelling antwoordt het endpoint met 403.

?format=json retourneert een gediscrimineerde structuur, zodat een aanroeper nooit een gegevensveld van een weigering uitleest. Bij succes:

{
  "allowed": true,
  // alleen aanwezig wanneer voor de sleutel gebruikslimieten per sleutel zijn ingesteld (dagelijks/wekelijks in USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // de geselecteerde momentopname van het providerquotum, of null wanneer er nog niets in de cache staat:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // de momentopname van elke verbinding, zodat een gebruikersinterface meerdere providers naast elkaar kan weergeven:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

Bij weigering (401 ongeldige sleutel / 403 niet toegestaan) retourneert dezelfde route { "allowed": false, "error": { "message": "…" } } — een aanwezige maar lege personal/provider (sleutel toegestaan, nog niets gedetecteerd) is een andere status dan een weigering, en alleen de JSON-vorm maakt daar onderscheid tussen.

Authenticatie: de eigen Bearer-API-sleutel van de aanroeper, gevalideerd met isValidApiKey — dit is niet het beheeroppervlak (/api/keys/…), dat beschermd blijft door requireManagementAuth.

---

Semantische cache

# Cachestatistieken ophalen
GET /api/cache/stats

# Alle caches wissen
DELETE /api/cache/stats

Voorbeeld van een respons:

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

Invloed op latentie

Bij een HIT in de semantische cache wordt de respons vanuit de cache geleverd zonder een upstream-aanroep, waardoor de gerapporteerde X-OmniRoute-Response-Latency vrijwel nul is (ongeacht de oorspronkelijke upstream-latentie). Clients waarvoor latentie belangrijk is (benchmarking, p50/p99-monitoring), moeten de responsheader X-OmniRoute-Cache-Latency controleren:

Waarde	Betekenis
synthetic	Respons geleverd vanuit de cache; latentie is geen echte upstream-tijd
(afwezig)	Respons van een echte upstream-aanroep

Cache per sleutel omzeilen

API-sleutels kunnen het lezen uit de semantische cache uitschakelen via cacheDefaultMode:

Waarde	Gedrag
legacy	Normaal cachegedrag (standaard)
bypass	Sla het raadplegen van de cache volledig over; gebruik altijd upstream

Instellen bij het maken van een sleutel (POST /api/keys) of bijwerken (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

Omzeilen per verzoek

Elk verzoek kan de cache omzeilen, ongeacht de sleutelinstellingen:

X-OmniRoute-No-Cache: true

---

Dashboard & beheer

Beheerroutes (/api/* met uitzondering van openbare authenticatie/aanmelding) worden niet geautoriseerd met gewone API-sleutels voor inferentie. Referentie voor typen inloggegevens, scopes en curl-voorbeelden: Beheerauthenticatie.

Authenticatie

Endpoint	Methode	Beschrijving
/api/auth/login	POST	Aanmelden
/api/auth/logout	POST	Afmelden
/api/settings/require-login	GET/PUT	Verplichte aanmelding in-/uitschakelen

Providerbeheer

Endpoint	Methode	Beschrijving
/api/providers	GET/POST	Providers weergeven / aanmaken
/api/providers/[id]	GET/PUT/DELETE	Een provider beheren
/api/providers/[id]/test	POST	Providerverbinding testen
/api/providers/[id]/models	GET	Providermodellen weergeven
/api/providers/validate	POST	Providerconfiguratie valideren
/api/providers/bulk	POST	API-sleutels voor ÉÉN provider bulksgewijs toevoegen
/api/providers/import	POST	Een heterogene providerLIJST importeren uit een geparseerd CSV-/JSON-bestand (#6836); resultaten met gedeeltelijke fouten per rij
/api/provider-nodes*	Diverse	Providernodes beheren
/api/provider-models	GET/POST/PATCH/DELETE	Aangepaste modellen (toevoegen, bijwerken, verbergen/weergeven, verwijderen)

OAuth-stromen

Endpoint	Methode	Beschrijving
/api/oauth/[provider]/[action]	Diverse	Providerspecifieke OAuth

Routering en configuratie

Endpoint	Methode	Beschrijving
/api/models/alias	GET/POST	Modelaliassen
/api/models/catalog	GET	Alle modellen per provider en type
/api/combos*	Diverse	Combobeheer
/api/keys*	Diverse	API-sleutelbeheer
/api/pricing	GET	Modelprijzen

Gebruik en analyses

Endpoint	Methode	Beschrijving
/api/usage/history	GET	Gebruiksgeschiedenis
/api/usage/logs	GET	Gebruikslogboeken
/api/usage/request-logs	GET	Logboeken op verzoekniveau
/api/usage/[connectionId]	GET	Gebruik per verbinding
/api/usage/token-limits	GET/POST/DELETE	Tokenlimietbudgetten per API-sleutel
/api/usage/model-latency-stats	GET	Doorlopend latentie-aggregaat per provider/model (gem./p50/p95/p99, succespercentage); filters: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health	GET	Samenvatting van de gezondheid van de promptcache op basis van call_logs — schrijf-/leesverhouding, p50/p90/p99-verdeling van schrijfgrootte, concentratie van zware schrijfacties, uitsplitsing per model en een oordeel healthy/degraded/thrash/no-data; queryparameters range (1h|24h|7d|30d, standaard 24h) en optioneel model (#8827)

Instellingen

Endpoint	Methode	Beschrijving
/api/settings	GET/PUT/PATCH	Algemene instellingen
/api/settings/proxy	GET/PUT	Netwerkproxyconfiguratie
/api/settings/proxy/test	POST	Proxyverbinding testen
/api/settings/ip-filter	GET/PUT	IP-toestaanlijst/blokkeerlijst
/api/settings/thinking-budget	GET/PUT	Herschrijfmodus voor verzoeken voor denk-/redeneerbudget (doorgeven / automatisch verwijderen / aangepast / adaptief). Onafhankelijk van compressie. Zie THINKING_BUDGET.md.
/api/settings/system-prompt	GET/PUT	Globale systeemprompt
/api/settings/compression	GET/PUT	Globale compressieconfiguratie
/api/settings/purge-request-history	POST	Rijen uit verzoeklogboek en lokale oproeplogboekartefacten wissen

Context en compressie

Endpoint	Methode	Beschrijving
/api/compression/preview	POST	Voorbeeld van uit/lite/standaard/agressieve/ultra/RTK/gestapelde compressie
/api/compression/language-packs	GET	Beschikbare Caveman-taalpakketten weergeven
/api/compression/rules	GET	Metadata van Caveman-regels weergeven
/api/context/caveman/config	GET/PUT	Alias voor Caveman-specifieke instellingen
/api/context/rtk/config	GET/PUT	RTK-specifieke instellingen, inclusief aangepaste filters en behoud van ruwe uitvoer
/api/context/rtk/filters	GET	RTK-filtercatalogus en diagnostiek voor aangepaste filters
/api/context/rtk/test	POST	RTK-voorbeeld/test uitvoeren op een tekstpayload
/api/context/rtk/raw-output/[id]	GET	Bewaarde, geredigeerde ruwe uitvoer lezen op basis van pointer-id
/api/context/combos	GET/POST	Lijst met compressiecombinaties/compressiecombinatie maken
/api/context/combos/[id]	GET/PUT/DELETE	Details van compressiecombinatie/compressiecombinatie bijwerken/verwijderen
/api/context/combos/[id]/assignments	GET/PUT	Compressiecombinaties toewijzen aan routeringscombinaties
/api/context/analytics	GET	Alias voor compressieanalyse

Monitoring

Endpoint	Methode	Beschrijving
/api/sessions	GET	Actieve sessies bijhouden
/api/rate-limits	GET	Snelheidslimieten per account
/api/monitoring/health	GET	Gezondheidscontrole + providersamenvatting (catalogCount, configuredCount, activeCount, monitoredCount). De beheerweergave bevat credentialHealth: scalaire waarden uit de probe-cache, failedConnections wanneer failed>0, en staleDbNonOkCount (blijvende SQLite-waarde test_status, niet de meter). Zie MONITORING_GUIDE.md.
/api/cache/stats	GET/DELETE	Cachestatistieken / wissen
/api/modality-bridge/stats	GET	In-memory attempts, geslaagde pogingen/bridged, mislukkingen, cachetreffers, totalLatencyMs, latencySamples, op steekproeven gebaseerde averageLatencyMs en tijdstip van laatste gebruik (wordt bij herstart gereset; beheerauthenticatie)
/api/modality-bridge/video/runtime	GET	Strikte controle op vertrouwde loopback vóór beheerauthenticatie/probe; opgeschoonde beschikbaarheid en versies van FFmpeg/ffprobe (no-store)
/api/modality-bridge/video/extract	POST	Interne, geauthenticeerde bytebroker via vertrouwde loopback; invoer van 50 MiB, begrensde wachtrij/uitvoer van 32 MiB, 503 bij onvoldoende capaciteit, 499 bij verbreking van de verbinding, 504 bij overschrijding van de deadline; geen openbare upload-API

Back-up en export/import

Endpoint	Methode	Beschrijving
/api/db-backups	GET	Beschikbare back-ups weergeven
/api/db-backups	PUT	Een handmatige back-up maken
/api/db-backups	POST	Herstellen vanuit een specifieke back-up
/api/db-backups/export	GET	Database downloaden als .sqlite-bestand
/api/db-backups/import	POST	.sqlite-bestand uploaden om de database te vervangen
/api/db-backups/exportAll	GET	Volledige back-up downloaden als .tar.gz-archief

Cloudsynchronisatie

Endpoint	Methode	Beschrijving
/api/sync/cloud	Verschillend	Bewerkingen voor cloudsynchronisatie
/api/sync/initialize	POST	Synchronisatie initialiseren
/api/cloud/*	Verschillend	Cloudbeheer

Tunnels

Endpoint	Methode	Beschrijving
/api/tunnels/cloudflared	GET	Installatie-/runtimestatus van Cloudflare Quick Tunnel voor het dashboard opvragen
/api/tunnels/cloudflared	POST	Cloudflare Quick Tunnel in- of uitschakelen (action=enable/disable)
/api/tunnels/ngrok	GET	Runtimestatus van ngrok Tunnel voor het dashboard opvragen
/api/tunnels/ngrok	POST	ngrok Tunnel in- of uitschakelen (action=enable/disable)

CLI-tools

Endpoint	Methode	Beschrijving
/api/cli-tools/claude-settings	GET	Status van Claude CLI
/api/cli-tools/codex-settings	GET	Status van Codex CLI
/api/cli-tools/droid-settings	GET	Status van Droid CLI
/api/cli-tools/openclaw-settings	GET	Status van OpenClaw CLI
/api/cli-tools/runtime/[toolId]	GET	Generieke CLI-runtime

CLI-responsen bevatten: installed, runnable, command, commandPath, runtimeMode, reason.

ACP-agents

Endpoint	Methode	Beschrijving
/api/acp/agents	GET	Alle gedetecteerde agents (ingebouwd + aangepast) met status weergeven
/api/acp/agents	POST	Aangepaste agent toevoegen of detectiecache vernieuwen
/api/acp/agents	DELETE	Een aangepaste agent verwijderen via de queryparameter id

De GET-respons bevat agents[] (id, name, binary, version, installed, protocol, isCustom) en summary (total, installed, notFound, builtIn, custom).

Veerkracht en frequentielimieten

Endpoint	Methode	Beschrijving
/api/resilience	GET/PATCH	Aanvraagwachtrij, verbindingsafkoeling, provideronderbreker en wachtinstellingen ophalen/bijwerken
/api/resilience/reset	POST	Circuitonderbrekers van providers resetten
/api/resilience/model-cooldowns	GET	Actieve blokkeringen per (provider, verbinding, model) weergeven, gesorteerd op resterende tijd
/api/resilience/model-cooldowns	DELETE	Een modelblokkering wissen — body {provider, model} of {all: true} om alles te wissen
/api/rate-limits	GET	Status van frequentielimieten per account
/api/rate-limit	GET	Globale configuratie van frequentielimieten

Voor alle vier de routes onder /api/resilience/* is beheer-authenticatie (requireManagementAuth) vereist. Zie Veerkracht (uitgebreid) voor een volledig overzicht van provideronderbrekers, verbindingsafkoeling en modelblokkeringen.

Evaluaties

Endpoint	Methode	Beschrijving
/api/evals	GET/POST	Evaluatiesuites weergeven / evaluatie uitvoeren

Beleidsregels

Endpoint	Methode	Beschrijving
/api/policies	GET/POST/DELETE	Routeringsbeleid beheren

Naleving

Endpoint	Methode	Beschrijving
/api/compliance/audit-log	GET	Auditlogboek voor naleving (laatste N)

v1beta (Gemini-compatibel)

Endpoint	Methode	Beschrijving
/v1beta/models	GET	Modellen in Gemini-indeling weergeven
/v1beta/models/{...path}	POST	Gemini-generateContent-endpoint

Deze endpoints weerspiegelen de API-indeling van Gemini voor clients die native compatibiliteit met de Gemini SDK verwachten.

Interne / systeem-API's

Eindpunt	Methode	Beschrijving
/api/init	GET	Controle van applicatie-initialisatie (bij de eerste start)
/api/tags	GET	Ollama-compatibele modeltags (voor Ollama-clients)
/api/restart	POST	Activeert een gecontroleerde herstart van de server
/api/shutdown	POST	Activeert een gecontroleerde afsluiting van de server
/api/system/env/repair	POST	Herstelt omgevingsvariabelen van de OAuth-provider

Opmerking: Deze eindpunten worden intern door het systeem of voor compatibiliteit met Ollama-clients gebruikt. Ze worden doorgaans niet door eindgebruikers aangeroepen.

Herstel van de OAuth-omgeving (v3.6.1+)

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

{
  "provider": "claude-code"
}

Herstelt ontbrekende of beschadigde OAuth-omgevingsvariabelen voor een specifieke provider. Retourneert:

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

---

Audiotranscriptie

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

Transcribeer audiobestanden met een geconfigureerde STT-provider. Het eerste padsegment selecteert de native provider (openai/…, deepgram/…). Gateways die het model van een andere leverancier opnieuw aanbieden, gebruiken een gekwalificeerde id (openrouter/deepgram/nova-3).

Verzoek:

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

Antwoord:

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

Voorbeelden van model-id's: openai/whisper-1 (vereist een OpenAI-sleutel), openrouter/deepgram/nova-3 (vereist een OpenRouter-sleutel), deepgram/nova-3 (vereist een native Deepgram-sleutel). Een verzoek met alleen deepgram/nova-3 gebruikt geen OpenRouter.

Ondersteunde indelingen: mp3, wav, m4a, flac, ogg, webm.

---

Ollama-compatibiliteit

Voor clients die de API-indeling van Ollama gebruiken:

# Chat-eindpunt (Ollama-indeling)
POST /v1/api/chat

# Modellijst (Ollama-indeling)
GET /api/tags

Verzoeken worden automatisch vertaald tussen de Ollama- en interne indelingen.

Getokeniseerde VS Code-aliassen / aliassen zonder headers

Gebruik deze aliassen wanneer een integratie geen Authorization-header kan invoegen en de API-sleutel in de basis-URL moet worden opgenomen.

# Catalogus-alias in OpenAI-stijl
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Chat-aliassen in OpenAI-stijl
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Aliassen in Ollama-stijl
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Voorbeeld:

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

Opmerkingen:

• De getokeniseerde aliassen hergebruiken dezelfde handlers als /v1/* en /api/tags; de antwoordstructuren blijven identiek.
• Geef de voorkeur aan Authorization: Bearer ... wanneer de client aangepaste headers ondersteunt.
• Op URL's gebaseerde tokens kunnen voorkomen in logs van reverse proxy's, browsergeschiedenis en telemetrie buiten OmniRoute. Beschouw ze als een compatibiliteitsoptie, niet als de standaardverificatiemethode.

---

Telemetrie

# Telemetrieoverzicht van de latentie ophalen (p50/p95/p99 per provider)
GET /api/telemetry/summary

Antwoord:

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

---

Budget

# Budgetstatus voor alle API-sleutels ophalen
GET /api/usage/budget

# Een budget instellen of bijwerken
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"
}

Schemaopmerkingen (setBudgetSchema): apiKeyId is verplicht; ten minste één van dailyLimitUsd, weeklyLimitUsd of monthlyLimitUsd moet groter zijn dan nul. Optionele velden: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). De verouderde structuur {keyId, limit, period} retourneert 400 Bad Request.

Tokenlimieten

Tokenbudgetten per API-sleutel (los van het bovenstaande op USD gebaseerde budget). Deze worden direct in het aanvraagpad afgedwongen: wanneer het gebruik van een sleutel binnen het huidige venster de limiet bereikt, worden aanvragen geweigerd met 429 Too Many Requests. Limieten kunnen worden beperkt tot een specifiek model of een specifieke provider, of global op de hele sleutel worden toegepast; wanneer meerdere limieten op een aanvraag van toepassing zijn, geldt de meest beperkende limiet.

# De tokenlimieten van een sleutel weergeven (inclusief actueel gebruik binnen het venster)
GET /api/usage/token-limits?apiKeyId=key-123

# Een tokenlimiet maken of bijwerken
POST /api/usage/token-limits
Content-Type: application/json

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

# Een tokenlimiet verwijderen op basis van id
DELETE /api/usage/token-limits?id=tl-abc

Schema-opmerkingen (setTokenLimitSchema): apiKeyId en scopeType (model | provider | global) zijn vereist. scopeValue is vereist, tenzij scopeType gelijk is aan global (bijvoorbeeld een model-id voor het bereik model of een provider-id voor het bereik provider). tokenLimit moet een positief geheel getal zijn (geconverteerd vanuit een tekenreeks). Optioneel: id (weglaten om aan te maken, opgeven om bij te werken), resetInterval (daily | weekly | monthly, standaard monthly), resetTime (HH:MM), enabled (standaard true). GET-antwoorden vullen elke limiet aan met tokensUsed, remaining, windowStart, periodStartAt en nextResetAt. Dit is een beheereindpunt (authenticatie wordt centraal afgedwongen door de autorisatiepipeline).

Aanvraagverwerking

1. Client verzendt een aanvraag naar /v1/*
2. De routehandler roept handleChat, handleEmbedding, handleAudioTranscription of handleImageGeneration aan
3. Het model wordt bepaald (directe provider/model of alias/combinatie)
4. Referenties worden geselecteerd uit de lokale database, met filtering op accountbeschikbaarheid
5. Voor chat: handleChatCore controleert de semantische cache/handtekeningcache en bepaalt de compressie-instellingen van de combinatie
6. Proactieve compressie wordt vóór de providervertaling uitgevoerd wanneer deze is ingeschakeld (lite, Caveman, RTK of gestapeld)
7. De providerexecutor verzendt de upstreamaanvraag
8. Het antwoord wordt terugvertaald naar de clientindeling (chat) of ongewijzigd geretourneerd (embeddings/afbeeldingen/audio)
9. Gebruik, compressieanalyses en aanvraaglogboeken worden vastgelegd
10. Bij fouten wordt volgens de combinatieregels een fallback toegepast

Volledige architectuurreferentie: ARCHITECTURE.md

---

Combinatiebeheer

Routeringscombinaties op een hoger niveau (al samengevat onder /api/combos*) kunnen ook één-op-één aan een model-id-patroon worden gekoppeld, waardoor een OpenAI-achtige model-id transparant naar een combinatie kan worden omgeleid.

Methode	Pad	Beschrijving
GET	/api/model-combo-mappings	Alle model→combinatie-toewijzingen weergeven
POST	/api/model-combo-mappings	Toewijzing maken — body: {pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	Eén toewijzing ophalen
PUT	/api/model-combo-mappings/[id]	Velden van een bestaande toewijzing bijwerken
DELETE	/api/model-combo-mappings/[id]	Een toewijzing verwijderen

Authenticatie: beheersessie/API-sleutel (requireManagementAuth).

---

Webhooks

Uitgaande webhookabonnementen voor OmniRoute-gebeurtenissen (voltooiing van verzoeken, uitputting van quota, sleutelrotatie, enz.).

Methode	Pad	Beschrijving
GET	/api/webhooks	Webhooks weergeven (geheimen worden gemaskeerd als <prefix>...)
POST	/api/webhooks	Webhook maken — body: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	Een webhook ophalen
PUT	/api/webhooks/[id]	url/events/secret/description bijwerken
DELETE	/api/webhooks/[id]	Een webhook verwijderen
POST	/api/webhooks/[id]/test	Een testpayload naar de webhook-URL sturen en de afleveringsstatus retourneren

Authenticatie: beheersessie/API-sleutel (requireManagementAuth).

---

Geregistreerde sleutels (automatisch beheer)

Wordt door het subsysteem voor automatisch sleutelbeheer gebruikt om API-sleutels uit te geven en te roteren bij een achterliggende provider/account, met dagelijkse/uurlijkse quota.

Methode	Pad	Beschrijving
GET	/api/v1/registered-keys	Geregistreerde sleutels weergeven (alleen gemaskeerd voorvoegsel)
POST	/api/v1/registered-keys	Een nieuwe geregistreerde sleutel uitgeven — body: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Retourneert de onbewerkte sleutel eenmalig. Retourneert 429 bij weigering wegens quota.
GET	/api/v1/registered-keys/[id]	De metadata van een geregistreerde sleutel ophalen (geen onbewerkt sleutelmateriaal)
DELETE	/api/v1/registered-keys/[id]	Een geregistreerde sleutel intrekken
POST	/api/v1/registered-keys/[id]/revoke	Expliciet eindpunt voor intrekking (hetzelfde effect als DELETE)

Authenticatie: Bearer-API-sleutel (isAuthenticated). Zie ook /v1/quotas/check en /v1/issues/report.

---

Agents-protocol

Cloudagenttaken (Claude Code, Codex Cloud, OpenHands, enz.) die op afstand namens OmniRoute-gebruikers worden uitgevoerd.

Methode	Pad	Beschrijving
GET	/api/v1/agents/tasks	Taken weergeven — optioneel ?provider=, ?status=, ?limit= (1–500, standaard 50)
POST	/api/v1/agents/tasks	Taak aanmaken — body gevalideerd door CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Retourneert 201 met taakenvelop
DELETE	/api/v1/agents/tasks?id=...	Een taak verwijderen
GET	/api/v1/agents/tasks/[id]	Taak lezen — vernieuwt de status synchroon vanuit de upstream-cloudagent wanneer een external_id is ingesteld
POST	/api/v1/agents/tasks/[id]	Onderscheiden actie: {action: "approve"}, {action: "message", message} of {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	Een specifieke taak op id verwijderen

Authenticatie: beheerauthenticatie is vereist voor elke methode (requireCloudAgentManagementAuth). Vóór v3.8.0 waren deze niet geauthenticeerd — zie commit 588a0333 voor de incompatibele wijziging.

# Een Claude Code-cloudtaak aanmaken
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":"..."}}'

---

Beheerproxy's

Uitgaande HTTP(S)/SOCKS-proxy's die aan providers, accounts of globaal kunnen worden toegewezen.

Methode	Pad	Beschrijving
GET	/api/v1/management/proxies	Proxy's weergeven (met ?id= wordt er één geretourneerd; met ?id=&where_used=1 wordt de toewijzingsgrafiek geretourneerd)
POST	/api/v1/management/proxies	Proxy aanmaken — body gevalideerd door createProxyRegistrySchema
PATCH	/api/v1/management/proxies	Proxy bijwerken — body gevalideerd door updateProxyRegistrySchema (vereist id)
DELETE	/api/v1/management/proxies?id=...&force=1	Proxy verwijderen (gebruik force=1 om toewijzingen los te koppelen)
GET	/api/v1/management/proxies/assignments	Toewijzingen weergeven — filterbaar op proxy_id, scope, scope_id; geef resolve_connection_id=<id> door om de actieve proxy voor een verbinding te bepalen
PUT	/api/v1/management/proxies/assignments	Toewijzen — body gevalideerd door proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Wist de dispatchercache
PUT	/api/v1/management/proxies/bulk-assign	Bulksgewijs toewijzen — body gevalideerd door bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?})
GET	/api/v1/management/proxies/health?hours=24	Geaggregeerde proxystatus (aantallen geslaagd/mislukt, latentie) gedurende een tijdvenster

Authenticatie: beheersessie/API-sleutel op elke route (requireManagementAuth).

De POST /api/v1/management/proxies/[id]/assignments en POST /api/v1/management/proxies/[id]/health uit de taakbeschrijving worden afgehandeld door de hierboven weergegeven platte routes /assignments en /health — er zijn geen subroutes per id in de codebase.

---

Veerkracht (uitgebreid)

OmniRoute biedt drie onafhankelijke mechanismen voor tijdelijke storingen; via de onderstaande beheerendpoints kunnen operators deze uitlezen en overschrijven:

Bereik	Statusopslag	Uitlezen	Resetten / wissen
Provider-circuitbreaker	domain_circuit_breakers + in het geheugen	/api/monitoring/health	POST /api/resilience/reset
Verbindingscooldown	rateLimitedUntil op providerverbindingen	/api/rate-limits, /api/providers/[id]	(wordt geleidelijk opnieuw ingeschakeld; wissen via provider-PUT)
Modelblokkering	Modelbeschikbaarheidsregister in het geheugen	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

PATCH /api/resilience accepteert overschrijvingen voor provider-circuitbreakers onder providerBreaker.oauth en providerBreaker.apikey. Elk profiel ondersteunt degradationThreshold, failureThreshold en resetTimeoutMs; dezelfde velden zijn beschikbaar via Dashboard → Instellingen → Veerkracht.

# Wis de blokkering van één model
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"}'

# Wis alle blokkeringen
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

Volledige conceptuele referentie en standaardwaarden voor circuitbreakers: zie CLAUDE.md → "Resilience Runtime State".

---

Vaardigheden

Framework voor vaardigheden waarmee OmniRoute kan worden uitgebreid met aangepaste uitvoerbare handlers, plus marketplace-integraties.

Methode	Pad	Beschrijving
GET	/api/skills	Geïnstalleerde vaardigheden weergeven — filterbaar via ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, gepagineerd
GET	/api/skills/[id]	Eén vaardigheid ophalen
PUT	/api/skills/[id]	Vaardigheid bijwerken (naam, beschrijving, modus, schema, handler, tags)
DELETE	/api/skills/[id]	Een vaardigheid verwijderen
POST	/api/skills/install	Een vaardigheid installeren vanuit een onbewerkt manifest — body: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	Recente uitvoeringen van vaardigheden weergeven (audittrail met invoer/uitvoer/duur)
GET	/api/skills/marketplace?q=...	Zoeken/populaire lijst van de SkillsMP-marketplace (vereist de instelling skillsmpApiKey)
POST	/api/skills/marketplace/install	Een vaardigheid op basis van id installeren vanuit SkillsMP
GET	/api/skills/skillssh?q=&limit=	Het skills.sh-register doorzoeken
POST	/api/skills/skillssh/install	Een vaardigheid op basis van id installeren vanuit skills.sh

Authenticatie: beheersessie/API-sleutel. Zoekroutes voor marketplaces accepteren beheer authenticatie of een Bearer-API-sleutel (isAuthenticated).

---

Geheugen

Permanente opslag voor conversationeel/feitelijk geheugen, afgebakend per API-sleutel/sessie.

Methode	Pad	Beschrijving
GET	/api/memory	Geheugens weergeven — ?apiKeyId=, ?type=, ?sessionId=, ?q=, met paginering via offset/limit of page/limit
POST	/api/memory	Geheugen aanmaken — body gevalideerd door Zod: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	Eén geheugen ophalen
DELETE	/api/memory/[id]	Een geheugen verwijderen
GET	/api/memory/health	Status van het geheugensubsysteem (databaseconnectiviteit, embeddings-backend, status van vectorindex)

Authenticatie: beheersessie/API-sleutel (requireManagementAuth). type-enum: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (zie MemoryType in src/lib/memory/types.ts).

---

MCP-server

OmniRoute wordt geleverd met een ingebouwde Model Context Protocol-server met 3 transportmethoden (stdio, SSE, streamable-http) en tools met afgebakende rechten. De onderstaande dashboard-endpoints lezen status-/auditgegevens en fungeren als proxy voor de HTTP-transportmethoden.

Methode	Pad	Beschrijving
GET	/api/mcp/status	Heartbeat, transportmethode, onlinestatus, laatste aanroep, meestgebruikte tools, slagingspercentage over 24 uur
GET	/api/mcp/tools	Lijst met MCP-tools met name, description, scopes, phase, auditLevel, sourceEndpoints
GET	/api/mcp/sse	SSE-stream openen voor het SSE-transport (retourneert 503 als MCP is uitgeschakeld of de transportmethode niet overeenkomt)
POST	/api/mcp/sse	JSON-RPC-frame verzenden via het SSE-transport
GET	/api/mcp/stream	SSE-zijde van het Streamable HTTP-transport openen (door de server geïnitieerde berichten)
POST	/api/mcp/stream	JSON-RPC-frame verzenden via het Streamable HTTP-transport
DELETE	/api/mcp/stream	Een Streamable HTTP-sessie beëindigen
GET	/api/mcp/audit	Auditlog doorzoeken — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	Geaggregeerde auditstatistieken (totalen, slagingspercentage, gemiddelde duur, meestgebruikte tools)

Authenticatie: de sse-/stream-transportmethoden respecteren het MCP-specifieke authenticatieoppervlak (Bearer-API-sleutel met mcp-scope); de routes status/tools/audit* zijn leesbaar vanuit het dashboard (geen aanvullende authenticatie vereist naast toegang tot de dashboardhost).

Beide HTTP-transportmethoden worden beheerd door settings.mcpEnabled en settings.mcpTransport — een niet-overeenkomende transportmethode retourneert 400, een uitgeschakelde MCP-status retourneert 503.

---

A2A-server

OmniRoute biedt een A2A-eindpunt (Agent-to-Agent) voor JSON-RPC 2.0, plus een REST-wrapper voor inspectie- en dashboarddoeleinden.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # optioneel, tenzij OMNIROUTE_API_KEY is ingesteld
Content-Type: application/json

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

Ondersteunde methoden (allemaal afhankelijk van settings.a2aEnabled):

Methode	Beschrijving
message/send	Synchrone uitvoering van een skill; retourneert {task, artifacts, metadata}
message/stream	Streaming SSE-uitvoering van dezelfde verzameling skills
tasks/get	Haal een taak op via taskId
tasks/cancel	Annuleer een taak via taskId

Ingebouwde skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Agentkaart

GET /.well-known/agent.json

Retourneert de openbare A2A-agentkaart (naam, beschrijving, mogelijkheden, skillcatalogus en authenticatieschema) — wordt gedurende 1 uur openbaar gecachet. Geen authenticatie vereist.

REST-hulproutes

Methode	Pad	Beschrijving
GET	/api/a2a/status	A2A ingeschakeld + taakstatistieken + samenvatting van de gecachete agentkaart
GET	/api/a2a/tasks	Taken weergeven — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST	/api/a2a/tasks	(Niet geïmplementeerd als REST-hulproute — maak een taak aan via JSON-RPC message/send)
GET	/api/a2a/tasks/[id]	Eén taak ophalen
POST	/api/a2a/tasks/[id]/cancel	Een taak annuleren

Authenticatie: de REST-hulproutes werken zonder beheer-authenticatie (leesbaar via het dashboard); de JSON-RPC-route /a2a gebruikt Bearer OMNIROUTE_API_KEY indien geconfigureerd.

---

Cloud, evaluaties en beoordeling

Methode	Pad	Beschrijving
POST	/api/cloud/auth	Verifieer een Bearer-sleutel en retourneer gemaskeerde providerverbindingen + modelaliassen voor cloudsynchronisatieclients
POST	/api/cloud/credentials/update	Werk versleutelde inloggegevens bij voor een met de cloud gesynchroniseerde provider
POST	/api/cloud/model/resolve	Zet een logische model-id om naar een concrete provider/model-combinatie met behulp van de lokale routeringstabel
GET	/api/cloud/models/alias	Geef modelaliassen weer zoals deze aan cloudsynchronisatie worden aangeboden
GET	/api/assess	Lees de nieuwste beoordelingscategorisaties (per provider/model)
POST	/api/assess	Voer een beoordeling uit — body: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	Geef ingebouwde evaluatiesuites + de meest recente uitvoeringen weer
POST	/api/evals	Start een evaluatie-uitvoering
POST	/api/evals/suites	Maak een aangepaste evaluatiesuite aan — body gevalideerd door evalSuiteSaveSchema
GET	/api/evals/suites/[id]	Haal een aangepaste evaluatiesuite op

Authenticatie: /api/cloud/auth valideert rechtstreeks een Bearer-sleutel; de andere routes onder /api/cloud/*, /api/evals/* en /api/assess vereisen een beheersessie/API-sleutel. POST op /api/assess gebruikt validateBody met een scopeschema op basis van een gediscrimineerde unie.

---

ACP-beheer (Agent Client Protocol)

als onderliggende processen. Deze eindpunten beheren de detectie van ACP-agents en de registratie van aangepaste agents.

Methode	Pad	Beschrijving
GET	/api/acp/agents	Alle bekende CLI-agents (ingebouwd + aangepast) weergeven met installatiestatus, versie en binair bestand
POST	/api/acp/agents	Een aangepaste ACP-agent registreren of de cache vernieuwen — body: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} of {action: "refresh"}
DELETE	/api/acp/agents	Een aangepaste ACP-agent verwijderen — queryparameter: ?id=<agentId>

Voorbeeldrespons (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
}

Authenticatie: Vereist een beheersessie (auth_token-cookie van het dashboard) of een API-sleutel met beheerbereik.

Zie ACP-framework voor volledige details.

---

Analyse en observeerbaarheid

Realtime analyse-eindpunten voor het bewaken van routering, compressie en providerdiversiteit. Deze sturen de pagina's onder /dashboard/analytics/* aan.

Analyse van automatische routering

Methode	Pad	Beschrijving
GET	/api/analytics/auto-routing	Geaggregeerde statistieken voor automatische routering: totaal aantal aanroepen, strategie-, niveau- en providerverdeling
GET	/api/analytics/auto-routing?days=7	Statistieken binnen een tijdvenster (standaard 24 uur)

Voorbeeldrespons:

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

Compressieanalyse

Methode	Pad	Beschrijving
GET	/api/analytics/compression	Geaggregeerde compressiestatistieken: bespaarde tokens, besparingspercentage, modusverdeling en enginegebruik

Voorbeeldrespons:

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

Bijhouden van providerdiversiteit

Methode	Pad	Beschrijving
GET	/api/analytics/diversity	Diversiteitsmeting op basis van Shannon-entropie: voorkomt enkelvoudige storingspunten door de spreiding over providers te meten

Voorbeeldrespons:

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

Authenticatie: Vereist een beheersessie of een API-sleutel met beheerbereik.

---

Beheerbewerkingen

Endpoints die uitsluitend voor beheerders zijn bedoeld voor operationeel beheer.

Methode	Pad	Beschrijving
GET	/api/admin/concurrency	Huidige gelijktijdigheidslimieten uitlezen (globaal + per provider)
POST	/api/admin/concurrency	Gelijktijdigheidslimieten bijwerken — body: {global?: number, perProvider?: Record<string, number>}

Authenticatie: Vereist een beheersessie met beheerdersbereik.

---

Beheer van CLI-tools

Beheer CLI-tools die met OmniRoute integreren (antigravity, chipotle, commandCode, devin-cli, enz.). Zie Providerreferentie voor de volledige lijst.

Methode	Pad	Beschrijving
GET	/api/cli-tools/all-statuses	Status van alle CLI-tools (geïnstalleerd, versie, laatst gezien)
GET	/api/cli-tools/status	Statusdetails voor één CLI-tool (?tool=-query)
POST	/api/cli-tools/apply	Gegenereerde configuratie van een tool schrijven (dryRun toont een voorbeeld; 422 + containerEphemeralTarget indien gecontaineriseerd; migration vermeldt verouderde Codex-YAML)
GET	/api/cli-tools/backups	Back-ups van CLI-toolconfiguraties weergeven
POST	/api/cli-tools/backups	Een back-up van alle CLI-toolconfiguraties maken
POST	/api/cli-tools/backups	Herstellen: hetzelfde endpoint met {tool, backupId} in de body herstelt die back-up
GET	/api/cli-tools/antigravity-mitm	Status van de Antigravity-MITM-proxy (de CLI-tool "antigravity-mitm")
POST	/api/cli-tools/antigravity-mitm/alias	Aliassen voor antigravity-mitm configureren

Authenticatie: Vereist een beheersessie.

---

Agentvaardigheden

Beheer vaardigheden van AI-agents (vergelijkbaar met aangepaste GPT's van OpenAI, maar dan voor agents).

Methode	Pad	Beschrijving
GET	/api/agent-skills	Alle agentvaardigheden weergeven (ingebouwd + aangepast)
GET	/api/agent-skills/[id]	Een specifieke agentvaardigheid ophalen
POST	/api/agent-skills	Een aangepaste agentvaardigheid maken — body: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	Een aangepaste agentvaardigheid bijwerken
DELETE	/api/agent-skills/[id]	Een aangepaste agentvaardigheid verwijderen
GET	/api/agent-skills/[id]/raw	Onbewerkte prompt + metadata ophalen (zonder uitvoering)
POST	/api/agent-skills/generate	Met AI een nieuwe vaardigheid genereren op basis van een beschrijving in natuurlijke taal

Authenticatie: Vereist een beheersessie of een API-sleutel met beheerbereik.

---

Cachebeheer

Beheer de semantische cache en de redeneercache.

Methode	Pad	Beschrijving
GET	/api/cache	Cacheoverzicht: totaal aantal items, hitpercentage, grootte op schijf
GET	/api/cache/entries	Items in de cache weergeven (met paginering)
DELETE	/api/cache/entries	Items uit de cache verwijderen (filteren op queryparameters)
GET	/api/cache/stats	Gedetailleerde cachestatistieken (per provider, per model)
GET	/api/cache/reasoning	Status van de redeneercache (voor het opnieuw afspelen van redeneringen)
DELETE	/api/cache/reasoning	Redeneercache wissen — queryparameters: ?toolCallId=<id> (één item), ?provider=<p> of geen parameters (alles)

Authenticatie: Vereist een beheersessie.

---

Geheugensysteem

Beheer permanent geheugen (FTS5 + vectorembeddings).

Methode	Pad	Beschrijving
GET	/api/memory	Geheugenitems weergeven (filteren op scope, type, zoekopdracht)
POST	/api/memory	Een nieuw geheugenitem maken — body: {scope, type, content, metadata?}
GET	/api/memory/[id]	Een specifiek geheugenitem ophalen
PUT	/api/memory/[id]	Een geheugenitem bijwerken
DELETE	/api/memory/[id]	Een geheugenitem verwijderen
GET	/api/memory?q=	Geheugen doorzoeken (FTS5 + vector) — statistieken zijn in hetzelfde antwoord opgenomen

Authenticatie: Vereist een beheersessie of een API-sleutel met beheerbereik.

---

Webhooks

Beheer webhookabonnementen voor gebeurtenissen.

Methode	Pad	Beschrijving
GET	/api/webhooks	Alle webhookabonnementen weergeven
POST	/api/webhooks	Een webhookabonnement maken — body: {url, events[], secret?, active?}
GET	/api/webhooks/[id]	Een specifiek webhookabonnement ophalen
PUT	/api/webhooks/[id]	Een webhookabonnement bijwerken
DELETE	/api/webhooks/[id]	Een webhookabonnement verwijderen
GET	/api/webhooks/[id]/deliveries	De afleveringsgeschiedenis voor een webhook weergeven (logboek van successen/fouten)
POST	/api/webhooks/[id]/test	Een testgebeurtenis naar een webhook verzenden

Authenticatie: Vereist een beheersessie.

Zie Webhookframework voor alle gebeurtenistypen.

---

Skills-framework

Beheer Skills (het framework voor agentische uitbreidingen).

Methode	Pad	Beschrijving
GET	/api/skills	Alle geïnstalleerde skills weergeven (ingebouwd + aangepast)
POST	/api/skills/install	Een skill installeren vanaf een lokaal pad of URL
DELETE	/api/skills/[id]	Een skill verwijderen
PUT	/api/skills/[id]	Een skill in- of uitschakelen — body: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST	/api/skills/executions	Een skill uitvoeren — body: {skillName, apiKeyId, input?, sessionId?}
GET	/api/skills/executions	Uitvoeringsgeschiedenis voor alle skills weergeven (filteren op ?apiKeyId=)

Authenticatie: Vereist een beheersessie of een API-sleutel met beheerbereik.

Zie Skills-framework voor alle details.

---

Plug-ins

Beheer OmniRoute-plug-ins (extensies van derden).

Methode	Pad	Beschrijving
GET	/api/plugins	Geïnstalleerde plug-ins weergeven
POST	/api/plugins/marketplace/install	Een plug-in installeren vanuit de marktplaats
DELETE	/api/plugins/[name]	Een plug-in verwijderen
POST	/api/plugins/[name]/activate	Een plug-in activeren
POST	/api/plugins/[name]/deactivate	Een plug-in deactiveren
GET	/api/plugins/[name]/config	De plug-inconfiguratie ophalen
PUT	/api/plugins/[name]/config	De plug-inconfiguratie bijwerken

Authenticatie: Vereist een beheersessie.

Zie Plug-inframework voor alle details.

---

Schaduwroutering

Schaduw-/A-B-vergelijking van providers is geen zelfstandige REST-interface — deze wordt geconfigureerd via combinatieroutering (zie Auto-Combo). Vergelijkingsstatistieken per combinatie worden aangeboden via GET /api/combos/metrics.

---

Beveiligingsmaatregelen

Inspecteer de beveiligingsmaatregelen tijdens runtime (detectie van persoonsgegevens, detectie van promptinjectie, vision-bridging). Beveiligingsmaatregelen worden voor elke aanvraag uitgevoerd; afmelden per aanroep gebeurt via de aanvraagheader x-omniroute-disabled-guardrails — er is geen permanente interface voor in- of uitschakeling.

Methode	Pad	Beschrijving
GET	/api/guardrails	De geregistreerde beveiligingsmaatregelen en hun status weergeven (naam / ingeschakeld / prioriteit)
POST	/api/guardrails/test	De pijplijn vóór de aanroep als test uitvoeren op voorbeeldinvoer — body: {input, disabledGuardrails?}

Authenticatie: Vereist een beheersessie.

Zie Beveiliging > Beveiligingsmaatregelen voor alle details.

---

---

Authenticatie

Zie Beheerauthenticatie voor de vier referentiefamilies (dashboardsessie, lokaal CLI-token, oma_live_…-toegangstoken, API-sleutel met beheerbereik) en hoe deze verschillen van inferentiesleutels.

• Dashboardroutes (/dashboard/*) gebruiken de cookie auth_token
• Bij het inloggen wordt de opgeslagen wachtwoordhash gebruikt, met INITIAL_PASSWORD als fallback
• requireLogin kan worden in- en uitgeschakeld via /api/settings/require-login
• /v1/*-routes vereisen optioneel een Bearer API-sleutel wanneer REQUIRE_API_KEY=true
• Met "beheertoken" / "API-sleutel met beheerbereik" wordt in deze referentie een van de families uit die handleiding bedoeld — niet een ongedefinieerd aanvullend geheimtype

Incompatibele wijziging (v3.8.0) — /api/v1/agents/tasks/* en de eindpunten voor cooldownbeheer vereisen nu beheerauthenticatie (de dashboardcookie auth_token of een API-sleutel met beheerbereik). Clients die deze routes voorheen zonder authenticatie aanriepen, ontvangen nu 401 Unauthorized. Zie commit 588a0333 (fix(auth): require management auth for agent and cooldown APIs).