Riferimento API
Ogni endpoint pubblico sotto /v1, con il suo scopo e la credenziale che accetta. I body sono validati con gli stessi schemi usati dalla console; una validazione fallita restituisce 400 invalid_body con gli errori per campo.
Autenticazione
Authorization: Bearer cak_… per le chiavi backend e agente, oppure il cookie di sessione della console. “editor+” significa che il ruolo nell’organizzazione deve essere editor o owner. Le chiamate machine-to-machine dovrebbero usare sempre una chiave.
Endpoint
| Metodo | Percorso | Scopo | Auth |
|---|---|---|---|
| POST | /v1/mandates | Registra un mandato (autorità, soggetto, limiti, scadenza) | chiave API backend o sessione (editor+) |
| POST | /v1/operations | Propone un’azione; 202 + decisione. Idempotency-Key rispettata | chiave agente o backend, o sessione (editor+) |
| GET | /v1/operations/{id} | Stato dell’operazione, motivi della decisione, approvazione, numero di prove | qualsiasi chiave o sessione |
| POST | /v1/operations/{id}/decision | Approva / rifiuta con il digest di approvazione esatto | solo sessione |
| POST | /v1/observations | Modalità osservazione: segnala un’azione compiuta dall’agente stesso; 201 + decisione ipotetica, verifica in sola lettura | chiave agente o backend, o sessione (editor+) |
| GET | /v1/observations | Osservazioni + riepilogo (?project_id, days, flagged=1) | qualsiasi chiave o sessione |
| GET | /v1/observations/{id} | Una osservazione con stato di verifica e nota | qualsiasi chiave o sessione |
| GET | /v1/projects | Elenca i progetti | qualsiasi chiave o sessione |
| POST | /v1/projects | Crea un progetto (modelli aggiunti automaticamente) | solo sessione |
| POST | /v1/projects/{id}/agent-builds | Registra una build dell’agente: version, endpoint_url, auth_header?, response_path?, set_default | chiave API backend o sessione (editor+) |
| POST | /v1/projects/{id}/agent-builds/probe | Prova un endpoint con una richiesta di esempio; non salva nulla | chiave API backend o sessione (editor+) |
| POST | /v1/projects/{id}/connections/sandbox | Crea un mondo Stripe simulato + connessione | chiave API backend o sessione (editor+) |
| POST | /v1/projects/{id}/pause · /unpause | Kill-switch: ferma le nuove scritture / rimette in coda le operazioni trattenute | solo sessione |
| GETPUT | /v1/projects/{id}/end-user-caps | Limiti di frequenza e di spesa per cliente finale | chiave API backend o sessione (editor+) |
| POST | /v1/projects/{id}/connections/stripe | Collega Stripe: chiave limitata + segreto webhook, permessi verificati in sola lettura | chiave API backend o sessione (editor+) |
| POST | /v1/projects/{id}/connections/chargebee | Collega un sito Chargebee: sito + chiave API, permessi verificati senza creare nulla; restituisce URL del webhook, username e password (una sola volta) | chiave API backend o sessione (editor+) |
| POST | /v1/projects/{id}/connections/paddle | Collega Paddle Billing: chiave API + chiave segreta delle notifiche, permessi verificati senza creare nulla | chiave API backend o sessione (editor+) |
| POST | /v1/projects/{id}/connections/{connection_id}/rotate | Ruota la chiave (stesso account Stripe) e, se vuoi, il segreto webhook | chiave API backend o sessione (editor+) |
| POST | /v1/projects/{id}/connections/{connection_id}/default | La rende la connessione Guard predefinita del progetto | chiave API backend o sessione (editor+) |
| DELETE | /v1/projects/{id}/connections/{connection_id} | Rimuove (credenziali eliminate; rifiutato se in uso) | chiave API backend o sessione (editor+) |
| GETPUTDELETE | /v1/projects/{id}/access-service | URL del servizio di accesso del cliente + segreto di firma (il segreto non viene mai restituito) | chiave API backend o sessione (editor+) |
| POST | /v1/projects/{id}/access-service/test | Una lettura firmata per un customer id; mostra lo stato o l’errore esatto | chiave API backend o sessione (editor+) |
| POST | /v1/test-runs | Avvia una suite (repeats 1–5); conta nel piano | chiave API backend o sessione (editor+) |
| GET | /v1/test-runs/{id} | Stato, verdetto, conteggi, costo, tentativi per scenario | qualsiasi chiave o sessione |
| GET | /v1/test-runs/{id}/export | ?format=json|csv|pdf | qualsiasi chiave o sessione |
| GET | /v1/test-runs/compare | ?base=&head= — confronto tra versioni | qualsiasi chiave o sessione |
| POST | /v1/test-runs/{id}/incidents | Apre un incidente da un’esecuzione fallita | solo sessione |
| GETPOST | /v1/schedules | Suite pianificate (cron) | chiave API backend o sessione (editor+) |
| PATCHDELETE | /v1/schedules/{id} · POST …/run | Modifica, elimina, esegui ora | chiave API backend o sessione (editor+) |
| GETPUT | /v1/guardrails | Configurazione dei rail per progetto | chiave API backend o sessione (editor+) |
| GET | /v1/guardrails/hits | Hit recenti (paginazione keyset) | qualsiasi chiave o sessione |
| GETPOST | /v1/alert-channels | Alert Slack / email / webhook per progetto | chiave API backend o sessione (editor+) |
| DELETE | /v1/alert-channels/{id} · POST …/test | Rimuove, invia un alert di prova | chiave API backend o sessione (editor+) |
| GETPOST | /v1/incidents | Elenca / crea incidenti | qualsiasi chiave o sessione |
| POST | /v1/incidents/{id}/transition · /notes | OPEN → ASSIGNED → RESOLVED / ACCEPTED_RISK; diario | solo sessione |
| POST | /v1/architect/drafts · /accept | Bozze di scenari da una descrizione; accetta quelli approvati | chiave API backend o sessione (editor+) |
| POST | /v1/redteam/suite | Genera input ostili e li esegue | chiave API backend o sessione (editor+) |
| GET | /v1/compliance/export | ?from&to&project_id&format=json|pdf — report a prova di manomissione | qualsiasi chiave o sessione |
| POST | /v1/compliance/email | Invia per email il PDF di conformità | solo sessione |
| GETPOST | /v1/api-keys | Elenca / crea chiavi (backend | agent, per progetto o organizzazione) | solo sessione (proprietario) |
| GETPUT | /v1/ai-settings · POST …/test | Modalità AI (off / byok / managed), modello, chiave, limite di spesa; vera chiamata di prova a consumo | solo sessione |
| GETPUT | /v1/plan | Piano e utilizzo (PUT solo se la fatturazione non è configurata; altrimenti 409 use_billing) | solo sessione (proprietario) |
| GET | /v1/billing | Stato della fatturazione: abbonato, status (active / past_due / canceled), rinnovo, fine del periodo di tolleranza | qualsiasi chiave o sessione |
| POST | /v1/billing/checkout | Avvia uno Stripe Checkout per { plan: test | guard }; restituisce l’URL | solo sessione (proprietario) |
| POST | /v1/billing/portal | Apre lo Stripe Customer Portal (carte, fatture, cambio di piano, disdetta) | solo sessione (proprietario) |
| POST | /v1/access-requests | Chiede a COLVO di sbloccare una funzionalità | solo sessione |
| POST | /v1/webhooks/stripe/{connectionId} | Ricezione Stripe con verifica della firma | stripe-signature |
Paginazione
Gli endpoint di elenco che possono crescere usano la paginazione keyset: ?limit= (max 200) e ?cursor= preso dal next_cursor della risposta precedente. L’ordine è dal più recente ed è stabile anche quando arrivano nuove righe.
Limiti di frequenza
I moduli pubblici sono limitati per IP (429 rate_limited). Durante il pilota le chiavi API non hanno limiti di frequenza oltre alle quote del piano; il traffico abusivo viene messo in pausa per organizzazione e l’owner viene informato del motivo.