API Reference (Français)

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

POST /api/v1/session-leases
Authorization: Bearer &lt;managed-api-key&gt;
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 :

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

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

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

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 :

{
  "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:<id>`	Un seul moteur lorsqu’il est activé, par exemple `engine:rtk`. Opt-in par requête pour ce moteur.
`<combo>`	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: &lt;mode&gt;; source=<source>

où <source> est l’un des suivants : 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/&lt;provider&gt;/&lt;model&gt;

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`	Réponses OpenAI
POST	`/v1/embeddings`	OpenAI
POST	`/v1/images/generations`	Images OpenAI
POST	`/v1/images/edits`	Images OpenAI (édition/inpaint)
POST	`/v1/videos/generations`	Génération de vidéo de style OpenAI
POST	`/v1/music/generations`	Génération de musique de style OpenAI
POST	`/v1/audio/transcriptions`	Audio OpenAI (STT)
POST	`/v1/audio/speech`	TTS OpenAI (renvoie le corps audio)
POST	`/v1/rerank`	Rerank de style Cohere/Voyage
POST	`/v1/classify`	Classification Jina (`api.jina.ai`)
POST	`/v1/segment`	Segmentateur Jina (`segment.jina.ai`)
POST	`/v1/moderations`	Modérations OpenAI
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 de catalogue OpenAI
GET	`/api/v1/vscode/{token}/models`	Alias de modèles OpenAI
POST	`/api/v1/vscode/{token}/chat/completions`	Alias tokenisé OpenAI
POST	`/api/v1/vscode/{token}/responses`	Alias tokenisé des réponses OpenAI
POST	`/api/v1/vscode/{token}/api/chat`	Alias tokenisé Ollama
GET	`/api/v1/vscode/{token}/api/tags`	Alias tokenisé des tags Ollama

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). Un code 4xx est renvoyé 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 via la compatibilité de la chaîne de requête (?token=..., ?apiKey=..., ?api_key=..., ?key=...) ou les points de terminaison dédiés /api/v1/vscode/{token}/... documentés ci-dessous.

# Rerank (fournisseur de registre cloud, ou un nœud de fournisseur compatible OpenAI sous la forme "&lt;prefix&gt;/&lt;model&gt;")
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

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

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

# Recherche Jina (s.jina.ai ; alias de fournisseur : jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

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

# TTS — renvoie le corps audio/mpeg (ou 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 de vidéo / musique (ID 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 de fournisseur Rerank : POST /v1/rerank achemine également vers des nœuds de fournisseur compatibles OpenAI (oMLX, vLLM, Infinity, TEI derrière une passerelle, …) adressés sous la forme <node-prefix>/<model>. Les nœuds de bouclage (localhost, 127.0.0.1, 172.16.0.0/12) sont toujours éligibles. Les nœuds sur tout autre hôte — une machine LAN ou un pair Tailscale — ne sont éligibles 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 d’URL sortante du fournisseur (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS / OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS) ; les hôtes de métadonnées cloud ne sont jamais acheminés. L’étape de rerank du moteur de mémoire appelle cette route via le bouclage, donc la même règle régit rerankProviderModel dans les paramètres de la mémoire.

Formes de serveur local : le nœud est appelé à <base>/v1/rerank et, en cas de 404, à <base>/rerank (Infinity, TEI). Le corps en amont contient à la fois l’orthographe Cohere/OpenAI (documents, return_documents) et l’orthographe TEI (texts, return_text), et la réponse en amont est normalisée à l’enveloppe Cohere : [{index, score, text}] nu de TEI, {results: [{index, score}]} des passerelles légères, et {data: [...]} de style Voyage reviennent tous au client sous la forme {results: [{index, relevance_score, document?}]}, triés par score et plafonnés à top_n.

Découverte des nœuds de fournisseur : les modèles sur un nœud de fournisseur compatible OpenAI apparaissent dans GET /v1/models sous le préfixe du nœud. Les lignes qui ne contiennent pas de métadonnées de point de terminaison (typiques pour les listes /v1/models locales) héritent de l’apiType du nœud, de sorte que les modèles d’un nœud embeddings sont de type: "embedding" et les modèles d’un nœud rerank sont de type: "rerank" au lieu de la valeur par défaut “chat” ; un supportedEndpoints explicite sur une ligne synchronisée ou ajoutée manuellement a toujours la priorité.

Routes de fournisseur dédiées

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

Le préfixe du fournisseur est automatiquement ajouté s’il est manquant. 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

Le client envoie une requête à /v1/*
Le gestionnaire de route appelle handleChat, handleEmbedding, handleAudioTranscription ou handleImageGeneration
Le modèle est résolu (fournisseur/modèle direct ou alias/combo)
Les identifiants sont sélectionnés depuis la base de données locale avec filtrage selon la disponibilité des comptes
Pour le chat : handleChatCore vérifie le cache sémantique/de signature et résout les paramètres de compression du combo
La compression proactive s’exécute avant la traduction pour le fournisseur lorsqu’elle est activée (lite, Caveman, RTK ou empilée)
L’exécuteur du fournisseur envoie la requête en amont
La réponse est retraduite au format du client (chat) ou renvoyée telle quelle (embeddings/images/audio)
L’utilisation, les analyses de compression et les journaux de requêtes sont enregistrés
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.

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, 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 (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=<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).

Code source d’OmniRoute (a58000c7685f)

HagiCode

HagiCode est un espace de développement agentique qui associe workflows structurés, exécution multi-agent et vues Hero Dungeon.

Transformez vos idées en logiciels utiles grâce à un workflow agentique plus intelligent, rapide et agréable.

Interface principale de HagiCode en thème clair

SmartDes workflows structurés transforment une intention en parcours exécutable, de l’idée à la livraison.
EfficientLes workflows multi-agents font avancer recherche, réalisation et revue en parallèle.
FunHero Dungeon rend les longues sessions de code plus visuelles et collaboratives.

Visiter HagiCode

API Reference (Français)

Table des matières

Complétions de chat

En-têtes personnalisés

Baux de session gérés exclusifs

x-omniroute-compression

Embeddings

Génération d’images

OCR de documents

Flux d’interrogation d’Azure Document Intelligence

Authentification et résolution du point de terminaison Vertex AI DeepSeek OCR

Lister les modèles

Préfixes des identifiants de modèle (?prefix=)

Variantes de modèles sans raisonnement

Manifeste des plugins de fournisseurs

Points de terminaison de compatibilité

Routes de fournisseur dédiées

API Files

API Batches

API de recherche

API de récupération Web

Diffusion WebSocket

API Responses via WebSocket (codex uniquement)

Identifiant du modèle : utilisez l’identifiant ChatGPT brut (sans préfixe codex/)

Configuration de l’interface en ligne de commande Codex d’OpenAI

Quotas et signalement des problèmes

Utilisation en libre-service (/api/usage/om-usage)

Cache sémantique

Impact sur la latence

Contournement du cache par clé

Contournement par requête

Tableau de bord et gestion

Authentification

Gestion des fournisseurs

Flux OAuth

Routage et configuration

Utilisation et analyses

Paramètres

Contexte et compression

Surveillance

Sauvegarde et exportation/importation

Synchronisation cloud

Tunnels

Outils CLI

Agents ACP

Résilience et limites de débit

Évaluations

Politiques

Conformité

v1beta (compatible avec Gemini)

API internes / système

Réparation de l’environnement OAuth (v3.6.1+)

Transcription audio

Compatibilité avec Ollama

Alias avec jeton pour VS Code / sans en-tête

Télémétrie

Budget

Limites de jetons

Traitement des requêtes

Gestion des combos

Webhooks

Clés enregistrées (gestion automatique)

Protocole des agents

Proxys de gestion

Résilience (étendue)

Compétences

Mémoire

Serveur MCP

Serveur A2A

JSON-RPC

Fiche de l’agent

Assistants REST

Cloud, évaluations et appréciations

Gestion d’ACP (Agent Client Protocol)

Analytique et observabilité

Analytique du routage automatique

Analytique de la compression

Suivi de la diversité des fournisseurs

Opérations d’administration

Gestion des outils CLI

`x-omniroute-compression`

Préfixes des identifiants de modèle (`?prefix=`)

Identifiant du modèle : utilisez l’identifiant ChatGPT brut (sans préfixe `codex/`)

Utilisation en libre-service (`/api/usage/om-usage`)