Die lokale API

Wofür sie da ist

Der Begleitprogramm-Dienst ist ein gewöhnlicher HTTP-Server. Er stellt das Konto, bei dem er angemeldet ist — Verbindungen, Codes, Einladungen, Etiketten, Vorlagen, offene Links, Organisationsverwaltung — als JSON über /api/v1/ bereit.

So nutzt ein Skript, ein Backoffice-System oder ein Maschinenkonto Trusted Codes ohne eine Person und ein Telefon. Der Dienst hält Sitzung und Schlüssel; das aufrufende Programm hält ein Token und spricht schlichtes HTTP.

Wo sie lauscht

Die Vorgabeadresse ist http://127.0.0.1:19821. Das ist der einzige Servereintrag im OpenAPI-Dokument, und der Port liegt fest — nur Loopback.

Zwei Umgebungsvariablen verschieben sie: TCC_HTTP_BIND und TCC_HTTP_PORT. Aufrufende Programme ohne Oberfläche sollten beide beachten, statt die Vorgabe anzunehmen.

Dass der Port festliegt, ist Absicht. Er lässt sich einmal auf eine Allowlist setzen und dann in Ruhe lassen.

Die beiden Dokumente

Der Dienst liefert zwei OpenAPI-Dokumente unter zwei Pfaden für zwei Zielgruppen aus.

GET /api/v1/openapi.json ist das typisierte REST-Dokument — die Routen, die diese Seiten beschreiben. Es wird aus den Rust-Structs erzeugt, die die Antworten serialisieren, sodass ein Feld nicht im Dokument anders geschrieben sein kann als auf der Leitung. Dasselbe Dokument liegt im Repository, und aus ihm werden auch die TypeScript-Antworttypen der Web-Oberfläche des Begleitprogramms erzeugt.

GET /openapi.json, unter dem unpräfigierten Pfad, ist etwas anderes: der Katalog der MCP-Werkzeuge des Dienstes, für MCP-Clients und eigene GPTs. Der MCP-Abschnitt behandelt diese Oberfläche.

GET /api/v1/docs liefert eine interaktive Seite, die das REST-Dokument rendert. Sowohl diese Seite als auch /api/v1/openapi.json sind öffentlich — kein Token nötig.

Gesundheit und Status

GET /health (auch GET /api/v1/health) braucht kein Token. Nutze es, um die Frage “läuft der Dienst” zu beantworten. Es ist die einzige dokumentierte Route, die antwortet, bevor der Dienst angemeldet ist.

GET /api/v1/status braucht ein Token und antwortet ausführlicher: ob der Dienst authentifiziert ist, ob das Gerät registriert ist, ob der globale Schlüssel aktiv ist, den Umgebungsnamen, mit dem er gestartet wurde, das Backend, das tatsächlich aufgelöst wurde, die Version des Dienstes, wie viele Verbindungen zwischengespeichert sind, den letzten Abgleichzeitpunkt und eine einzeilige Zusammenfassung.

Der Umgebungsname und das aufgelöste Backend sind bewusst getrennte Felder. Ein Dienst, der mit einem Umgebungsnamen gestartet wurde, kann durch eine Übersteuerung woanders hingelenkt werden, und nur der aufgelöste Wert sagt dir, wohin er wirklich spricht.

Manche dieser Felder sind für ein aufrufendes Programm ohne eigenen Nutzer (Maschine-zu-Maschine) null, weil es keinen lokalen Zwischenspeicher hält und nicht der eigene Nutzer des Dienstes ist. Ein null dort bedeutet “nicht zutreffend”, nicht “unbekannt”.

Pfadpräfix und Kompatibilität

Die Werkzeug- und MCP-Endpunkte sind doppelt registriert: einmal unter einem flachen Pfad für ältere aufrufende Programme, und einmal unter /api/v1/. Neue Integrationen sollten die präfigierte Form ansteuern. Die unpräfigierten Pfade bleiben über den gesamten v1-Lebenszyklus stabil und werden erst entfernt, wenn /api/v2/ erscheint.

Die REST-Routen auf diesen Seiten existieren nur unter /api/v1/.