# 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` で返されます。リトライによって月間制限の枠が消費されることはありません。

```bash
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."}'
```

## スコープ付きキー

ボードには、[スコープ付きキー](api-keys.md#scoped-keys)に付与できる2つのセクションがあります：

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

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

## MCP について

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