DM Champ Docs

Champions Circle ボード API

Champions Circle リクエストボードは API 経由で利用可能です。独自のスクリプトから読み取り、検索、投稿を行ったり、MCP を通じて AI アシスタントに操作させたりすることができます。これはアプリ内の Circle → Requests で表示されるものと同じボードであり、同じリクエスト、同じコメント、同じ月間制限が適用されます。

これらのエンドポイントは Champions Circle メンバーのみが使用できます。それ以外のアカウントでは 403 と reason: "not_circle_member" が返されます。投稿は API キーが属するアカウントとして行われます。

エンドポイント

メソッド パス 説明
GET /v1/circle/requests ボードを一覧表示します（ピン留めされたリクエストが先頭、次に新しい順）。q で検索（タイトルと詳細）、status でフィルタリング（open, planned, building, shipped, declined）、limit（1〜100、デフォルト25）と cursor でページングが可能です。
GET /v1/circle/requests/{requestId} リクエストの詳細を取得します。
GET /v1/circle/requests/{requestId}/comments リクエストに対するコメントを取得します（古い順、ページングは同様）。
POST /v1/circle/requests リクエストを投稿します。ボディ: title（必須）および details。
PATCH /v1/circle/requests/{requestId} 自身が作成したリクエストの title や details を編集します。他人のリクエストに対しては 403 と reason: "edit_not_allowed" が返されます。
POST /v1/circle/requests/{requestId}/comments リクエストに返信します。ボディ: body。

すべてのリクエストには、id, title, details, status, author_name, vote_count, comment_count, created_at, updated_at、およびアプリで開くための url が含まれます。他のメンバーのメールアドレスは一切返されません。

ページング

リスト取得の呼び出しは next_cursor を返します。これを cursor として渡すことで次のページを取得できます。最後のページでは null となります。total は全ページを通じた一致件数です。

月間制限

API 経由の投稿もアプリ内のボードと同じ制限の対象となります。メンバーごとに直近30日間で4件のリクエストと4件のコメントまでです。制限を超えると、呼び出しに対して 429 が返され、次の利用可能枠までの時間が resets_at に示されます。

安全なリトライ

リクエストやコメントを投稿する際、任意のユニークな文字列を Idempotency-Key ヘッダー（またはボディの idempotency_key フィールド）に含めて送信してください。呼び出しがタイムアウトし、同じキーでリトライした場合、重複作成される代わりに、最初の呼び出しで作成された投稿がステータス 200 および idempotent_replay: true で返されます。リトライによって月間制限の枠が消費されることはありません。

curl -X POST "https://api.dmchamp.com/v1/circle/requests" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: dark-mode-2026-10-06" \
  -H "Content-Type: application/json" \
  -d '{"title": "Dark mode for the inbox", "details": "My team works late and would love a dark theme."}'

スコープ付きキー

ボードには、スコープ付きキーに付与できる2つのセクションがあります：

セクション 許可される操作
Circle リクエストとコメントの一覧表示、検索、読み取り。
Circle Write リクエストの投稿、自身のリクエストの編集、コメントの投稿。

ボードの読み取りのみを行うキーには Circle のみを付与してください。メインキー、および tags リストが空のスコープ付きキーは、両方の操作が可能です。

MCP について

これらのエンドポイントは API 仕様の一部であるため、MCP 経由で接続した AI アシスタントには追加設定なしでツールとして表示されます。重複したリクエストを作成しないよう、アシスタントにボードを検索させてから既存のリクエストにコメントするように依頼してください。