从 API 管理 Caputchin

你在仪表盘里能做的一切，除了账单，也都能从代码里做。Caputchin 暴露 一个管理 API，三个面坐落在它之上：直接的这个 HTTP API、给 AI 代理用的 MCP 服务器，以及给基础设施即代码用的 Terraform 和 OpenTofu 提供方。它们只在边缘有所不同；无论你用哪个，同样的校验、权限和审计日志都适用。

三者都用同一份凭据做身份验证：一个你铸造一次的访问令牌。

铸造一个访问令牌

你把令牌作为一个 Bearer 头发送。有两种，在 个人访问令牌 和 团队令牌 下有完整说明：

用一个个人访问令牌来做你自己的全账户自动化；用一个团队令牌来做限定范围、最小权限的访问（一个只碰一个团队的 CI 任务）。下面任何地方两者都能用。令牌的值在创建时只 显示一次，所以把它复制进一个密钥存储里。

基址与认证

管理 API 的根是：

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

每个请求都把令牌作为一个 Bearer 头带上：

Authorization: Bearer cpt_pat_...

请求和响应是 JSON。一个你的令牌不被允许发起的调用返回 403；一个未知或已吊销的令牌返回 401。

一个完整示例：创建一个站点密钥

假设你想在你的 shop-team 团队里要一个新的站点密钥。先列出你的团队以找到它的 id，然后在它里面创建密钥。

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

响应携带这个新密钥的公开 key 和它的 secret。密钥只显示一次，就在这里，所以现在就抓住它；你会 在你的后端用它核验。省略 troop_id，密钥就落在你的个人团队里。

这就是整个套路：一个 Bearer 令牌、一个 JSON 体、每个操作一个调用。列出是 GET，创建是 POST，更新是 PATCH 或 PUT，移除是 DELETE，针对基址下的资源路径。

完整参考

每个端点，带它的参数、请求和响应模式，以及一个用你的令牌做身份验证的内置“试一试”面板，都在 交互式 API 参考 里。它是从 API 所依据的同一份 OpenAPI 规范生成的，所以它绝不偏离线上的真实面。把你自己的客户端生成器指向那里链接的规范。

另见

• 个人访问令牌：那份主凭据，以及如何追踪它的使用。
• 使用 MCP 服务器：同样的 API，由一个 AI 代理驱动。
• 使用 Terraform 或 OpenTofu：同样的 API，作为基础设施即代码。
• 交互式 API 参考：每个端点和模式。