Gestiona Caputchin desde la API

Todo lo que puedes hacer en el dashboard, salvo la facturación, puedes hacerlo también desde código. Caputchin expone una API de gestión, y tres superficies se asientan encima de ella: esta API HTTP directamente, el servidor MCP para agentes de IA, y el proveedor de Terraform y OpenTofu para infraestructura como código. Difieren solo en el borde; la misma validación, los mismos permisos y el mismo audit logging aplican cualquiera que uses.

Las tres se autentican con la misma credencial: un access token que acuñas una vez.

Acuña un access token

Envías el token como un header Bearer. Hay dos tipos, cubiertos por completo bajo personal access token y tokens de equipo:

Token	Alcance	Acúñalo
Personal access token	Maestro sobre toda tu cuenta	Ajustes de cuenta. Gratis, uno por cuenta.
Troop access token	Solo los equipos a los que está adjunto, con los permisos concedidos	La página de tokens de un equipo. Ocupa un asiento.

Usa un personal access token para tu propia automatización de toda la cuenta; usa un token de equipo para acceso acotado, de mínimo privilegio (un job de CI que solo toca un equipo). Cualquiera funciona en todo lo de abajo. El valor del token se muestra una vez al crearlo, así que cópialo a un almacén de secretos.

URL base y auth

La API de gestión tiene su raíz en:

https://caputchin.com/api/v1/management

Cada petición lleva el token como un header Bearer:

Authorization: Bearer cpt_pat_...

Las peticiones y respuestas son JSON. Una llamada que tu token no tiene permitido hacer devuelve 403; un token desconocido o revocado devuelve 401.

Un ejemplo trabajado: crear una clave de sitio

Digamos que quieres una nueva clave de sitio en tu equipo shop-team. Primero lista tus equipos para encontrar su id, luego crea la clave en él.

# 1. Find the troop id.
curl -s https://caputchin.com/api/v1/management/troops \
  -H "Authorization: Bearer $CAPUTCHIN_MANAGEMENT_TOKEN"
# → { "troops": [ { "id": "troop_…", "name": "shop-team", … }, … ] }

# 2. Create a site key in that troop.
curl -s -X POST https://caputchin.com/api/v1/management/sites \
  -H "Authorization: Bearer $CAPUTCHIN_MANAGEMENT_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "name": "shop-frontend", "troop_id": "troop_…" }'
# → { "id": "site_…", "key": "cpt_pub_…", "secret": "cpt_sec_…", … }

La respuesta lleva la key pública de la nueva clave y su secret. El secreto se muestra una vez, aquí, así que captúralo ahora; lo usarás para verificar en tu backend. Omite troop_id y la clave aterriza en tu equipo Personal.

Ese es el patrón entero: un token Bearer, un cuerpo JSON, una llamada por operación. Listar es GET, crear es POST, actualizar es PATCH o PUT, quitar es DELETE, contra las rutas de recurso bajo la URL base.

La referencia completa

Cada endpoint, con sus parámetros, sus esquemas de petición y respuesta, y un panel integrado de "pruébalo" que se autentica con tu token, está en la referencia interactiva de la API. Se genera a partir de la misma especificación OpenAPI contra la que se construye la API, así que nunca se desvía de la superficie real. Apunta tus propios generadores de cliente a la spec enlazada ahí.

Véase también

Personal access token: la credencial maestra y cómo rastrear su uso.
Usa el servidor MCP: la misma API, conducida por un agente de IA.
Usa Terraform o OpenTofu: la misma API, como infraestructura como código.
Referencia interactiva de la API: cada endpoint y esquema.