COLVO documentation

COLVO tests AI agents before launch and guards their real actions in production, verifying the actual outcome instead of the agent’s reply. This is the developer documentation: the HTTP contract to your agent, the API your backend and agent call, the CLI, and how decisions and verdicts are made.

Written from the code · updated 26 Sep 2026 · Something wrong or missing? Tell us

Two modules, one contract

• COLVO Test replays scenarios against an isolated simulated Stripe world. Your agent receives a customer, their subscriptions and payments and a message, and answers as it would in production. When it wants to act it proposes an operation to COLVO. The verdict is computed from the resulting state: PASS, FAIL or INCONCLUSIVE.
• COLVO Guard stands in front of your real provider. Your trusted backend registers a mandate (who may do what, with which limits); the agent proposes; COLVO decides ALLOW / REVIEW / HOLD / DENY, executes exactly once, and verifies against the provider.

The agent speaks the same small contract in both modules and never holds provider write credentials.

Where to start

1. Getting started — invite to first green run.
2. Connect your agent — the request COLVO sends and the reply it expects.
3. Mandates & connections then the Guard API — when you go live.
4. CLI & CI gate — fail the build on FAIL.

Base URL and versioning

All endpoints live under https://colvo.app/v1. Bodies are JSON. Breaking changes get a new prefix; additive fields may appear at any time, so ignore unknown keys.

Authentication

Two credentials, both sent as Authorization: Bearer …:

• Backend key (cak_…, scope backend) — your trusted server. Registers mandates, starts runs, manages configuration.
• Agent key (cak_…, scope agent) — the agent itself. Can only propose operations and read their state. During a test run COLVO hands the agent a per-attempt key in the request, so a test agent needs no stored secret.

Console users act with their session; the org role (owner / editor / viewer) decides what they may change. Keys are shown once, hashed at rest, and can be revoked or rotated from Settings.