# Champions Circle Board API

The Champions Circle request board is available over the API, so you can read it, search it and post to it from your own scripts, or let an AI assistant do it for you over MCP. It is the same board you see under **Circle → Requests** in the app: the same requests, the same comments and the same monthly limits.

Only Champions Circle members can use these endpoints. Any other account gets `403` with `reason: "not_circle_member"`. Posts are made as the account the API key belongs to.

## Endpoints

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | `/v1/circle/requests` | List the board, pinned requests first, then newest first. Search with `q` (title and details), filter with `status` (`open`, `planned`, `building`, `shipped`, `declined`), page with `limit` (1 to 100, default 25) and `cursor`. |
| `GET` | `/v1/circle/requests/{requestId}` | One request with its full details. |
| `GET` | `/v1/circle/requests/{requestId}/comments` | The comments on a request, oldest first, paged the same way. |
| `POST` | `/v1/circle/requests` | File a request. Body: `title` (required) and `details`. |
| `PATCH` | `/v1/circle/requests/{requestId}` | Edit the `title` and/or `details` of a request you wrote. Anyone else's request answers `403` with `reason: "edit_not_allowed"`. |
| `POST` | `/v1/circle/requests/{requestId}/comments` | Reply on a request. Body: `body`. |

Every request comes back with its `id`, `title`, `details`, `status`, `author_name`, `vote_count`, `comment_count`, `created_at`, `updated_at` and a `url` that opens it in the app. Other members' email addresses are never returned.

### Paging

List calls return `next_cursor`. Pass it as `cursor` to get the next page; it is `null` on the last page. `total` is the number of matches across all pages.

### Monthly limits

API posts count against the same limits as the board in the app: 4 requests and 4 comments per member in any rolling 30 days. Over the limit the call answers `429` with a `resets_at` time for the next free slot.

### Safe retries

Send an `Idempotency-Key` header (or an `idempotency_key` field in the body) with any unique string when you file a request or a comment. If the call times out and you retry with the same key, you get back the post the first call created, with status `200` and `idempotent_replay: true`, instead of a duplicate. A retry never uses up another slot of your monthly limit.

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

## Scoped keys

The board has two sections you can grant to a [scoped key](api-keys.md#scoped-keys):

| Section | Allows |
| --- | --- |
| `Circle` | Listing, searching and reading requests and comments. |
| `Circle Write` | Filing requests, editing your own requests and commenting. |

Grant only `Circle` to a key that should just read the board. Your main key, and a scoped key with an empty `tags` list, can use both.

## Over MCP

These endpoints are part of the API specification, so they show up as tools for any AI assistant you [connect over MCP](../integrations/connect-ai-clients.md), with no extra setup. Ask your assistant to search the board before filing, so it comments on an existing request instead of filing a duplicate.