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

API Reference (Français)

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

---

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

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 et l’arborescence des routes sous src/app/api/ constituent les sources exhaustives.

---

Table des matières

• Complétions de chat
• Baux exclusifs de sessions gérées
• Embeddings
• Génération d’images
• OCR de documents
• Liste des modèles
• Manifeste du plugin fournisseur
• Points de terminaison de compatibilité
• API des fichiers
• API des traitements par lots
• API de recherche
• Diffusion en continu via WebSocket
• Quotas et signalement des problèmes
• Cache sémantique
• Tableau de bord et gestion
• Gestion des combinaisons
• Webhooks
• Clés enregistrées (gestion automatique)
• Protocole des agents
• Proxys de gestion
• Résilience (étendue)
• Compétences
• Mémoire
• Serveur MCP
• Serveur A2A
• Cloud, évaluations et appréciation
• Traitement des requêtes
• Authentification

---

Complétions de chat

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=<name>; provider=<alias>; latency_ms=<n> (<name> 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 exclusifs de sessions gérées

La location exclusive de sessions gérées est un contrat de routage facultatif et indépendant du client : un propriétaire actif détient une connexion OmniRoute éligible. Elle ne réserve pas un modèle, n’exige pas OAuth, n’identifie pas un client particulier et n’impose pas de fournisseur particulier.

La clé API utilisée pour l’authentification doit disposer de la portée lease:exclusive et d’une liste allowedConnections explicite et non vide. La limite transactionnelle des mutations de la base de données impose conjointement ces deux champs lors de la création d’une clé et des mises à jour partielles.

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

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

Les réponses réussies d’acquisition, de renouvellement et de libération exposent les horodatages, state et la valeur positive exacte de generation, mais jamais la connexion sélectionnée ni les identifiants d’authentification. Pour le renouvellement et la libération, la génération est fournie dans le corps JSON :

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

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

Le propriétaire d’un bail actif peut demander explicitement des métadonnées d’affichage respectueuses de la confidentialité pour son association actuelle :

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

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

Cette action d’état facultative est protégée par le propriétaire opaque, la clé API gérée authentifiée et la génération active exacte, au sein d’une même transaction de base de données. displayName correspond uniquement au nom configuré de la connexion, après suppression des espaces superflus ; sa valeur est null lorsqu’aucun nom configuré sûr n’existe. OmniRoute ne lui substitue jamais une adresse e-mail ni une identité de compte générée. La valeur du fournisseur est une étiquette d’affichage non sensible et jamais un identifiant généré de fournisseur compatible. Les identifiants d’authentification, jetons, cookies, identifiants bruts de connexion ou de clé API, empreintes de propriétaires, secrets de cloisonnement et données de routage internes sont exclus.

Les recherches avec une clé incorrecte, un propriétaire incorrect, une génération obsolète, un bail manquant, expiré, libéré ou invalidé renvoient toutes la même erreur 409 LEASE_FENCE_STALE, sans métadonnées de connexion. Un client ayant reçu la réponse d’attente de capacité ne dispose d’aucune association active à inspecter. Lorsque le routage fait basculer un bail actif, la même génération reste valide et l’état renvoie atomiquement la nouvelle association, 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 structures précédentes.

Ce contrat serveur ne modifie pas /status dans la version standard d’OpenAI Codex. À l’heure actuelle, la version standard de Codex indique son fournisseur de modèle et l’état intégré de l’authentification et du compte, mais n’affiche pas les métadonnées de compte arbitraires des fournisseurs personnalisés ; une future intégration côté client devra appeler cette action et déterminer comment afficher connection.displayName.

Chaque requête d’inférence gérée fournit ensuite les deux en-têtes de contrôle :

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 cloisonnés immédiatement avant chaque tentative en amont prise en charge. La réutilisation du propriétaire et de 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 ni conservés, ni journalisés, ni retenus dans l’instantané de la requête, ni transmis en amont.

Une contention temporaire renvoie le code HTTP 429 avec Retry-After et :

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

Cette réponse signifie uniquement que l’ensemble éligible ordinaire n’était pas vide et que chaque candidat libre était détenu par un bail actif tiers. Les modèles ou fournisseurs non pris en charge, les incompatibilités de politique, les périodes de récupération, les quotas, l’état de santé et les autres échecs ordinaires d’éligibilité conservent leurs réponses OmniRoute existantes.

x-omniroute-compression

Remplacement, pour chaque requête, du plan de compression. Priorité la plus élevée — prévaut sur le remplacement de la combinaison de routage, le profil actif, le déclenchement automatique et la valeur par défaut du panneau. Valeurs :

Valeur	Effet
off	Aucune compression pour cette requête.
default	Le profil par défaut dérivé du panneau (ignore le profil actif).
engine:<id>	Un moteur unique lorsqu’il est activé, par ex. engine:rtk.
<combo>	Une combinaison nommée, recherchée d’abord par nom (sans tenir compte de la casse), puis par identifiant.

Remarques :

• Les valeurs inconnues sont ignorées (la requête n’est jamais rejetée) ; la résolution passe alors à l’ordre de priorité normal des opérateurs.
• Si plusieurs combinaisons partagent le même nom, transmettez l’id de la combinaison pour obtenir une correspondance déterministe.
• Une combinaison dont le nom est off ou default ne peut pas être sélectionnée par son nom (ces mots-clés sont interprétés en premier) ; référencez une telle combinaison par son identifiant.
• Le commutateur principal de compression constitue un verrou absolu : 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: <mode>; source=<source>

où <source> est l’une des valeurs suivantes : request-header, routing-override, active-profile, auto-trigger, default ou off.

---

Embeddings

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 suivent le 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. Pour les opérations d’embedding, de reranking, de classification et de segmentation de Jina, les identifiants jina-ai du tableau de bord sont utilisés en priorité ; 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 sans modification à https://api.jina.ai/v1/embeddings :

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "task": "retrieval.query",
  "normalized": true,
  "input": [
    { "text": "a red bicycle" },
    { "image": "https://example.com/bike.png" },
    {
      "content": [{ "text": "caption" }, { "image": "data:image/png;base64,..." }]
    }
  ]
}

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 exclusivement textuels 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) et intégrés avant l’appel au fournisseur. Les éléments Jina natifs {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 le fournisseur (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 seule requête native models/{model}:embedContent avec content.parts (text ou inline_data).
• Les modèles inconnus/dynamiques dépourvus de métadonnées explicites sur les modalités rejettent les entrées structurées avec HTTP 400.

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "input": [
    { "type": "text", "text": "A red bicycle" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/bicycle.png" }
    }
  ],
  "dimensions": 512,
  "encoding_format": "float"
}

Les combinaisons modèle/modalité non prises en charge renvoient HTTP 400 au lieu de convertir de force l’élément. Les champs d’extension autres que ceux d’entrée dans les requêtes héritées de chaînes/jetons continuent d’être transmis sans modification.

# Répertorier tous les modèles d’embedding
GET /v1/embeddings

---

Génération d’images

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

Fournisseurs disponibles : OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (local), ComfyUI (local).

# Répertorier tous les modèles d’image
GET /v1/images/generations

---

OCR de documents

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 :

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

---

Lister les modèles

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

→ Renvoie tous les modèles de chat, d'embedding et d'image ainsi que les combinaisons 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 le feature flag MODELS_CATALOG_PREFIX_MODE et peut être remplacé pour chaque requête à l'aide d'un paramètre de requête — pratique pour un client qui souhaite une liste épurée sans modifier le paramètre global du serveur pour tous les autres utilisateurs :

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	Par défaut. Les deux identifiants sont routé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. Double approximativement la taille du catalogue.
alias	cc/claude-sonnet-4-6	Une entrée par modèle. Les fournisseurs sans alias distinct publient tout de même leur entrée, donc 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 (p. ex. antigravity/…, agy/…) publient également ici leur identifiant unique, donc 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 qui pointe 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.

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

La sélection de cet identifiant (p. ex. dans une configuration Claude Code qui ajoute systématiquement un bloc thinking) le résout vers le véritable <provider>/<model> avec le raisonnement désactivé — thinking:{type:"disabled"} sur le chemin /v1/messages, ou les champs reasoning/reasoning_effort supprimés sur le chemin /v1/chat/completions. La variante n'est répertoriée que pour les modèles de la famille Claude qui prennent en charge le raisonnement et respectent disabled (ainsi, par exemple, les modèles exclusivement adaptatifs qui rejettent disabled sont exclus). Les opérateurs peuvent forcer l'activation ou la désactivation de la variante pour chaque modèle via ModelSpec.noThinkingAlias.

---

Manifeste des plugins de fournisseurs

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 (reconnaissance vocale)
POST	/v1/audio/speech	OpenAI TTS (renvoie un corps 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 erreur 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 API dans l’URL, soit via les paramètres de requête compatibles (?token=..., ?apiKey=..., ?api_key=..., ?key=...), soit via les points de terminaison dédiés /api/v1/vscode/{token}/... documentés ci-dessous.

# Reclassement
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 corps audio/mpeg (ou dans le format demandé)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# É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": "suno/v3.5",   "prompt": "..." }

Routes dédiées aux fournisseurs

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

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)

# 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=<OMNIROUTE_API_KEY>"
# (ou : -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

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

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)

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

# Format texte (le contrat historique — texte brut pour un terminal)
curl -H "Authorization: Bearer <votre-clé-api>" \
  http://localhost:20128/api/usage/om-usage

# Format structuré — celui qu’utilise une interface utilisateur
curl -H "Authorization: Bearer <votre-clé-api>" \
  "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 l’active ou le désactive pour chaque clé). Sans cette option, le point de terminaison répond avec 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 réussite :

{
  "allowed": true,
  // présent uniquement lorsque la clé a activé des limites d’utilisation propres à la clé (USD quotidiens/hebdomadaires) :
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // instantané du quota du fournisseur sélectionné, ou null si rien n’est encore mis en cache :
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // 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 (401 clé incorrecte / 403 accès non autorisé), la même route renvoie { "allowed": false, "error": { "message": "…" } } — un champ personal/provider présent mais vide (clé autorisée, aucune donnée obtenue pour le moment) représente un état différent d’un refus, et seul le format JSON permet de les distinguer.

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.

---

Cache sémantique

# Obtenir les statistiques du cache
GET /api/cache/stats

# Vider tous les caches
DELETE /api/cache/stats

Exemple de réponse :

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

{ "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. Familles d’identifiants, portées et exemples curl : Authentification de gestion.

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 requise

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 fournisseur
/api/providers/import	POST	Importer une LISTE hétérogène de fournisseurs depuis un fichier CSV/JSON analysé (#6836) ; résultats d’échec partiel par ligne
/api/provider-nodes*	Diverses	Gestion des nœuds de fournisseurs
/api/provider-models	GET/POST/PATCH/DELETE	Modèles personnalisés (ajouter, mettre à jour, masquer/afficher, supprimer)

Flux OAuth

Point de terminaison	Méthode	Description
/api/oauth/[provider]/[action]	Diverses	OAuth spécifique 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*	Diverses	Gestion des combinaisons
/api/keys*	Diverses	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 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 de prompts sur call_logs — ratio écriture/lecture, distribution p50/p90/p99 de la taille des écritures, concentration des écritures volumineuses, ventilation 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)

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/liste de blocage des adresses IP
/api/settings/thinking-budget	GET/PUT	Mode de réécriture des requêtes pour le budget de réflexion/raisonnement (transmission directe / suppression automatique / personnalisé / adaptatif). Indépendant de la compression. Voir THINKING_BUDGET.md.
/api/settings/system-prompt	GET/PUT	Prompt système global
/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

Endpoint	Méthode	Description
/api/compression/preview	POST	Prévisualiser la compression off/lite/standard/aggressive/ultra/RTK/stacked
/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, notamment 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 à l’aide de l’identifiant de 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 à des combinaisons de routage
/api/context/analytics	GET	Alias des analyses de compression

Surveillance

Endpoint	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é + résumé des fournisseurs (catalogCount, configuredCount, activeCount, monitoredCount). La vue de gestion inclut credentialHealth : valeurs scalaires du cache de sondes, failedConnections lorsque failed>0, et staleDbNonOkCount (test_status persistant de SQLite, et non la jauge). Voir MONITORING_GUIDE.md.
/api/cache/stats	GET/DELETE	Statistiques du cache / effacement
/api/modality-bridge/stats	GET	attempts en mémoire, réussites/bridged, échecs, accès au cache, totalLatencyMs, latencySamples, averageLatencyMs calculée selon le nombre d’échantillons et heure de la dernière utilisation (réinitialisés au redémarrage ; authentification de gestion)
/api/modality-bridge/video/runtime	GET	Vérification stricte de la boucle locale de confiance avant l’authentification/la sonde de gestion ; disponibilité et versions nettoyées de FFmpeg/ffprobe (sans stockage)
/api/modality-bridge/video/extract	POST	Courtier interne authentifié d’octets sur boucle locale de confiance ; entrée de 50 Mio, file d’attente limitée/sortie de 32 Mio, capacité 503, déconnexion 499, délai dépassé 504 ; ne constitue pas une API publique de téléversement

Sauvegarde et exportation/importation

Endpoint	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 au format .sqlite
/api/db-backups/import	POST	Importer un fichier .sqlite pour remplacer la base de données
/api/db-backups/exportAll	GET	Télécharger la sauvegarde complète sous forme d’archive .tar.gz

Synchronisation cloud

Endpoint	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	Consulter l’état d’installation et d’exécution de Cloudflare Quick Tunnel dans le tableau de bord
/api/tunnels/cloudflared	POST	Activer ou désactiver Cloudflare Quick Tunnel (action=enable/disable)
/api/tunnels/ngrok	GET	Consulter l’état d’exécution de ngrok Tunnel dans le tableau de bord
/api/tunnels/ngrok	POST	Activer ou désactiver ngrok Tunnel (action=enable/disable)

Outils CLI

Endpoint	Méthode	Description
/api/cli-tools/claude-settings	GET	État de Claude CLI
/api/cli-tools/codex-settings	GET	État de Codex CLI
/api/cli-tools/droid-settings	GET	État de Droid CLI
/api/cli-tools/openclaw-settings	GET	État d’OpenClaw CLI
/api/cli-tools/runtime/[toolId]	GET	Environnement d’exécution CLI générique

Les réponses 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 et 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	Consulter/mettre à jour la file d’attente des requêtes, le délai de récupération des connexions, le disjoncteur des fournisseurs et les paramètres d’attente
/api/resilience/reset	POST	Réinitialiser les disjoncteurs des fournisseurs
/api/resilience/model-cooldowns	GET	Répertorier les blocages actifs par (fournisseur, connexion, modèle), triés par durée restante
/api/resilience/model-cooldowns	DELETE	Supprimer un blocage de modèle — corps {provider, model} ou {all: true} pour tout effacer
/api/rate-limits	GET	État de la limite de débit par compte
/api/rate-limit	GET	Configuration globale de la limite de débit

Les quatre routes /api/resilience/* nécessitent une authentification de gestion (requireManagementAuth). Consultez Résilience (détaillée) pour une présentation complète des différences entre le disjoncteur de fournisseur, le délai de récupération de connexion et le blocage de modèle.

É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 qui nécessitent 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éclenche le redémarrage contrôlé du serveur
/api/shutdown	POST	Déclenche l'arrêt contrôlé du serveur
/api/system/env/repair	POST	Répare les variables d'environnement du fournisseur OAuth

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

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 :

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

---

Transcription audio

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 :

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 :

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

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

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

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

# Obtenir le résumé de la télémétrie de latence (p50/p95/p99 par fournisseur)
GET /api/telemetry/summary

Réponse :

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

---

Budget

# 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 globalement à l’ensemble de la clé ; lorsque plusieurs limites correspondent à une requête, la plus restrictive l’emporte.

# 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

---

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 <prefix>...)
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 d’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 données brutes)
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 : clé d’API Bearer (isAuthenticated). 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.

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

# 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 → « É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

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

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 appréciations

Méthode	Chemin	Description
POST	/api/cloud/auth	Vérifie une clé Bearer et renvoie les connexions masquées aux fournisseurs ainsi que les alias de modèles pour les clients de synchronisation cloud
POST	/api/cloud/credentials/update	Met à jour les identifiants chiffrés d’un fournisseur synchronisé avec le cloud
POST	/api/cloud/model/resolve	Résout un identifiant logique de modèle en un fournisseur/modèle concret à l’aide de la table de routage locale
GET	/api/cloud/models/alias	Répertorie les alias de modèles tels qu’ils sont exposés à la synchronisation cloud
GET	/api/assess	Lit les catégorisations de la dernière appréciation (par fournisseur/modèle)
POST	/api/assess	Exécute une appréciation — corps : `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	Répertorie les suites d’évaluation intégrées et les exécutions les plus récentes
POST	/api/evals	Déclenche une exécution d’évaluation
POST	/api/evals/suites	Crée une suite d’évaluation personnalisée — corps validé par evalSuiteSaveSchema
GET	/api/evals/suites/[id]	Récupère une suite d’évaluation personnalisée

Authentification : /api/cloud/auth valide directement une clé Bearer ; les autres routes /api/cloud/*, /api/evals/* et /api/assess nécessitent une session de gestion/clé API. La requête POST vers /api/assess utilise validateBody avec un schéma de portée sous forme d’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=<agentId>

Exemple de réponse (GET /api/acp/agents) :

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

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

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

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

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

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, chipotle, commandCode, devin-cli, etc.). Consultez la Référence des fournisseurs 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 (?tool= dans la requête)
POST	/api/cli-tools/apply	Écrire la configuration générée d’un outil (dryRun fournit un aperçu ; 422 + containerEphemeralTarget en cas de conteneurisation ; migration signale une ancienne configuration YAML de Codex)
GET	/api/cli-tools/backups	Répertorier les sauvegardes de configuration des outils CLI
POST	/api/cli-tools/backups	Créer une sauvegarde de toutes les configurations des outils CLI
POST	/api/cli-tools/backups	Restaurer : 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	Configurer les alias d’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=<id> (un seul), ?provider=<p> 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 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 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 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). 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 pour plus de détails.

---

---

Authentification

Consultez Authentification de gestion 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).