API から Caputchin を管理する

ダッシュボードでできることは、請求を除き、コードからもすべてできます。Caputchin は 唯一の管理 API を公開し、その上に 3 つの面が乗ります。この HTTP API を直接、AI エージェント向けの MCP サーバー、そして infrastructure-as-code 向けの Terraform と OpenTofu のプロバイダーです。それらは縁でしか違いません。どれを使っても、同じ検証、権限、監査ログが適用されます。

3 つすべてが同じ資格情報で認証します。一度発行するアクセストークンです。

アクセストークンを発行する

トークンは Bearer ヘッダーとして送ります。2 種類あり、Personal Access Token とチームトークンの下で完全に扱われます：

トークン	到達範囲	発行する場所
Personal Access Token	あなたのアカウント全体へのマスター	アカウント設定。無料、アカウントにつき 1 つ。
Troop Access Token	紐づけられたチームだけ、付与された権限で	チームのトークンページ。シートを取る。

あなた自身のアカウント全体の自動化にはPersonal Access Tokenを、スコープづけされた最小権限のアクセス（1 つのチームだけに触れる CI ジョブ）にはチームトークンを使ってください。どちらも以下のすべてで動きます。トークンの値は作成時に 一度だけ 表示されるので、シークレットストアにコピーしてください。

ベース URL と認証

管理 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 のボディ、操作ごとに 1 回の呼び出し。一覧は GET、作成は POST、更新は PATCH か PUT、削除は DELETE を、ベース URL の下のリソースパスに対して行います。

完全なリファレンス

すべてのエンドポイントを、そのパラメータ、リクエストとレスポンスのスキーマ、そしてあなたのトークンで認証する組み込みの「試す」パネルとともに、インタラクティブ API リファレンスで示します。それは API が作られているのと同じ OpenAPI 仕様から生成されるので、ライブの面から決してずれません。あなた自身のクライアントジェネレーターを、そこにリンクされた仕様に向けてください。

あわせて読む

Personal Access Token：マスター資格情報と、その使用を追跡する方法。
MCP サーバーを使う：同じ API を、AI エージェントが駆動する。
Terraform または OpenTofu を使う：同じ API を、infrastructure-as-code として。
インタラクティブ API リファレンス：すべてのエンドポイントとスキーマ。