De lokale API

Waarvoor ze is

De companiondaemon is een gewone HTTP-server. Hij stelt het account waarmee hij is aangemeld — verbindingen, codes, uitnodigingen, tags, presets, open links, organisatiebeheer — beschikbaar als JSON via /api/v1/.

Zo gebruikt een script, een backofficesysteem of een machineaccount Trusted Codes zonder een persoon en een telefoon. De daemon houdt de sessie en de sleutels; de aanroeper houdt een token en spreekt gewoon HTTP.

Waar hij luistert

Het standaardadres is http://127.0.0.1:19821. Dat is het enige serveradres in het OpenAPI-document, en het is de vaste poort — alleen loopback.

Twee omgevingsvariabelen verplaatsen dat: TCC_HTTP_BIND en TCC_HTTP_PORT. Headless aanroepers moeten beide respecteren in plaats van de standaard aan te nemen.

Dat de poort vastligt, is met opzet. Ze kan één keer op de allowlist worden gezet en dan met rust worden gelaten.

De twee documenten

De daemon bedient twee OpenAPI-documenten op twee paden, voor twee doelgroepen.

GET /api/v1/openapi.json is het typegebonden REST-document — de routes die deze pagina’s beschrijven. Het wordt gegenereerd uit de Rust-structs die de antwoorden serialiseren, dus een veld kan niet op de ene manier in het document en op de andere op de lijn zijn gespeld. Hetzelfde document ligt vastgelegd in de repository, en de TypeScript-responstypes van de companion-webinterface worden ervan afgeleid.

GET /openapi.json, op het pad zonder voorvoegsel, is iets anders: de catalogus van de MCP-tools van de daemon, voor MCP-clients en aangepaste GPT’s. De MCP-sectie behandelt dat vlak.

GET /api/v1/docs bedient een interactieve pagina die het REST-document weergeeft. Zowel die pagina als /api/v1/openapi.json zijn openbaar — geen token nodig.

Health en status

GET /health (ook GET /api/v1/health) heeft geen token nodig. Gebruik hem om “is de daemon actief” te beantwoorden. Het is de enige gedocumenteerde route die antwoordt voordat de daemon is aangemeld.

GET /api/v1/status heeft een token nodig en antwoordt uitgebreider: of de daemon is geauthenticeerd, of het apparaat is geregistreerd, of de globale sleutel actief is, de omgevingsnaam waarmee hij is gestart, de backend die hij werkelijk heeft opgelost, de daemonversie, hoeveel verbindingen zijn gecachet, het laatste synchronisatietijdstip, en een samenvatting van één regel.

De omgevingsnaam en de opgeloste backend zijn met opzet aparte velden. Een daemon die met de ene omgevingsnaam is gestart, kan door een override naar elders worden verwezen, en alleen de opgeloste waarde vertelt je waar hij echt mee praat.

Sommige van die velden zijn null voor een machine-tot-machine-aanroeper, die geen lokale cache heeft en niet de eigen gebruiker van de daemon is. Een null daar betekent “niet van toepassing”, niet “onbekend”.

Padvoorvoegsel en compatibiliteit

De tool- en MCP-eindpunten zijn dubbel geregistreerd: één keer op een plat pad voor oudere clients, en één keer onder /api/v1/. Nieuwe integraties moeten de variant met voorvoegsel gebruiken. De paden zonder voorvoegsel blijven stabiel gedurende de levensduur van v1 en worden pas verwijderd zodra /api/v2/ uitkomt.

De REST-routes op deze pagina’s bestaan alleen onder /api/v1/.