Manage Caputchin from the API
Everything you can do in the dashboard, short of billing, you can also do from code. Caputchin exposes one management API, and three surfaces sit on top of it: this HTTP API directly, the MCP server for AI agents, and the Terraform and OpenTofu provider for infrastructure-as-code. They differ only at the edge; the same validation, permissions, and audit logging apply whichever you use.
All three authenticate with the same credential: an access token you mint once.
Mint an access token
You send the token as a Bearer header. There are two kinds, covered in full under personal access token and troop tokens:
| Token | Reach | Mint it |
|---|---|---|
| Personal access token | Master over your whole account | Account settings. Free, one per account. |
| Troop access token | Only the troops it is attached to, with granted permissions | A troop's tokens page. Takes a seat. |
Use a personal access token for your own full-account automation; use a troop token for scoped, least-privilege access (a CI job that only touches one troop). Either works everywhere below. The token value is shown once at creation, so copy it into a secret store.
Base URL and auth
The management API is rooted at:
https://caputchin.com/api/v1/managementEvery request carries the token as a Bearer header:
Authorization: Bearer cpt_pat_...Requests and responses are JSON. A call your token is not allowed to make returns 403; an unknown or revoked token returns 401.
A worked example: create a site key
Say you want a new site key in your shop-team troop. First list your troops to find its id, then create the key in it.
# 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_…", … }The response carries the new key's public key and its secret. The secret is shown once, here, so capture it now; you will verify with it on your backend. Omit troop_id and the key lands in your Personal troop.
That is the whole pattern: a Bearer token, a JSON body, one call per operation. Listing is GET, creating is POST, updating is PATCH or PUT, removing is DELETE, against the resource paths under the base URL.
The full reference
Every endpoint, with its parameters, request and response schemas, and a built-in "try it" panel that authenticates with your token, is in the interactive API reference. It is generated from the same OpenAPI specification the API is built against, so it never drifts from the live surface. Point your own client generators at the spec linked there.
See also
- Personal access token: the master credential and how to trace its use.
- Use the MCP server: the same API, driven by an AI agent.
- Use Terraform or OpenTofu: the same API, as infrastructure-as-code.
- Interactive API reference: every endpoint and schema.