API-Referenz
Jeder öffentliche Endpunkt unter /v1, mit seinem Zweck und den Zugangsdaten, die er akzeptiert. Bodys werden mit denselben Schemas validiert, die auch die Konsole verwendet; eine fehlgeschlagene Validierung liefert 400 invalid_body mit den Feldfehlern.
Authentifizierung
Authorization: Bearer cak_… für Backend- und Agenten-Schlüssel oder das Sitzungs-Cookie der Konsole. „editor+“ bedeutet, dass die Rolle in der Organisation editor oder owner sein muss. Maschine-zu-Maschine-Aufrufe sollten immer einen Schlüssel verwenden.
Endpunkte
| Methode | Pfad | Zweck | Auth |
|---|---|---|---|
| POST | /v1/mandates | Ein Mandat registrieren (Befugnis, Gegenstand, Limits, Ablauf) | Backend-API-Schlüssel oder Sitzung (Editor+) |
| POST | /v1/operations | Eine Aktion vorschlagen; 202 + Entscheidung. Idempotency-Key wird beachtet | Agenten- oder Backend-Schlüssel oder Sitzung (Editor+) |
| GET | /v1/operations/{id} | Zustand der Operation, Entscheidungsgründe, Freigabe, Anzahl der Nachweise | beliebiger Schlüssel oder Sitzung |
| POST | /v1/operations/{id}/decision | Freigeben / ablehnen mit dem exakten Freigabe-Digest | nur Sitzung |
| POST | /v1/observations | Beobachtungsmodus: eine Aktion melden, die der Agent selbst ausgeführt hat; 201 + hypothetische Entscheidung, rein lesende Verifizierung | Agenten- oder Backend-Schlüssel oder Sitzung (Editor+) |
| GET | /v1/observations | Beobachtungen + Zusammenfassung (?project_id, days, flagged=1) | beliebiger Schlüssel oder Sitzung |
| GET | /v1/observations/{id} | Eine Beobachtung mit Verifizierungsstatus und Hinweis | beliebiger Schlüssel oder Sitzung |
| GET | /v1/projects | Projekte auflisten | beliebiger Schlüssel oder Sitzung |
| POST | /v1/projects | Ein Projekt anlegen (Vorlagen werden automatisch hinzugefügt) | nur Sitzung |
| POST | /v1/projects/{id}/agent-builds | Einen Agenten-Build registrieren: version, endpoint_url, auth_header?, response_path?, set_default | Backend-API-Schlüssel oder Sitzung (Editor+) |
| POST | /v1/projects/{id}/agent-builds/probe | Einen Endpunkt mit einer Beispielanfrage testen; nichts wird gespeichert | Backend-API-Schlüssel oder Sitzung (Editor+) |
| POST | /v1/projects/{id}/connections/sandbox | Eine simulierte Stripe-Welt + Verbindung anlegen | Backend-API-Schlüssel oder Sitzung (Editor+) |
| POST | /v1/projects/{id}/pause · /unpause | Kill-Switch: neue Schreibvorgänge stoppen / zurückgehaltene Operationen erneut einreihen | nur Sitzung |
| GETPUT | /v1/projects/{id}/end-user-caps | Frequenz- und Ausgabenlimits pro Endkunde | Backend-API-Schlüssel oder Sitzung (Editor+) |
| POST | /v1/projects/{id}/connections/stripe | Stripe verbinden: eingeschränkter Schlüssel + Webhook-Secret, Berechtigungen nur lesend geprüft | Backend-API-Schlüssel oder Sitzung (Editor+) |
| POST | /v1/projects/{id}/connections/chargebee | Eine Chargebee-Site verbinden: Site + API-Schlüssel, Berechtigungen geprüft, ohne etwas anzulegen; liefert Webhook-URL, Benutzername und Passwort (einmalig) | Backend-API-Schlüssel oder Sitzung (Editor+) |
| POST | /v1/projects/{id}/connections/paddle | Paddle Billing verbinden: API-Schlüssel + Secret Key der Benachrichtigungen, Berechtigungen geprüft, ohne etwas anzulegen | Backend-API-Schlüssel oder Sitzung (Editor+) |
| POST | /v1/projects/{id}/connections/{connection_id}/rotate | Den Schlüssel rotieren (gleiches Stripe-Konto) und optional das Webhook-Secret | Backend-API-Schlüssel oder Sitzung (Editor+) |
| POST | /v1/projects/{id}/connections/{connection_id}/default | Zur Standard-Guard-Verbindung des Projekts machen | Backend-API-Schlüssel oder Sitzung (Editor+) |
| DELETE | /v1/projects/{id}/connections/{connection_id} | Entfernen (Zugangsdaten gelöscht; abgelehnt, solange in Gebrauch) | Backend-API-Schlüssel oder Sitzung (Editor+) |
| GETPUTDELETE | /v1/projects/{id}/access-service | URL des Kunden-Zugangsdienstes + Signatur-Secret (das Secret wird nie zurückgegeben) | Backend-API-Schlüssel oder Sitzung (Editor+) |
| POST | /v1/projects/{id}/access-service/test | Ein signierter Lesezugriff für eine Kunden-ID; zeigt den Zustand oder den exakten Fehler | Backend-API-Schlüssel oder Sitzung (Editor+) |
| POST | /v1/test-runs | Eine Suite starten (repeats 1–5); wird auf den Tarif angerechnet | Backend-API-Schlüssel oder Sitzung (Editor+) |
| GET | /v1/test-runs/{id} | Laufstatus, Urteil, Zählungen, Kosten, Versuche pro Szenario | beliebiger Schlüssel oder Sitzung |
| GET | /v1/test-runs/{id}/export | ?format=json|csv|pdf | beliebiger Schlüssel oder Sitzung |
| GET | /v1/test-runs/compare | ?base=&head= – Versionsvergleich | beliebiger Schlüssel oder Sitzung |
| POST | /v1/test-runs/{id}/incidents | Einen Vorfall aus einem fehlgeschlagenen Lauf eröffnen | nur Sitzung |
| GETPOST | /v1/schedules | Geplante Suiten (cron) | Backend-API-Schlüssel oder Sitzung (Editor+) |
| PATCHDELETE | /v1/schedules/{id} · POST …/run | Bearbeiten, löschen, jetzt ausführen | Backend-API-Schlüssel oder Sitzung (Editor+) |
| GETPUT | /v1/guardrails | Rail-Konfiguration pro Projekt | Backend-API-Schlüssel oder Sitzung (Editor+) |
| GET | /v1/guardrails/hits | Aktuelle Treffer (Keyset-Paginierung) | beliebiger Schlüssel oder Sitzung |
| GETPOST | /v1/alert-channels | Slack- / E-Mail- / Webhook-Alerts pro Projekt | Backend-API-Schlüssel oder Sitzung (Editor+) |
| DELETE | /v1/alert-channels/{id} · POST …/test | Entfernen, einen Test-Alert senden | Backend-API-Schlüssel oder Sitzung (Editor+) |
| GETPOST | /v1/incidents | Vorfälle auflisten / anlegen | beliebiger Schlüssel oder Sitzung |
| POST | /v1/incidents/{id}/transition · /notes | OPEN → ASSIGNED → RESOLVED / ACCEPTED_RISK; Journal | nur Sitzung |
| POST | /v1/architect/drafts · /accept | Szenarien aus einer Beschreibung entwerfen; die freigegebenen übernehmen | Backend-API-Schlüssel oder Sitzung (Editor+) |
| POST | /v1/redteam/suite | Feindselige Eingaben erzeugen und ausführen | Backend-API-Schlüssel oder Sitzung (Editor+) |
| GET | /v1/compliance/export | ?from&to&project_id&format=json|pdf – manipulationssicherer Bericht | beliebiger Schlüssel oder Sitzung |
| POST | /v1/compliance/email | Das Compliance-PDF per E-Mail senden | nur Sitzung |
| GETPOST | /v1/api-keys | Schlüssel auflisten / anlegen (backend | agent, pro Projekt oder Organisation) | nur Sitzung (Inhaber) |
| GETPUT | /v1/ai-settings · POST …/test | KI-Modus (off / byok / managed), Modell, Schlüssel, Ausgabenlimit; echter abgerechneter Testaufruf | nur Sitzung |
| GETPUT | /v1/plan | Tarif und Nutzung (PUT nur, wenn keine Abrechnung konfiguriert ist; sonst 409 use_billing) | nur Sitzung (Inhaber) |
| GET | /v1/billing | Abrechnungsstatus: abonniert, status (active / past_due / canceled), Verlängerung, Ende der Karenzzeit | beliebiger Schlüssel oder Sitzung |
| POST | /v1/billing/checkout | Einen Stripe Checkout für { plan: test | guard } starten; liefert die URL | nur Sitzung (Inhaber) |
| POST | /v1/billing/portal | Das Stripe Customer Portal öffnen (Karten, Rechnungen, Tarifwechsel, Kündigung) | nur Sitzung (Inhaber) |
| POST | /v1/access-requests | COLVO bitten, eine Funktion freizuschalten | nur Sitzung |
| POST | /v1/webhooks/stripe/{connectionId} | Stripe-Eingang mit Signaturprüfung | stripe-signature |
Paginierung
Listen-Endpunkte, die wachsen können, verwenden Keyset-Paginierung: ?limit= (max. 200) und ?cursor= aus dem next_cursor der vorherigen Antwort. Die Reihenfolge ist neueste zuerst und bleibt stabil, während neue Zeilen hinzukommen.
Ratenlimits
Öffentliche Formulare sind pro IP begrenzt (429 rate_limited). API-Schlüssel sind während der Pilotphase über die Tarifkontingente hinaus nicht ratenbegrenzt; missbräuchlicher Traffic wird pro Organisation pausiert, und der Owner erfährt den Grund.