# Champions Circle 看板 API

Champions Circle 请求看板可通过 API 访问，因此您可以从自己的脚本中读取、搜索和发布内容，或者让 AI 助手通过 MCP 为您代劳。它与您在应用程序中 **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)：

| 部分 | 允许 |
| --- | --- |
| `Circle` | 列出、搜索和读取请求及评论。 |
| `Circle Write` | 提交请求、编辑您自己的请求以及发表评论。 |

如果密钥仅用于读取看板，请仅授予 `Circle`。您的主密钥以及 `tags` 列表为空的作用域密钥可以使用这两个部分。

## 关于 MCP

这些端点是 API 规范的一部分，因此它们会作为工具显示在您通过 [MCP 连接](../integrations/connect-ai-clients.md) 的任何 AI 助手上，无需额外设置。在提交请求之前，请让您的助手搜索看板，这样它就可以在现有请求上发表评论，而不是提交重复的请求。