# API Reference (Nederlands) 🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇧🇦 [bs](../../../bs/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md) --- 🌐 **Talen:** 🇺🇸 [English](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇧🇦 [Bosanski](../i18n/bs/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md) Kernreferentie voor de OmniRoute-API. Deze behandelt het openbare `/v1`-oppervlak en de meest gebruikte beheer-eindpunten; het machineleesbare bestand [`docs/openapi.yaml`](../openapi.yaml) en de routestructuur onder `src/app/api/` zijn de volledige bronnen. Raadpleeg voor het specifieke OpenAI-compatibele protocol en de matrix met providermogelijkheden [`OPENAI_COMPATIBILITY.md`](./OPENAI_COMPATIBILITY.md). --- ## Inhoudsopgave - [Chatvoltooiingen](#chat-completions) - [Exclusieve leases voor beheerde sessies](#exclusive-managed-session-leases) - [Embeddings](#embeddings) - [Afbeeldingen genereren](#image-generation) - [OCR voor documenten](#document-ocr) - [Modellen weergeven](#list-models) - [Manifest voor providerplug-ins](#provider-plugin-manifest) - [Compatibiliteitseindpunten](#compatibility-endpoints) - [Bestanden-API](#files-api) - [Batches-API](#batches-api) - [Zoek-API](#search-api) - [WebSocket-streaming](#websocket-streaming) - [Quota- en probleemrapportage](#quotas--issues-reporting) - [Semantische cache](#semantic-cache) - [Dashboard en beheer](#dashboard--management) - [Combobeheer](#combo-management) - [Webhooks](#webhooks) - [Geregistreerde sleutels (automatisch beheer)](#registered-keys-auto-management) - [Agentprotocol](#agents-protocol) - [Beheerproxy's](#management-proxies) - [Robuustheid (uitgebreid)](#resilience-extended) - [Vaardigheden](#skills) - [Geheugen](#memory) - [MCP-server](#mcp-server) - [A2A-server](#a2a-server) - [Cloud, evaluaties en beoordeling](#cloud-evals--assess) - [Verwerking van verzoeken](#request-processing) - [Authenticatie](#authentication) --- ## Chatvoltooiingen ```bash 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=; provider=; latency_ms=` (`` 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 beheerde sessieleasing is een opt-in, client-neutraal routeringscontract: één actieve eigenaar bezit één in aanmerking komende OmniRoute-verbinding. Het leaset geen model, vereist geen OAuth, identificeert geen specifieke client en vereist geen specifieke provider. De authenticerende API-sleutel moet de scope `lease:exclusive` en een expliciete niet-lege `allowedConnections`-lijst hebben. De database-mutatiegrens handhaaft beide velden samen bij het aanmaken van sleutels en gedeeltelijke updates. ```http POST /api/v1/session-leases Authorization: Bearer Content-Type: application/json X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> {"action":"acquire","model":"glm/glm-4.6"} ``` Succesvolle acquire-, renew- en release-antwoorden tonen tijdstempels, `state` en de exacte positieve `generation`, maar nooit de geselecteerde verbinding of inloggegevens. Renew en release leveren de generation in de JSON-body: ```json { "action": "renew", "generation": 1 } ``` ```json { "action": "release", "generation": 1, "reason": "OWNER_EXIT" } ``` Een actieve lease-eigenaar kan expliciet privacyveilige weergavemetadata opvragen voor zijn huidige binding: ```json { "action": "status", "generation": 1 } ``` ```json { "state": "ACTIVE", "generation": 1, "acquiredAt": "2026-08-28T12:00:00.000Z", "renewedAt": "2026-08-28T12:00:30.000Z", "expiresAt": "2026-08-28T12:02:30.000Z", "connection": { "displayName": "Primary Codex", "provider": "codex" } } ``` Deze opt-in statusactie wordt afgeschermd door de ondoorzichtige eigenaar, geauthenticeerde beheerde API-sleutel en exacte actieve generatie in één databasetransactie. `displayName` is alleen de ingekorte geconfigureerde verbindingsnaam; het is `null` wanneer er geen veilige geconfigureerde naam bestaat. OmniRoute vervangt nooit een e-mailadres of gegenereerde accountidentiteit. De providerwaarde is een niet-gevoelig weergavelabel en nooit een gegenereerde compatibele-provider-identificatie. Inloggegevens, tokens, cookies, ruwe verbinding- of API-sleutel-ID's, eigenaar-hashes, afschermingsgeheimen en interne routeringsgegevens zijn uitgesloten. Zoekopdrachten met een verkeerde sleutel, verkeerde eigenaar, verouderde generatie, ontbrekende, verlopen, vrijgegeven en ongeldige opzoekingen retourneren allemaal dezelfde `409 LEASE_FENCE_STALE` fout zonder verbindingsmetadata. Een client die de capaciteitswachtreactie heeft ontvangen, heeft geen actieve binding om te inspecteren. Wanneer routering een actieve lease overdraagt, blijft dezelfde generatie geldig en retourneert de status atomisch de nieuwe binding, nooit de oude. Bestaande clients blijven ongewijzigd omdat acquire-, renew-, release- en wachtende reacties hun eerdere vormen behouden. Dit servercontract wijzigt de standaard OpenAI Codex `/status` niet. Standaard Codex rapporteert momenteel zijn modelprovider en ingebouwde authenticatie-/accountstatus, maar rendert geen willekeurige aangepaste provideraccountmetadata; een latere clientintegratie moet deze actie aanroepen en beslissen hoe `connection.displayName` moet worden weergegeven. Elke beheerde inferentieaanvraag levert dan beide controleheaders: ```http 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 afgeschermd vóór elke ondersteunde upstream-poging. Het opnieuw afspelen van eigenaar en generatie met een andere sleutel mislukt, zelfs wanneer die sleutel dezelfde verbinding toestaat. Ruwe eigenaren worden niet opgeslagen, gelogd, bewaard in de aanvraagsnapshot of doorgestuurd naar upstream. Tijdelijke concurrentie retourneert HTTP `429` met `Retry-After` en: ```json { "state": "WAITING_FOR_CAPACITY", "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" }, "reason": "NO_FREE_ELIGIBLE_CONNECTION", "retryAfter": 30 } ``` Deze reactie betekent alleen dat de gewone in aanmerking komende set niet leeg was en dat elke vrije kandidaat in bezit was van een externe actieve lease. Niet-ondersteunde modellen/providers, beleidsconflicten, cooldown, quota, gezondheid en andere gewone geschiktheidsfouten behouden hun bestaande OmniRoute-reacties. ### `x-omniroute-compression` Per-aanvraag overschrijving van het compressieplan. Hoogste prioriteit — overtreft de routing-combo overschrijving, het actieve profiel, auto-trigger en het paneel Standaard. Waarden: | Value | Effect | | ------------- | ---------------------------------------------------------------------------------------------------------- | | `off` | Geen compressie voor deze aanvraag. | | `default` | Het paneel-afgeleide Standaard profiel (negeert het actieve profiel). Lossy engines blijven uitgeschakeld. | | `safe` | Alleen deduplicatie en witruimte-vouwing. | | `allow-lossy` | Behoud het operatorplan voor deze aanvraag, inclusief samenvattingen en stijlherschrijvingen. | | `engine:` | Eén enkele engine indien ingeschakeld, bijv. `engine:rtk`. Per-aanvraag opt-in voor die engine. | | `` | Een benoemde combo, eerst gematcht op naam (hoofdletterongevoelig), daarna op id. | Notities: - Onbekende waarden worden genegeerd (de aanvraag wordt nooit afgewezen); de resolutie valt terug op de normale operatorprioriteit. - Als meerdere combo's een naam delen, geef dan de combo **id** door voor een deterministische match. - Een combo waarvan de naam `off` of `default` is, kan niet op naam worden geselecteerd (deze trefwoorden worden eerst geïnterpreteerd); verwijs naar zo'n combo via zijn id. - De hoofdcompressieschakelaar is een harde poort: wanneer compressie wereldwijd is uitgeschakeld, kan deze header deze niet inschakelen. Het toegepaste plan wordt teruggestuurd in de response header: ``` X-OmniRoute-Compression: ; source= ``` waarbij `` één van `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, of `off` is. --- ## Embeddings ```bash 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`-referenties uit het dashboard; `JINA_AI_API_KEY` wordt alleen als fallback gebruikt wanneer er geen dashboardsleutel bestaat. De kaart `jina-reader` is uitsluitend bedoeld voor Reader / `r.jina.ai` (`POST /v1/web/fetch`) en levert nooit embeddings of reranking. Registermodellen die multimodale ondersteuning vermelden, accepteren ook maximaal 32 providerneutrale 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 familiealias `jina-ai/jina-embeddings-v5-omni` → omni-small) accepteert ook Jina's eigen EmbeddingsV5Request-documenten en **stuurt deze intact door** naar `https://api.jina.ai/v1/embeddings`: ```json { "model": "jina-ai/jina-embeddings-v5-omni-small", "task": "retrieval.query", "normalized": true, "input": [ { "text": "a red bicycle" }, { "image": "https://example.com/bike.png" }, { "content": [{ "text": "caption" }, { "image": "data:image/png;base64,..." }] } ] } ``` Eigen `{ image | audio | video | pdf }`-waarden kunnen een openbare HTTPS-URL, een `data:`-URI of onbewerkte base64 zijn. OmniRoute zet deze objecten niet om naar tekenreeksen en haalt eigen 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, blijven documenten met andere inhoud dan tekst weigeren. Beveiligings- en transportlimieten: - Externe media-URL's moeten openbaar en via HTTPS toegankelijk zijn. Canonieke `{type,source:url}`-items worden aan de serverzijde opgehaald (opnieuw valideren van omleidingen, time-out, groottelimieten, openbare DNS, vastzetten van verbindingen) en inline opgenomen vóór de provideraanroep. Jina-eigen `{image:"https://..."}`-items worden ongewijzigd doorgestuurd na dezelfde controle op openbare HTTPS-toegang; Jina haalt de URL op. - Inline base64-media zijn beperkt tot 8 MiB gedecodeerd per item en 16 MiB gedecodeerd voor de gehele aanvraag. 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 voor inline media worden gebruikt; één vector per item op het hoogste niveau. - Gemini Embedding 2-familie: één array op het hoogste niveau wordt één eigen `models/{model}:embedContent`-aanvraag met `content.parts` (`text` of `inline_data`). - llama.cpp (`llama-cpp/`, elk model dat door de lokale server is geladen): canonieke `text`-items worden gewone tekenreeksen, en `image` / `audio` / `video` worden elk één `{"content": [part]}`-object, waarbij llama-server's chatinhoudsonderdelen (`image_url`, `input_audio` met indeling `wav` / `mp3` / `flac`, `input_video`) met inline gegevens worden gebruikt; één vector per item op het hoogste niveau. De server moet worden uitgevoerd met `--embedding --mmproj …`; zonder projector weigert de server zelf media. `document` wordt niet ondersteund. - Onbekende/dynamische modellen zonder expliciete modaliteitsmetadata weigeren gestructureerde invoer met HTTP 400. ```json { "model": "jina-ai/jina-embeddings-v5-omni-small", "input": [ { "type": "text", "text": "A red bicycle" }, { "type": "image", "source": { "type": "url", "url": "https://example.com/bicycle.png" } } ], "dimensions": 512, "encoding_format": "float" } ``` Niet-ondersteunde combinaties van model en modaliteit retourneren HTTP 400 in plaats van het item te converteren. Uitbreidingsvelden die geen invoervelden zijn in verouderde aanvragen met tekenreeksen/tokens, worden nog steeds ongewijzigd doorgegeven. ```bash # Alle embeddingmodellen weergeven GET /v1/embeddings ``` --- ## Afbeeldingen genereren ```bash 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 zijn onder andere OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, **ZenMux**, SD WebUI (lokaal), ComfyUI (lokaal). `n` retourneert `n` afbeeldingen in `data[]`. Voor providers waarvan de upstream-API één afbeelding per aanroep retourneert (Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik, NVIDIA NIM, Cloudflare Workers AI), worden `n` afzonderlijke upstream-aanroepen uitgevoerd, met maximaal 4 gelijktijdige aanroepen. Een vaste `seed` wordt verhoogd met de aanroepindex (`seed`, `seed + 1`, …), zodat de afbeeldingen verschillen maar reproduceerbaar blijven. `n` is beperkt tot 10. De aanvraag mislukt in zijn geheel als een van de aanroepen mislukt. De lijst met fan-outindelingen staat in `SINGLE_IMAGE_FANOUT_FORMATS` in `open-sse/handlers/imageGeneration/fanOut.ts`. ZenMux hergebruikt de bestaande API-sleutelverbinding en accepteert de voorvoegsels `zenmux/` of `zm/`: - `zenmux/openai/gpt-image-2` gebruikt de OpenAI Images API van ZenMux. Opties zijn onder andere `size`, `quality`, `n`, `output_format`, `output_compression`, `background` en `response_format`. - Andere uitgevers, zoals `zm/meta/muse-image-1.0`, gebruiken ZenMux' Vertex AI-`:predict`- endpoint. `n` wordt gekoppeld aan `sampleCount`, `aspect_ratio` aan `aspectRatio` en `image_size` (`1K`, `2K`, `4K`) aan `sampleImageSize`. Een `size` in pixels bepaalt alleen een beeldverhouding, niet gegarandeerde pixelafmetingen. Ondersteunde verhoudingen, resoluties en aantallen verschillen per model. - `zm/inclusionai/ming-image-0.1-design` kiest zijn eigen afmetingen. Laat `size`, `aspect_ratio` en `image_size` weg; expliciete waarden retourneren HTTP 400. PNG, JPEG en WebP kunnen worden aangevraagd met `output_format`. Deze integratie ondersteunt het genereren van tekst naar afbeelding, niet het bewerken van referentieafbeeldingen. Vertex- uitvoer wordt genormaliseerd naar `data[].b64_json`; `response_format: "url"` retourneert een upstream- HTTPS-URL of een base64-data-URL wanneer alleen afbeeldingsbytes beschikbaar zijn. Lege/gefilterde uitvoer retourneert een fout in plaats van een leeg succesvol resultaat. Toegang tot modellen is afhankelijk van het ZenMux-account. Zie [de Vertex API van ZenMux](https://docs.zenmux.ai/api/vertexai/generate-images) en [OpenAI Images API](https://docs.zenmux.ai/api/openai/generate-an-image). ```bash # Alle afbeeldingsmodellen weergeven GET /v1/images/generations ``` --- ## OCR voor documenten ```bash POST /v1/ocr Authorization: Bearer your-api-key Content-Type: application/json { "model": "mistral/mistral-ocr-latest", "document": { "type": "document_url", "document_url": "https://example.com/invoice.pdf" } } ``` `model` 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: ```json { "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 ```bash 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**. Welke prefix u 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: ```bash GET /v1/models?prefix=alias # één id per model — de korte aliasprefix GET /v1/models?prefix=dual # beide vormen (standaardinstelling van de server) GET /v1/models?prefix=canonical # alleen de volledige provider-id-prefix ``` | Modus | Genereert | Opmerkingen | | ----------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dual` | `cc/claude-sonnet-4-6` **en** `claude/claude-sonnet-4-6` | **Standaard.** Beide id's worden naar hetzelfde model gerouteerd; dit is behouden zodat clientconfiguraties waarin een van beide vormen hardgecodeerd is, blijven werken. Verdubbelt de catalogus ongeveer. | | `alias` | `cc/claude-sonnet-4-6` | Eén item per model. Providers zonder een afzonderlijke alias genereren nog steeds hun item, zodat er niets verloren gaat. | | `canonical` | `claude/claude-sonnet-4-6` | Eén item per model onder de volledige provider-id-prefix. Providers zonder een afzonderlijke alias (bijv. `antigravity/…`, `agy/…`) genereren hier ook hun enige id, zodat er niets verloren gaat. | Een mirror in de modus `dual` kan ook zonder de queryparameter worden herkend: deze bevat een `parent`-veld dat naar het primaire id verwijst. Clients die een modelkiezer weergeven, moeten `?prefix=alias` opvragen — dit is wat de [OmniCopilot VS Code-extensie](../guides/VSCODE-COPILOT.md) doet. ### Afzonderlijk verborgen chatmodellen Een model dat op de providerpagina als **Verborgen** is gemarkeerd, wordt uitgesloten van de catalogus en afgewezen met HTTP `404` / `model_not_found` wanneer het expliciet wordt opgevraagd. De controle gebruikt de vastgestelde provider en het vastgestelde model, met inbegrip van provideraliases, nodeprefixen van compatibele providers en standaardwaarden voor verbindingen. Een combinatie slaat verborgen doelen over en kan een zichtbaar zustermodel gebruiken; wanneer er geen uitvoerbaar doel overblijft, wordt dezelfde foutcode geretourneerd. Het zichtbaar maken wordt bij het volgende verzoek van kracht. Zichtbaarheidsoverschrijvingen die alleen voor afbeeldingen gelden, verbergen het chatmodel met hetzelfde id niet. Deze afzonderlijke modelinstelling staat los van de [allow-/deny-lijsten voor modelbeschikbaarheid](../routing/MODEL_EXPOSURE_LIST.md), die de weergave in de catalogus en kandidaten voor automatische routering filteren, terwijl expliciete routering behouden blijft. Modelmachtigingen voor API-sleutels blijven onafhankelijk van toepassing. De standaardmodus voor catalogusprefixen blijft `dual`. ### Modelvarianten zonder denken Voor Claude-modellen die denken ondersteunen, biedt `/v1/models` ook een **variant zonder denken** aan waarvan het id het voorvoegsel `claude-3-omniroute-no-thinking/` heeft: ``` claude-3-omniroute-no-thinking// ``` Als dit id wordt geselecteerd (bijv. in een Claude Code-configuratie die altijd een `thinking`-blok toevoegt), wordt het terugvertaald naar het echte `/`, 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 denken ondersteunen **en** `disabled` respecteren (dus bijv. 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 ```bash 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. --- ## Compatibiliteitseindpunten | Methode | Pad | Formaat | | ------- | ----------------------------------------- | ----------------------------------- | | 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/inpainting) | | 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` | Herordening 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 met Zod gevalideerde JSON-body (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, enz.; zie `src/shared/validation/schemas.ts`). Bij een schemafout wordt 4xx geretourneerd. Voor clients die geen `Authorization: Bearer ...` kunnen toevoegen, accepteert OmniRoute ook API-sleutels in de URL, via compatibiliteit met querystrings (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) of via de hieronder beschreven speciale `/api/v1/vscode/{token}/...`-eindpunten. ```bash # Herordenen (provider uit het cloudregister, of een OpenAI-compatibele providernode als "/") POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] } # Jina-classificatie (Foundation API-referenties) 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; provideraliasnamen: 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 body in de aangevraagde indeling) POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" } # Soniox TTS vereist een taal en een stem: `language` is standaard "en"; een ontbrekende # stem of de naam van een standaardstem van OpenAI (alloy, nova, …) wordt "Adrian" POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" } # 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": "kie/suno-v4.0", "prompt": "..." } ``` > **Providernodes voor herordening:** `POST /v1/rerank` routeert ook naar OpenAI-compatibele providernodes > (oMLX, vLLM, Infinity, TEI achter een gateway, …) die worden geadresseerd als `/`. Loopback- > nodes (`localhost`, `127.0.0.1`, `172.16.0.0/12`) komen altijd in aanmerking, net als hostnamen die de > beheerder opneemt in `OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS` (bijvoorbeeld een Docker/Compose-servicenaam zoals > `http://reranker:8080/v1`; deze worden rechtstreeks aangeroepen, nooit via `HTTP(S)_PROXY` of de > vastgezette proxy van een verbinding). Nodes op elke andere > host — een machine op het LAN of een Tailscale-peer — komen alleen in aanmerking wanneer de beheerder de > featureflag `RERANK_REMOTE_PROVIDER_NODES` inschakelt **en** de basis-URL van de node voldoet aan het beleid > voor uitgaande provider-URL's (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`). > De herordeningsstap van de geheugenengine roept deze route aan via > loopback, zodat dezelfde regel geldt voor `rerankProviderModel` in de geheugeninstellingen. > > **Structuren van lokale servers:** de node wordt aangeroepen via `/v1/rerank` en, bij een 404, via `/rerank` > (Infinity, TEI). De upstream-body bevat zowel de schrijfwijze van Cohere/OpenAI (`documents`, > `return_documents`) als die van TEI (`texts`, `return_text`), en de upstream-respons wordt > genormaliseerd naar de Cohere-envelope: de kale `[{index, score, text}]` van TEI, `{results: [{index, score}]}` > van eenvoudige gateways en `{data: [...]}` in Voyage-stijl worden allemaal aan de client geretourneerd als > `{results: [{index, relevance_score, document?}]}`, gesorteerd op score en begrensd op `top_n`. > **Detectie van provider-nodes:** modellen op een OpenAI-compatibele provider-node verschijnen in `GET /v1/models` > onder het nodeprefix. Rijen zonder endpointmetadata (gebruikelijk voor lokale `/v1/models`-lijsten) > nemen het `apiType` van de node over, zodat de modellen van een `embeddings`-node `type: "embedding"` hebben en die van een > `rerank`-node `type: "rerank"` in plaats van standaard chat te gebruiken; een expliciete > `supportedEndpoints` in een gesynchroniseerde of handmatig toegevoegde rij heeft nog steeds voorrang. ### Specifieke providerroutes ```bash 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 ```bash 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) ```bash # Dezelfde host:poort als de HTTP-API (standaard 20128); upgrade de verbinding: wscat -c "ws://localhost:20128/v1/responses?api_key=" # (of: -H "Authorization: Bearer ") # 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//codex/"`. 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): ```toml 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) ``` ```bash 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`). --- ## Selfservicegebruik (`/api/usage/om-usage`) Elke API-sleutel kan **zijn eigen** gebruik en quota lezen — zonder beheerdersauthenticatie. Dit is het endpoint dat een client (CLI, het OmniCopilot-paneel) gebruikt om de houder van een sleutel diens uitgaven te tonen. ```bash # Tekstvorm (het historische contract — platte tekst voor een terminal) curl -H "Authorization: Bearer " \ http://localhost:20128/api/usage/om-usage # Gestructureerde vorm — wat een UI gebruikt curl -H "Authorization: Bearer " \ "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 leest. Bij succes: ```jsonc { "allowed": true, // alleen aanwezig wanneer voor de sleutel gebruikslimieten per sleutel zijn ingeschakeld (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 nog niets in de cache staat: "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */}, }, // de momentopname van elke verbinding, zodat een UI 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 bekend) is een andere toestand 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`. ### Ruwe versus voor afkapwaarden gecorrigeerde quotapercentages Bij het gebruiken van `/api/usage/om-usage` moeten aanroepers rekening houden met het verschil tussen de percentages in de **platte-tekstuitvoer** en die in de gestructureerde **JSON-uitvoer**: | Aspect | Platte-tekstindeling (`/api/usage/om-usage` / `@@om-usage`) | JSON-indeling (`?format=json`) | | :--------------------- | :------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | | **Uitvoerveld** | `NN% left` (bijv. `20% left`) | `provider.quotas` / `providers[].quotas` | | **Meting** | **Voor afkapwaarde gecorrigeerde bruikbare ruimte**: resterende capaciteit boven de afkapdrempel | **Ruw upstreamquotum**: niet-gecorrigeerde meting van de provider | | **Afkapschaling** | Geschaald via `effectiveRemainingPercent()`, zodat de beschermde reserve als `0% left` wordt weergegeven | Geen (ruwe momentopnamewaarden zoals gerapporteerd door de provider) | | **Drempelgegevens** | Verwerkt in het weergegeven percentage | Opgeslagen in `quotaWindowThresholds` per verbinding (of serverstandaarden) | | **Primaire gebruiker** | Interactieve CLI's, terminalprompts, menselijke operators | Programmatische integraties, dashboards, analyses, factureringstrackers | #### De formule voor correctie op basis van de afkapwaarde OmniRoute ondersteunt proactieve quota-afkapwaarden om uitputting bij de upstreamprovider te voorkomen (geconfigureerd via `quotaWindowThresholds` van de verbinding, providerstandaarden of globale weerbaarheidsinstellingen). Wanneer een afkapdrempel (bijv. `cutoff = 25%`) actief is voor een quotavenster, berekent de tekstweergave de resterende ruimte als volgt: - Als `remaining <= cutoff`: retourneert `0%`. - Als `remaining > cutoff`: retourneert `((remaining - cutoff) / (100 - cutoff)) * 100`. De opgemaakte tekstuitvoer rondt dit af op het dichtstbijzijnde gehele getal (`Math.round(...)`). #### Illustratief voorbeeld Neem een providervenster met **60% ruw gebruik** (en dus **40% ruw resterend quotum**) en een geconfigureerde **afkapdrempel van 25% resterend quotum**: | Weergave | Berekening | Resterend | Impliciet gebruikt | | :----------------------------- | :------------------------------------------------- | :-------: | :--------------------------------------------: | | **Ruwe JSON (`?format=json`)** | Upstreammomentopname (`quotas[window]`) | **40%** | **60%** | | **Tekstindeling (`NN% left`)** | `((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100` | **20%** | **80%** (bij berekening van `100 - remaining`) | - **Waarom de tekst 20% resterend toont:** Van het fysieke quotum van 40% dat nog op het account beschikbaar is, wordt 25% door het afkapbeleid gereserveerd. De aanroeper heeft nog slechts 15% van de 75% bruikbare marge over voordat de router stopt met het routeren naar deze verbinding. De schaling zorgt ervoor dat de verbinding uitputting aangeeft (`0% left`) precies wanneer het routeren wordt beëindigd. - **Waarom JSON de ruwe waarden behoudt:** De JSON-payload retourneert de exacte providermomentopname (`UsageSnapshot`), zodat externe tools toegang hebben tot de werkelijke upstreambenutting en `quotaWindowThresholds` op verbindingsniveau, zonder verliesgevende schaling aan de serverzijde. #### Richtlijnen voor de migratie van gebruikers Als een externe integratie (zoals een editorplug-in of agentextensie) eerder het tekstendpoint (`NN% left`) uitleesde en het gebruikte percentage berekende als `100 - NN`, betekent migratie naar `?format=json` het volgende: - Het lezen van ruwe JSON-waarden weerspiegelt het **werkelijke upstreamverbruik** (60% gebruikt in het bovenstaande voorbeeld). - Als de integratie de semantiek voor bruikbare ruimte van het tekstendpoint wil behouden, kan deze de formule voor effectief resterende ruimte aan de clientzijde berekenen met `quotaWindowThresholds` voor overschrijvingen op verbindingsniveau. --- ## Semantische cache ```bash # Cachestatistieken ophalen GET /api/cache/stats # Alle caches wissen DELETE /api/cache/stats ``` Voorbeeld van een respons: ```json { "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]`): ```json { "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. Zie voor typen referenties, bereiken en curl-voorbeelden: [Beheerauthenticatie](../guides/MANAGEMENT-AUTH.md). ### 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/PUT/PATCH/DELETE | Aangepaste modellen en overschrijvingen per model (toevoegen, bijwerken, verbergen/weergeven, verwijderen) | | `/api/provider-models/validate-and-add` | POST | Met beheerauthenticatie, optionele strikte verbindingsvalidatie en atomische registratie van aangepaste modellen; zie [Modelvalidatie](../guides/MODEL-VALIDATION.md) | Voor gesynchroniseerde/geïmporteerde modellen accepteert `PUT /api/provider-models` de velden `provider`, `modelId` en `maxOutputTokenOverride`: een positief geheel getal stelt de handmatige limiet voor uitvoertokens in en `null` wist deze om de standaardwaarde te herstellen. `GET /api/provider-models?provider=` retourneert deze waarden in `modelOutputOverrides`, inclusief modellen zonder rij voor een aangepast model. De overschrijving gebruikt tijdens runtime de mogelijkheid `max_output_tokens` en blijft behouden wanneer een model opnieuw wordt gesynchroniseerd. De pagina voor OpenAI-compatibele providers biedt dezelfde bedieningselementen voor bewerken/wissen en markeert modellen met expliciete ondersteuning voor visuele invoer. Aangepaste Chat Completions-nodes passen expliciete afmeldingen voor redeneren aan voor de upstreambackend. Een geslaagde verbindingstest selecteert automatisch chattemplates voor elke exacte model-ID waarvan de vermelding in `/models` een herkende waarde voor `owned_by` aantoont: `vllm`, `sglang` of `llamacpp`. Transparante OpenAI-compatibele wrappers kunnen de oorspronkelijke modelvermelding bewaren in een genest `openai`-object; de detectie volgt maximaal drie van zulke enveloppen. Modellen met ontbrekend, onbekend of tegenstrijdig eigenaarschap behouden normaal OpenAI-gedrag. De detectie hergebruikt de bestaande catalogusaanvraag, genereert geen voltooiingstokens en wordt ongeldig gemaakt wanneer het verbindingseindpunt verandert. Gebruik de bestaande API voor gedeeltelijke providerupdates om dit gedrag vast te leggen voor een backend die deze metadata niet beschikbaar stelt: ```json { "providerSpecificData": { "reasoningControl": "chat-template" } } ``` Verzend die body met `PUT /api/providers/`. Voor die verbinding wordt een expliciete redeneerinspanning van `none` verzonden als `chat_template_kwargs.thinking=false` en `chat_template_kwargs.enable_thinking=false`. Expliciete native templatewaarden blijven leidend, tenzij een redeneerregel aan de serverzijde een inspanning afdwingt. De instelling is alleen van toepassing wanneer een aangepaste OpenAI-compatibele verbinding een Chat Completions-body verzendt; Responses-aanvragen en gewone providers behouden hun native aanvraagstructuur. Stel `reasoningControl` in op `openai` om de gewone OpenAI-doorgifte van `reasoning_effort` af te dwingen, of laat deze waarde weg/stel deze in op `null` om automatische detectie te gebruiken. Claude Code-auto-modeclassificatieverzoeken stellen standaard native thinking in op uitgeschakeld wanneer ze geen expliciete besturingselementen voor redenering bevatten. De detectie gebruikt de systeemmarkering van de classifier in verzoeken met Claude-indeling, niet modelnamen of voltooiingslimieten. Expliciete besturingselementen in de body, ondersteunde effort/thinking- headers, routeringsregels en vastgestelde modelinspanning behouden hun bestaande prioriteit. Beide classifier- fasen behouden hun prompts, voltooiingslimieten, stopsequenties en daadwerkelijke upstream- toestemmingsbeslissingen; de tweede fase kan de gevraagde zichtbare redenering nog steeds als gewone tekst produceren. ### OAuth-stromen | Endpoint | Methode | Beschrijving | | -------------------------------- | ------- | ------------------------- | | `/api/oauth/[provider]/[action]` | Diverse | Aanbiederspecifieke OAuth | ### Routering en configuratie | Endpoint | Methode | Beschrijving | | --------------------- | -------- | ---------------------------------- | | `/api/models/alias` | GET/POST | Modelaliassen | | `/api/models/catalog` | GET | Alle modellen per aanbieder + type | | `/api/combos*` | Diverse | Combobeheer | | `/api/keys*` | Diverse | Beheer van API-sleutels | | `/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 | Budgetten voor tokenlimieten per API-sleutel | | `/api/usage/model-latency-stats` | GET | Voortschrijdend latentieaggregaat per aanbieder/model (gem./p50/p95/p99, succespercentage); filters: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) | | `/api/usage/cache-health` | GET | Samenvatting van de prompt-cachegezondheid voor `call_logs` — schrijf-/leesverhouding, p50/p90/p99-verdeling van de schrijfgrootte, concentratie van zware schrijfbewerkingen, uitsplitsing per model en een oordeel `healthy`/`degraded`/`thrash`/`no-data`; queryparameters `range` (`1h`\|`24h`\|`7d`\|`30d`, standaard `24h`) en optioneel `model` (#8827) | ### Machtigingen voor API-sleutels `PATCH /api/keys/{id}` werkt de machtigingen van een bestaande sleutel bij. Net als elke `/api/keys*`-route vereist deze beheerautorisatie (zie [Beheerauthenticatie](../guides/MANAGEMENT-AUTH.md)), niet een inferentiesleutel. Stuur alleen de velden die u wilt wijzigen; een verzoek zonder een van deze velden wordt afgewezen met `No valid fields to update`. De geaccepteerde velden worden gedefinieerd door `updateKeyPermissionsSchema` in `src/shared/validation/schemas/keys.ts`. | Veld | Type | Opmerkingen | | ------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string, 1-200 tekens | | | `isActive` | boolean | | | `isBanned` | boolean | | | `expiresAt` | ISO 8601-datum/tijd of `null` | `null` wist de vervaldatum | | `modelAccessMode` | `all` \| `restricted` | `allowedModels` moet leeg zijn wanneer de modus `all` is | | `allowedModels`, `blockedModels` | array van strings, maximaal 1000 | | | `allowedCombos` | array van strings, maximaal 500 | Bepaalt welke combo's de sleutel mag aanroepen; directe modellen worden beheerd door `modelAccessMode` / `allowedModels` | | `connectionAccessMode` | `all` \| `restricted` | `allowedConnections` mag niet leeg zijn bij `restricted` en moet leeg zijn bij `all` | | `allowedConnections` | array van UUID's, maximaal 100 | | | `allowAutoCombos` | boolean | `false` weigert aanvragen voor `auto/*`-modellen met deze sleutel; sleutels waarvoor dit nooit is ingesteld, zijn toegestaan | | `catalogScope` | `all` \| `combos` \| `models` | Wat `GET /v1/models` voor deze sleutel weergeeft (alleen combo's, alleen modellen of beide); dit verandert niet wat de sleutel mag aanroepen | | `noLog`, `autoResolve` | boolean | | | `throttleDelayMs` | integer, 0-300000 | | | `maxSessions` | integer, 0-10000 | | | `rateLimits` | array van `{ limit, window }` (positieve integers, maximaal 50) of `null` | `null` wist de limieten | | `accessSchedule` | planningsobject of `null` | `null` wist de planning | | `scopes` | array van strings, maximaal 32 | | | `allowedEndpoints` | array van strings, maximaal 20 | | | `streamDefaultMode` | `legacy` \| `json` | | | `cacheDefaultMode` | `legacy` \| `bypass` | Zie [Cache omzeilen per sleutel](#per-key-cache-bypass) | | `compressionEnabled` | boolean | | | `codexServiceMode` | een van de Codex-servicemodi | | | `disableNonPublicModels` | boolean | | | `allowUsageCommand` | boolean | | | `usageLimitEnabled` | boolean | | | `dailyUsageLimitUsd`, `weeklyUsageLimitUsd` | getal >= 0 of `null` | | | `chaosModeEnabled` | boolean | | ```bash curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "allowAutoCombos": false, "catalogScope": "combos" }' ``` ### Instellingen | Eindpunt | 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 (ongewijzigd doorgeven / automatisch verwijderen / aangepast / adaptief). Onafhankelijk van compressie. Zie [THINKING_BUDGET.md](../guides/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 in het verzoeklogboek en lokale aanroeplogartefacten wissen | ### Context en compressie | Eindpunt | Methode | Beschrijving | | -------------------------------------- | -------------- | -------------------------------------------------------------------------------------- | | `/api/compression/preview` | POST | Voorbeeld van off/lite/standard/aggressive/ultra/RTK/stacked-compressie | | `/api/compression/language-packs` | GET | Beschikbare Caveman-taalpakketten weergeven | | `/api/compression/rules` | GET | Metagegevens 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 bewaring 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 via aanwijzer-id | | `/api/context/combos` | GET/POST | Lijst met compressiecombinaties/compressiecombinatie maken | | `/api/context/combos/[id]` | GET/PUT/DELETE | Details van compressiecombinatie ophalen/bijwerken/verwijderen | | `/api/context/combos/[id]/assignments` | GET/PUT | Compressiecombinaties aan routeringscombinaties toewijzen | | `/api/context/analytics` | GET | Alias voor compressieanalyses | ### Monitoring | Endpoint | Methode | Beschrijving | | ------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/sessions` | GET | Actieve sessies bijhouden | | `/api/rate-limits` | GET | Snelheidslimieten per account | | `/api/monitoring/health` | GET | Statuscontrole + 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](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). | | `/api/cache/stats` | GET/DELETE | Cachestatistieken / wissen | | `/api/modality-bridge/stats` | GET | In-memory `attempts`, geslaagde pogingen/`bridged`, mislukte pogingen, cachetreffers, `totalLatencyMs`, `latencySamples`, op steekproeven gebaseerde `averageLatencyMs` en tijdstip van het laatste gebruik (wordt bij herstart gereset; beheerauthenticatie) | | `/api/modality-bridge/video/runtime` | GET | Strikte controle op vertrouwde loopback vóór beheerauthenticatie/probe; opgeschoonde beschikbaarheids- en versiegegevens 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 capaciteitsgebrek, `499` bij verbroken verbinding, `504` bij overschreden deadline; geen openbare upload-API | ### Back-up & 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 (`?dryRun=true` valideert alleen) | | `/api/db-backups/exportAll` | GET | Volledige back-up downloaden als .tar.gz-archief | `/api/db-backups/export`, `/api/db-backups/exportAll` en `/api/settings/export-json` geven alle opgeslagen aanmeldgegevens vrij en vereisen daarom de dashboardsessie of de lokale CLI (of dat aanmelden is uitgeschakeld). API-sleutels van elk bereik en `oma_`-toegangstokens krijgen `403`. `/api/db-backups/export`, `/api/db-backups/exportAll` and `/api/settings/export-json` hand out every stored credential, so they require the dashboard session or the local CLI (or login disabled). API keys of any scope and `oma_` access tokens get `403`. The restores hold the same boundary: `POST /api/db-backups/import` (`dryRun=true` included), `POST /api/db-backups` (restore by id) and `POST /api/settings/import-json` replace the live database or settings, so a machine credential gets `403` there too; `omniroute sync import` sends the local CLI credential. ### Cloudsynchronisatie | Endpoint | Methode | Beschrijving | | ---------------------- | ------------ | ------------------------------ | | `/api/sync/cloud` | Verschillend | Cloudsynchronisatiebewerkingen | | `/api/sync/initialize` | POST | Synchronisatie initialiseren | | `/api/cloud/*` | Verschillend | Cloudbeheer | ### Tunnels | Endpoint | Methode | Beschrijving | | -------------------------- | ------- | --------------------------------------------------------------------------------- | | `/api/tunnels/cloudflared` | GET | Lees de installatie-/runtimestatus van Cloudflare Quick Tunnel voor het dashboard | | `/api/tunnels/cloudflared` | POST | Schakel Cloudflare Quick Tunnel in of uit (`action=enable/disable`) | | `/api/tunnels/ngrok` | GET | Lees de runtimestatus van ngrok Tunnel voor het dashboard | | `/api/tunnels/ngrok` | POST | Schakel ngrok Tunnel in of uit (`action=enable/disable`) | ### CLI-hulpprogramma's | 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 | Algemene CLI-runtime | CLI-responsen bevatten: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. ### ACP-agents | Endpoint | Methode | Beschrijving | | ----------------- | ------- | -------------------------------------------------------------------------- | | `/api/acp/agents` | GET | Geef alle gedetecteerde agents (ingebouwd + aangepast) met hun status weer | | `/api/acp/agents` | POST | Voeg een aangepaste agent toe of vernieuw de detectiecache | | `/api/acp/agents` | DELETE | Verwijder een aangepaste agent via de queryparameter `id` | De GET-respons bevat `agents[]` (id, name, binary, version, installed, protocol, isCustom) en `summary` (total, installed, notFound, builtIn, custom). ### Robuustheid en snelheidslimieten | Endpoint | Methode | Beschrijving | | --------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------- | | `/api/resilience` | GET/PATCH | Haal de aanvraagwachtrij, verbindingsafkoelperiode, provideronderbreker en wachtinstellingen op of werk ze bij | | `/api/resilience/reset` | POST | Stel de stroomonderbrekers van providers opnieuw in | | `/api/resilience/model-cooldowns` | GET | Geef actieve blokkeringen per (provider, verbinding, model) weer, gesorteerd op resterende tijd | | `/api/resilience/model-cooldowns` | DELETE | Wis een modelblokkering — body `{provider, model}` of `{all: true}` om alles te wissen | | `/api/rate-limits` | GET | Status van snelheidslimieten per account | | `/api/rate-limit` | GET | Algemene configuratie van snelheidslimieten | > Alle vier de routes onder `/api/resilience/*` vereisen **beheerautorisatie** (`requireManagementAuth`). Zie [Robuustheid (uitgebreid)](#resilience-extended) voor een volledig overzicht van provideronderbrekers, verbindingsafkoelperioden en modelblokkeringen. ### Evaluaties | Endpoint | Methode | Beschrijving | | ------------ | -------- | ---------------------------------------------- | | `/api/evals` | GET/POST | Geef evaluatiesuites weer / voer evaluatie uit | ### Beleidsregels | Endpoint | Methode | Beschrijving | | --------------- | --------------- | ------------------------------ | | `/api/policies` | GET/POST/DELETE | Beheer routeringsbeleidsregels | ### Compliance | Endpoint | Methode | Beschrijving | | --------------------------- | ------- | ----------------------------------- | | `/api/compliance/audit-log` | GET | Compliance-auditlogboek (laatste N) | ### v1beta (compatibel met Gemini) | Endpoint | Methode | Beschrijving | | -------------------------- | ------- | ------------------------------------- | | `/v1beta/models` | GET | Geef modellen weer in Gemini-indeling | | `/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 API's / systeem-API's | Endpoint | Methode | Beschrijving | | ------------------------ | ------- | -------------------------------------------------------------------- | | `/api/init` | GET | Controle van applicatie-initialisatie (gebruikt bij de eerste start) | | `/api/tags` | GET | Ollama-compatibele modeltags (voor Ollama-clients) | | `/api/restart` | POST | Activeer een gecontroleerde herstart van de server | | `/api/shutdown` | POST | Activeer een gecontroleerde uitschakeling van de server | | `/api/system/env/repair` | POST | Herstel omgevingsvariabelen van de OAuth-provider | | `/api/system/version` | GET | Huidige/nieuwste versie, updatestatus en releasekanaal | | `/api/system/version` | POST | Start een implementatiebewuste update naar de nieuwste versie | > **Opmerking:** Deze endpoints worden intern door het systeem of voor compatibiliteit met Ollama-clients gebruikt. Ze worden doorgaans niet rechtstreeks door eindgebruikers aangeroepen. ### Herstel van de OAuth-omgeving _(v3.6.1+)_ ```bash POST /api/system/env/repair Content-Type: application/json { "provider": "claude-code" } ``` Herstelt ontbrekende of beschadigde OAuth-omgevingsvariabelen voor een specifieke provider. Retourneert: ```json { "success": true, "repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"], "backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak" } ``` ### Versie en releasekanaal ```bash GET /api/system/version ``` Beheerroute die alleen via loopback toegankelijk is (adminauthenticatie). Retourneert de actieve versie, de nieuwste gepubliceerde versie en de status van automatische updates. `releaseChannel` en `channels` zijn aanvullende velden (rail 3.8.54); `channel` behoudt zijn betekenis — de implementatiemodus die de dashboard-updater gebruikt (`npm`, `source` of `docker-compose`). ```json { "current": "3.8.52", "latest": "3.8.52", "updateAvailable": false, "channel": "npm", "autoUpdateSupported": true, "autoUpdateError": null, "news": null, "releaseChannel": "latest", "channels": { "latest": "3.8.52", "next": "3.8.53-rc.1" } } ``` - `releaseChannel` — npm-kanaal van de actieve build: `nightly` voor versies met `-nightly.*`, `next` voor andere prereleases (`-rc.*`, `-beta.*`, `-alpha.*`), `lts` voor een stabiele versie met een oudere hoofdversie dan `channels.latest`, en anders `latest`. Dezelfde regels als in `scripts/release/dist-tag.mjs`, dat tijdens het publiceren de npm-dist-tag kiest. - `channels` — de laatst gepubliceerde versie van elke dist-tag, opgehaald via `npm view omniroute dist-tags` (met het register via HTTP als terugvaloptie), gecachet met dezelfde TTL van 10 minuten als `latest`. `latest` is altijd aanwezig (valt terug op het veld `latest` en vervolgens op `"unavailable"`); `next`, `nightly` en `lts` worden alleen weergegeven wanneer die dist-tag bestaat. Een verzoek met `Cache-Control: no-cache` vernieuwt beide opzoekbewerkingen. Het kanaalmodel (`latest` = v3 tot de algemene beschikbaarheid van 4.0, `next` = rc, `nightly` = builds van `develop`, `lts` = patches voor v3 na de algemene beschikbaarheid van 4.0) wordt beschreven in `docs/ops/RELEASE_STRATEGY.md`. --- ## Audiotranscriptie ```bash 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:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ -H "Authorization: Bearer your-api-key" \ -F "file=@recording.mp3" \ -F "model=openai/whisper-1" ``` **Antwoord:** ```json { "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: ```bash # 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. ```bash # 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: ```bash curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}' ``` 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 ```bash # Telemetrieoverzicht van de latentie ophalen (p50/p95/p99 per provider) GET /api/telemetry/summary ``` **Antwoord:** ```json { "providers": { "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } } } ``` --- ## Budget ```bash # 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. ```bash # 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`](../architecture/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 `...`) | | 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 gebruikt door het subsysteem voor automatisch sleutelbeheer 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 vanwege 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 endpoint voor intrekking (zelfde effect als DELETE) | **Authenticatie:** beheersessie/API-sleutel (`requireManagementAuth`) — dezelfde toegangscontrole als `/api/keys`: een dashboardsessie, het lokale CLI-token of een API-sleutel met het bereik `manage`/`admin`; API-sleutels die uitsluitend voor inferentie bestemd zijn, krijgen `403`. 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. ```bash # 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=` 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. ```bash # 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`](../../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 ```bash 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 ```bash 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 & beoordelingen | Methode | Pad | Beschrijving | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- | | POST | `/api/cloud/auth` | Verifieer een Bearer-sleutel en retourneer gemaskeerde providerverbindingen en modelaliassen voor cloudsynchronisatieclients | | POST | `/api/cloud/credentials/update` | Werk versleutelde referenties voor een met de cloud gesynchroniseerde provider bij | | POST | `/api/cloud/model/resolve` | Zet een logische model-ID om naar een concrete provider en een concreet model met behulp van de lokale routeringstabel | | GET | `/api/cloud/models/alias` | Geef modelaliassen weer zoals beschikbaar gesteld voor cloudsynchronisatie | | 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 en de meest recente uitvoeringen weer | | POST | `/api/evals` | Start een evaluatie-uitvoering | | POST | `/api/evals/suites` | Maak een aangepaste evaluatiesuite — body gevalideerd door `evalSuiteSaveSchema` | | GET | `/api/evals/suites/[id]` | Haal een aangepaste evaluatiesuite op | **Authenticatie:** `/api/cloud/auth` valideert rechtstreeks een Bearer-sleutel en retourneert de gemaskeerde sleutel en `projectId` van elke verbinding uitsluitend voor een sleutel met het bereik `manage` / `admin`; de overige routes onder `/api/cloud/*`, `/api/evals/*` en `/api/assess` vereisen een beheersessie/API-sleutel. POST voor `/api/assess` gebruikt `validateBody` met een scopeschema op basis van een discriminated union. --- ## 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=` | **Voorbeeldrespons** (`GET /api/acp/agents`): ```json { "agents": [ { "id": "claude", "name": "Claude Code CLI", "binary": "claude", "version": "1.0.45", "installed": true, "protocol": "stdio", "providerAlias": "claude", "isCustom": false }, { "id": "my-custom-cli", "name": "My Custom CLI", "installed": false, "protocol": "stdio", "providerAlias": "my-provider", "isCustom": true } ], "cacheTtlMs": 60000, "cacheAge": 1234 } ``` **Authenticatie:** Vereist een beheersessie (`auth_token`-cookie van het dashboard) of een API-sleutel met beheerbereik. Zie [ACP-framework](../frameworks/ACP.md) 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**: ```json { "window": "24h", "totalCalls": 1234, "strategyBreakdown": { "rules": 800, "cost": 200, "latency": 150, "sla-aware": 50, "lkgp": 34 }, "tierBreakdown": { "ultra": 100, "pro": 500, "standard": 400, "free": 234 }, "topProviders": [ { "provider": "openai", "calls": 500, "avgLatencyMs": 850 }, { "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 } ] } ``` ### Compressieanalyse | Methode | Pad | Beschrijving | | ------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/compression` | Geaggregeerde compressiestatistieken: bespaarde tokens, besparingspercentage, modusverdeling en enginegebruik | **Voorbeeldrespons**: ```json { "window": "24h", "totalOriginalTokens": 5000000, "totalCompressedTokens": 3500000, "totalSavings": 1500000, "savingsPct": 30.0, "modeBreakdown": { "lite": 400, "standard": 600, "aggressive": 100, "ultra": 50, "rtk": 84 }, "engineBreakdown": { "caveman": 800, "rtk": 434 } } ``` ### 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**: ```json { "window": "24h", "shannonEntropy": 2.45, "maxEntropy": 3.17, "diversityRatio": 0.77, "providerUsage": { "openai": 0.4, "anthropic": 0.25, "google": 0.2, "kiro": 0.15 }, "warnings": ["OpenAI accounts for 40% of traffic — consider diversifying"] } ``` **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}` | **Authenticatie:** Vereist een beheersessie met beheerdersbereik. --- ## Beheer van CLI-tools Beheer CLI-tools die met OmniRoute integreren (antigravity, commandCode, devin-cli, enz.). Zie [Providerreferentie](./PROVIDER_REFERENCE.md) 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` | Schrijft de gegenereerde configuratie van een tool (`dryRun` toont een voorbeeld; `422` + `containerEphemeralTarget` bij uitvoering in een container; `migration` vermeldt verouderde Codex-YAML) | | GET | `/api/cli-tools/backups` | Geeft een lijst met back-ups van CLI-toolconfiguraties | | POST | `/api/cli-tools/backups` | Maakt een back-up van alle CLI-toolconfiguraties | | 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` | Configureert aliassen voor antigravity-mitm | **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=` (één item), `?provider=

` 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](../frameworks/WEBHOOKS.md) 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](../frameworks/SKILLS.md) 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](../frameworks/PLUGIN_SDK.md) voor alle details. --- ## Schaduwroutering Schaduw-/A-B-vergelijking van providers is **geen zelfstandige REST-interface** — deze wordt geconfigureerd via combinatieroutering (zie [Auto-Combo](../routing/AUTO-COMBO.md)). 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](../security/GUARDRAILS.md) voor alle details. --- --- ## Authenticatie Zie [Beheerauthenticatie](../guides/MANAGEMENT-AUTH.md) 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`).