Gerencie o Caputchin pela API

Tudo o que você consegue fazer no painel, salvo faturamento, você também consegue fazer a partir do código. O Caputchin expõe uma API de gestão, e três superfícies ficam em cima dela: esta API HTTP diretamente, o servidor MCP para agentes de IA, e o provedor Terraform e OpenTofu para infraestrutura como código. Elas diferem só na borda; a mesma validação, permissões e registro de auditoria se aplicam qualquer que seja a que você use.

As três se autenticam com a mesma credencial: um token de acesso que você acune uma vez.

Acune um token de acesso

Você envia o token como um cabeçalho Bearer. Há dois tipos, cobertos por completo em token de acesso pessoal e tokens de equipe:

Token	Alcance	Acune-o
Token de acesso pessoal	Mestre sobre toda a sua conta	Configurações da conta. Grátis, um por conta.
Token de acesso de equipe	Só as equipes a que está ligado, com as permissões concedidas	A página de tokens de uma equipe. Ocupa um assento.

Use um token de acesso pessoal para sua própria automação de conta inteira; use um token de equipe para acesso delimitado, de menor privilégio (um job de CI que só toca uma equipe). Qualquer um funciona em todo o resto abaixo. O valor do token é mostrado uma vez na criação, então copie-o para um cofre de segredos.

URL base e autenticação

A API de gestão tem raiz em:

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

Toda requisição carrega o token como um cabeçalho Bearer:

Authorization: Bearer cpt_pat_...

Requisições e respostas são JSON. Uma chamada que seu token não tem permissão de fazer retorna 403; um token desconhecido ou revogado retorna 401.

Um exemplo prático: criar uma chave de site

Digamos que você queira uma nova chave de site na sua equipe shop-team. Primeiro liste suas equipes para achar o id dela, depois crie a chave nela.

# 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_…", … }

A resposta carrega a key pública da nova chave e seu secret. O segredo é mostrado uma vez, aqui, então capture-o agora; você vai verificar com ele no seu backend. Omita troop_id e a chave cai na sua equipe Pessoal.

Esse é o padrão inteiro: um token Bearer, um corpo JSON, uma chamada por operação. Listar é GET, criar é POST, atualizar é PATCH ou PUT, remover é DELETE, contra os caminhos de recurso sob a URL base.

A referência completa

Cada endpoint, com seus parâmetros, esquemas de requisição e resposta, e um painel embutido de "experimente" que se autentica com seu token, está na referência interativa da API. Ela é gerada da mesma especificação OpenAPI contra a qual a API é construída, então nunca desvia da superfície ativa. Aponte seus próprios geradores de cliente para a spec linkada ali.

Veja também

Token de acesso pessoal: a credencial mestre e como rastrear seu uso.
Use o servidor MCP: a mesma API, conduzida por um agente de IA.
Use Terraform ou OpenTofu: a mesma API, como infraestrutura como código.
Referência interativa da API: cada endpoint e esquema.