L'API locale

À quoi elle sert

Le démon compagnon est un serveur HTTP ordinaire. Il expose le compte auquel il est connecté — connexions, codes, invitations, tags, préréglages, liens ouverts, gestion d’organisation — en JSON sous /api/v1/.

C’est ainsi qu’un script, un système back-office ou un compte machine utilise Trusted Codes sans personne ni téléphone. Le démon détient la session et les clés ; l’appelant détient un jeton et parle du HTTP simple.

Où il écoute

L’adresse par défaut est http://127.0.0.1:19821. C’est la seule entrée de serveur dans le document OpenAPI, et c’est le port fixe — boucle locale uniquement.

Deux variables d’environnement le déplacent : TCC_HTTP_BIND et TCC_HTTP_PORT. Les appelants sans interface devraient respecter les deux plutôt que de supposer la valeur par défaut.

Que le port soit fixe est délibéré. Il peut être ajouté une fois à une liste d’autorisation, puis laissé tranquille.

Les deux documents

Le démon sert deux documents OpenAPI à deux chemins, pour deux publics.

GET /api/v1/openapi.json est le document REST typé — les routes que ces pages décrivent. Il est généré à partir des structures Rust qui sérialisent les réponses, donc un champ ne peut pas être orthographié d’une façon dans le document et d’une autre sur le fil. Le même document est versionné dans le dépôt, et les types de réponse TypeScript de l’interface web du compagnon sont générés à partir de lui.

GET /openapi.json, au chemin sans préfixe, est une chose différente : le catalogue des outils MCP du démon, pour les clients MCP et les GPT personnalisés. La section MCP couvre cette surface.

GET /api/v1/docs sert une page interactive affichant le document REST. Cette page et /api/v1/openapi.json sont toutes deux publiques — aucun jeton.

Santé et statut

GET /health (aussi GET /api/v1/health) ne nécessite aucun jeton. Utilise-la pour répondre à « le démon est-il actif ». C’est la seule route documentée qui répond avant que le démon ne soit connecté.

GET /api/v1/status nécessite un jeton et répond davantage : si le démon est authentifié, si l’appareil est enregistré, si la clé globale est active, le nom d’environnement avec lequel il a démarré, le serveur qu’il a réellement résolu, la version du démon, combien de connexions sont en cache, l’heure de la dernière synchronisation, et un résumé en une ligne.

Le nom d’environnement et le serveur résolu sont des champs séparés, délibérément. Un démon démarré avec un nom d’environnement peut être pointé ailleurs par une surcharge, et seule la valeur résolue indique où il parle vraiment.

Certains de ces champs sont null pour un appelant machine à machine, qui ne détient aucun cache local et n’est pas l’utilisateur propre du démon. Un null ici signifie « non applicable », pas « inconnu ».

Préfixe de chemin et compatibilité

Les points de terminaison outils et MCP sont enregistrés deux fois : une fois à un chemin plat pour les clients plus anciens, et une fois sous /api/v1/. Les nouvelles intégrations devraient cibler la forme préfixée. Les chemins sans préfixe restent stables pendant tout le cycle de vie de v1 et ne sont retirés qu’au lancement de /api/v2/.

Les routes REST de ces pages n’existent que sous /api/v1/.