# API Reference (Français) 🌐 **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) · 🇮🇪 [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) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md) --- 🌐 **Langues :** 🇺🇸 [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) Référence principale de l’API OmniRoute. Elle couvre l’interface publique `/v1` et les points de terminaison de gestion les plus utilisés ; le fichier lisible par machine [`docs/openapi.yaml`](../openapi.yaml) et l’arborescence des routes sous `src/app/api/` constituent les sources exhaustives. Pour le protocole ciblé compatible avec OpenAI et la matrice des capacités des fournisseurs, consultez [`OPENAI_COMPATIBILITY.md`](./OPENAI_COMPATIBILITY.md). --- ## Table des matières - [Complétions de chat](#chat-completions) - [Baux exclusifs de sessions gérées](#exclusive-managed-session-leases) - [Embeddings](#embeddings) - [Génération d’images](#image-generation) - [OCR de documents](#document-ocr) - [Liste des modèles](#list-models) - [Manifeste du plugin fournisseur](#provider-plugin-manifest) - [Points de terminaison de compatibilité](#compatibility-endpoints) - [API des fichiers](#files-api) - [API des traitements par lots](#batches-api) - [API de recherche](#search-api) - [Diffusion en continu via WebSocket](#websocket-streaming) - [Quotas et signalement des problèmes](#quotas--issues-reporting) - [Cache sémantique](#semantic-cache) - [Tableau de bord et gestion](#dashboard--management) - [Gestion des combinaisons](#combo-management) - [Webhooks](#webhooks) - [Clés enregistrées (gestion automatique)](#registered-keys-auto-management) - [Protocole des agents](#agents-protocol) - [Proxys de gestion](#management-proxies) - [Résilience (étendue)](#resilience-extended) - [Compétences](#skills) - [Mémoire](#memory) - [Serveur MCP](#mcp-server) - [Serveur A2A](#a2a-server) - [Cloud, évaluations et appréciation](#cloud-evals--assess) - [Traitement des requêtes](#request-processing) - [Authentification](#authentication) --- ## Complétions de chat ```bash POST /v1/chat/completions Authorization: Bearer your-api-key Content-Type: application/json { "model": "cc/claude-opus-4-6", "messages": [ {"role": "user", "content": "Write a function to..."} ], "stream": true } ``` ### En-têtes personnalisés | En-tête | Direction | Description | | ------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `X-OmniRoute-No-Cache` | Requête | Définissez-le sur `true` pour contourner le cache | | `x-omniroute-no-memory` | Requête | Définissez-le sur `true` pour ignorer l’injection de mémoire et de compétences pour cette requête (reproduit le comportement sans cache et évite le surcoût en jetons et en coût pour chaque appel) | | `X-OmniRoute-Progress` | Requête | Définissez-le sur `true` pour recevoir les événements de progression | | `X-Session-Id` | Requête | Clé de session persistante pour l’affinité de session externe | | `x_session_id` | Requête | Variante avec trait de soulignement également acceptée (HTTP direct) | | `X-OmniRoute-Session-Id` | Requête | Étiquette de session/conversation fournie par l’appelant (également transmise à la mémoire). Lorsqu’elle est présente, elle est conservée telle quelle dans `call_logs.session_tag` pour l’attribution des coûts par session (#8249) — elle n’est jamais générée lorsqu’elle est absente | | `Idempotency-Key` | Requête | Clé de déduplication (fenêtre de 5 s) | | `X-Request-Id` | Requête | Clé de déduplication alternative | | `X-OmniRoute-Cache` | Réponse | `HIT` ou `MISS` (hors diffusion en continu) | | `X-OmniRoute-Idempotent` | Réponse | `true` en cas de déduplication | | `X-OmniRoute-Progress` | Réponse | `enabled` si le suivi de la progression est activé | | `X-OmniRoute-Session-Id` | Réponse | ID de session effectif utilisé par OmniRoute | | `X-OmniRoute-Request-Id` | Réponse | ID de corrélation de la requête (lorsqu’il est connu) | | `X-OmniRoute-Version` | Réponse | Version de build d’OmniRoute (toujours présente) | | `X-OmniRoute-Cost-Saved` | Réponse | Montant en USD économisé grâce au cache lors d’un `HIT` (uniquement pour les accès au cache) | | `X-OmniRoute-Decision` | Réponse | Trace de routage : `strategy=; provider=; latency_ms=` (`` est la stratégie de combinaison, ou `single` pour une requête sans combinaison) — toujours présente dans les réponses finales | > Remarque concernant Nginx : si vous utilisez des en-têtes contenant des traits de soulignement (par exemple `x_session_id`), activez `underscores_in_headers on;`. > **En-têtes de télémétrie des coûts :** les réponses réussies non diffusées en continu incluent également l’ensemble d’en-têtes de télémétrie des coûts `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, avec exactement 10 décimales ; `0.0000000000` si gratuit ou sans tarification), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit` et `X-OmniRoute-Fallback-Attempts` (uniquement lorsque > 0), ainsi que `X-OmniRoute-Request-Id` et `X-OmniRoute-Version`. Ils sont émis par les complétions de chat, `/v1/responses`, `/v1/messages`, **ainsi que par les points de terminaison multimédias** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations` et `/v1/moderations` (coût toujours égal à `0`). Le coût des contenus multimédias est calculé selon la modalité (par image, par seconde, par caractère ou par unité de recherche) lorsque la tarification est disponible ; dans le cas contraire, il est égal à `0` (mode ouvert en cas d’échec). > **Sémantique du coût en cas d’accès au cache :** lors d’un accès au cache sémantique (`X-OmniRoute-Cache-Hit: true`), aucun appel en amont n’est effectué ; `X-OmniRoute-Response-Cost` vaut donc `0.0000000000` (le coût **incrémental** du traitement de cet accès). Le coût initial ou celui qui aurait été engagé est indiqué séparément dans `X-OmniRoute-Cost-Saved`. Les systèmes de facturation doivent additionner les valeurs de `X-OmniRoute-Response-Cost` (les accès au cache ne coûtent rien) ; les outils d’analyse du cache peuvent agréger les valeurs de `X-OmniRoute-Cost-Saved`. ## Baux de session gérés exclusifs Le bail de session géré exclusif est un contrat de routage opt-in, neutre au client : un propriétaire actif détient une connexion OmniRoute éligible. Il ne loue pas de modèle, ne nécessite pas OAuth, n'identifie pas de client particulier, ni ne requiert de fournisseur particulier. La clé API d'authentification doit avoir la portée `lease:exclusive` et une liste `allowedConnections` explicite et non vide. La limite de mutation de la base de données applique ces deux champs ensemble lors de la création de la clé et des mises à jour partielles. ```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"} ``` Les réponses d'acquisition, de renouvellement et de libération réussies exposent les horodatages, l'`état` et la `génération` positive exacte, mais jamais la connexion sélectionnée ou les informations d'identification. Le renouvellement et la libération fournissent la génération dans le corps JSON : ```json { "action": "renew", "generation": 1 } ``` ```json { "action": "release", "generation": 1, "reason": "OWNER_EXIT" } ``` Un propriétaire de bail actif peut explicitement demander des métadonnées d'affichage respectueuses de la vie privée pour sa liaison actuelle : ```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" } } ``` Cette action de statut opt-in est protégée par le propriétaire opaque, la clé API gérée authentifiée et la génération active exacte dans une seule transaction de base de données. `displayName` est uniquement le nom de connexion configuré tronqué ; il est `null` lorsqu'aucun nom configuré sûr n'existe. OmniRoute ne substitue jamais un e-mail ou une identité de compte générée. La valeur du fournisseur est une étiquette d'affichage non sensible et jamais un identifiant de fournisseur compatible généré. Les informations d'identification, les jetons, les cookies, les identifiants de connexion bruts ou de clé API, les hachages de propriétaire, les secrets de protection et les données de routage internes sont exclus. Les recherches avec une clé incorrecte, un propriétaire incorrect, une génération obsolète, manquantes, expirées, libérées et invalidées renvoient toutes la même erreur `409 LEASE_FENCE_STALE` sans métadonnées de connexion. Un client qui a reçu la réponse d'attente de capacité n'a aucune liaison active à inspecter. Lorsque le routage fait transiter un bail actif, la même génération reste valide et le statut renvoie atomiquement la nouvelle liaison, jamais l'ancienne. Les clients existants restent inchangés car les réponses d'acquisition, de renouvellement, de libération et d'attente conservent leurs formes précédentes. Ce contrat de serveur ne modifie pas le `/status` standard d'OpenAI Codex. Le Codex standard rapporte actuellement son fournisseur de modèle et son état d'authentification/compte intégré, mais ne rend pas de métadonnées de compte de fournisseur personnalisées arbitraires ; une intégration client ultérieure doit appeler cette action et décider comment afficher `connection.displayName`. Chaque demande d'inférence gérée fournit alors les deux en-têtes de contrôle : ```http X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> X-OmniRoute-Lease-Generation: 1 ``` Le propriétaire exact, la génération, la connexion active et la clé API authentifiée sont protégés immédiatement avant chaque tentative en amont prise en charge. Rejouer le propriétaire et la génération avec une autre clé échoue même lorsque cette clé autorise la même connexion. Les propriétaires bruts ne sont pas persistés, journalisés, conservés dans l'instantané de la demande ou transmis en amont. Une contention temporaire renvoie HTTP `429` avec `Retry-After` et : ```json { "state": "WAITING_FOR_CAPACITY", "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" }, "reason": "NO_FREE_ELIGIBLE_CONNECTION", "retryAfter": 30 } ``` Cette réponse signifie seulement que l'ensemble éligible ordinaire n'était pas vide et que chaque candidat libre était détenu par un bail actif étranger. Les modèles/fournisseurs non pris en charge, les non-concordances de politique, les délais de grâce, les quotas, la santé et d'autres défaillances d'éligibilité ordinaires conservent leurs réponses OmniRoute existantes. ### `x-omniroute-compression` Remplacement par requête du plan de compression. Priorité la plus élevée — l'emporte sur le remplacement de la combinaison de routage, le profil actif, le déclenchement automatique et le panneau par défaut. Valeurs : | Valeur | Effet | | ------------- | -------------------------------------------------------------------------------------------------------- | | `off` | Aucune compression pour cette requête. | | `default` | Le profil par défaut dérivé du panneau (ignore le profil actif). Les moteurs avec perte sont désactivés. | | `safe` | Déduplication et repli d'espaces blancs uniquement. | | `allow-lossy` | Conserve le plan de l'opérateur pour cette requête, y compris les résumés et les réécritures de style. | | `engine:` | Un seul moteur lorsqu'il est activé, par exemple `engine:rtk`. Opt-in par requête pour ce moteur. | | `` | Une combinaison nommée, correspondant par nom (insensible à la casse) d'abord, puis par id. | Remarques : - Les valeurs inconnues sont ignorées (la requête n'est jamais rejetée) ; la résolution se poursuit selon la précédence normale de l'opérateur. - Si plusieurs combinaisons partagent un nom, passez l'**id** de la combinaison pour une correspondance déterministe. - Une combinaison dont le nom est `off` ou `default` ne peut pas être sélectionnée par nom (ces mots-clés sont interprétés en premier) ; référencez une telle combinaison par son id. - L'interrupteur de compression principal est une porte dure : lorsque la compression est désactivée globalement, cet en-tête ne peut pas l'activer. Le plan appliqué est renvoyé dans l'en-tête de réponse : ``` X-OmniRoute-Compression: ; source= ``` où `` est l'un des suivants : `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, ou `off`. --- ## 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" } ``` Fournisseurs disponibles : Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI. Les identifiants du catalogue sont au format `provider/model` (exemple : `jina-ai/jina-embeddings-v5-omni-small`). Les identifiants de modèles Jina sans préfixe qui figurent dans le registre (par exemple `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) sont également résolus. Les opérations Jina d’embedding, de reranking, de classification et de segmentation utilisent d’abord les identifiants `jina-ai` du tableau de bord ; `JINA_AI_API_KEY` n’est utilisé comme solution de secours que lorsqu’aucune clé du tableau de bord n’existe. La fiche `jina-reader` est réservée à Reader / `r.jina.ai` (`POST /v1/web/fetch`) et ne fournit jamais d’embeddings ni de reranking. Les modèles du registre qui annoncent une prise en charge multimodale acceptent également jusqu’à 32 éléments structurés indépendants du fournisseur. Les types d’éléments multimédias sont `text`, `image`, `audio`, `video` et `document`. Leur `source` multimédia est soit `{"type":"url","url":"https://..."}`, soit `{"type":"base64","data":"...","media_type":"..."}`. Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano` et l’alias de famille `jina-ai/jina-embeddings-v5-omni` → omni-small) accepte également les documents EmbeddingsV5Request natifs de Jina et **les transmet intacts** à `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,..." }] } ] } ``` Les valeurs natives `{ image | audio | video | pdf }` peuvent être une URL HTTPS publique, un URI `data:` ou des données base64 brutes. OmniRoute ne convertit pas ces objets en chaînes et ne récupère pas les URL d’images natives : Jina récupère lui-même les médias publics. Les champs Jina supplémentaires (`task`, `normalized`, `truncate`, `embedding_type`) sont transmis. Les SKU Jina limités au texte continuent de rejeter les documents non textuels. Limites de sécurité et de transport : - Les URL de médias distants doivent être des URL HTTPS publiques. Les éléments canoniques `{type,source:url}` sont récupérés côté serveur (nouvelle validation des redirections, délai d’expiration, limites de taille, DNS public, épinglage de connexion), puis incorporés avant l’appel au fournisseur. Les éléments natifs Jina `{image:"https://..."}` sont transmis tels quels après la même vérification HTTPS publique ; Jina récupère l’URL. - Les médias base64 intégrés sont limités à 8 Mio décodés par élément et à 16 Mio décodés pour l’ensemble de la requête. Traduction pour les fournisseurs (les éléments canoniques ne sont jamais transmis sans modification) : - Modèles multimodaux Jina : chaque élément de premier niveau devient un objet associé à une modalité (`text` / `image` / `audio` / `video` / `pdf`), utilisant des URI de données pour les médias intégrés ; un vecteur par élément de premier niveau. - Famille Gemini Embedding 2 : un tableau de premier niveau devient une requête native `models/{model}:embedContent` unique avec `content.parts` (`text` ou `inline_data`). - llama.cpp (`llama-cpp/`, tout modèle chargé par le serveur local) : les éléments canoniques `text` deviennent de simples chaînes, tandis que `image` / `audio` / `video` deviennent chacun un objet `{"content": [part]}`, utilisant les parties de contenu de conversation de llama-server (`image_url`, `input_audio` avec le format `wav` / `mp3` / `flac`, `input_video`) et des données intégrées ; un vecteur par élément de premier niveau. Le serveur doit être exécuté avec `--embedding --mmproj …` ; sans projecteur, il rejette lui-même les médias. `document` n’est pas pris en charge. - Les modèles inconnus/dynamiques sans métadonnées explicites de modalité rejettent les entrées structurées avec le code 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" } ``` Les combinaisons modèle/modalité non prises en charge renvoient le code HTTP 400 au lieu de convertir l’élément. Les champs d’extension autres que ceux d’entrée dans les requêtes historiques utilisant des chaînes ou des jetons continuent d’être transmis sans modification. ```bash # Répertorier tous les modèles d’embedding GET /v1/embeddings ``` --- ## Génération d’images ```bash POST /v1/images/generations Authorization: Bearer your-api-key Content-Type: application/json { "model": "openai/gpt-image-2", "prompt": "Un magnifique coucher de soleil sur les montagnes", "size": "1024x1024" } ``` Les fournisseurs disponibles incluent OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, **ZenMux**, SD WebUI (local), ComfyUI (local). `n` renvoie `n` images dans `data[]`. Pour les fournisseurs dont l’API en amont renvoie une image par appel (Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik, NVIDIA NIM, Cloudflare Workers AI), `n` appels distincts sont effectués en amont, avec au plus 4 appels simultanés. Une `seed` fixe est décalée selon l’index de l’appel (`seed`, `seed + 1`, …), afin que les images soient différentes tout en restant reproductibles. `n` est plafonné à 10. La requête échoue dans son intégralité si l’un des appels échoue. La liste des formats de distribution est définie dans `SINGLE_IMAGE_FANOUT_FORMATS` dans `open-sse/handlers/imageGeneration/fanOut.ts`. ZenMux réutilise la connexion par clé d’API existante et accepte les préfixes `zenmux/` ou `zm/` : - `zenmux/openai/gpt-image-2` utilise l’API OpenAI Images de ZenMux. Les options incluent `size`, `quality`, `n`, `output_format`, `output_compression`, `background` et `response_format`. - Les autres éditeurs, tels que `zm/meta/muse-image-1.0`, utilisent le point de terminaison `:predict` de Vertex AI de ZenMux. `n` correspond à `sampleCount`, `aspect_ratio` à `aspectRatio` et `image_size` (`1K`, `2K`, `4K`) à `sampleImageSize`. Une valeur `size` en pixels fournit uniquement un rapport d’aspect, sans garantir les dimensions en pixels. Les rapports, résolutions et nombres pris en charge varient selon le modèle. - `zm/inclusionai/ming-image-0.1-design` choisit ses propres dimensions. Omettez `size`, `aspect_ratio` et `image_size` ; des valeurs explicites renvoient une erreur HTTP 400. Les formats PNG, JPEG et WebP peuvent être demandés avec `output_format`. Cette intégration prend en charge la génération de texte en image, mais pas la retouche à partir d’une image de référence. La sortie Vertex est normalisée dans `data[].b64_json` ; `response_format: "url"` renvoie une URL HTTPS provenant du service en amont ou une URL de données en base64 lorsque seuls les octets de l’image sont disponibles. Les sorties vides ou filtrées renvoient une erreur plutôt qu’un succès vide. L’accès aux modèles dépend du compte ZenMux. Consultez [l’API Vertex de ZenMux](https://docs.zenmux.ai/api/vertexai/generate-images) et [l’API OpenAI Images](https://docs.zenmux.ai/api/openai/generate-an-image). ```bash # Répertorier tous les modèles d’images GET /v1/images/generations ``` --- ## OCR de documents ```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` sélectionne le fournisseur d’OCR via un préfixe `provider/model` ; un identifiant de modèle seul (par ex. `mistral-ocr-latest`) est associé à son fournisseur enregistré, tandis que si `model` est omis, Mistral (`mistral-ocr-latest`) est utilisé par défaut. Fournisseurs enregistrés (`open-sse/config/ocrRegistry.ts`) : | Identifiant du fournisseur | Identifiant du modèle | Valeur de `model` | Remarques | | ----------------------------- | --------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (ou simplement `mistral-ocr-latest`) | Synchrone — la réponse est renvoyée directement à partir de l’unique appel en amont. | | `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Traitement en amont asynchrone (`analyze` + interrogation) — voir ci-dessous. | | `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Synchrone, via le point de terminaison partenaire `openapi/chat/completions` de Vertex AI — voir ci-dessous pour l’authentification et l’URL. | Les trois fournisseurs renvoient le même corps au format Mistral : ```json { "pages": [{ "index": 0, "markdown": "# Texte extrait..." }], "model": "mistral-ocr-latest", "usage_info": { "pages_processed": 1 } } ``` ### Flux d’interrogation d’Azure Document Intelligence L’API `analyze` d’Azure Document Intelligence est asynchrone : la requête initiale renvoie un en-tête `Operation-Location` au lieu d’un corps, et le résultat doit être récupéré par interrogations successives. Le gestionnaire (`open-sse/handlers/ocr.ts`) interroge cette URL toutes les secondes, jusqu’à 30 tentatives, échoue immédiatement (sans poursuivre les interrogations) si une réponse d’interrogation n’est pas `ok` ou si le statut est `"failed"`, et renvoie `504` si l’opération est toujours en cours une fois le nombre maximal de tentatives épuisé. La réponse Azure finale est normalisée dans le même format `pages`/`markdown` que celui utilisé par Mistral avant d’être renvoyée à l’appelant, de sorte que le code client n’a pas besoin de traiter le fournisseur comme un cas particulier. ### Authentification et résolution du point de terminaison Vertex AI DeepSeek OCR `vertex-deepseek-ocr` réutilise la même authentification Vertex AI qu’OmniRoute prend déjà en charge pour le trafic de chat et d’images (`open-sse/executors/vertex.ts`) : la clé API de la connexion est soit un identifiant Service Account JSON (échangé contre un jeton d’accès OAuth de courte durée via le flux JWT bearer), soit un jeton d’accès OAuth déjà généré, utilisé tel quel. L’URL du point de terminaison en amont est le point de terminaison partenaire générique `openapi/chat/completions` de Vertex, construit à partir du projet et de la région de la connexion — une valeur explicite `providerSpecificData.project`/`providerSpecificData.region` est toujours prioritaire ; sinon, le projet est déduit du champ `project_id` du Service Account JSON et la région prend par défaut la valeur `us-central1`. Ces deux résolutions ont lieu dans `open-sse/handlers/ocr.ts` (`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`) et sont utilisées par `src/app/api/v1/ocr/route.ts` avant la délégation à `handleOcr`. --- ## Répertorier les modèles ```bash GET /v1/models Authorization: Bearer your-api-key → Renvoie tous les modèles de chat, d’embedding et d’image, ainsi que les combos, au format OpenAI ``` ### Préfixes des identifiants de modèle (`?prefix=`) La plupart des modèles sont publiés sous un **préfixe de fournisseur**. Le préfixe obtenu est contrôlé par l’indicateur de fonctionnalité `MODELS_CATALOG_PREFIX_MODE` et peut être remplacé **pour chaque requête** à l’aide d’un paramètre de requête — utile pour un client qui souhaite une liste épurée sans modifier le paramètre global du serveur pour tous les autres utilisateurs : ```bash GET /v1/models?prefix=alias # un identifiant par modèle — le préfixe d’alias court GET /v1/models?prefix=dual # les deux formes (valeur par défaut du serveur) GET /v1/models?prefix=canonical # uniquement le préfixe complet de l’identifiant du fournisseur ``` | Mode | Émet | Remarques | | ----------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dual` | `cc/claude-sonnet-4-6` **et** `claude/claude-sonnet-4-6` | **Valeur par défaut.** Les deux identifiants sont acheminés vers le même modèle ; ils sont conservés afin que les configurations clientes ayant codé en dur l’une ou l’autre forme continuent de fonctionner. Cela double approximativement la taille du catalogue. | | `alias` | `cc/claude-sonnet-4-6` | Une entrée par modèle. Les fournisseurs sans alias distinct publient quand même leur entrée, de sorte que rien n’est perdu. | | `canonical` | `claude/claude-sonnet-4-6` | Une entrée par modèle sous le préfixe complet de l’identifiant du fournisseur. Les fournisseurs sans alias distinct (par ex. `antigravity/…`, `agy/…`) publient également ici leur identifiant unique, de sorte que rien n’est perdu. | Un miroir en mode `dual` peut également être reconnu sans le paramètre de requête : il comporte un champ `parent` pointant vers l’identifiant principal. Les clients qui affichent un sélecteur de modèles doivent demander `?prefix=alias` — c’est ce que fait l’[extension OmniCopilot pour VS Code](../guides/VSCODE-COPILOT.md). ### Modèles de chat masqués individuellement Un modèle marqué **Masqué** sur la page de son fournisseur est exclu du catalogue et rejeté avec HTTP `404` / `model_not_found` lorsqu’il est demandé explicitement. La vérification utilise le fournisseur et le modèle résolus, y compris les alias de fournisseur, les préfixes de nœuds de fournisseurs compatibles et les valeurs par défaut de connexion. Un combo ignore les cibles masquées et peut utiliser une cible apparentée visible ; lorsqu’il ne reste aucune cible exécutable, il renvoie le même code d’erreur. La suppression du masquage prend effet dès la requête suivante. Les remplacements de visibilité propres aux images ne masquent pas le modèle de chat portant le même identifiant. Ce paramètre propre à chaque modèle est distinct des [listes d’autorisation et de refus d’exposition des modèles](../routing/MODEL_EXPOSURE_LIST.md), qui filtrent la publication dans le catalogue et les candidats au routage automatique tout en conservant l’envoi explicite. Les autorisations de modèles liées aux clés API continuent de s’appliquer indépendamment. Le mode de préfixe par défaut du catalogue reste `dual`. ### Variantes de modèles sans raisonnement Pour les modèles Claude capables de raisonnement, `/v1/models` publie également une variante **sans raisonnement** dont l’identifiant est préfixé par `claude-3-omniroute-no-thinking/` : ``` claude-3-omniroute-no-thinking// ``` La sélection de cet identifiant (par ex. dans une configuration Claude Code qui joint systématiquement un bloc `thinking`) est résolue vers le véritable `/` avec le raisonnement désactivé — `thinking:{type:"disabled"}` sur le chemin `/v1/messages`, ou avec les champs `reasoning`/`reasoning_effort` supprimés sur le chemin `/v1/chat/completions`. La variante est uniquement répertoriée pour les modèles de la famille Claude qui prennent en charge le raisonnement **et** respectent `disabled` (ainsi, par ex., les modèles uniquement adaptatifs qui rejettent `disabled` sont exclus). Les opérateurs peuvent forcer l’activation ou la désactivation de cette variante pour chaque modèle via `ModelSpec.noThinkingAlias`. --- ## Manifeste des plugins de fournisseurs ```bash GET /api/v1/provider-plugin-manifest ``` Renvoie le manifeste JSON sécurisé des plugins de fournisseurs utilisé par Bifrost, CLIProxyAPI et les futurs routeurs side-car. La réponse est générée à partir du registre TypeScript des fournisseurs et exclut volontairement les secrets clients OAuth, la résolution de l’environnement d’exécution, les fonctions d’exécution, les en-têtes de requête et les données de compte. Utilisez ce point de terminaison lorsqu’un side-car s’exécute dans un processus distinct et ne peut pas importer directement `open-sse/config/providerPluginManifestRegistry.ts`. --- ## Points de terminaison de compatibilité | Méthode | Chemin | Format | | ------- | ----------------------------------------- | ------------------------------------- | | 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 (édition/inpainting) | | POST | `/v1/videos/generations` | Génération vidéo de style OpenAI | | POST | `/v1/music/generations` | Génération musicale de style OpenAI | | POST | `/v1/audio/transcriptions` | OpenAI Audio (STT) | | POST | `/v1/audio/speech` | OpenAI TTS (renvoie le contenu audio) | | POST | `/v1/rerank` | Reclassement de style Cohere/Voyage | | POST | `/v1/classify` | Classification Jina (`api.jina.ai`) | | POST | `/v1/segment` | Segmenteur Jina (`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}/` | Alias du catalogue OpenAI | | GET | `/api/v1/vscode/{token}/models` | Alias des modèles OpenAI | | POST | `/api/v1/vscode/{token}/chat/completions` | Alias OpenAI avec jeton | | POST | `/api/v1/vscode/{token}/responses` | Alias OpenAI Responses avec jeton | | POST | `/api/v1/vscode/{token}/api/chat` | Alias Ollama avec jeton | | GET | `/api/v1/vscode/{token}/api/tags` | Alias des balises Ollama avec jeton | Toutes les routes POST suivent la même structure : `Bearer your-api-key` + corps JSON validé par Zod (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, etc. ; voir `src/shared/validation/schemas.ts`). Une réponse 4xx est renvoyée en cas d’échec de validation du schéma. Pour les clients qui ne peuvent pas joindre `Authorization: Bearer ...`, OmniRoute accepte également les clés d’API dans l’URL, soit via les paramètres de requête de compatibilité (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`), soit via les points de terminaison dédiés `/api/v1/vscode/{token}/...` documentés ci-dessous. ```bash # Reclassement (fournisseur du registre cloud, ou nœud fournisseur compatible OpenAI sous la forme "/") POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] } # Classification Jina (identifiants de l’API Foundation) POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] } # Segmenteur Jina POST /v1/segment { "content": "...", "return_chunks": true } # Recherche Jina (s.jina.ai ; alias de fournisseurs : jina-search, jina-ai, jina) POST /v1/search { "query": "...", "provider": "jina-search" } # Modérations POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." } # TTS — renvoie un contenu audio/mpeg (ou au format demandé) POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" } # Le TTS Soniox nécessite une langue et une voix : `language` vaut "en" par défaut ; une voix # manquante ou un nom de voix OpenAI standard (alloy, nova, …) devient "Adrian" POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" } # Édition d’image (multipart) POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png # Génération vidéo / musicale (identifiant de modèle préfixé par le fournisseur) POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." } POST /v1/music/generations { "model": "kie/suno-v4.0", "prompt": "..." } ``` > **Nœuds fournisseurs de reclassement :** `POST /v1/rerank` achemine également les requêtes vers des nœuds fournisseurs compatibles OpenAI > (oMLX, vLLM, Infinity, TEI derrière une passerelle, …) désignés sous la forme `/`. Les nœuds de bouclage > (`localhost`, `127.0.0.1`, `172.16.0.0/12`) sont toujours admissibles, tout comme les noms d’hôte que > l’opérateur répertorie dans `OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS` (par exemple, un nom de service Docker/Compose tel > que `http://reranker:8080/v1` ; ceux-ci sont appelés directement, sans jamais passer par `HTTP(S)_PROXY` ni par le > proxy épinglé d’une connexion). Les nœuds situés sur tout autre > hôte — une machine du réseau local ou un pair Tailscale — ne sont admissibles que lorsque l’opérateur active > l’indicateur de fonctionnalité `RERANK_REMOTE_PROVIDER_NODES` **et** que l’URL de base du nœud respecte la politique > relative aux URL sortantes des fournisseurs (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`). > L’étape de reclassement du moteur de mémoire appelle cette route via > l’interface de bouclage ; la même règle s’applique donc à `rerankProviderModel` dans les paramètres de mémoire. > > **Formats des serveurs locaux :** le nœud est appelé à l’adresse `/v1/rerank` puis, en cas de réponse 404, à l’adresse `/rerank` > (Infinity, TEI). Le corps transmis en amont contient à la fois la nomenclature Cohere/OpenAI (`documents`, > `return_documents`) et la nomenclature TEI (`texts`, `return_text`), tandis que la réponse en amont est > normalisée selon l’enveloppe Cohere : le tableau brut `[{index, score, text}]` de TEI, la structure `{results: [{index, score}]}` > des passerelles légères et la structure de style Voyage `{data: [...]}` sont tous renvoyés au client sous la forme > `{results: [{index, relevance_score, document?}]}`, triés par score et limités à `top_n`. > **Découverte des nœuds de fournisseur :** les modèles d'un nœud de fournisseur compatible avec OpenAI apparaissent dans `GET /v1/models` > sous le préfixe du nœud. Les lignes dépourvues de métadonnées de point de terminaison (cas typique des listes locales `/v1/models`) > héritent de l'`apiType` du nœud, de sorte que les modèles d'un nœud `embeddings` ont `type: "embedding"` et ceux d'un > nœud `rerank` ont `type: "rerank"` au lieu d'utiliser le chat par défaut ; un > `supportedEndpoints` explicite sur une ligne synchronisée ou ajoutée manuellement reste prioritaire. ### Routes dédiées aux fournisseurs ```bash POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` Le préfixe du fournisseur est ajouté automatiquement s'il est absent. Les modèles incompatibles renvoient `400`. --- ## API Files Point de terminaison compatible avec OpenAI pour les fichiers d’entrée/sortie par lots et les téléversements associés à un usage spécifique. | Méthode | Chemin | Description | | ------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | POST | `/v1/files` | Téléverser un fichier (multipart : `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — 512 Mio maximum | | GET | `/v1/files` | Répertorier les fichiers associés à la clé API authentifiée | | GET | `/v1/files/[id]` | Récupérer les métadonnées d’un fichier | | DELETE | `/v1/files/[id]` | Supprimer un fichier | | GET | `/v1/files/[id]/content` | Diffuser en continu le contenu brut du fichier | **Authentification :** clé API Bearer — les fichiers sont isolés par clé API via `getApiKeyRequestScope`. Une clé peut uniquement voir, télécharger et supprimer ses propres fichiers ; une session du tableau de bord sans clé peut lire l’ensemble de l’instance ; un fichier sans propriétaire (téléversement anonyme ou depuis une session du tableau de bord) est inaccessible à tout appelant hors session. `GET /v1/files` rejette un appelant anonyme — ainsi qu’une clé fournie qui ne peut pas être résolue — avec `401`, même lorsque `REQUIRE_API_KEY=false`, au lieu de répertorier les fichiers de tous les locataires (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523). --- ## API Batches Traitement par lots compatible avec OpenAI. | Méthode | Chemin | Description | | ------- | ------------------------- | -------------------------------------------------------------------------------------------------------- | | POST | `/v1/batches` | Créer un lot — corps validé par `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) | | GET | `/v1/batches` | Répertorier les lots | | GET | `/v1/batches/[id]` | Récupérer l’état du lot et `request_counts` | | DELETE | `/v1/batches/[id]` | Supprimer un lot terminé ou ayant échoué | | POST | `/v1/batches/[id]/cancel` | Annuler un lot en cours | **Authentification :** clé API Bearer. Les lots sont isolés par clé API selon la même règle à trois niveaux que les fichiers : accès limité à la clé propriétaire, accès à l’ensemble de l’instance pour une session du tableau de bord, enregistrements sans propriétaire inaccessibles à tout appelant hors session (récupération, suppression, annulation et vérification de `input_file_id` lors de la création). `GET /v1/batches` rejette un appelant anonyme avec `401`, même lorsque `REQUIRE_API_KEY=false`. --- ## API de recherche Abstraction des fournisseurs de recherche Web (Tavily, Brave, Exa, Serper, etc.). | Méthode | Chemin | Description | | ------- | ---------------------- | -------------------------------------------------------------------------------------------------------- | | GET | `/v1/search` | Répertorie les fournisseurs de recherche configurés et leurs capacités | | POST | `/v1/search` | Exécute une requête de recherche — corps validé par `v1SearchSchema`, prend en charge le cache/la fusion | | GET | `/v1/search/analytics` | Statistiques par fournisseur sur les résultats/latences/caches | **Authentification :** clé d’API Bearer (`extractApiKey` + `isValidApiKey`). La politique de recherche est appliquée via `enforceApiKeyPolicy`. --- ## API de récupération Web Extrait le contenu d’une URL via un fournisseur de récupération Web configuré (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract). | Méthode | Chemin | Description | | ------- | --------------- | -------------------------------------------------------------- | | POST | `/v1/web/fetch` | Récupère/extrait une URL — corps validé par `v1WebFetchSchema` | **Authentification :** clé d’API Bearer (`extractApiKey` + `isValidApiKey`). La politique est appliquée via `enforceApiKeyPolicy`. **Repli tenant compte des quotas (#8297) :** lorsqu’aucun `provider` explicite n’est indiqué, le pool (`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) est parcouru selon un ordre de priorité fixe (remplissage prioritaire) — un fournisseur configuré mais soumis à une limitation de débit est ignoré au lieu d’interrompre immédiatement la requête, et un échec amont réessayable ou lié au quota (HTTP 429 dans tous les cas ; 402/403 pour les offres gratuites de type quota de Firecrawl/Tavily/TinyFish — pas pour Jina Reader, et jamais pour une simple requête incorrecte 400) provoque le passage au fournisseur suivant, non encore essayé et disposant d’identifiants, au moment de la requête. Lorsque tous les fournisseurs du pool sont épuisés, le point de terminaison renvoie un unique `429` (avec un en-tête `Retry-After`) au lieu de l’ancien `400` générique. Lorsqu’un `provider` explicite est demandé, il n’y a **aucun** repli silencieux — un fournisseur explicite soumis à une limitation de débit ou en échec expose sa propre erreur (`429` en cas de limitation de débit, sinon le statut amont). --- ## Diffusion WebSocket ```bash GET /v1/ws?handshake=1 ``` Valide une négociation de mise à niveau WebSocket et renvoie les exemples de messages du protocole filaire (`request`, `cancel`). Les trames WS réelles sont gérées par le serveur WS inclus, en dehors de la table de routage Next.js. **Authentification :** clé d’API Bearer pendant la négociation. ### API Responses via WebSocket (codex uniquement) ```bash # Même hôte:port que l’API HTTP (20128 par défaut) ; mettez à niveau la connexion : wscat -c "ws://localhost:20128/v1/responses?api_key=" # (ou : -H "Authorization: Bearer ") # La première trame DOIT être response.create : { "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] } ``` Un proxy de l’API Responses via WebSocket est relié **exclusivement à `codex`** (backend ChatGPT). Il écoute sur le même port que l’API/le tableau de bord aux chemins `/v1/responses`, `/responses` et `/api/v1/responses`. À la première trame `response.create`, il authentifie et prépare la requête via le pont interne `codex-responses-ws`, sélectionne une connexion OAuth codex et établit un tunnel vers `wss://chatgpt.com/backend-api/codex/responses` via le transport `wreq-js`. **Les modèles non-codex sont rejetés** (`codex_ws_provider_required`). Pour le routage par partage de quota, utilisez `model: "qtSd//codex/"`. Implémenté dans `app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`. **Authentification :** clé d’API Bearer pendant la négociation. Le serveur HTTP inclus (`server-ws.mjs`) doit être le point d’entrée actif (c’est le cas par défaut lorsque `app/server-ws.mjs` existe). #### Identifiant du modèle : utilisez l’identifiant ChatGPT brut (sans préfixe `codex/`) L’interface en ligne de commande **Codex d’OpenAI** valide le nom du modèle côté client lorsque `supports_websockets = true` et **rejette les identifiants préfixés par un fournisseur** tels que `codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account`). Envoyez l’identifiant **brut** (par ex. `gpt-5.5`). Le pont d’OmniRoute est réservé à codex ; il résout donc à nouveau un identifiant brut comme modèle codex (`resolveCodexWsModelInfo`) avant d’établir le tunnel vers le service amont — même si un identifiant brut `gpt-5.5` serait autrement acheminé vers un autre fournisseur via HTTP. #### Configuration de l’interface en ligne de commande Codex d’OpenAI Orientez l’interface en ligne de commande Codex vers OmniRoute en ajoutant un fournisseur personnalisé prenant en charge WebSocket dans `~/.codex/config.toml` (utilisez un `CODEX_HOME` distinct afin de ne pas modifier une configuration existante) : ```toml model = "gpt-5.5" # identifiant brut — PAS "codex/gpt-5.5" model_provider = "omniroute" [model_providers.omniroute] name = "OmniRoute (WS)" base_url = "http://localhost:20128/v1" # sans barre oblique finale ; l’URL WS est dérivée (utilisez https/wss en production) wire_api = "responses" # seule valeur prise en charge depuis févr. 2026 supports_websockets = true # active le transport Responses via WS env_key = "OMNIROUTE_API_KEY" # contient la clé d’API OmniRoute (Bearer) ``` ```bash export OMNIROUTE_API_KEY=sk-... # une clé d’API OmniRoute (n’importe quelle clé si REQUIRE_API_KEY=false) codex exec "Responda apenas: PONG" ``` L’interface en ligne de commande met à niveau `base_url + /responses` vers une connexion WebSocket, et OmniRoute établit un tunnel vers la connexion OAuth codex sélectionnée. Validation de bout en bout effectuée avec le serveur local : ChatGPT renvoie `codex.rate_limits` + `response.created` et diffuse progressivement la réponse. --- ## Quotas et signalement des problèmes | Méthode | Chemin | Description | | ------- | ------------------- | ---------------------------------------------------------------------------------------------------- | | GET | `/v1/quotas/check` | Prévalider le quota pour un `provider` + `accountId` avant d’émettre une clé enregistrée | | POST | `/v1/issues/report` | Signaler à GitHub un échec de quota ou d’émission de clé (nécessite `GITHUB_ISSUES_REPO` + un jeton) | **Authentification :** clé API Bearer (`isAuthenticated`). --- ## Utilisation en libre-service (`/api/usage/om-usage`) Toute clé API peut consulter **sa propre** utilisation et ses propres quotas — sans authentification de gestion. Il s’agit du point de terminaison qu’un client (CLI, panneau OmniCopilot) utilise pour afficher les dépenses du détenteur d’une clé. ```bash # Format texte (le contrat historique — texte brut destiné à un terminal) curl -H "Authorization: Bearer " \ http://localhost:20128/api/usage/om-usage # Format structuré — celui qu’utilise une interface utilisateur curl -H "Authorization: Bearer " \ "http://localhost:20128/api/usage/om-usage?format=json" ``` La clé doit avoir **`allowUsageCommand`** activé (désactivé par défaut — le gestionnaire de clés API du tableau de bord permet de le basculer pour chaque clé). Sans cette option, le point de terminaison répond `403`. `?format=json` renvoie une structure discriminée afin qu’un appelant ne lise jamais un champ de données dans une réponse de refus. En cas de succès : ```jsonc { "allowed": true, // présent uniquement lorsque des limites d’utilisation par clé ont été activées (USD quotidiens/hebdomadaires) : "personal": { "dailySpentUsd": 1.25, "dailyLimitUsd": 5, "dailyResetAtIso": "…", "weeklySpentUsd": 8, "weeklyLimitUsd": 20, "weeklyResetAtIso": "…" /* … */, }, // l’instantané des quotas du fournisseur sélectionné, ou null lorsqu’aucune donnée n’est encore en cache : "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */}, }, // l’instantané de chaque connexion, afin qu’une interface puisse afficher plusieurs fournisseurs côte à côte : "providers": [ { "connectionId": "…", "provider": "claude" /* … */ }, { "provider": "codex" /* … */ }, ], } ``` En cas de refus (clé incorrecte avec `401` / accès non autorisé avec `403`), la même route renvoie `{ "allowed": false, "error": { "message": "…" } }` — la présence d’un champ `personal`/`provider` vide (clé autorisée, mais aucune donnée encore obtenue) constitue un état distinct d’un refus, et seul le format JSON permet de les différencier. **Authentification :** la propre clé API Bearer de l’appelant, validée avec `isValidApiKey` — il ne s’agit _pas_ de l’interface de gestion (`/api/keys/…`), qui reste protégée par `requireManagementAuth`. ### Pourcentages de quotas bruts et ajustés selon le seuil de coupure Lors de l’utilisation de `/api/usage/om-usage`, les appelants doivent noter la différence entre les pourcentages présentés par la **sortie en texte brut** et ceux de la **sortie JSON** structurée : | Aspect | Format texte brut (`/api/usage/om-usage` / `@@om-usage`) | Format JSON (`?format=json`) | | :--------------------------------------- | :------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------- | | **Champ de sortie** | `NN% left` (par ex., `20% left`) | `provider.quotas` / `providers[].quotas` | | **Mesure** | **Disponibilité utilisable ajustée selon le seuil** : capacité restante au-dessus du seuil de coupure | **Quota brut en amont** : mesure non ajustée du fournisseur | | **Mise à l’échelle du seuil de coupure** | Mise à l’échelle via `effectiveRemainingPercent()` afin que la réserve protégée soit affichée comme `0% left` | Aucune (valeurs brutes de l’instantané telles que rapportées par le fournisseur) | | **Données de seuil** | Intégrées au pourcentage affiché | Stockées dans `quotaWindowThresholds` pour chaque connexion (ou valeurs par défaut du serveur) | | **Utilisateur principal** | CLI interactives, invites de terminal, opérateurs humains | Intégrations programmatiques, tableaux de bord, analyses, outils de suivi de la facturation | #### Formule d’ajustement selon le seuil de coupure OmniRoute prend en charge des seuils de coupure de quota proactifs afin d’éviter l’épuisement des ressources en amont (configurés via les `quotaWindowThresholds` de la connexion, les valeurs par défaut du fournisseur ou les paramètres globaux de résilience). Lorsqu’un seuil de coupure (par ex., `cutoff = 25%`) est actif sur une fenêtre de quota, le moteur de rendu du texte calcule la disponibilité restante comme suit : - Si `remaining <= cutoff` : renvoie `0%`. - Si `remaining > cutoff` : renvoie `((remaining - cutoff) / (100 - cutoff)) * 100`. La sortie texte mise en forme arrondit ce résultat à l’entier le plus proche (`Math.round(...)`). #### Exemple illustratif Prenons une fenêtre de fournisseur avec une **utilisation brute de 60 %** (et donc **40 % de quota brut restant**) et un seuil configuré de **coupure à 25 % du quota restant** : | Représentation | Calcul | Restant | Utilisation implicite | | :----------------------------- | :------------------------------------------------- | :------: | :---------------------------------------: | | **JSON brut (`?format=json`)** | Instantané en amont (`quotas[window]`) | **40 %** | **60 %** | | **Format texte (`NN% left`)** | `((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100` | **20 %** | **80 %** (en calculant `100 - remaining`) | - **Pourquoi le texte affiche 20 % restant :** Sur les 40 % de quota physique restant sur le compte, 25 % sont réservés par la politique de coupure. L’appelant ne dispose plus que de 15 % sur les 75 % de marge utilisable avant que le routeur cesse d’acheminer les requêtes vers cette connexion. La mise à l’échelle garantit que la connexion signale son épuisement (`0% left`) exactement au moment où l’acheminement cessera. - **Pourquoi le JSON conserve les valeurs brutes :** La charge utile JSON renvoie l’instantané exact du fournisseur (`UsageSnapshot`) afin que les outils externes puissent accéder à l’utilisation réelle en amont ainsi qu’aux `quotaWindowThresholds` propres à la connexion, sans mise à l’échelle avec perte côté serveur. #### Recommandations pour la migration des consommateurs Si une intégration externe (telle qu’un plugin d’éditeur ou une extension d’agent) analysait auparavant le point de terminaison texte (`NN% left`) et calculait le pourcentage utilisé comme `100 - NN`, la migration vers `?format=json` implique que : - La lecture des valeurs JSON brutes reflétera la **consommation réelle en amont** (60 % utilisés dans l’exemple ci-dessus). - Si l’intégration souhaite conserver la sémantique de disponibilité utilisable du point de terminaison texte, elle peut évaluer côté client la formule de disponibilité effective à l’aide de `quotaWindowThresholds` pour les remplacements propres à la connexion. --- ## Cache sémantique ```bash # Obtenir les statistiques du cache GET /api/cache/stats # Vider tous les caches DELETE /api/cache/stats ``` Exemple de réponse : ```json { "semanticCache": { "memorySize": 42, "memoryMaxSize": 500, "dbSize": 128, "hitRate": 0.65 }, "idempotency": { "activeKeys": 3, "windowMs": 5000 } } ``` ### Impact sur la latence Une correspondance dans le cache sémantique sert la réponse depuis le cache **sans appel en amont** ; la valeur `X-OmniRoute-Response-Latency` indiquée est donc proche de zéro (indépendamment de la latence initiale du service en amont). Les clients sensibles à la latence (évaluation des performances, surveillance p50/p99) doivent vérifier l’en-tête de réponse `X-OmniRoute-Cache-Latency` : | Valeur | Signification | | ----------- | ------------------------------------------------------------------------------------ | | `synthetic` | Réponse servie depuis le cache ; la latence ne correspond pas au temps réel en amont | | _(absent)_ | Réponse issue d’un véritable appel en amont | ### Contournement du cache par clé Les clés API peuvent désactiver la lecture du cache sémantique via `cacheDefaultMode` : | Valeur | Comportement | | -------- | ------------------------------------------------------------------------------------ | | `legacy` | Comportement normal du cache (par défaut) | | `bypass` | Ignore entièrement la recherche dans le cache ; appelle toujours le service en amont | À définir lors de la création de la clé (`POST /api/keys`) ou de sa mise à jour (`PATCH /api/keys/[id]`) : ```json { "cacheDefaultMode": "bypass" } ``` ### Contournement par requête Toute requête peut contourner le cache, quels que soient les paramètres de la clé : ``` X-OmniRoute-No-Cache: true ``` --- ## Tableau de bord et gestion Les routes de gestion (`/api/*` à l’exception de l’authentification/connexion publique) ne sont **pas** autorisées par les clés API d’inférence ordinaires. Pour les familles d’identifiants, les portées et les exemples curl : [Authentification de gestion](../guides/MANAGEMENT-AUTH.md). ### Authentification | Point de terminaison | Méthode | Description | | ----------------------------- | ------- | ------------------------------------------- | | `/api/auth/login` | POST | Connexion | | `/api/auth/logout` | POST | Déconnexion | | `/api/settings/require-login` | GET/PUT | Activer/désactiver la connexion obligatoire | ### Gestion des fournisseurs | Point de terminaison | Méthode | Description | | --------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/providers` | GET/POST | Répertorier / créer des fournisseurs | | `/api/providers/[id]` | GET/PUT/DELETE | Gérer un fournisseur | | `/api/providers/[id]/test` | POST | Tester la connexion au fournisseur | | `/api/providers/[id]/models` | GET | Répertorier les modèles du fournisseur | | `/api/providers/validate` | POST | Valider la configuration du fournisseur | | `/api/providers/bulk` | POST | Ajouter en masse des clés API pour UN seul fournisseur | | `/api/providers/import` | POST | Importer une LISTE hétérogène de fournisseurs depuis un fichier CSV/JSON analysé (#6836) ; résultats avec échecs partiels pour chaque ligne | | `/api/provider-nodes*` | Diverses | Gestion des nœuds de fournisseur | | `/api/provider-models` | GET/POST/PUT/PATCH/DELETE | Modèles personnalisés et remplacements propres à chaque modèle (ajout, mise à jour, masquage/affichage, suppression) | | `/api/provider-models/validate-and-add` | POST | Validation stricte et facultative de la connexion, authentifiée pour la gestion, et enregistrement atomique du modèle personnalisé ; voir [Validation des modèles](../guides/MODEL-VALIDATION.md) | Pour les modèles synchronisés/importés, `PUT /api/provider-models` accepte `provider`, `modelId` et `maxOutputTokenOverride` : un entier positif définit la limite manuelle de jetons de sortie, tandis que `null` la supprime afin de rétablir la valeur par défaut. `GET /api/provider-models?provider=` renvoie ces valeurs dans `modelOutputOverrides`, y compris pour les modèles ne disposant pas d’une ligne de modèle personnalisé. Le remplacement utilise la capacité d’exécution `max_output_tokens` et persiste après une nouvelle synchronisation du modèle. La page du fournisseur compatible avec OpenAI propose les mêmes contrôles de modification/suppression et signale les modèles prenant explicitement en charge la vision. Les nœuds Chat Completions personnalisés adaptent les désactivations explicites du raisonnement au backend en amont. Un test de connexion réussi sélectionne automatiquement les contrôles du modèle de chat pour chaque ID de modèle exact dont l’entrée `/models` confirme une valeur `owned_by` reconnue : `vllm`, `sglang` ou `llamacpp`. Les wrappers transparents compatibles avec OpenAI peuvent conserver l’entrée de modèle d’origine dans un objet `openai` imbriqué ; la détection suit jusqu’à trois enveloppes de ce type. Les modèles dont la propriété est absente, inconnue ou conflictuelle conservent le comportement OpenAI ordinaire. La détection réutilise la requête de catalogue existante, ne génère aucun jeton de complétion et est invalidée lorsque le point de terminaison de connexion change. Pour imposer ce comportement à un backend qui n’expose pas ces métadonnées, utilisez l’API existante de mise à jour partielle du fournisseur : ```json { "providerSpecificData": { "reasoningControl": "chat-template" } } ``` Envoyez ce corps avec `PUT /api/providers/`. Sur cette connexion, un effort de raisonnement explicitement défini sur `none` est envoyé sous la forme `chat_template_kwargs.thinking=false` et `chat_template_kwargs.enable_thinking=false`. Les valeurs natives explicites du modèle restent prioritaires, sauf si une règle de raisonnement côté serveur impose un effort. Le paramètre s’applique uniquement lorsqu’une connexion personnalisée compatible avec OpenAI transmet un corps Chat Completions ; les requêtes Responses et les fournisseurs ordinaires conservent la structure native de leur requête. Définissez `reasoningControl` sur `openai` pour imposer la transmission directe ordinaire de `reasoning_effort` d’OpenAI, ou omettez-le/définissez-le sur `null` pour utiliser la détection automatique. Les requêtes du classificateur en mode automatique de Claude Code désactivent par défaut la réflexion native lorsqu’elles ne contiennent aucun contrôle explicite du raisonnement. La détection utilise le marqueur système du classificateur dans les requêtes au format Claude, et non les noms de modèles ou les limites de complétion. Les contrôles explicites dans le corps, les en-têtes d’effort/de réflexion pris en charge, les règles de routage et l’effort du modèle résolu conservent leur priorité existante. Les deux étapes du classificateur conservent leurs invites, leurs limites de complétion, leurs séquences d’arrêt et les véritables verdicts d’autorisation du service en amont ; la deuxième étape peut toujours produire le raisonnement visible demandé sous forme de texte ordinaire. ### Flux OAuth | Point de terminaison | Méthode | Description | | -------------------------------- | ------- | --------------------------- | | `/api/oauth/[provider]/[action]` | Divers | OAuth propre au fournisseur | ### Routage et configuration | Point de terminaison | Méthode | Description | | --------------------- | -------- | ---------------------------------------- | | `/api/models/alias` | GET/POST | Alias de modèles | | `/api/models/catalog` | GET | Tous les modèles par fournisseur et type | | `/api/combos*` | Divers | Gestion des combinaisons | | `/api/keys*` | Divers | Gestion des clés API | | `/api/pricing` | GET | Tarification des modèles | ### Utilisation et analyses | Point de terminaison | Méthode | Description | | -------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/usage/history` | GET | Historique d’utilisation | | `/api/usage/logs` | GET | Journaux d’utilisation | | `/api/usage/request-logs` | GET | Journaux au niveau des requêtes | | `/api/usage/[connectionId]` | GET | Utilisation par connexion | | `/api/usage/token-limits` | GET/POST/DELETE | Budgets de limite de jetons par clé API | | `/api/usage/model-latency-stats` | GET | Agrégat glissant de la latence par fournisseur/modèle (moyenne/p50/p95/p99, taux de réussite) ; filtres : `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) | | `/api/usage/cache-health` | GET | Résumé de l’état du cache des invites sur `call_logs` — rapport écritures/lectures, distribution p50/p90/p99 de la taille des écritures, concentration des écritures volumineuses, répartition par modèle et verdict `healthy`/`degraded`/`thrash`/`no-data` ; paramètres de requête `range` (`1h`\|`24h`\|`7d`\|`30d`, valeur par défaut : `24h`) et `model` facultatif (#8827) | ### Autorisations des clés API `PATCH /api/keys/{id}` met à jour les autorisations d’une clé existante. Comme toutes les routes `/api/keys*`, cette opération nécessite une autorisation de gestion (voir [Authentification de gestion](../guides/MANAGEMENT-AUTH.md)), et non une clé d’inférence. Envoyez uniquement les champs que vous souhaitez modifier ; une requête n’en contenant aucun est rejetée avec le message `No valid fields to update`. Les champs acceptés sont définis par `updateKeyPermissionsSchema` dans `src/shared/validation/schemas/keys.ts`. | Champ | Type | Remarques | | ------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | chaîne, 1 à 200 caractères | | | `isActive` | booléen | | | `isBanned` | booléen | | | `expiresAt` | date et heure ISO 8601 ou `null` | `null` supprime la date d’expiration | | `modelAccessMode` | `all` \| `restricted` | `allowedModels` doit être vide lorsque le mode est `all` | | `allowedModels`, `blockedModels` | tableau de chaînes, jusqu’à 1 000 | | | `allowedCombos` | tableau de chaînes, jusqu’à 500 | Détermine les combos que la clé peut appeler ; les modèles directs sont régis par `modelAccessMode` / `allowedModels` | | `connectionAccessMode` | `all` \| `restricted` | `allowedConnections` doit être non vide avec `restricted` et vide avec `all` | | `allowedConnections` | tableau d’UUID, jusqu’à 100 | | | `allowAutoCombos` | booléen | `false` rejette les requêtes de modèles `auto/*` avec cette clé ; les clés pour lesquelles cette option n’a jamais été définie sont autorisées | | `catalogScope` | `all` \| `combos` \| `models` | Ce que `GET /v1/models` répertorie pour cette clé (uniquement les combos, uniquement les modèles, ou les deux) ; cela ne modifie pas ce que la clé peut appeler | | `noLog`, `autoResolve` | booléen | | | `throttleDelayMs` | entier, 0 à 300000 | | | `maxSessions` | entier, 0 à 10000 | | | `rateLimits` | tableau de `{ limit, window }` (entiers positifs, jusqu’à 50) ou `null` | `null` supprime les limites | | `accessSchedule` | objet de planification ou `null` | `null` supprime la planification | | `scopes` | tableau de chaînes, jusqu’à 32 | | | `allowedEndpoints` | tableau de chaînes, jusqu’à 20 | | | `streamDefaultMode` | `legacy` \| `json` | | | `cacheDefaultMode` | `legacy` \| `bypass` | Voir [Contournement du cache par clé](#per-key-cache-bypass) | | `compressionEnabled` | booléen | | | `codexServiceMode` | l’un des modes de service Codex | | | `disableNonPublicModels` | booléen | | | `allowUsageCommand` | boolean | | | `usageLimitEnabled` | boolean | | | `dailyUsageLimitUsd`, `weeklyUsageLimitUsd` | number >= 0 ou `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" }' ``` ### Paramètres | Point de terminaison | Méthode | Description | | ------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/settings` | GET/PUT/PATCH | Paramètres généraux | | `/api/settings/proxy` | GET/PUT | Configuration du proxy réseau | | `/api/settings/proxy/test` | POST | Tester la connexion au proxy | | `/api/settings/ip-filter` | GET/PUT | Liste d’autorisation/de blocage des adresses IP | | `/api/settings/thinking-budget` | GET/PUT | Mode de réécriture des **requêtes** de réflexion/raisonnement (transmission directe / suppression automatique / personnalisé / adaptatif). Indépendant de la compression. Voir [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). | | `/api/settings/system-prompt` | GET/PUT | Invite système globale | | `/api/settings/compression` | GET/PUT | Configuration globale de la compression | | `/api/settings/purge-request-history` | POST | Effacer les lignes du journal des requêtes et les artefacts locaux du journal des appels | ### Contexte et compression | Point de terminaison | Méthode | Description | | -------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------- | | `/api/compression/preview` | POST | Prévisualiser la compression désactivée/légère/standard/agressive/ultra/RTK/empilée | | `/api/compression/language-packs` | GET | Répertorier les packs linguistiques Caveman disponibles | | `/api/compression/rules` | GET | Répertorier les métadonnées des règles Caveman | | `/api/context/caveman/config` | GET/PUT | Alias des paramètres propres à Caveman | | `/api/context/rtk/config` | GET/PUT | Paramètres propres à RTK, y compris les filtres personnalisés et la conservation de la sortie brute | | `/api/context/rtk/filters` | GET | Catalogue des filtres RTK et diagnostics des filtres personnalisés | | `/api/context/rtk/test` | POST | Exécuter une prévisualisation/un test RTK sur une charge utile textuelle | | `/api/context/rtk/raw-output/[id]` | GET | Lire la sortie brute expurgée conservée à partir de l’identifiant du pointeur | | `/api/context/combos` | GET/POST | Répertorier/créer des combinaisons de compression | | `/api/context/combos/[id]` | GET/PUT/DELETE | Détails/mise à jour/suppression d’une combinaison de compression | | `/api/context/combos/[id]/assignments` | GET/PUT | Affecter des combinaisons de compression aux combinaisons de routage | | `/api/context/analytics` | GET | Alias des analyses de compression | ### Surveillance | Point de terminaison | Méthode | Description | | ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/api/sessions` | GET | Suivi des sessions actives | | `/api/rate-limits` | GET | Limites de débit par compte | | `/api/monitoring/health` | GET | Contrôle d’intégrité et résumé des fournisseurs (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). La vue de gestion inclut `credentialHealth` : valeurs scalaires du cache des sondes, `failedConnections` lorsque `failed>0` et `staleDbNonOkCount` (`test_status` persistant de SQLite, et non la jauge). Voir [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). | | `/api/cache/stats` | GET/DELETE | Statistiques du cache / vidage | | `/api/modality-bridge/stats` | GET | Valeurs en mémoire pour `attempts`, réussites/`bridged`, échecs, accès au cache, `totalLatencyMs`, `latencySamples`, `averageLatencyMs` calculée selon le nombre d’échantillons et heure de dernière utilisation (réinitialisées au redémarrage ; authentification de gestion) | | `/api/modality-bridge/video/runtime` | GET | Vérification stricte de la boucle locale approuvée avant l’authentification de gestion/la sonde ; disponibilité et versions assainies de FFmpeg/ffprobe (sans stockage) | | `/api/modality-bridge/video/extract` | POST | Courtier d’octets interne authentifié via une boucle locale approuvée ; entrée de 50 Mio, file d’attente limitée/sortie de 32 Mio, capacité `503`, déconnexion `499`, délai dépassé `504` ; il ne s’agit pas d’une API publique de téléversement | ### Sauvegarde et exportation/importation | Point de terminaison | Méthode | Description | | --------------------------- | ------- | -------------------------------------------------------------------------------------- | | `/api/db-backups` | GET | Répertorier les sauvegardes disponibles | | `/api/db-backups` | PUT | Créer une sauvegarde manuelle | | `/api/db-backups` | POST | Restaurer à partir d’une sauvegarde spécifique | | `/api/db-backups/export` | GET | Télécharger la base de données sous forme de fichier .sqlite | | `/api/db-backups/import` | POST | Téléverser un fichier .sqlite pour remplacer la base (`?dryRun=true` valide seulement) | | `/api/db-backups/exportAll` | GET | Télécharger une sauvegarde complète sous forme d’archive .tar.gz | `/api/db-backups/export`, `/api/db-backups/exportAll` et `/api/settings/export-json` fournissent tous les identifiants stockés ; ils nécessitent donc la session du tableau de bord ou la CLI locale (ou que la connexion soit désactivée). Les clés d’API, quelle que soit leur portée, et les jetons d’accès `oma_` reçoivent une réponse `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. ### Synchronisation avec le cloud | Point de terminaison | Méthode | Description | | ---------------------- | ------- | ----------------------------------- | | `/api/sync/cloud` | Divers | Opérations de synchronisation cloud | | `/api/sync/initialize` | POST | Initialiser la synchronisation | | `/api/cloud/*` | Divers | Gestion du cloud | ### Tunnels | Endpoint | Méthode | Description | | -------------------------- | ------- | ------------------------------------------------------------------------------------------ | | `/api/tunnels/cloudflared` | GET | Lire l’état d’installation/d’exécution du tunnel rapide Cloudflare pour le tableau de bord | | `/api/tunnels/cloudflared` | POST | Activer ou désactiver le tunnel rapide Cloudflare (`action=enable/disable`) | | `/api/tunnels/ngrok` | GET | Lire l’état d’exécution du tunnel ngrok pour le tableau de bord | | `/api/tunnels/ngrok` | POST | Activer ou désactiver le tunnel ngrok (`action=enable/disable`) | ### Outils CLI | Endpoint | Méthode | Description | | ---------------------------------- | ------- | --------------------------- | | `/api/cli-tools/claude-settings` | GET | État de la CLI Claude | | `/api/cli-tools/codex-settings` | GET | État de la CLI Codex | | `/api/cli-tools/droid-settings` | GET | État de la CLI Droid | | `/api/cli-tools/openclaw-settings` | GET | État de la CLI OpenClaw | | `/api/cli-tools/runtime/[toolId]` | GET | Environnement CLI générique | Les réponses de la CLI incluent : `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. ### Agents ACP | Endpoint | Méthode | Description | | ----------------- | ------- | ------------------------------------------------------------------------------ | | `/api/acp/agents` | GET | Répertorier tous les agents détectés (intégrés + personnalisés) avec leur état | | `/api/acp/agents` | POST | Ajouter un agent personnalisé ou actualiser le cache de détection | | `/api/acp/agents` | DELETE | Supprimer un agent personnalisé via le paramètre de requête `id` | La réponse GET inclut `agents[]` (id, name, binary, version, installed, protocol, isCustom) et `summary` (total, installed, notFound, builtIn, custom). ### Résilience et limites de débit | Endpoint | Méthode | Description | | --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/api/resilience` | GET/PATCH | Obtenir/mettre à jour la file d’attente des requêtes, le délai de récupération des connexions, le coupe-circuit des fournisseurs et les paramètres d’attente | | `/api/resilience/reset` | POST | Réinitialiser les coupe-circuits des fournisseurs | | `/api/resilience/model-cooldowns` | GET | Répertorier les verrouillages actifs par (fournisseur, connexion, modèle), triés par temps restant | | `/api/resilience/model-cooldowns` | DELETE | Effacer un verrouillage de modèle — corps `{provider, model}` ou `{all: true}` pour tout supprimer | | `/api/rate-limits` | GET | État de la limite de débit par compte | | `/api/rate-limit` | GET | Configuration globale des limites de débit | > Les quatre routes `/api/resilience/*` nécessitent une **authentification de gestion** (`requireManagementAuth`). Consultez [Résilience (détaillée)](#resilience-extended) pour une présentation complète du coupe-circuit des fournisseurs, du délai de récupération des connexions et du verrouillage des modèles. ### Évaluations | Endpoint | Méthode | Description | | ------------ | -------- | ------------------------------------------------------------- | | `/api/evals` | GET/POST | Répertorier les suites d’évaluation / exécuter une évaluation | ### Politiques | Endpoint | Méthode | Description | | --------------- | --------------- | ------------------------------- | | `/api/policies` | GET/POST/DELETE | Gérer les politiques de routage | ### Conformité | Endpoint | Méthode | Description | | --------------------------- | ------- | ------------------------------------------ | | `/api/compliance/audit-log` | GET | Journal d’audit de conformité (N derniers) | ### v1beta (compatible avec Gemini) | Endpoint | Méthode | Description | | -------------------------- | ------- | ---------------------------------------- | | `/v1beta/models` | GET | Répertorier les modèles au format Gemini | | `/v1beta/models/{...path}` | POST | Endpoint Gemini `generateContent` | Ces endpoints reproduisent le format de l’API Gemini pour les clients nécessitant une compatibilité native avec le SDK Gemini. ### API internes / système | Endpoint | Méthode | Description | | ------------------------ | ------- | --------------------------------------------------------------------------------- | | `/api/init` | GET | Vérification de l’initialisation de l’application (utilisée au premier démarrage) | | `/api/tags` | GET | Étiquettes de modèles compatibles avec Ollama (pour les clients Ollama) | | `/api/restart` | POST | Déclencher un redémarrage contrôlé du serveur | | `/api/shutdown` | POST | Déclencher un arrêt contrôlé du serveur | | `/api/system/env/repair` | POST | Réparer les variables d’environnement du fournisseur OAuth | | `/api/system/version` | GET | Version actuelle/récente, état de la mise à jour, canal de publication | | `/api/system/version` | POST | Démarrer une mise à jour tenant compte du déploiement vers la dernière version | > **Remarque :** Ces endpoints sont utilisés en interne par le système ou pour assurer la compatibilité avec les clients Ollama. Ils ne sont généralement pas appelés par les utilisateurs finaux. ### Réparation de l’environnement OAuth _(v3.6.1+)_ ```bash POST /api/system/env/repair Content-Type: application/json { "provider": "claude-code" } ``` Répare les variables d’environnement OAuth manquantes ou corrompues pour un fournisseur spécifique. Renvoie : ```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" } ``` ### Version et canal de publication ```bash GET /api/system/version ``` Route de gestion accessible uniquement via l’interface de bouclage (authentification administrateur). Renvoie la version en cours d’exécution, la dernière version publiée et l’état de la mise à jour automatique. `releaseChannel` et `channels` sont des champs supplémentaires (rail 3.8.54) ; `channel` conserve sa signification — le mode de déploiement utilisé par le programme de mise à jour du tableau de bord (`npm`, `source` ou `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` — canal npm du build en cours d’exécution : `nightly` pour les versions `-nightly.*`, `next` pour les autres préversions (`-rc.*`, `-beta.*`, `-alpha.*`), `lts` pour une version stable d’une version majeure antérieure à `channels.latest`, sinon `latest`. Mêmes règles que `scripts/release/dist-tag.mjs`, qui sélectionne le dist-tag npm au moment de la publication. - `channels` — version de tête publiée de chaque dist-tag, obtenue via `npm view omniroute dist-tags` (avec repli HTTP vers le registre), mise en cache avec la même durée de vie de 10 minutes que `latest`. `latest` est toujours présent (repli sur le champ `latest`, puis sur `"unavailable"`) ; `next`, `nightly` et `lts` n’apparaissent que lorsque le dist-tag correspondant existe. Une requête `Cache-Control: no-cache` actualise les deux consultations. Le modèle de canaux (`latest` = v3 jusqu’à la disponibilité générale de la version 4.0, `next` = rc, `nightly` = builds de `develop`, `lts` = correctifs v3 après la disponibilité générale de la version 4.0) est décrit dans `docs/ops/RELEASE_STRATEGY.md`. --- ## Transcription audio ```bash POST /v1/audio/transcriptions Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` Transcrivez des fichiers audio à l’aide de n’importe quel fournisseur STT configuré. Le premier segment du chemin sélectionne le fournisseur natif (`openai/…`, `deepgram/…`). Les passerelles qui réexportent le modèle d’un autre fournisseur utilisent un identifiant qualifié (`openrouter/deepgram/nova-3`). **Requête :** ```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" ``` **Réponse :** ```json { "text": "Bonjour, ceci est le contenu audio transcrit.", "task": "transcribe", "language": "en", "duration": 12.5 } ``` **Exemples d’identifiants de modèles :** `openai/whisper-1` (nécessite une clé OpenAI), `openrouter/deepgram/nova-3` (nécessite une clé OpenRouter), `deepgram/nova-3` (nécessite une clé Deepgram native). Une requête simple `deepgram/nova-3` n’utilise **pas** OpenRouter. **Formats pris en charge :** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- ## Compatibilité avec Ollama Pour les clients qui utilisent le format d’API d’Ollama : ```bash # Point de terminaison de chat (format Ollama) POST /v1/api/chat # Liste des modèles (format Ollama) GET /api/tags ``` Les requêtes sont automatiquement traduites entre les formats Ollama et internes. ## Alias avec jeton pour VS Code / sans en-tête Utilisez ces alias lorsqu’une intégration ne peut pas injecter d’en-tête `Authorization` et nécessite que la clé API soit intégrée dans l’URL de base. ```bash # Alias du catalogue au format OpenAI GET /api/v1/vscode/{token}/ GET /api/v1/vscode/{token}/models # Alias de chat au format OpenAI POST /api/v1/vscode/{token}/chat/completions POST /api/v1/vscode/{token}/responses # Alias au format Ollama POST /api/v1/vscode/{token}/api/chat GET /api/v1/vscode/{token}/api/tags ``` Exemple : ```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":"bonjour"}]}' ``` Remarques : - Les alias avec jeton réutilisent les mêmes gestionnaires que `/v1/*` et `/api/tags` ; les formats de réponse restent identiques. - Privilégiez `Authorization: Bearer ...` lorsque le client prend en charge les en-têtes personnalisés. - Les jetons intégrés aux URL peuvent apparaître dans les journaux des proxys inverses, l’historique des navigateurs et la télémétrie en dehors d’OmniRoute. Considérez-les comme une option de compatibilité, et non comme le mode d’authentification par défaut. --- ## Télémétrie ```bash # Obtenir le résumé de la télémétrie de latence (p50/p95/p99 par fournisseur) GET /api/telemetry/summary ``` **Réponse :** ```json { "providers": { "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } } } ``` --- ## Budget ```bash # Obtenir l’état du budget pour toutes les clés API GET /api/usage/budget # Définir ou mettre à jour un budget 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" } ``` > **Remarques sur le schéma** (`setBudgetSchema`) : `apiKeyId` est obligatoire ; au moins l’une des valeurs `dailyLimitUsd`, `weeklyLimitUsd` ou `monthlyLimitUsd` doit être supérieure à zéro. Champs facultatifs : `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). L’ancien format `{keyId, limit, period}` renvoie `400 Bad Request`. ## Limites de jetons Budgets de **jetons** par clé d’API (distincts du budget en USD ci-dessus). Ils sont appliqués directement lors du traitement de la requête : lorsque l’utilisation d’une clé pendant la fenêtre en cours atteint sa limite, les requêtes sont rejetées avec `429 Too Many Requests`. Les limites peuvent être restreintes à un `model` spécifique, à un `provider`, ou appliquées `global`ement à l’ensemble de la clé ; lorsque plusieurs limites correspondent à une requête, la plus restrictive l’emporte. ```bash # Répertorier les limites de jetons d’une clé (inclut l’utilisation en temps réel de la fenêtre) GET /api/usage/token-limits?apiKeyId=key-123 # Créer ou mettre à jour une limite de jetons POST /api/usage/token-limits Content-Type: application/json { "apiKeyId": "key-123", "scopeType": "model", "scopeValue": "openai/gpt-4o", "tokenLimit": 1000000, "resetInterval": "monthly", "enabled": true } # Supprimer une limite de jetons par identifiant DELETE /api/usage/token-limits?id=tl-abc ``` > **Remarques sur le schéma** (`setTokenLimitSchema`) : `apiKeyId` et `scopeType` (`model` | `provider` | `global`) sont obligatoires. `scopeValue` est obligatoire, sauf si `scopeType` vaut `global` (par exemple, un identifiant de modèle pour la portée `model`, ou un identifiant de fournisseur pour la portée `provider`). `tokenLimit` doit être un entier positif (converti depuis une chaîne). Facultatifs : `id` (omettre pour créer, fournir pour mettre à jour), `resetInterval` (`daily` | `weekly` | `monthly`, valeur par défaut `monthly`), `resetTime` (`HH:MM`), `enabled` (valeur par défaut `true`). Les réponses `GET` enrichissent chaque limite avec `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` et `nextResetAt`. Il s’agit d’un point de terminaison de gestion (l’authentification est appliquée de manière centralisée par le pipeline d’autorisation). ## Traitement des requêtes 1. Le client envoie une requête à `/v1/*` 2. Le gestionnaire de route appelle `handleChat`, `handleEmbedding`, `handleAudioTranscription` ou `handleImageGeneration` 3. Le modèle est résolu (fournisseur/modèle direct ou alias/combo) 4. Les identifiants sont sélectionnés depuis la base de données locale avec filtrage selon la disponibilité des comptes 5. Pour le chat : `handleChatCore` vérifie le cache sémantique/de signature et résout les paramètres de compression du combo 6. La compression proactive s’exécute avant la traduction pour le fournisseur lorsqu’elle est activée (`lite`, Caveman, RTK ou empilée) 7. L’exécuteur du fournisseur envoie la requête en amont 8. La réponse est retraduite au format du client (chat) ou renvoyée telle quelle (embeddings/images/audio) 9. L’utilisation, les analyses de compression et les journaux de requêtes sont enregistrés 10. Un repli est appliqué en cas d’erreur conformément aux règles du combo Référence complète de l’architecture : [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md) --- ## Gestion des combos Les combos de routage de plus haut niveau (déjà résumés sous `/api/combos*`) peuvent également être associés individuellement à partir d’un motif d’identifiant de modèle, ce qui permet la redirection transparente d’un identifiant de modèle de style OpenAI vers un combo. | Méthode | Chemin | Description | | ------- | -------------------------------- | --------------------------------------------------------------------------------------- | | GET | `/api/model-combo-mappings` | Répertorier toutes les associations modèle→combo | | POST | `/api/model-combo-mappings` | Créer une association — corps : `{pattern, comboId, priority?, enabled?, description?}` | | GET | `/api/model-combo-mappings/[id]` | Récupérer une association spécifique | | PUT | `/api/model-combo-mappings/[id]` | Mettre à jour les champs d’une association existante | | DELETE | `/api/model-combo-mappings/[id]` | Supprimer une association | **Authentification :** session/clé d’API de gestion (`requireManagementAuth`). --- ## Webhooks Abonnements aux webhooks sortants pour les événements OmniRoute (fin d’une requête, épuisement d’un quota, rotation d’une clé, etc.). | Méthode | Chemin | Description | | ------- | ------------------------- | -------------------------------------------------------------------------------------- | | GET | `/api/webhooks` | Répertorier les webhooks (les secrets sont masqués sous la forme `...`) | | POST | `/api/webhooks` | Créer un webhook — corps : `{url, events?: ["*"], secret?, description?}` | | GET | `/api/webhooks/[id]` | Récupérer un webhook | | PUT | `/api/webhooks/[id]` | Mettre à jour url/events/secret/description | | DELETE | `/api/webhooks/[id]` | Supprimer un webhook | | POST | `/api/webhooks/[id]/test` | Envoyer une charge utile de test à l’URL du webhook et renvoyer l’état de la livraison | **Authentification :** session de gestion/clé d’API (`requireManagementAuth`). --- ## Clés enregistrées (gestion automatique) Utilisées par le sous-système de gestion automatique des clés pour émettre et renouveler des clés API auprès d’un fournisseur/compte sous-jacent, avec des quotas quotidiens/horaires. | Méthode | Chemin | Description | | ------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/v1/registered-keys` | Répertorier les clés enregistrées (préfixe masqué uniquement) | | POST | `/api/v1/registered-keys` | Émettre une nouvelle clé enregistrée — corps : `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Renvoie la clé brute **une seule fois**. Renvoie `429` en cas de refus lié au quota. | | GET | `/api/v1/registered-keys/[id]` | Récupérer les métadonnées d’une clé enregistrée (sans la clé brute) | | DELETE | `/api/v1/registered-keys/[id]` | Révoquer une clé enregistrée | | POST | `/api/v1/registered-keys/[id]/revoke` | Point de terminaison de révocation explicite (même effet que DELETE) | **Authentification :** session/clé API de gestion (`requireManagementAuth`) — le même contrôle d’accès que pour `/api/keys` : une session du tableau de bord, le jeton CLI local ou une clé API avec la portée `manage`/`admin` ; les clés API limitées à l’inférence reçoivent une réponse `403`. Voir également `/v1/quotas/check` et `/v1/issues/report`. --- ## Protocole des agents Tâches d’agents cloud (Claude Code, Codex Cloud, OpenHands, etc.) exécutées à distance pour le compte des utilisateurs d’OmniRoute. | Méthode | Chemin | Description | | ------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/agents/tasks` | Répertorie les tâches — paramètres facultatifs `?provider=`, `?status=`, `?limit=` (1–500, 50 par défaut) | | POST | `/api/v1/agents/tasks` | Crée une tâche — corps validé par `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Renvoie `201` avec l’enveloppe de la tâche | | DELETE | `/api/v1/agents/tasks?id=...` | Supprime une tâche | | GET | `/api/v1/agents/tasks/[id]` | Lit la tâche — actualise de manière synchrone son statut depuis l’agent cloud en amont lorsqu’un `external_id` est défini | | POST | `/api/v1/agents/tasks/[id]` | Action discriminée : `{action: "approve"}`, `{action: "message", message}` ou `{action: "cancel"}` | | DELETE | `/api/v1/agents/tasks/[id]` | Supprime une tâche spécifique par identifiant | > **Authentification :** une authentification de gestion est requise pour chaque méthode (`requireCloudAgentManagementAuth`). Avant la v3.8.0, ces méthodes n’étaient pas authentifiées — consultez le commit `588a0333` pour cette modification incompatible. ```bash # Créer une tâche cloud Claude Code curl -X POST http://localhost:20128/api/v1/agents/tasks \ -H "Authorization: Bearer your-management-key" \ -H "Content-Type: application/json" \ -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}' ``` --- ## Proxys de gestion Proxys HTTP(S)/SOCKS sortants pouvant être affectés à des fournisseurs, à des comptes ou globalement. | Méthode | Chemin | Description | | ------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/management/proxies` | Répertorie les proxys (avec `?id=`, en renvoie un ; avec `?id=&where_used=1`, renvoie le graphe des affectations) | | POST | `/api/v1/management/proxies` | Crée un proxy — corps validé par `createProxyRegistrySchema` | | PATCH | `/api/v1/management/proxies` | Met à jour un proxy — corps validé par `updateProxyRegistrySchema` (`id` requis) | | DELETE | `/api/v1/management/proxies?id=...&force=1` | Supprime un proxy (utilisez `force=1` pour dissocier les affectations) | | GET | `/api/v1/management/proxies/assignments` | Répertorie les affectations — filtrables par `proxy_id`, `scope`, `scope_id` ; transmettez `resolve_connection_id=` pour déterminer le proxy actif d’une connexion | | PUT | `/api/v1/management/proxies/assignments` | Affecte — corps validé par `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Vide le cache du répartiteur | | PUT | `/api/v1/management/proxies/bulk-assign` | Affecte en masse — corps validé par `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) | | GET | `/api/v1/management/proxies/health?hours=24` | Agrège l’état de santé des proxys (nombre de réussites/d’échecs, latence) sur une période donnée | **Authentification :** session de gestion/clé d’API requise sur chaque route (`requireManagementAuth`). > Les routes `POST /api/v1/management/proxies/[id]/assignments` et `POST /api/v1/management/proxies/[id]/health` mentionnées dans la description de la tâche sont fournies par les routes plates `/assignments` et `/health` présentées ci-dessus — il n’existe aucune sous-route par identifiant dans la base de code. --- ## Résilience (étendue) OmniRoute expose trois mécanismes indépendants de gestion des défaillances temporaires ; les points de terminaison de gestion ci-dessous permettent aux opérateurs de les consulter et de les remplacer : | Portée | Stockage de l’état | Consultation | Réinitialisation / effacement | | -------------------------- | ------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------- | | Disjoncteur du fournisseur | `domain_circuit_breakers` + en mémoire | `/api/monitoring/health` | `POST /api/resilience/reset` | | Délai de connexion | `rateLimitedUntil` sur les connexions fournisseur | `/api/rate-limits`, `/api/providers/[id]` | (réactivation différée ; effacement via PUT sur le fournisseur) | | Verrouillage du modèle | Registre en mémoire de disponibilité des modèles | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` | `PATCH /api/resilience` accepte les remplacements de disjoncteur du fournisseur sous `providerBreaker.oauth` et `providerBreaker.apikey`. Chaque profil prend en charge `degradationThreshold`, `failureThreshold` et `resetTimeoutMs` ; les mêmes champs sont disponibles dans Tableau de bord → Paramètres → Résilience. ```bash # Effacer le verrouillage d’un seul modèle 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"}' # Effacer tous les verrouillages curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \ -H "Cookie: auth_token=..." \ -d '{"all":true}' ``` Pour la référence conceptuelle complète et les valeurs par défaut des disjoncteurs, consultez [`CLAUDE.md`](../../CLAUDE.md) → « État d’exécution de la résilience ». --- ## Compétences Cadre de compétences permettant d’étendre OmniRoute avec des gestionnaires exécutables personnalisés, ainsi que des intégrations de places de marché. | Méthode | Chemin | Description | | ------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/skills` | Répertorie les compétences installées — filtrables par `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, avec pagination | | GET | `/api/skills/[id]` | Récupère une compétence | | PUT | `/api/skills/[id]` | Met à jour une compétence (nom, description, mode, schéma, gestionnaire, étiquettes) | | DELETE | `/api/skills/[id]` | Désinstalle une compétence | | POST | `/api/skills/install` | Installe une compétence à partir d’un manifeste brut — corps : `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` | | GET | `/api/skills/executions` | Répertorie les exécutions récentes de compétences (journal d’audit avec entrées/sorties/durée) | | GET | `/api/skills/marketplace?q=...` | Recherche/liste des compétences populaires de la place de marché SkillsMP (nécessite le paramètre `skillsmpApiKey`) | | POST | `/api/skills/marketplace/install` | Installe une compétence par identifiant depuis SkillsMP | | GET | `/api/skills/skillssh?q=&limit=` | Recherche dans le registre skills.sh | | POST | `/api/skills/skillssh/install` | Installe une compétence par identifiant depuis skills.sh | **Authentification :** session de gestion/clé API. Les routes de recherche des places de marché acceptent soit l’authentification de gestion, soit une clé API Bearer (`isAuthenticated`). --- ## Mémoire Stockage persistant de la mémoire conversationnelle/factuelle, limité par clé API / session. | Méthode | Chemin | Description | | ------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/memory` | Répertorie les souvenirs — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, avec une pagination `offset/limit` ou `page/limit` | | POST | `/api/memory` | Crée un souvenir — corps validé par Zod : `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` | | GET | `/api/memory/[id]` | Récupère un souvenir | | DELETE | `/api/memory/[id]` | Supprime un souvenir | | GET | `/api/memory/health` | État du sous-système de mémoire (connectivité à la base de données, backend d'embeddings, état de l'index vectoriel) | **Authentification :** session de gestion/clé API (`requireManagementAuth`). Énumération `type` : `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (voir `MemoryType` dans `src/lib/memory/types.ts`). --- ## Serveur MCP OmniRoute intègre un serveur Model Context Protocol avec 3 transports (stdio, SSE, streamable-http) et des outils à portée limitée. Les endpoints du tableau de bord ci-dessous lisent les données d'état/d'audit et servent de proxy aux transports HTTP. | Méthode | Chemin | Description | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- | | GET | `/api/mcp/status` | Signal de présence, transport, état en ligne, dernier appel, principaux outils, taux de réussite sur 24 h | | GET | `/api/mcp/tools` | Liste des outils MCP avec `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` | | GET | `/api/mcp/sse` | Ouvre un flux SSE pour le transport SSE (renvoie `503` si MCP est désactivé ou si le transport ne correspond pas) | | POST | `/api/mcp/sse` | Envoie une trame JSON-RPC sur le transport SSE | | GET | `/api/mcp/stream` | Ouvre le côté SSE du transport HTTP streamable (messages initiés par le serveur) | | POST | `/api/mcp/stream` | Envoie une trame JSON-RPC sur le transport HTTP streamable | | DELETE | `/api/mcp/stream` | Met fin à une session HTTP streamable | | GET | `/api/mcp/audit` | Interroge le journal d'audit — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` | | GET | `/api/mcp/audit/stats` | Statistiques d'audit agrégées (totaux, taux de réussite, durée moyenne, principaux outils) | **Authentification :** les transports `sse`/`stream` respectent le mécanisme d'authentification propre à MCP (clé API Bearer avec la portée `mcp`) ; les routes `status`/`tools`/`audit*` sont accessibles depuis le tableau de bord (aucune authentification supplémentaire n'est requise au-delà de l'accès à l'hôte du tableau de bord). > Les deux transports HTTP sont contrôlés par `settings.mcpEnabled` et `settings.mcpTransport` — une incompatibilité de transport renvoie `400`, tandis qu'un état MCP désactivé renvoie `503`. --- ## Serveur A2A OmniRoute expose un endpoint A2A (Agent-to-Agent) JSON-RPC 2.0 ainsi qu’une surcouche REST pour les besoins d’inspection et de tableau de bord. ### JSON-RPC ```bash POST /a2a Authorization: Bearer your-api-key # facultatif, sauf si OMNIROUTE_API_KEY est défini Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "method": "message/send", "params": { "skill": "smart-routing", "messages": [{"role": "user", "content": "Route this coding task"}] } } ``` Méthodes prises en charge (toutes conditionnées par `settings.a2aEnabled`) : | Méthode | Description | | ---------------- | ---------------------------------------------------------------------------- | | `message/send` | Exécution synchrone d’une compétence ; renvoie `{task, artifacts, metadata}` | | `message/stream` | Exécution SSE en streaming du même ensemble de compétences | | `tasks/get` | Récupère une tâche par `taskId` | | `tasks/cancel` | Annule une tâche par `taskId` | Compétences intégrées : `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`. ### Fiche de l’agent ```bash GET /.well-known/agent.json ``` Renvoie la fiche publique de l’agent A2A (nom, description, capacités, catalogue des compétences, schéma d’authentification) — mise en cache publiquement pendant 1 h. Aucune authentification requise. ### Assistants REST | Méthode | Chemin | Description | | ------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/a2a/status` | Activation d’A2A + statistiques des tâches + résumé de la fiche d’agent mise en cache | | GET | `/api/a2a/tasks` | Répertorie les tâches — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` | | POST | `/api/a2a/tasks` | (Non implémenté comme assistant REST — créer via JSON-RPC `message/send`) | | GET | `/api/a2a/tasks/[id]` | Récupère une tâche | | POST | `/api/a2a/tasks/[id]/cancel` | Annule une tâche | **Authentification :** les assistants REST fonctionnent sans authentification de gestion (lisibles depuis le tableau de bord) ; la route JSON-RPC `/a2a` utilise le jeton Bearer `OMNIROUTE_API_KEY` s’il est configuré. --- ## Cloud, évaluations et analyses | Méthode | Chemin | Description | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- | | POST | `/api/cloud/auth` | Vérifier une clé Bearer et renvoyer les connexions masquées aux fournisseurs ainsi que les alias de modèles pour les clients de synchronisation cloud | | POST | `/api/cloud/credentials/update` | Mettre à jour les identifiants chiffrés d’un fournisseur synchronisé avec le cloud | | POST | `/api/cloud/model/resolve` | Résoudre l’identifiant logique d’un modèle en un fournisseur/modèle concret à l’aide de la table de routage locale | | GET | `/api/cloud/models/alias` | Répertorier les alias de modèles tels qu’ils sont exposés à la synchronisation cloud | | GET | `/api/assess` | Lire les dernières catégorisations d’analyse (par fournisseur/modèle) | | POST | `/api/assess` | Exécuter une analyse — corps : `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` | | GET | `/api/evals` | Répertorier les suites d’évaluation intégrées ainsi que leurs exécutions les plus récentes | | POST | `/api/evals` | Déclencher une exécution d’évaluation | | POST | `/api/evals/suites` | Créer une suite d’évaluation personnalisée — corps validé par `evalSuiteSaveSchema` | | GET | `/api/evals/suites/[id]` | Récupérer une suite d’évaluation personnalisée | **Authentification :** `/api/cloud/auth` valide directement une clé Bearer et renvoie la clé masquée ainsi que le `projectId` de chaque connexion uniquement pour une clé dotée de la portée `manage` / `admin` ; les autres routes `/api/cloud/*`, `/api/evals/*` et `/api/assess` nécessitent une session de gestion/clé d’API. La requête POST vers `/api/assess` utilise `validateBody` avec un schéma de portée fondé sur une union discriminée. --- ## Gestion d’ACP (Agent Client Protocol) en tant que processus enfants. Ces points de terminaison gèrent la détection des agents ACP et l’enregistrement d’agents personnalisés. | Méthode | Chemin | Description | | ------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/acp/agents` | Répertorie tous les agents CLI connus (intégrés + personnalisés) avec leur statut d’installation, leur version et leur binaire | | POST | `/api/acp/agents` | Enregistre un agent ACP personnalisé ou actualise le cache — corps : `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` ou `{action: "refresh"}` | | DELETE | `/api/acp/agents` | Supprime un agent ACP personnalisé — paramètre de requête : `?id=` | **Exemple de réponse** (`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 } ``` **Authentification :** nécessite une session de gestion (cookie `auth_token` du tableau de bord) ou une clé API avec une portée de gestion. Consultez [Framework ACP](../frameworks/ACP.md) pour plus de détails. --- ## Analytique et observabilité Points de terminaison d’analytique en temps réel permettant de surveiller le routage, la compression et la diversité des fournisseurs. Ils alimentent les pages `/dashboard/analytics/*`. ### Analytique du routage automatique | Méthode | Chemin | Description | | ------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/auto-routing` | Statistiques agrégées du routage automatique : nombre total d’appels, répartition par stratégie, niveau et fournisseur | | GET | `/api/analytics/auto-routing?days=7` | Statistiques sur une fenêtre temporelle (24 h par défaut) | **Exemple de réponse** : ```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 } ] } ``` ### Analytique de la compression | Méthode | Chemin | Description | | ------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/compression` | Statistiques agrégées de compression : jetons économisés, pourcentage d’économie, répartition par mode et moteur | **Exemple de réponse** : ```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 } } ``` ### Suivi de la diversité des fournisseurs | Méthode | Chemin | Description | | ------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/diversity` | Suivi de la diversité fondé sur l’entropie de Shannon : évite les points de défaillance uniques en mesurant la répartition des fournisseurs | **Exemple de réponse** : ```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 représente 40 % du trafic — envisagez de diversifier les fournisseurs"] } ``` **Authentification :** nécessite une session de gestion ou une clé API avec une portée de gestion. --- ## Opérations d’administration Points de terminaison réservés aux administrateurs pour la gestion opérationnelle. | Méthode | Chemin | Description | | ------- | ------------------------ | ------------------------------------------------------------------------------------------------------------ | | GET | `/api/admin/concurrency` | Lire les limites de concurrence actuelles (globales et par fournisseur) | | POST | `/api/admin/concurrency` | Mettre à jour les limites de concurrence — corps : `{global?: number, perProvider?: Record}` | **Authentification :** nécessite une session de gestion avec une portée d’administrateur. --- ## Gestion des outils CLI Gérez les outils CLI qui s’intègrent à OmniRoute (antigravity, commandCode, devin-cli, etc.). Consultez la [référence des fournisseurs](./PROVIDER_REFERENCE.md) pour obtenir la liste complète. | Méthode | Chemin | Description | | ------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/cli-tools/all-statuses` | État de tous les outils CLI (installation, version, dernière détection) | | GET | `/api/cli-tools/status` | Détails de l’état d’un outil CLI (requête `?tool=`) | | POST | `/api/cli-tools/apply` | Écrit la configuration générée d’un outil (`dryRun` fournit un aperçu ; `422` + `containerEphemeralTarget` en environnement conteneurisé ; `migration` signale un ancien YAML Codex) | | GET | `/api/cli-tools/backups` | Répertorie les sauvegardes de configuration des outils CLI | | POST | `/api/cli-tools/backups` | Crée une sauvegarde des configurations de tous les outils CLI | | POST | `/api/cli-tools/backups` | Restauration : le même point de terminaison avec `{tool, backupId}` dans le corps restaure cette sauvegarde | | GET | `/api/cli-tools/antigravity-mitm` | État du proxy MITM Antigravity (l’outil CLI « antigravity-mitm ») | | POST | `/api/cli-tools/antigravity-mitm/alias` | Configure les alias antigravity-mitm | **Authentification :** nécessite une session de gestion. --- ## Compétences d’agent Gérez les compétences des agents d’IA (similaires aux GPT personnalisés d’OpenAI, mais destinées aux agents). | Méthode | Chemin | Description | | ------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- | | GET | `/api/agent-skills` | Répertorier toutes les compétences d’agent (intégrées et personnalisées) | | GET | `/api/agent-skills/[id]` | Obtenir une compétence d’agent spécifique | | POST | `/api/agent-skills` | Créer une compétence d’agent personnalisée — corps : `{name, description, prompt, model?, temperature?}` | | PUT | `/api/agent-skills/[id]` | Mettre à jour une compétence d’agent personnalisée | | DELETE | `/api/agent-skills/[id]` | Supprimer une compétence d’agent personnalisée | | GET | `/api/agent-skills/[id]/raw` | Obtenir le prompt brut et les métadonnées (sans exécution) | | POST | `/api/agent-skills/generate` | Générer par IA une nouvelle compétence à partir d’une description en langage naturel | **Authentification :** nécessite une session de gestion ou une clé API avec une portée de gestion. --- ## Gestion du cache Gérez le cache sémantique et le cache de raisonnement. | Méthode | Chemin | Description | | ------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/cache` | Vue d’ensemble du cache : nombre total d’entrées, taux de succès, taille sur le disque | | GET | `/api/cache/entries` | Répertorier les entrées mises en cache (avec pagination) | | DELETE | `/api/cache/entries` | Supprimer des entrées du cache (filtrage par paramètres de requête) | | GET | `/api/cache/stats` | Statistiques détaillées du cache (par fournisseur, par modèle) | | GET | `/api/cache/reasoning` | État du cache de raisonnement (pour la relecture du raisonnement) | | DELETE | `/api/cache/reasoning` | Vider le cache de raisonnement — paramètres de requête : `?toolCallId=` (un seul), `?provider=

` ou aucun paramètre (tout) | **Authentification :** nécessite une session de gestion. --- ## Système de mémoire Gérez la mémoire persistante (FTS5 + plongements vectoriels). | Méthode | Chemin | Description | | ------- | ------------------ | -------------------------------------------------------------------------------------------------- | | GET | `/api/memory` | Répertorier les entrées de mémoire (filtrage par portée, type et requête de recherche) | | POST | `/api/memory` | Créer une entrée de mémoire — corps : `{scope, type, content, metadata?}` | | GET | `/api/memory/[id]` | Obtenir une entrée de mémoire spécifique | | PUT | `/api/memory/[id]` | Mettre à jour une entrée de mémoire | | DELETE | `/api/memory/[id]` | Supprimer une entrée de mémoire | | GET | `/api/memory?q=` | Rechercher dans la mémoire (FTS5 + vecteurs) — les statistiques sont incluses dans la même réponse | **Authentification :** nécessite une session de gestion ou une clé d’API limitée à la gestion. --- ## Webhooks Gérez les abonnements webhook aux événements. | Méthode | Chemin | Description | | ------- | ------------------------------- | -------------------------------------------------------------------------------- | | GET | `/api/webhooks` | Répertorier tous les abonnements webhook | | POST | `/api/webhooks` | Créer un abonnement webhook — corps : `{url, events[], secret?, active?}` | | GET | `/api/webhooks/[id]` | Obtenir un abonnement webhook spécifique | | PUT | `/api/webhooks/[id]` | Mettre à jour un abonnement webhook | | DELETE | `/api/webhooks/[id]` | Supprimer un abonnement webhook | | GET | `/api/webhooks/[id]/deliveries` | Répertorier l’historique des livraisons d’un webhook (journal des succès/échecs) | | POST | `/api/webhooks/[id]/test` | Envoyer un événement de test à un webhook | **Authentification :** nécessite une session de gestion. Consultez [Infrastructure des webhooks](../frameworks/WEBHOOKS.md) pour obtenir la liste complète des types d’événements. --- ## Framework de compétences Gérez les compétences (le framework d’extensions agentiques). | Méthode | Chemin | Description | | ------- | ------------------------ | ---------------------------------------------------------------------------------------------------- | | GET | `/api/skills` | Répertorier toutes les compétences installées (intégrées + personnalisées) | | POST | `/api/skills/install` | Installer une compétence depuis un chemin local ou une URL | | DELETE | `/api/skills/[id]` | Désinstaller une compétence | | PUT | `/api/skills/[id]` | Activer ou désactiver une compétence — corps : `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` | | POST | `/api/skills/executions` | Exécuter une compétence — corps : `{skillName, apiKeyId, input?, sessionId?}` | | GET | `/api/skills/executions` | Répertorier l’historique d’exécution de toutes les compétences (filtrer par `?apiKeyId=`) | **Authentification :** nécessite une session de gestion ou une clé API avec une portée de gestion. Consultez [Framework de compétences](../frameworks/SKILLS.md) pour plus de détails. --- ## Plugins Gérez les plugins OmniRoute (extensions tierces). | Méthode | Chemin | Description | | ------- | ---------------------------------- | ----------------------------------------- | | GET | `/api/plugins` | Répertorier les plugins installés | | POST | `/api/plugins/marketplace/install` | Installer un plugin depuis la marketplace | | DELETE | `/api/plugins/[name]` | Désinstaller un plugin | | POST | `/api/plugins/[name]/activate` | Activer un plugin | | POST | `/api/plugins/[name]/deactivate` | Désactiver un plugin | | GET | `/api/plugins/[name]/config` | Obtenir la configuration du plugin | | PUT | `/api/plugins/[name]/config` | Mettre à jour la configuration du plugin | **Authentification :** nécessite une session de gestion. Consultez [Framework des plugins](../frameworks/PLUGIN_SDK.md) pour plus de détails. --- ## Routage fantôme La comparaison fantôme / A-B des fournisseurs **ne constitue pas une surface REST autonome** — elle est configurée via le routage combiné (consultez [Auto-Combo](../routing/AUTO-COMBO.md)). Les métriques de comparaison par combinaison sont fournies par `GET /api/combos/metrics`. --- ## Garde-fous Inspectez les garde-fous d’exécution (détection des informations personnelles, détection des injections de prompt, passerelle de vision). Les garde-fous s’exécutent à chaque requête ; la désactivation pour un appel spécifique s’effectue via l’en-tête de requête `x-omniroute-disabled-guardrails` — il n’existe aucune interface persistante d’activation ou de désactivation. | Méthode | Chemin | Description | | ------- | ---------------------- | ---------------------------------------------------------------------------------------------------------- | | GET | `/api/guardrails` | Répertorier les garde-fous enregistrés et leur statut (nom / activé / priorité) | | POST | `/api/guardrails/test` | Exécuter à blanc le pipeline de pré-appel sur un exemple d’entrée — corps : `{input, disabledGuardrails?}` | **Authentification :** nécessite une session de gestion. Consultez [Sécurité > Garde-fous](../security/GUARDRAILS.md) pour plus de détails. --- --- ## Authentification Consultez [Authentification de gestion](../guides/MANAGEMENT-AUTH.md) pour découvrir les quatre familles d’identifiants (session du tableau de bord, jeton CLI local, jeton d’accès `oma_live_…`, clé API avec portée de gestion) et leurs différences avec les clés d’inférence. - Les routes du tableau de bord (`/dashboard/*`) utilisent le cookie `auth_token` - La connexion utilise le hachage du mot de passe enregistré, avec repli sur `INITIAL_PASSWORD` - `requireLogin` peut être activé ou désactivé via `/api/settings/require-login` - Les routes `/v1/*` peuvent exiger une clé API Bearer lorsque `REQUIRE_API_KEY=true` - Dans cette référence, « jeton de gestion » / « clé API avec portée de gestion » désigne l’une des familles décrites dans ce guide, et non un type de secret supplémentaire non défini > **Modification avec rupture de compatibilité (v3.8.0)** — `/api/v1/agents/tasks/*` et les points de terminaison de gestion des délais de récupération exigent désormais une **authentification de gestion** (cookie `auth_token` du tableau de bord ou clé API avec portée de gestion). Les clients qui appelaient auparavant ces routes sans authentification recevront `401 Unauthorized`. Consultez le commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).