API HTTP Gateway

La passerelle expose une surface REST aux côtés du CLI local. Tout ce qui peut être défini avec zeroclaw config get/set/list/init/migrate est également accessible via HTTP, de sorte que le tableau de bord, les outils tiers et le CLI pilotent tous le même cœur de mutation Config sous-jacent.

Cette page constitue une vue d’ensemble générale. Les définitions au niveau des champs, les structures des requêtes et des réponses, ainsi que les formulaires « Try it out » pour le sous-ensemble OpenAPI actuellement documenté se trouvent à /api/docs sur une passerelle en cours d’exécution. Ces schémas proviennent des types d’exécution, mais l’inventaire des routes est assemblé séparément et ne couvre pas encore toutes les routes enregistrées par la passerelle. Le routeur dans crates/zeroclaw-gateway/src/lib.rs reste la référence pour l’ensemble de la surface active.

Suivi dans le ticket #6175.

Authentification

Les lectures et mutations de valeurs de configuration décrites sur cette page sont soumises à l’authentification par appairage et par jeton bearer existante. La découverte de forme via /api/docs, /api/openapi.json, et OPTIONS de configuration est publique. Un code d’appairage de première exécution est affiché au démarrage du daemon ; les appels authentifiés suivants envoient le jeton bearer dérivé dans l’en-tête Authorization. L’explorateur Scalar disponible à /api/docs expose un panneau « Authentication » où vous collez le jeton avant d’émettre des appels authentifiés.

Limité au réseau local par défaut. L’accès via le réseau nécessite une terminaison TLS au niveau de la passerelle ou en amont de celle-ci ; les points de terminaison par propriété et PATCH ne peuvent pas être exposés sans authentification, quelle que soit la configuration TLS.

Explorer la surface

Deux endpoints répondent à la question « que puis-je faire ici ? » :

• OPTIONS /api/config retourne le schéma JSON pour le type de configuration globale. Statique par build ; les clients devraient mettre en cache en fonction de l’en-tête ETag. Son en-tête Allow actuel liste toujours l’ancien PUT, que le routeur n’enregistre pas.
• OPTIONS /api/config/prop?path=<dotted> renvoie le fragment de schéma pour un chemin spécifique avec Allow: GET, PUT, DELETE, OPTIONS. Renvoie 404 si le chemin n’existe pas dans le schéma.

OPTIONS renvoie les capacités. GET /api/config/prop et GET /api/config/list renvoient les valeurs actuelles de l’utilisateur. Les formulaires du tableau de bord émettent OPTIONS une fois au chargement pour connaître les types et les contraintes, puis GET pour remplir les champs, puis PUT/PATCH pour écrire. Une route de compatibilité GET /api/config renvoie également un instantané complet de la configuration avec les secrets masqués, afin que les anciennes pages du tableau de bord intégré ne rencontrent pas d’échec face à des passerelles plus récentes. Les nouveaux clients devraient privilégier la surface par propriété, car elle transporte les métadonnées des champs et une gestion explicite des secrets.

Les requêtes de pré-vérification CORS (celles portant l’en-tête Access-Control-Request-Method) reçoivent la réponse de pré-vérification standard et sont court-circuitées avant que le corps du schéma ne soit retourné.

CRUD par propriété

Écritures atomiques par lots : JSON Patch

PATCH /api/config accepte un document JSON Patch (RFC 6902). Les opérations de configuration prises en charge sont add, replace, remove et test. ZeroClaw accepte également une extension comment pour les annotations de configuration. Les opérations de configuration s’exécutent sur une copie en mémoire ; une fois toutes les opérations appliquées, Config::validate() s’exécute une seule fois sur le résultat. Si la validation réussit, le nouvel état est persisté et mis en service. Si une opération quelconque ou la validation finale échoue, les états sur disque et en mémoire restent inchangés. Les annotations de commentaires sont appliquées après la sauvegarde de manière non bloquante et selon le principe du meilleur effort.

move et copy renvoient 400 op_not_supported car la réécriture sécurisée du graphe de références ne fait pas partie de cette surface. test sur un chemin #[secret] est rejeté avec secret_test_forbidden : un résultat différentiel serait le seul signal qu’un client pourrait lire, et cela divulguerait la valeur.

Syntaxe de chemin : JSON Pointer (/agents/researcher/model_provider) ou la forme avec points (agents.researcher.model_provider). Les deux sont acceptées ; le serveur normalise.

L’équivalent CLI est zeroclaw config patch <file-or-stdin>, qui applique le même ensemble d’opérations sur la Config locale et renvoie la même structure de réponse structurée (--json pour les scripts).

Secrets : écriture seule via HTTP

Les lectures par propriété n’exposent jamais les champs secrets (ceux marqués #[secret] ou #[derived_from_secret] dans le schéma). Leurs réponses ne comportent que {populated: bool}, sans valeur, longueur, substitut masqué ni hachage. Le point d’accès de compatibilité GET /api/config sérialise à la place l’ensemble de la configuration après application de MaskSecrets, de sorte que les champs secrets ne peuvent y apparaître que sous forme d’espaces réservés masqués. Aucune de ces surfaces de lecture de configuration ne renvoie la valeur secrète sous-jacente.

PUT et PATCH écrivent la nouvelle valeur du secret et répondent avec {populated: true} ; DELETE l’efface et répond avec {populated: false}. Il n’existe aucun chemin HTTP permettant de récupérer un secret, par quelque moyen que ce soit.

Codes d’erreur stables

Les erreurs renvoient du JSON avec un champ code stable et un message lisible par l’utilisateur. Les frontends et les scripts effectuent une correspondance avec le code ; l’interface utilisateur effectue une correspondance avec le chemin.

Exploration en direct

Une fois qu’une passerelle est en cours d’exécution, accédez à http://<gateway-host>:<port>/api/docs pour l’explorateur d’API Scalar. La spécification brute est disponible à l’adresse /api/openapi.json pour les autres visionneuses compatibles.

Le panneau d’authentification de l’explorateur se lie au schéma bearerAuth déclaré dans la spécification ; collez-y votre jeton bearer dérivé de l’appariement avant d’effectuer des appels en direct. Le raccourci CLI pour l’URL est zeroclaw config docs.

Si le bundle Scalar ne peut pas être chargé depuis le CDN (installation hors ligne / isolée), la page se dégrade correctement et vous redirige vers la spécification brute à l’adresse /api/openapi.json afin que vous puissiez utiliser n’importe quel visualiseur compatible (Insomnia, Postman, Swagger UI, etc.).

Contrat de flux d’événements

GET /api/events est un flux brut Server-Sent Events d’événements d’exécution observables. Ce n’est pas une chronologie de cycle de vie dédupliquée avec une ligne par tour.

Les gestionnaires de passerelle, le traitement des webhooks, les tâches cron/heartbeat et les observateurs de boucle d’agent peuvent tous publier des événements de type cycle de vie dans le même chemin de diffusion. Les clients doivent considérer le flux comme un journal d’observation en ajout seul. Si un tableau de bord souhaite une chronologie de tours compacte, il doit regrouper ou dédupliquer selon les identifiants présents dans la charge utile de l’événement plutôt que de supposer que chaque trame agent_start, llm_request ou agent_end n’apparaît qu’une seule fois.

GET /api/events/history rejoue les événements récents conservés dans le même tampon, du plus ancien au plus récent. Il s’agit d’une fenêtre de reconnexion pour les abonnés, et non d’un magasin de cycle de vie canonique distinct.