Aller au contenu

API de gestion

L’API de gestion constitue le plan de contrôle d’opencodex. Le tableau de bord accessible à http://localhost:10100 en est l’un des clients ; les commandes ocx sans interface graphique qui gèrent les fournisseurs, les modèles, les combinaisons, les comptes, les paramètres, les diagnostics et le cycle de vie en sont également clientes. L’API n’est disponible que lorsque le proxy est en cours d’exécution.

Utilisez le tableau de bord web comme client interactif, ou cette référence pour créer des automatisations. Les valeurs persistantes obéissent en dernier ressort à la configuration.

L’API de gestion possède son propre identifiant d’administrateur, indépendant des clés API du plan de données. Au démarrage, opencodex le détermine dans l’ordre suivant :

  1. OPENCODEX_ADMIN_AUTH_TOKEN, lorsqu’il est défini.
  2. Un jeton ocx_admin_* généré dans un fichier secret renforcé.

Le jeton stocké dans un fichier n’est accepté qu’après le durcissement des autorisations ou des listes de contrôle d’accès (ACL) du répertoire et du fichier. Si cette protection ne peut pas être garantie, l’authentification de gestion échoue de manière sûre et l’API renvoie 503 jusqu’à ce qu’un jeton soit fourni par l’environnement ou que l’état du fichier soit corrigé.

Envoyez le jeton d’administrateur sous l’une ou l’autre forme :

X-OpenCodex-API-Key: <admin-token>
Authorization: Bearer <admin-token>

Sessions du tableau de bord sur l’interface de bouclage

Section intitulée « Sessions du tableau de bord sur l’interface de bouclage »

Sur une liaison de bouclage, l’amorçage du tableau de bord peut recevoir un identifiant ocx_session_* de courte durée. Chaque session dure cinq minutes et est liée à l’origine exacte du tableau de bord. Les requêtes sûres doivent correspondre à cette origine. Les méthodes non sûres exigent également l’en-tête Origin du navigateur et le jeton CSRF de la session.

L’émission de sessions est désactivée dès que l’authentification du plan de données est requise, notamment pour les liaisons distantes. Un opérateur distant doit s’authentifier avec le jeton d’administrateur brut ; aucune session d’interface graphique propre au bouclage n’est créée.

Toutes les lignes de points de terminaison ci-dessous héritent de ces erreurs de périmètre. La colonne « Erreurs notables » répertorie les résultats propres à chaque route, sans répéter ce tableau.

Statut Type ou code Signification
401 opencodex admin token required Le jeton d’administrateur ou la session d’interface graphique est absent, invalide, expiré, associé à une autre origine, ou la preuve CSRF est manquante
403 cross-origin request blocked L’origine de la demande se trouve en dehors de la liste autorisée de gestion
404 not_found Aucune route de gestion ne correspond à la méthode et au chemin
413 request body too large Un corps POST, PUT ou PATCH dépasse la limite de gestion de 2 MiB
503 management API unavailable L’initialisation ou le renforcement des informations d’identification d’administrateur n’est pas disponible
503 oauth_mutation_busy Une autre modification des identifiants OAuth détient le verrou d’écriture ; la réponse comprend Retry-After: 1
503 catalog_busy La collecte du catalogue est déjà à pleine capacité ; la réponse comprend Retry-After: 1
Méthode et chemin Objectif Erreurs notables
GET, PUT /api/v2 Lire ou modifier le mode multi-agent v2 natif et les paramètres de tâche 400 paramètres invalides ; 502 échec de transition ou de persistance
GET, PUT /api/injection-model Lire ou définir les paramètres du modèle de sous-agent injecté, de l’effort, de l’invite et du guidage 400 modèle, effort ou corps invalide
GET, PUT /api/effort-caps Lire ou définir les plafonds d’effort de raisonnement globaux et sous-agents 400 valeur d’échelle invalide
GET, PUT /api/subagent-models Lire ou ordonner les modèles annoncés aux sous-agents 400 liste invalide ou plus de cinq modèles
GET, PUT /api/subagent-model-fallback Lire ou définir la chaîne de secours ordonnée et l’intervalle d’interrogation 400 liste ou intervalle d’interrogation invalide
GET /api/grok Lire l’état de la configuration Grok gérée et les modèles candidats 400 échec de lecture de l’état
PUT /api/grok/selection Persister les modèles Grok exclus 400 sélection invalide ou surdimensionnée
POST /api/grok/apply Appliquer la configuration Grok persistante par la synchronisation gérée 409 grok_apply_busy ; 400/500 échec de l’application
GET /api/grok/reset-coupons?accountId=... Lire les jetons de réinitialisation de facturation Grok restants et leurs fenêtres de validité pour le compte xAI actif ou spécifié 400 compte manquant ; 401 non authentifié ; 502 erreur gRPC-Web en amont
POST /api/grok/reset-coupons/consume Échanger un coupon de réinitialisation éligible. Corps { accountId?, tokenId?, operationId? }. L’operationId facultatif (UUIDv4) rend l’échange idempotent : répéter le même identifiant rejoue le résultat durable sans double échange. 400 JSON/UUID invalide ; 401 non authentifié ; 409 operation_id_owned_by_another_account / coupon_unavailable / operation_token_mismatch / operation_state_changed / attempt_in_progress / attempt_unresolved ; 502 erreur en amont ; 503 capacité du registre / ledger_unavailable; 500 attempt_mark_failed
GET /api/anthropic/reset-grants?accountId=... Lire les réinitialisations des limites d’utilisation de Claude pour un compte OAuth Anthropic : son admissibilité, le nombre de réinitialisations restantes pour chaque attribution, sa période de validité et les fenêtres qu’elle remet à zéro, ainsi que toute tentative non confirmée pouvant encore être relancée 400 aucun compte correspondant ; 401 nouvelle authentification requise ; 502 service en amont indisponible
POST /api/anthropic/reset-grants/consume Utiliser une réinitialisation. Corps { accountId, grantId, operationId } ; operationId est un UUIDv4 envoyé en amont comme identifiant de requête : le répéter relance la même demande. Nécessite une session du tableau de bord. 400 corps invalide ; 401 nouvelle authentification requise ; 403 session_required ; 409 grant_not_usable, in_flight, unresolved_prior_operation, unknown_outcome_expired, operation_identity_mismatch ; 500 journal_write_failed ; 502 unknown_outcome ; 503 journal occupé, indisponible ou saturé
GET, PUT /api/claude-desktop Lire ou enregistrer le profil Claude Desktop routé ou natif 400 affectation invalide ou indisponible
POST /api/claude-desktop/apply Écrire le profil enregistré dans la configuration gérée de Claude Desktop 400/500 échec d’écriture
GET /api/claude-desktop/status Inspecter le profil enregistré par rapport à celui appliqué et l’état du bureau 400 échec de lecture de l’état
GET, PUT /api/claude-code Lire ou mettre à jour les paramètres de passerelle, de mode d’authentification, de correspondance des modèles, de contexte, d’agent et de service auxiliaire 400 champ ou structure invalide

Si tokenId est fourni, il doit être une chaîne non vide ; sinon la requête renvoie 400 invalid_token_id avant de lire les identifiants ou d’ouvrir le journal. Pendant les 30 jours de conservation, une reprise du même operationId sans accountId utilise le compte enregistré, même si le compte actif a changé. Une opération open exécutable sans tokenId reprend le token enregistré. Un autre compte ou token explicite reste refusé. Après un échec définitif, le tableau de bord libère le blocage provisoire correspondant pour permettre une nouvelle tentative expressément confirmée ; les résultats réellement incertains restent bloqués.

La tentative est enregistrée durablement avant l’échange. Seule une réponse de succès confirmée par le service en amont permet d’enregistrer redeemed ; la disparition du coupon de la liste ne prouve pas que cette opération a réussi. Après un délai dépassé ou un résultat non enregistré, les nouvelles requêtes vérifient seulement la disponibilité, sans nouvel échange, et renvoient attempt_unresolved. Une tentative récente renvoie attempt_in_progress. Un refus issu d’une inspection tardive ne peut régler qu’une opération encore open. Dans la même transaction, un résultat final confirmé dont le compte et le jeton correspondent est rejoué avec HTTP 200 et son code d’origine. Un résultat non confirmé ou une identité différente renvoie operation_state_changed ; conservez le même identifiant pour la récupération. Un registre illisible ou verrouillé renvoie ledger_unavailable sans lancer d’échange.

Un échange non confirmé renvoie HTTP 502 avec error.code: "attempt_unresolved" et l’operationId effectif. Conservez cet identifiant : un nouvel identifiant lancerait une autre opération. La CLI crée l’identifiant avant l’envoi et indique de conserver le même --operation-id si la livraison ou la réponse est incertaine. Les anciens enregistrements open du registre version un et les redeem_failed non confirmés sont isolés comme tentatives incertaines et n’autorisent aucun nouvel échange.

Dans Providers > xAI Grok > Accounts, le badge de ticket de chaque compte affiche les coupons restants et leurs fenêtres de validité. Le dialogue envoie un operationId créé par le client. Si la livraison ou le résultat est incertain, le tableau de bord conserve cette tentative pendant la session de l’onglet du navigateur, même après fermeture puis réouverture du dialogue, changement de page ou rechargement. Cette retenue est enregistrée avant l’envoi de la requête et n’est levée que par une réponse définitive pour le même operationId. L’actualisation utilise uniquement GET et n’autorise aucun autre POST d’échange. ocx account grok-reset-coupons est l’équivalent en terminal.

Les réinitialisations de l’utilisation de Claude fonctionnent de la même manière depuis Providers > Anthropic > Accounts. Chaque ligne de compte connecté porte un badge de ticket indiquant le nombre de réinitialisations restantes, et la boîte de dialogue en utilise une après une seconde confirmation. Une réinitialisation recharge les limites sur 5 heures et sur une semaine sans déplacer le jour de réinitialisation hebdomadaire. Si une demande ne reçoit pas de réponse, la boîte de dialogue conserve son operationId et propose de réessayer avec le même identifiant pendant dix minutes, comme le fait le client Claude Code pour reprendre une demande ; toute nouvelle opération pour la même attribution est refusée jusque-là. L’utilisation est réservée au tableau de bord : le jeton administrateur seul reçoit 403 session_required.

Pour comprendre la liste de modèles et le comportement chiffré des tâches confiées aux agents d’exécution, voir Surface des sous-agents.

Journal de restauration des intégrations clientes

Section intitulée « Journal de restauration des intégrations clientes »
Méthode et chemin Objectif Erreurs notables
GET /api/client-integrations/journal?client=... Lister les opérations de restauration, éventuellement pour un seul client. Chaque ligne contient le champ deletable calculé par le serveur. 400 client invalide
DELETE /api/client-integrations/journal?opId=... Retirer une ancienne opération et supprimer son instantané si possible. La réponse contient snapshotRemoved ; false conserve le nettoyage pour une nouvelle tentative de maintenance. 400 opId absent ; 404 opération absente ou déjà retirée ; 409 opération la plus récente du client

Une prévisualisation montre ce qu’une modification ferait sans la faire. Ces routes n’écrivent rien : ni instantané, ni enregistrement de propriété, ni ligne de journal, ni verrou, ni maintenance, ni récupération.

Méthode et chemin Objet Erreurs notables
POST /api/client-integrations/preview Planifier apply, overwrite ou disable pour un client ; corps { "clientId": "...", "operation": "..." } 400 client ou opération invalide ; 400 invalid_aside_profile_path; 409 integration_preview_unavailable
POST /api/client-integrations/restore/preview Planifier une annulation ; corps { "opId": "...", "confirmDrift": false } 404 opération inconnue ; 400 invalid_aside_profile_path; 409 integration_preview_unavailable
POST /api/client-integrations/aside/profiles/{profileId}/preview Planifier la modification d’un seul profil Aside ; restore exige un opId 400 corps invalide ou profil non précisé ; 404 profil ou opération inconnus; 409 integration_preview_unavailable

Un plan contient version, clientId, operation, state, foreignEdit, une liste changes de paires kind et path, une empreinte fingerprint opaque, canApply, willChange, ainsi que refusalReason et profileId facultatifs. Les chemins sont des chemins de schéma gérés ou les marqueurs fixes $snapshot, $ownership et $journal ; une position déterminée à l’exécution apparaît comme *. Aucune valeur de configuration, aucun emplacement de fichier et aucune identité d’élément sélectionné n’est renvoyé.

canApply à vrai avec willChange à faux signifie que l’opération réussit sans rien changer dans le document client géré, par exemple appliquer ce qui est déjà appliqué.

Une modification de profil Aside enregistre tout de même une chose dans ce cas : la confirmation enregistre la préférence de synchronisation du profil avant de toucher au moindre document client. Désactiver un profil dont le bloc géré est déjà absent enregistre donc la préférence et laisse le document et son historique intacts.

integration_preview_unavailable indique qu’aucune liste de modèles utilisable n’est actuellement conservée : un proxy qui vient de démarrer est un cas, une liste abandonnée parce que la configuration ou le cache de fournisseurs a changé en est un autre. Lire GET /api/client-integrations en établit une lorsque la découverte réussit et que la configuration peut être identifiée ; c’est le remède habituel, pas une garantie.

Les routes de modification acceptent operation et planFingerprint à côté de leur corps habituel. Envoyez les deux ou aucun : une requête n’en portant qu’un est rejetée, tout comme une requête dont l’operation contredit la modification demandée. Une liaison Aside porte sur un seul profil, car une empreinte ne peut pas décrire plusieurs fichiers qui changent indépendamment.

Le serveur replanifie avant d’écrire et renvoie 409 integration_preview_stale avec un plan recalculé lorsque la confirmation ne décrit plus ce qui se produirait. Décidez de nouveau d’après ce plan ; la requête n’est pas réessayée automatiquement.

Une empreinte est une vérification optimiste, jamais une autorisation. L’authentification de l’API d’administration et les règles de propriété décident seules si une modification peut avoir lieu.

La suppression ajoute une pierre tombale au lieu de réécrire le journal. Le serveur protège l’opération la plus récente de chaque client afin de conserver le point d’annulation actuel.

Méthode et chemin Objectif Erreurs notables
GET /api/combos Répertorier les combinaisons normalisées et leurs identifiants de modèle publics Le traitement du catalogue peut renvoyer catalog_busy
PUT /api/combos Créer, remplacer ou renommer un combo 400 identifiant, cible, configuration, renommage ou collision ordinaire invalide ; 409 Collision d’espace de noms de compte Codex
DELETE /api/combos?id=... Supprimer une combinaison et effacer son état de sélection et de temporisation 400 identifiant manquant ; 404 combinaison inconnue

Voir Combos pour les stratégies cibles, les temps de recharge, les alias et les échecs de routage.

Méthode et chemin Objectif Erreurs notables
GET /api/codex-prompt Lire l’instantané des couches de prompt : couches, variantes de base, sélection et état de drift —
GET /api/codex-prompt/text Sonder le texte du prompt visible par le modèle via codex debug prompt-input Fail-soft : une sonde indisponible se dégrade en statut dans le corps, pas en erreur HTTP
PUT /api/codex-prompt/toggle Activer ou désactiver une couche commutable 400 corps invalide ou couche inconnue ; 409 stale_revision, layer_not_toggleable
PUT /api/codex-prompt/custom Remplacer l’ensemble des couches personnalisées 400 corps invalide, invalid_characters, body_too_large quand une couche UTF-8 normalisée dépasse 65 536 octets, composed_too_large au-delà de 131 072 octets ; 409 stale_revision
PUT /api/codex-prompt/base/select Sélectionner le prompt de base par défaut ou une variante enregistrée 400 corps invalide, unknown_layer pour un id qui ne correspond à aucune variante enregistrée ; 409 stale_revision, developer_instructions_not_owned quand la base actuelle est externe
PUT /api/codex-prompt/base Créer (id omis ou id: null), modifier ou supprimer (delete: true) une variante de base. Un id fourni est réservé à la modification et doit référencer une variante enregistrée. body est normalisé (tabulations expansées, CR/CRLF convertis en LF) avant d’être mesuré ou stocké 400 corps invalide, unknown_layer pour l’id default ou un id qui ne correspond à aucune variante enregistrée, body_too_large quand le corps UTF-8 normalisé dépasse 65 536 octets ; 409 stale_revision
POST /api/codex-prompt/adopt Importer developer_instructions de config.toml comme couche personnalisée 400 corps invalide, invalid_characters, body_too_large, composed_too_large ; 409 config_unreadable, nothing_to_adopt, adopt_unsupported_form, stale_revision
POST /api/codex-prompt/repair Réparer le drift entre config.toml et la projection possédée 400 corps invalide ; 409 config_unreadable, nothing_to_repair, repair_unsupported, stale_revision

Voir Couches de prompt Codex pour le modèle de couches et les clés écrites par chacune.

Configuration, démarrage, synchronisation et mises à jour

Section intitulée « Configuration, démarrage, synchronisation et mises à jour »
Méthode et chemin Objectif Erreurs notables
GET /api/config Renvoyer l’objet de transfert de configuration expurgé et sécurisé pour la gestion —
PUT /api/config Toujours refusé : le remplacement intégral de la configuration est désactivé 405 ; utiliser les points de terminaison ciblés, notamment POST /api/providers pour les fournisseurs
GET, PUT /api/settings Lire les paramètres d’exécution et de démarrage, ou mettre à jour le démarrage automatique, le mode de diffusion, le budget mémoire propre à l’application et codexAccountPickerEnabled 400 mise à jour invalide, vide ou qui n’est pas un objet
GET /api/startup-health Lire l’état de santé du service et du lanceur intermédiaire, mis en cache au démarrage —
POST /api/startup-action Installer ou réparer le service ou le lanceur intermédiaire Codex 400 action invalide ; 500 échec de l’action
GET, POST /api/windows-tray Lire l’état de l’icône de notification Windows, ou l’installer, la démarrer, l’arrêter ou la désinstaller 400 plateforme ou action non prise en charge ; 500 échec de l’opération
GET /api/diagnostics/project-config Lire les avertissements de configuration du projet mis en cache —
POST /api/sync Synchroniser le catalogue de modèles actuel dans Codex 500 échec de synchronisation
GET /api/update/check Vérifier de façon asynchrone le canal latest ou preview et actualiser le cache du paquet en cas de succès 400 balise invalide
POST /api/update/run Vérifier de façon asynchrone la dernière version du paquet, puis démarrer une tâche de mise à jour, suivie éventuellement d’un redémarrage 400 corps invalide ; état de conflit ou d’erreur propre à la tâche
GET /api/update/status Interroger une tâche de mise à jour par identifiant 404 tâche inconnue
GET, PUT /api/sidecar-settings Lire ou mettre à jour les paramètres de modèle et de moteur des services auxiliaires de recherche Web et de vision 400 structure, moteur ou limite invalide
GET, PUT /api/shadow-call-settings Lire ou mettre à jour les paramètres d’interception d’appels fantômes 400 forme ou valeur invalide

Les journaux de requêtes conservent servedModel lorsque le fournisseur en amont indique le modèle qui a répondu, et wireModel lorsque le modèle envoyé en amont diffère de celui présenté au client. Le tableau de bord affiche wire → served si ces modèles diffèrent ; l’infobulle conserve les deux valeurs. En l’absence d’indication du modèle par le fournisseur en amont, cette information reste absente : elle n’est pas déduite du modèle demandé.

Méthode et chemin Objectif Erreurs notables
GET /api/logs Requête filtrée dans les journaux de requêtes en mémoire —
GET, PUT /api/debug Lire les indicateurs de débogage ; définir, effacer ou réinitialiser les catégories de capture 400 mise à jour invalide ou vide
GET /api/debug/logs Lire un nombre limité d’entrées de journal des fournisseurs et du débogage —
GET /api/debug/usage-logs Lire un nombre limité d’entrées de débogage de l’utilisation —
GET /api/debug/injection-logs Lire un nombre limité d’entrées de débogage de l’injection du guidage —
GET /api/claude/inbound-debug Lire l’état et les entrées du débogage entrant —
GET /api/usage Résumer l’utilisation par période et par interface cliente ; les réponses Codex comprennent aussi une ventilation accounts indexée par des libellés de journalisation stables ne contenant aucune donnée personnelle Renvoie 500 { "error": "read_failed" } si le stockage ne peut pas être lu
GET /api/metrics Renvoyer les métriques texte Prometheus locales au processus : requêtes logiques, envois physiques, types de récupération, durée et TTFT. Les métriques de requêtes utilisent des libellés fermés ; les jauges Kiro ajoutent uniquement un libellé de compte opaque et borné ; aucun identifiant de requête ou d’identifiant secret n’est exporté. Les quatre jauges opencodex_kiro_quota_{used_credits,limit_credits,used_percent,seconds_to_reset} lisent uniquement le cache et utilisent au plus 32 étiquettes de compte opaques. Aucune sonde réseau lors de la collecte. 404 si metricsExport.enabled n’était pas vrai au démarrage ; l’authentification de gestion est obligatoire et les identifiants du plan de données ne donnent aucun accès
GET /api/storage Analyser l’utilisation du stockage Codex par catégorie Renvoie une charge utile error: "scan_failed" en cas d’échec de l’analyse
POST /api/storage/cleanup/preview Prévisualiser le nettoyage des sessions archivées et renvoyer une empreinte contraignante 400 invalid_json ou invalid_percent
POST /api/storage/cleanup Mettre en quarantaine ou supprimer définitivement l’ensemble archivé prévisualisé 400 saisie invalide ; 409 état obsolète, occupé ou référencé ; 500 échec du système de fichiers ou de la base de données
GET /api/storage/trash Répertorier les entrées de nettoyage mises en quarantaine 500 trash_list_failed
POST /api/storage/trash/restore Restaurer une entrée en quarantaine 400 identifiant invalide ; 404 entrée absente de la corbeille ; 409 opération occupée ou conflit de destination ; 500 échec de la restauration
GET /api/storage/trash/restore/test-stream Point d’ancrage du flux de restauration réservé aux tests 404 not_available lorsque les points d’ancrage de test sont désactivés
GET, PUT /api/storage/cleanup-policy Lire ou mettre à jour la stratégie de nettoyage planifié et l’état du travail 400 politique invalide
POST /api/storage/cleanup-policy/run Démarrer une exécution manuelle de la politique de nettoyage 409 already_running ; 500 cleanup_failed
GET /api/storage/cleanup-policy/test-stream Point d’ancrage du flux de stratégie réservé aux tests 404 not_found en cas d’indisponibilité

Si une ligne dépasse la limite de taille du parseur, GET /api/usage et GET /api/keys conservent les agrégats lisibles et ajoutent usageIncomplete: true avec usageIncompleteReason: "oversized_rows" au niveau de la réponse. Ce diagnostic reste présent dans le cache et après les ajouts incrémentaux, même sans résultat ni correspondance de filtre ; une reconstruction le recalcule. Les identifiants de fournisseur, de modèle et de clé API ne sont pas raccourcis. L’absence du champ ne prouve pas la validité de toutes les lignes. Ce signal est distinct de historyTruncated, entriesTruncated et de la couverture de mesure des tokens.

Pour GET /api/usage?range=30d&surface=codex, accounts contient une ligne par libellé de pool Codex observé. Chaque ligne indique accountLogLabel, le total de jetons, usageCoverageRatio et une valeur facultative estimatedCostUsd calculée selon les tarifs d’affichage actuellement configurés. Les substitutions modelCosts actives de l’utilisateur sont prioritaires sur le catalogue vérifié fourni et sur les tarifs de repli ; l’utilisation historique est réestimée d’après la tarification active au moment de la lecture du résumé. Il s’agit d’une estimation équivalente à un usage d’API, et non de frais d’abonnement. Les nouvelles requêtes du pool principal utilisent le libellé réservé main ; les anciennes lignes openai sans qualification restent dans une catégorie ambiguë au lieu d’être réaffectées d’après la configuration actuelle.

Les lignes de models, providers et days[].models comportent également cacheHitRate : la part des jetons d’entrée servis depuis le cache d’invites du fournisseur, limitée à [0, 1]. Cette valeur est null — jamais 0 — lorsque le fournisseur n’a transmis aucune télémétrie de cache ou que la ligne ne contient aucun jeton d’entrée, car « aucune donnée de cache » et « un véritable taux de succès de 0 % » sont deux faits distincts, et un graphique qui les représente de la même manière est trompeur.

Méthode et chemin Objectif Erreurs notables
GET /api/catalog Renvoyer le document catalogue Codex installé 404 catalogue introuvable
GET /api/models Renvoyer les lignes de modèles destinées au tableau de bord et à l’interface en ligne de commande catalog_busy lorsque la collecte est saturée
GET /api/client-config?client=... Créez une configuration client en lecture seule pour toute intégration de fichiers prise en charge 400 client non pris en charge ; 503 catalogue indisponible
PUT /api/disabled-models Remplacer la liste partagée des modèles désactivés 400 invalide JSON
PUT /api/model-visibility Modifier atomiquement la visibilité au niveau du fournisseur ou du modèle 400 fournisseur, portée, cible ou corps non valide; 409 initial_model_selection_pending (Actualisez la liste des modèles, puis réessayez.)
GET, POST /api/custom-models Répertoriez les modèles personnalisés ou ajoutez-en un 400 champs invalides ; 404 fournisseur manquant ; 409 dupliquer le modèle
PUT, DELETE /api/custom-models/{id} Modifier ou supprimer un modèle personnalisé 400 invalide id/fields ; 404 introuvable ; 409 modèle en double
GET, PUT /api/selected-models Lire les listes autorisées et la disponibilité des fournisseurs, ou remplacer une liste autorisée 400 fournisseur ou corps manquant ; 404 fournisseur inconnu; PUT 409 initial_model_selection_pending
GET, PUT /api/model-presets Lire les préréglages ou choisir le mode preset/all/custom 400 mode invalide ou préréglage indisponible; 404 fournisseur inconnu; PUT 409 initial_model_selection_pending

Un modèle manuel remplace la ligne du tableau de bord Models ayant le même fournisseur et identifiant de modèle. Pour OpenAI, la ligne manuelle conserve openai/<model> et ses contrôles de visibilité. Sa suppression restaure la ligne native sans qualificatif de compte. Les lignes natives qualifiées par compte restent distinctes. Les routes natives et les droits du compte ne changent pas. Une cible de visibilité OpenAI non native doit correspondre à un modèle manuel configuré.

Tant qu’une liste initiale fiable n’est pas disponible, les requêtes PUT valides vers /api/selected-models et /api/model-presets renvoient HTTP 409 avec le code initial_model_selection_pending. Actualisez la découverte des modèles (par exemple, GET /api/models), puis réessayez après sa réussite.

Comptes OAuth, clés de fournisseur et clés du plan de données

Section intitulée « Comptes OAuth, clés de fournisseur et clés du plan de données »
Méthode et chemin Objectif Erreurs notables
GET /api/oauth/providers Répertorier les fournisseurs avec des flux de connexion publics OAuth —
GET /api/key-providers Répertorier les fournisseurs configurés par connexion avec une clé API —
POST /api/oauth/login Démarrez un processus de connexion OAuth ou d’ajout de compte 400 unknown/invalid fournisseur ; oauth_mutation_busy
POST /api/oauth/login/code Soumettre manuellement une URL de rappel ou un code d’autorisation 400 fournisseur ou code invalide ; oauth_mutation_busy
POST /api/oauth/login/cancel Annuler un flux OAuth public en cours 400 fournisseur inconnu
GET /api/oauth/status Sonder le flux OAuth d’un fournisseur 400 fournisseur inconnu
POST /api/oauth/logout Supprimer les informations d’identification du fournisseur sélectionné 400 fournisseur inconnu ; oauth_mutation_busy
GET, DELETE /api/oauth/accounts Répertorier les comptes masqués ou supprimer un compte Les lignes Kiro ajoutent autoSelectable et un skipReason fermé en cas d’exclusion de la sélection automatique ; un compte actif unique peut encore servir. Le quota reste facultatif. 400 invalide provider/id ; 404 compte manquant ; oauth_mutation_busy
PUT /api/oauth/accounts/active Sélectionnez le compte OAuth actif 400 invalide provider/account ; oauth_mutation_busy; 503 affinity_reset_not_persisted (Anthropic: selectionCommitted: true, retryable: true; sélection enregistrée ; renvoyer la même requête même si le compte est actif)
GET, PUT, PATCH /api/oauth/accounts/pool Lire ou mettre à jour la stratégie du pool OAuth Anthropic 400 fournisseur non Anthropic ou stratégie invalide
POST /api/oauth/accounts/clear-cooldown Effacer le temps de recharge d’un compte OAuth 400 invalide provider/account
PUT /api/oauth/accounts/alias Définir ou supprimer un alias de compte OAuth 400 invalide provider/account/alias
PUT /api/oauth/accounts/pause Suspendre/reprendre Anthropic ou un compte OAuth générique. Body { provider, accountId, paused } ; la suspension du compte actif sélectionne un autre compte utilisable s’il existe. 400 fournisseur non pris en charge ou body invalide ; 404 compte absent ; oauth_mutation_busy; 503 affinity_reset_not_persisted (Anthropic: pauseCommitted: true, retryable: true; état de suspension enregistré ; conserver le compte et cet état, ajouter retryAffinityReset: true et réessayer, même après un redémarrage du serveur)
GET, POST, DELETE /api/providers/keys Répertorier les clés de fournisseur masquées, en ajouter ou en activer une, ou en supprimer une 400 saisie invalide ; 404 fournisseur ou clé manquante
PUT /api/providers/keys/active Sélectionnez la clé active d’un fournisseur 400 saisie invalide ; 404 provider/key manquant
PUT /api/providers/keys/alias Définir ou supprimer un alias de clé de fournisseur 400 saisie invalide ; 404 provider/key manquant
GET, POST, PATCH, DELETE /api/keys Répertorier, créer, modifier ou supprimer les clés d’admission du plan de données 400 corps ou identifiant invalide ; 404 clé manquante
PUT /api/oauth/accounts/affinity-reset Confirmer le reset des associations de conversations du provider sans exiger de compte. Body { provider } ; succès : affinityResetConfirmed: true. CLI: ocx account reset-affinity anthropic --json (anthropic2 supported). 400 invalid body/provider; 503 affinity_reset_not_persisted, retryable: true

Le tableau de bord conserve l’avertissement tant que la publication du reset n’est pas confirmée, même si le compte a disparu. Un échec de chargement, une suspension ou une réauthentification requise conserve la tentative avec un message. Une fois l’absence confirmée par la liste, Réessayer appelle PUT /api/oauth/accounts/affinity-reset avec { provider } et attend affinityResetConfirmed: true avant d’effacer l’avertissement. Cette opération supprime toutes les associations, y compris celles créées depuis le premier échec, sans sélectionner ni réactiver de compte ; une liste vide est acceptée. Une suppression avec un reset en attente envoie retryAffinityReset=true. En cas d’échec de publication, elle renvoie 503 affinity_reset_not_persisted, deletionCommitted: true et retryable: true. Le compte est déjà supprimé : réessayez le reset seul, pas la suppression. Une suppression ordinaire conserve les associations des comptes restants. Ce nettoyage est limité aux instances Anthropic OAuth enregistrées et conserve les contrôles d’authentification et d’origine de gestion.

Les réponses qui répertorient les identifiants sont délibérément masquées. Les jetons d’accès OAuth et les clés API complètes des fournisseurs ne sont pas renvoyés aux clients du tableau de bord.

La commande CLI suspend ou reprend un compte Anthropic OAuth par id ou alias unique (correspondance exacte, puis sans distinction de casse). Utilise PUT /api/oauth/accounts/pause avec { provider: "anthropic", accountId, paused }, également utilisé par le tableau de bord. L’état paused est enregistré dans le compte et exposé par GET /api/oauth/accounts. La suspension s’applique même si le pool proactif est désactivé : le compte est exclu de la sélection, des affinités et des successeurs 429. Si tous les comptes sont suspendus, les requêtes renvoient 403 jusqu’à une reprise. Les requêtes déjà envoyées continuent ; les identifiants et l’état de santé sont conservés. La suspension survit au redémarrage et à une nouvelle connexion, et disparaît avec la suppression du compte. Les seuils individuels ne font pas partie de cette commande.

Méthode et chemin Objectif Erreurs notables
GET /api/providers Répertorier la configuration du fournisseur expurgée et l’état de découverte —
POST /api/providers Ajouter ou remplacer un fournisseur validé et éventuellement le définir par défaut 400 destination invalide ou dangereuse, ou configuration invalide ; 409 collision d’espace de noms
PATCH /api/providers?name=... Mettre à jour les champs de fournisseur autorisés, notamment un bloc headers fusionné, l’état d’activation ou de fournisseur par défaut, ou le mode de compte OpenAI 400 champ ou transition invalide ; 404 fournisseur inconnu
DELETE /api/providers?name=... Supprimer un fournisseur, en réattribuant la valeur par défaut lorsque cela est possible 404 fournisseur inconnu ; 409 last_provider ; 409 provider_has_dependent_combos
POST /api/providers/test?name=... Effectuer une sonde en direct, limitée à la connectivité et à la découverte des modèles du fournisseur 404 fournisseur inconnu ; les échecs sont normalement renvoyés sous forme de résultat ok: false
GET /api/provider-quotas Lire les rapports de quotas des fournisseurs ; refresh=1 force le rafraîchissement —
GET, PUT /api/provider-context-caps Lire ou mettre à jour les plafonds de contexte globaux, communs à tous les fournisseurs ou propres à un fournisseur 400 requête invalide ; 404 fournisseur inconnu
GET /api/provider-presets Renvoyer les préréglages de fournisseur de l’interface graphique dérivés du registre d’exécution —

La réponse des plafonds de contexte comprend caps (limites actives) et values (dernières sélections, conservées après désactivation). Activer un fournisseur sans value restaure sa sélection, ou utilise la valeur globale contextCapValue lors de la première activation. Cela vaut aussi pour OpenAI : le commutateur ne sélectionne pas un mode spécial à 922k. Un plafond actif borne chaque fenêtre native ; les modèles prenant en charge un contexte long peuvent être étendus uniquement jusqu’à leur propre plafond pris en charge. { "value": 600000, "setAll": true } modifie la valeur globale et uniquement les plafonds actifs ; les fournisseurs dont le plafond est désactivé conservent leur sélection pour une réactivation ultérieure. { "setAll": true } sans value active tous les fournisseurs configurés à la valeur globale actuelle et remplace leurs sélections mémorisées. La désactivation conserve la sélection, même après rechargement, sans l’appliquer comme limite.

provider_has_dependent_combos est une barrière de sécurité : supprimez ou modifiez les combinaisons dépendantes avant de supprimer leur fournisseur.

Méthode et chemin Objectif Erreurs notables
GET /api/github/star Lire le statut de l’étoile du référentiel via la session gh de l’utilisateur Codes de résultat fixes spécifiques au statut
POST /api/github/star Ajouter une étoile au dépôt uniquement à la suite d’une action humaine authentifiée 403 agent_consent_required pour les appelants pilotés par un agent sans preuve de session du tableau de bord
GET /api/update/badge Lire le badge du paquet mis en cache sans interroger le registre ; un cache absent, d’un autre canal ou vieux de 40 heures renvoie unknown: true. surface=desktop&session=<id> ne lit que cette session de l’application de bureau. 400 surface invalide ; une session de bureau absente ou expirée renvoie unknown: true
POST /api/update/desktop-snapshot Le shell de bureau publie l’état d’affichage de son updater Tauri via le client proxy lié 403 si l’en-tête Origin est présent ou sans le principal brut admin-token ; 400 champs invalides ; 413 au-delà de 1 KiB

Le snapshot de bureau est un état d’affichage temporaire, pas une demande d’installation. Le proxy conserve au plus 32 sessions en mémoire et en expire une 180 secondes après son dernier heartbeat. Un navigateur ordinaire sans surface=desktop continue de lire le badge du paquet.

Le proxy vérifie les installations éligibles après le démarrage si le cache est absent ou vieux de plus de 20 heures, puis contrôle sa fraîcheur chaque heure. OCX_DISABLE_UPDATE_CHECK=1 désactive uniquement les vérifications automatiques. Les demandes explicites de vérification et de mise à jour restent disponibles.

POST /api/system/restart conserve par défaut un délai de 60 secondes lorsque le corps est absent ou vaut {}. Une session de gestion ou un jeton administrateur peut choisir explicitement un délai plus court avec {"drainGraceMs":2000} : la valeur doit être un entier compris entre 1 et 60000 millisecondes. Un corps ou une valeur invalide renvoie 400 sans lancer le redémarrage ; la capacité locale liée à la cible ne permet pas cette option (403). drainTimeoutMs indique le délai accepté, fixé par le premier appel et inchangé lors des appels suivants. Il inclut le temps de transmission de la réponse ; les budgets de nettoyage et de préparation du processus de remplacement restent respectivement de 60 et 70 secondes. Une requête interrompue peut déjà avoir été exécutée : vérifiez son résultat avant de la renvoyer, sans répétition automatique.

Méthode et chemin Objectif Erreurs notables
GET /api/system/memory Renvoyer les mesures scalaires du processus, du tas, des flux, de l’état des réponses, du mécanisme de surveillance et des tours actifs —
POST /api/system/restart Amorcer un redémarrage du processus qui attend l’évacuation des requêtes, sans retirer l’injection du client Renvoie 202 ; les appels répétés signalent l’évacuation déjà en cours
POST /api/stop Arrêter le service, restaurer Codex en mode natif, retirer l’injection Grok gérée et évacuer les requêtes du proxy 409 conflit de propriété du service; 409 respawnable_service lorsqu’un wrapper du Planificateur de tâches Windows pourrait relancer le proxy et que l’appelant n’est pas ocx stop (rien n’est modifié) ; 409 lorsque le gestionnaire installé refuse de s’arrêter ; 409 service_state_unknown lorsque l’état du Planificateur de tâches ne peut pas être lu (rien n’est modifié ; réparez la requête puis réessayez)
GET /api/system/codex-app-server Indiquer si les serveurs d’application Codex en cours d’exécution sont antérieurs au catalogue de modèles actuel —
POST /api/system/codex-restart Actualiser le catalogue, puis redémarrer les serveurs d’application Codex. Une application Codex Desktop en cours reçoit une tentative de redémarrage afin que le sélecteur de modèles puisse se recharger ; les champs desktopApp de la réponse signalent un refus, des cibles survivantes ou un échec de relance. Un processus plus récent que le catalogue est tout de même signalé avec desktopApp.pickerState: "unknown", car son heure de démarrage ne prouve pas quelle liaison model_catalog_json il a chargée ; une synchronisation antérieure peut avoir relié un catalogue déjà existant. Un processus qui n’est pas plus récent que le catalogue, ou dont cette requête a changé la liaison, est stale. Une application fermée renvoie desktopApp.reason: "no_targets" ; son pickerState peut être not_running, ou stale si cette requête a changé la liaison au catalogue. Lorsque le proxy lui-même s’exécute dans l’application Codex, le redémarrage Desktop est refusé plutôt que transféré. Renvoie 200 avec code: partially_stopped lorsqu’une cible ne s’arrête pas

GET /api/settings indique la valeur effective du booléen codexAccountPickerEnabled. Un PUT contenant strictement ce booléen initialise des sélecteurs de compte respectueux de la confidentialité lorsqu’une table vide est activée, préserve les libellés de sélection existants lors d’une désactivation ou d’une réactivation, enregistre d’abord les changements, puis demande une convergence limitée du catalogue uniquement si la visibilité effective du sélecteur a changé. La réponse en cas de réussite comprend catalogRefreshPending : false signifie que la validation du catalogue est terminée, ou qu’aucune actualisation n’était nécessaire ; true signifie que le paramètre a été enregistré, mais que POST /api/sync doit être utilisé pour retenter l’actualisation du catalogue. Un échec de l’enregistrement ou de l’attribution d’un sélecteur rétablit les paramètres en mémoire et n’exécute pas la convergence.

Le répartiteur racine de l’API de gestion délègue chaque requête /api/codex-auth/* au gestionnaire de comptes Codex. Ses routes sont les suivantes :

Méthode et chemin Objectif Erreurs notables
GET, POST, DELETE /api/codex-auth/accounts Répertorier, actualiser ou supprimer des comptes Codex. POST est conservé comme point de terminaison de compatibilité désactivé ; les réponses DELETE réussies incluent catalogRefreshPending. POST renvoie toujours 403 manual_import_disabled ; 400 entrée DELETE invalide
PUT /api/codex-auth/accounts/alias Définir ou supprimer un alias de compte 400 invalide account/alias
PUT /api/codex-auth/accounts/pause Suspendre ou reprendre manuellement un compte et ses entrées principales ou du pool existantes de même identité ; renvoie affectedAccountIds 400 compte/état invalide ; 404 compte introuvable ; 503 identité du compte principal occupée ou illisible
PUT /api/codex-auth/accounts/pause-exhausted Suspendre les comptes dont le quota est épuisé Les échecs de verrouillage de mutation deviennent 503
POST /api/codex-auth/accounts/clear-cooldown Effacer le temps de recharge d’exécution pour un compte ou tous les comptes 400 identifiant invalide
GET, PUT /api/codex-auth/active Lire ou sélectionner le compte actif 400 compte invalide ou manquant ; 409 conflit avec un compte suspendu ou une ancienne ligne
PUT /api/codex-auth/auto-switch Définir le seuil global avec { threshold } sans id, ou la valeur spécifique à un compte avec { id, threshold } ; id: '__main__' désigne le compte Codex Desktop. Avec un id, threshold: null supprime la valeur spécifique et rétablit l’héritage du seuil global 400 id/seuil invalide ; 404 compte absent
PUT, PATCH /api/codex-auth/pool-strategy Mettre à jour la stratégie de sélection du groupe de comptes Codex 400 stratégie ou configuration invalide
PUT /api/codex-auth/failover Définir le seuil de basculement du compte 400 seuil invalide
GET /api/codex-auth/quota Lire l’état du quota mis en cache par compte —
GET /api/codex-auth/reset-credits Inspecter l’éligibilité au crédit de réinitialisation pour un compte 400 identifiant de compte manquant ; transmission du statut en amont ; 500 échec de recherche
POST /api/codex-auth/reset-credits/consume Consommer un crédit de réinitialisation éligible. L’operationId facultatif (UUIDv4) rend la consommation idempotente : le même id rejoue un unique résultat durable au lieu de consommer un second crédit. 400 identifiant de compte manquant ou operationId invalide ; 409 identity_mismatch si l’id appartient à un autre compte ; transmission du statut en amont ; 503 server_busy, capacity ou unavailable ; 500 consommer l’échec
POST /api/codex-auth/login Démarrer une connexion ou une réauthentification Codex 400 requête invalide ; état de connexion en conflit ou occupé
POST /api/codex-auth/login/code Soumettre manuellement un code pour un flux de connexion Codex 400 flux ou code invalide
POST /api/codex-auth/login/cancel Annuler uniquement la connexion Codex en attente identifiée par { "flowId": "..." } 400 identifiant de flux absent, inconnu ou non en attente
GET /api/codex-auth/login-status Interrogez un flux ou un état de connexion à un compte. Un flux de nouveau compte terminé inclut catalogRefreshPending: true uniquement lorsque la récupération est nécessaire. Rapport de flux inconnus expired ; aucun rapport de flux actif idle

Si une nouvelle ligne de configuration de compte est enregistrée, mais que la mise en place des identifiants ne peut pas aboutir, le login-status OAuth indique status: "error" avec code: "codex_credential_persistence_failed", accountId, needsReauth: true et en option catalogRefreshPending: true ; les détails des erreurs de stockage ne sont pas exposés. La ligne du compte reste enregistrée : réauthentifiez-le ou supprimez-le avant de réessayer de créer un compte.

Les délais d’attente du verrou d’écriture de la configuration ou d’actualisation des identifiants dans cette famille de routes déléguées renvoient le statut HTTP 503 avec le code CONFIG_MUTATION_LOCK_UNAVAILABLE. Les clients doivent réessayer rapidement plutôt que de considérer cette réponse comme un échec de compte permanent.

La création et la suppression d’un compte valident les identifiants et la configuration avant la convergence du catalogue. Une tentative de catalogue différée ou en échec n’annule jamais la modification persistante du compte et ne révèle jamais de détails internes sur le fournisseur, le compte, le chemin ou les identifiants ; les clients ne reçoivent que le booléen d’achèvement. La suppression d’un compte conserve sa liaison au sélecteur : les routes exactes échouent ainsi de manière sûre tant que le compte est absent, et le même sélecteur est restauré si cet identifiant de compte est ajouté de nouveau.

Pour l’administration courante, le tableau de bord web offre le parcours guidé le plus sûr. Pour les hôtes sans interface graphique et l’automatisation, utilisez les commandes ocx correspondantes : elles appellent cette même API active et renvoient un code différent de zéro lorsque le proxy est inaccessible ou que l’opération échoue. L’accès HTTP direct est surtout utile aux intégrations qui exigent les contrats exacts des points de terminaison ci-dessus.

Sessions distantes et rotation des clés de données

Section intitulée « Sessions distantes et rotation des clés de données »

POST /api/keys/rotate {id} démarre un chevauchement de dix minutes et renvoie le nouveau secret une seule fois. POST /api/keys/rotate/commit {id,rotationId} valide; DELETE /api/keys/rotate {id,rotationId} annule. L’authentification de gestion est obligatoire et une clé de données ne suffit pas. POST /api/session/logout exige la gui-session courante, l’Origin correspondante et CSRF. Un jeton admin reçoit 403 et ne peut jamais créer une session de consentement.

PUT /api/oauth/accounts/auto-switch

Anthropic OAuth uniquement. { provider: "anthropic", accountId, threshold } : entier 0–100 ou null pour hériter ; champ absent invalide. Conservé au redémarrage, supprimé avec le compte.

Le DTO inclut autoSwitchThresholdOverride (entier/null), autoSwitchThreshold (défaut du pool) et effectiveAutoSwitchThreshold. 0 désactive seulement le basculement selon l’utilisation ; pause et reprise après 429 restent actives.

HTTP: 400 invalid/unsupported; 404 missing account; oauth_mutation_busy on lock contention.

The Subagents page offers Force all subagents onto one model, off by default. Select an exposed roster-style id, such as combo/tev-auto, then enable the switch. The roster is offered first; unavailable saved roster entries cannot be force targets.

ocx agent subagents force combo/tev-auto sets claudeCode.subagentModelForce; ocx agent subagents force - clears it. ocx agent status reports the setting. GET /api/subagent-models returns force, forceAvailable, and forceStatus; PUT accepts { "force": "combo/tev-auto" } or { "force": null } without changing the roster. Omitting force leaves it unchanged. Invalid or unexposed targets are rejected on write; stale targets are reported and skipped at launch.

This takes effect on the next routed ocx claude launch, injecting CLAUDE_CODE_SUBAGENT_MODEL as an explicit proxy alias (with [1m] only for an authoritative million-token window; native Claude targets use a reversible native alias) and CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1. Each nonempty shell-exported variable independently wins. Native launches inject neither variable; plain claude is not affected. No plugin files or settings.json are modified by this setting.

Claude Code 2.1.257 or newer is required for FORCE. Plugin and built-in agents (including Explore/Plan) and per-call model arguments are overridden. Forks and subagent skills with model: inherit keep the main conversation model. The main loop and Haiku/small-fast sidecars are unaffected. Existing roster files remain available.

The dashboard warns about old or unknown CLI versions, unavailable targets, and either variable already present in settings.json → env (which overrides launch env). Detection is read-only and server-local: it cannot inspect another launch shell, another machine, or project-local settings. An unknown result is not proof of force support.