Caputchin über die API verwalten

Alles, was du im Dashboard tun kannst, außer Abrechnung, kannst du auch aus Code tun. Caputchin stellt eine Management-API bereit, und drei Flächen sitzen darauf: diese HTTP-API direkt, der MCP-Server für KI-Agenten und der Terraform- und OpenTofu-Provider für Infrastructure-as-Code. Sie unterscheiden sich nur am Rand; dieselbe Validierung, dieselben Berechtigungen und dasselbe Audit-Logging gelten, welche du auch nutzt.

Alle drei authentifizieren sich mit derselben Anmeldedatei: einem Access Token, das du einmal prägst.

Ein Access Token prägen

Du sendest den Token als Bearer-Header. Es gibt zwei Arten, in voller Länge behandelt unter Personal Access Token und Team-Tokens:

Token	Reichweite	Präg es
Personal Access Token	Master über dein ganzes Konto	Kontoeinstellungen. Kostenlos, einer pro Konto.
Troop Access Token	Nur die Teams, an die es angehängt ist, mit gewährten Berechtigungen	Die Token-Seite eines Teams. Nimmt einen Sitz.

Nimm ein Personal Access Token für deine eigene vollständige Konto-Automatisierung; nimm ein Team-Token für eingeschränkten Least-Privilege-Zugriff (ein CI-Job, der nur ein Team berührt). Beide funktionieren überall unten. Der Token-Wert wird einmal bei der Erstellung gezeigt, also kopier ihn in einen Secret-Store.

Basis-URL und Auth

Die Management-API ist gewurzelt bei:

https://caputchin.com/api/v1/management

Jede Anfrage trägt den Token als Bearer-Header:

Authorization: Bearer cpt_pat_...

Anfragen und Antworten sind JSON. Ein Aufruf, den dein Token nicht machen darf, gibt 403 zurück; ein unbekannter oder widerrufener Token gibt 401 zurück.

Ein ausgearbeitetes Beispiel: einen Site-Key erstellen

Sagen wir, du willst einen neuen Site-Key in deinem shop-team-Team. Liste zuerst deine Teams auf, um die id zu finden, dann erstell den Key darin.

# 1. Find the troop id.
curl -s https://caputchin.com/api/v1/management/troops \
  -H "Authorization: Bearer $CAPUTCHIN_MANAGEMENT_TOKEN"
# → { "troops": [ { "id": "troop_…", "name": "shop-team", … }, … ] }

# 2. Create a site key in that troop.
curl -s -X POST https://caputchin.com/api/v1/management/sites \
  -H "Authorization: Bearer $CAPUTCHIN_MANAGEMENT_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "name": "shop-frontend", "troop_id": "troop_…" }'
# → { "id": "site_…", "key": "cpt_pub_…", "secret": "cpt_sec_…", … }

Die Antwort trägt den öffentlichen key des neuen Keys und sein secret. Das Secret wird einmal gezeigt, hier, also fang es jetzt ein; du wirst damit auf deinem Backend verifizieren. Lass troop_id weg, und der Key landet in deinem persönlichen Team.

Das ist das ganze Muster: ein Bearer-Token, ein JSON-Body, ein Aufruf pro Operation. Auflisten ist GET, Erstellen ist POST, Aktualisieren ist PATCH oder PUT, Entfernen ist DELETE, gegen die Ressourcen-Pfade unter der Basis-URL.

Die vollständige Referenz

Jeder Endpunkt, mit seinen Parametern, Anfrage- und Antwort-Schemas und einem eingebauten "Try it"-Panel, das sich mit deinem Token authentifiziert, ist in der interaktiven API-Referenz. Sie wird aus derselben OpenAPI-Spezifikation generiert, gegen die die API gebaut ist, also driftet sie nie von der Live-Fläche ab. Richte deine eigenen Client-Generatoren auf die dort verlinkte Spec.

Siehe auch

Personal Access Token: die Master-Anmeldedatei und wie du ihre Nutzung nachverfolgst.
Den MCP-Server nutzen: dieselbe API, gesteuert von einem KI-Agenten.
Terraform oder OpenTofu nutzen: dieselbe API, als Infrastructure-as-Code.
Interaktive API-Referenz: jeder Endpunkt und jedes Schema.