Referencia de la API
Todos los endpoints públicos bajo /v1, con su propósito y la credencial que aceptan. Los cuerpos se validan con los mismos esquemas que usa la consola; un fallo de validación devuelve 400 invalid_body con los errores por campo.
Autenticación
Authorization: Bearer cak_… para las claves de backend y de agente, o la cookie de sesión de la consola. “editor+” significa que el rol en la organización debe ser editor u owner. Las llamadas de máquina a máquina deberían usar siempre una clave.
Endpoints
| Método | Ruta | Propósito | Auth |
|---|---|---|---|
| POST | /v1/mandates | Registra un mandato (autoridad, sujeto, límites, caducidad) | clave API de backend o sesión (editor+) |
| POST | /v1/operations | Propone una acción; 202 + decisión. Respeta Idempotency-Key | clave de agente o de backend, o sesión (editor+) |
| GET | /v1/operations/{id} | Estado de la operación, motivos de la decisión, aprobación, número de evidencias | cualquier clave o sesión |
| POST | /v1/operations/{id}/decision | Aprueba / rechaza con el digest de aprobación exacto | solo sesión |
| POST | /v1/observations | Modo observación: informa de una acción que el agente hizo por su cuenta; 201 + decisión hipotética, verificación de solo lectura | clave de agente o de backend, o sesión (editor+) |
| GET | /v1/observations | Observaciones + resumen (?project_id, days, flagged=1) | cualquier clave o sesión |
| GET | /v1/observations/{id} | Una observación con su estado de verificación y su nota | cualquier clave o sesión |
| GET | /v1/projects | Lista los proyectos | cualquier clave o sesión |
| POST | /v1/projects | Crea un proyecto (las plantillas se añaden automáticamente) | solo sesión |
| POST | /v1/projects/{id}/agent-builds | Registra una build del agente: version, endpoint_url, auth_header?, response_path?, set_default | clave API de backend o sesión (editor+) |
| POST | /v1/projects/{id}/agent-builds/probe | Prueba un endpoint con una petición de ejemplo; no guarda nada | clave API de backend o sesión (editor+) |
| POST | /v1/projects/{id}/connections/sandbox | Crea un mundo Stripe simulado + conexión | clave API de backend o sesión (editor+) |
| POST | /v1/projects/{id}/pause · /unpause | Kill-switch: detiene las nuevas escrituras / vuelve a poner en cola las operaciones retenidas | solo sesión |
| GETPUT | /v1/projects/{id}/end-user-caps | Límites de frecuencia y de gasto por cliente final | clave API de backend o sesión (editor+) |
| POST | /v1/projects/{id}/connections/stripe | Conecta Stripe: clave restringida + secreto de webhook, permisos comprobados en solo lectura | clave API de backend o sesión (editor+) |
| POST | /v1/projects/{id}/connections/chargebee | Conecta un sitio de Chargebee: sitio + clave API, permisos comprobados sin crear nada; devuelve la URL del webhook, el usuario y la contraseña (una sola vez) | clave API de backend o sesión (editor+) |
| POST | /v1/projects/{id}/connections/paddle | Conecta Paddle Billing: clave API + clave secreta de notificaciones, permisos comprobados sin crear nada | clave API de backend o sesión (editor+) |
| POST | /v1/projects/{id}/connections/{connection_id}/rotate | Rota la clave (misma cuenta de Stripe) y, opcionalmente, el secreto de webhook | clave API de backend o sesión (editor+) |
| POST | /v1/projects/{id}/connections/{connection_id}/default | La convierte en la conexión Guard por defecto del proyecto | clave API de backend o sesión (editor+) |
| DELETE | /v1/projects/{id}/connections/{connection_id} | Elimina (credenciales borradas; se rechaza si está en uso) | clave API de backend o sesión (editor+) |
| GETPUTDELETE | /v1/projects/{id}/access-service | URL del servicio de acceso del cliente + secreto de firma (el secreto nunca se devuelve) | clave API de backend o sesión (editor+) |
| POST | /v1/projects/{id}/access-service/test | Una lectura firmada para un customer id; muestra el estado o el error exacto | clave API de backend o sesión (editor+) |
| POST | /v1/test-runs | Inicia una suite (repeats 1–5); cuenta para el plan | clave API de backend o sesión (editor+) |
| GET | /v1/test-runs/{id} | Estado, veredicto, recuentos, coste e intentos por escenario | cualquier clave o sesión |
| GET | /v1/test-runs/{id}/export | ?format=json|csv|pdf | cualquier clave o sesión |
| GET | /v1/test-runs/compare | ?base=&head= — comparación de versiones | cualquier clave o sesión |
| POST | /v1/test-runs/{id}/incidents | Abre un incidente a partir de una ejecución fallida | solo sesión |
| GETPOST | /v1/schedules | Suites programadas (cron) | clave API de backend o sesión (editor+) |
| PATCHDELETE | /v1/schedules/{id} · POST …/run | Editar, eliminar, ejecutar ahora | clave API de backend o sesión (editor+) |
| GETPUT | /v1/guardrails | Configuración de los rails por proyecto | clave API de backend o sesión (editor+) |
| GET | /v1/guardrails/hits | Hits recientes (paginación keyset) | cualquier clave o sesión |
| GETPOST | /v1/alert-channels | Alertas de Slack / email / webhook por proyecto | clave API de backend o sesión (editor+) |
| DELETE | /v1/alert-channels/{id} · POST …/test | Elimina, envía una alerta de prueba | clave API de backend o sesión (editor+) |
| GETPOST | /v1/incidents | Lista / crea incidentes | cualquier clave o sesión |
| POST | /v1/incidents/{id}/transition · /notes | OPEN → ASSIGNED → RESOLVED / ACCEPTED_RISK; diario | solo sesión |
| POST | /v1/architect/drafts · /accept | Borradores de escenarios a partir de una descripción; acepta los aprobados | clave API de backend o sesión (editor+) |
| POST | /v1/redteam/suite | Genera entradas hostiles y las ejecuta | clave API de backend o sesión (editor+) |
| GET | /v1/compliance/export | ?from&to&project_id&format=json|pdf — informe a prueba de manipulaciones | cualquier clave o sesión |
| POST | /v1/compliance/email | Envía por email el PDF de cumplimiento | solo sesión |
| GETPOST | /v1/api-keys | Lista / crea claves (backend | agent, por proyecto u organización) | solo sesión (propietario) |
| GETPUT | /v1/ai-settings · POST …/test | Modo de IA (off / byok / managed), modelo, clave, límite de gasto; llamada de prueba real y medida | solo sesión |
| GETPUT | /v1/plan | Plan y uso (PUT solo si la facturación no está configurada; si no, 409 use_billing) | solo sesión (propietario) |
| GET | /v1/billing | Estado de facturación: suscrito, status (active / past_due / canceled), renovación, fin del periodo de gracia | cualquier clave o sesión |
| POST | /v1/billing/checkout | Inicia un Stripe Checkout para { plan: test | guard }; devuelve la URL | solo sesión (propietario) |
| POST | /v1/billing/portal | Abre el Stripe Customer Portal (tarjetas, facturas, cambio de plan, cancelación) | solo sesión (propietario) |
| POST | /v1/access-requests | Pide a COLVO que desbloquee una funcionalidad | solo sesión |
| POST | /v1/webhooks/stripe/{connectionId} | Recepción de Stripe con firma verificada | stripe-signature |
Paginación
Los endpoints de listado que pueden crecer usan paginación keyset: ?limit= (máx. 200) y ?cursor= con el next_cursor de la respuesta anterior. El orden es del más reciente al más antiguo y se mantiene estable aunque lleguen filas nuevas.
Límites de frecuencia
Los formularios públicos están limitados por IP (429 rate_limited). Durante el piloto, las claves API no tienen límite de frecuencia más allá de las cuotas del plan; el tráfico abusivo se pausa por organización y se le explica el motivo al owner.