Référence de l’API
Chaque endpoint public sous /v1, avec son objet et l’identifiant qu’il accepte. Les corps sont validés avec les mêmes schémas que ceux de la console ; un échec de validation renvoie 400 invalid_body avec les erreurs par champ.
Authentification
Authorization: Bearer cak_… pour les clés backend et agent, ou le cookie de session de la console. « éditeur+ » signifie que le rôle dans l’organisation doit être editor ou owner. Les appels de machine à machine doivent toujours utiliser une clé.
Endpoints
| Méthode | Chemin | Objet | Auth |
|---|---|---|---|
| POST | /v1/mandates | Enregistre un mandat (autorité, sujet, limites, expiration) | clé API backend ou session (éditeur+) |
| POST | /v1/operations | Propose une action ; 202 + décision. Idempotency-Key respectée | clé agent ou backend, ou session (éditeur+) |
| GET | /v1/operations/{id} | État de l’opération, motifs de la décision, approbation, nombre de preuves | toute clé ou session |
| POST | /v1/operations/{id}/decision | Approuve / rejette avec le digest d’approbation exact | session uniquement |
| POST | /v1/observations | Mode observation : signale une action effectuée par l’agent lui-même ; 201 + décision hypothétique, vérification en lecture seule | clé agent ou backend, ou session (éditeur+) |
| GET | /v1/observations | Observations + résumé (?project_id, days, flagged=1) | toute clé ou session |
| GET | /v1/observations/{id} | Une observation avec son état de vérification et sa note | toute clé ou session |
| GET | /v1/projects | Liste les projets | toute clé ou session |
| POST | /v1/projects | Crée un projet (modèles ajoutés automatiquement) | session uniquement |
| POST | /v1/projects/{id}/agent-builds | Enregistre un build de l’agent : version, endpoint_url, auth_header?, response_path?, set_default | clé API backend ou session (éditeur+) |
| POST | /v1/projects/{id}/agent-builds/probe | Teste un endpoint avec une requête d’exemple ; rien n’est enregistré | clé API backend ou session (éditeur+) |
| POST | /v1/projects/{id}/connections/sandbox | Crée un monde Stripe simulé + une connexion | clé API backend ou session (éditeur+) |
| POST | /v1/projects/{id}/pause · /unpause | Kill-switch : stoppe les nouvelles écritures / remet en file les opérations retenues | session uniquement |
| GETPUT | /v1/projects/{id}/end-user-caps | Plafonds de fréquence et de dépenses par client final | clé API backend ou session (éditeur+) |
| POST | /v1/projects/{id}/connections/stripe | Connecte Stripe : clé restreinte + secret de webhook, permissions vérifiées en lecture seule | clé API backend ou session (éditeur+) |
| POST | /v1/projects/{id}/connections/chargebee | Connecte un site Chargebee : site + clé API, permissions vérifiées sans rien créer ; renvoie l’URL du webhook, le nom d’utilisateur et le mot de passe (une seule fois) | clé API backend ou session (éditeur+) |
| POST | /v1/projects/{id}/connections/paddle | Connecte Paddle Billing : clé API + clé secrète des notifications, permissions vérifiées sans rien créer | clé API backend ou session (éditeur+) |
| POST | /v1/projects/{id}/connections/{connection_id}/rotate | Renouvelle la clé (même compte Stripe) et, si besoin, le secret de webhook | clé API backend ou session (éditeur+) |
| POST | /v1/projects/{id}/connections/{connection_id}/default | En fait la connexion Guard par défaut du projet | clé API backend ou session (éditeur+) |
| DELETE | /v1/projects/{id}/connections/{connection_id} | Supprime (identifiants effacés ; refusé si elle est utilisée) | clé API backend ou session (éditeur+) |
| GETPUTDELETE | /v1/projects/{id}/access-service | URL du service d’accès du client + secret de signature (le secret n’est jamais renvoyé) | clé API backend ou session (éditeur+) |
| POST | /v1/projects/{id}/access-service/test | Une lecture signée pour un identifiant client ; affiche l’état ou l’erreur exacte | clé API backend ou session (éditeur+) |
| POST | /v1/test-runs | Lance une suite (repeats 1–5) ; décomptée de l’offre | clé API backend ou session (éditeur+) |
| GET | /v1/test-runs/{id} | Statut de l’exécution, verdict, compteurs, coût, tentatives par scénario | toute clé ou session |
| GET | /v1/test-runs/{id}/export | ?format=json|csv|pdf | toute clé ou session |
| GET | /v1/test-runs/compare | ?base=&head= — comparaison de versions | toute clé ou session |
| POST | /v1/test-runs/{id}/incidents | Ouvre un incident à partir d’une exécution en échec | session uniquement |
| GETPOST | /v1/schedules | Suites planifiées (cron) | clé API backend ou session (éditeur+) |
| PATCHDELETE | /v1/schedules/{id} · POST …/run | Modifier, supprimer, exécuter maintenant | clé API backend ou session (éditeur+) |
| GETPUT | /v1/guardrails | Configuration des rails par projet | clé API backend ou session (éditeur+) |
| GET | /v1/guardrails/hits | Déclenchements récents (pagination keyset) | toute clé ou session |
| GETPOST | /v1/alert-channels | Alertes Slack / e-mail / webhook par projet | clé API backend ou session (éditeur+) |
| DELETE | /v1/alert-channels/{id} · POST …/test | Supprime, envoie une alerte de test | clé API backend ou session (éditeur+) |
| GETPOST | /v1/incidents | Liste / crée des incidents | toute clé ou session |
| POST | /v1/incidents/{id}/transition · /notes | OPEN → ASSIGNED → RESOLVED / ACCEPTED_RISK ; journal | session uniquement |
| POST | /v1/architect/drafts · /accept | Rédige des scénarios à partir d’une description ; accepte ceux qui sont approuvés | clé API backend ou session (éditeur+) |
| POST | /v1/redteam/suite | Génère des entrées hostiles et les exécute | clé API backend ou session (éditeur+) |
| GET | /v1/compliance/export | ?from&to&project_id&format=json|pdf — rapport rendant toute altération détectable | toute clé ou session |
| POST | /v1/compliance/email | Envoie par e-mail le PDF de conformité | session uniquement |
| GETPOST | /v1/api-keys | Liste / crée des clés (backend | agent, par projet ou organisation) | session uniquement (propriétaire) |
| GETPUT | /v1/ai-settings · POST …/test | Mode IA (off / byok / managed), modèle, clé, plafond de dépenses ; véritable appel de test facturé | session uniquement |
| GETPUT | /v1/plan | Offre et usage (PUT uniquement si la facturation n’est pas configurée ; sinon 409 use_billing) | session uniquement (propriétaire) |
| GET | /v1/billing | État de la facturation : abonné, statut (active / past_due / canceled), renouvellement, fin du délai de grâce | toute clé ou session |
| POST | /v1/billing/checkout | Lance un Stripe Checkout pour { plan: test | guard } ; renvoie l’URL | session uniquement (propriétaire) |
| POST | /v1/billing/portal | Ouvre le Stripe Customer Portal (cartes, factures, changement d’offre, résiliation) | session uniquement (propriétaire) |
| POST | /v1/access-requests | Demande à COLVO de débloquer une fonctionnalité | session uniquement |
| POST | /v1/webhooks/stripe/{connectionId} | Réception Stripe avec vérification de signature | stripe-signature |
Pagination
Les endpoints de liste susceptibles de grossir utilisent la pagination keyset : ?limit= (200 max) et ?cursor= repris du next_cursor de la réponse précédente. L’ordre va du plus récent au plus ancien et reste stable lorsque de nouvelles lignes arrivent.
Limites de fréquence
Les formulaires publics sont limités par IP (429 rate_limited). Pendant la phase pilote, les clés API ne sont soumises à aucune limite de fréquence au-delà des quotas de l’offre ; un trafic abusif est suspendu par organisation et l’owner en est informé, avec le motif.