创建和使用 API 密钥。
工作区所有者和管理员可在“开发者工具”中创建密钥。新密钥显示时立即复制；MCPBinder 仅保存其哈希值，不会再次显示。选择读取或任务编辑权限、设置到期时间，不再需要时撤销。
每次请求通过 HTTPS 发送，并附上 Authorization: Bearer YOUR_API_KEY。每个密钥每分钟限 120 次请求。API 返回 JSON。项目和任务列表支持游标分页；每页最多 1,000 条记录。
https://www.mcpbinder.com/api/v1
可用端点。
读取权限支持工作区详情、项目和任务。任务编辑密钥还可创建、更新和归档任务。更新任务需要当前版本号；若他人已先更改任务，API 将返回冲突，你可获取最新记录后重试。
createdAt 等时间戳为 UTC 的 ISO 8601 字符串，例如 2026-09-28T14:05:00.000Z。dueOn 为日历日期，例如 2026-09-28，不含时间或时区。
- GET /workspace — 当前工作区身份。
- GET /projects — 可见项目。
- GET /tasks — 可见的活跃任务；可用 ?projectId={uuid} 筛选。GET /tasks/{id} — 可见任务记录，归档时含 archivedAt。
- POST /tasks — 创建任务，提供 title 和可选的 description、projectId、dueOn。
- PATCH /tasks/{id} — 更新 title、description、dueOn、status、工作流状态、sectionId、labelIds 或 assignee。包含 version 和至少一个要更改的字段。
- DELETE /tasks/{id}?version={n} — 使用当前版本归档任务。这不会永久删除任务。
读取项目或任务的每一页。
GET /projects 和 GET /tasks 接受 limit（1–1,000；默认 1,000）及 cursor。每次响应包含 data、hasMore、nextCursor。将 nextCursor 作为下一次请求的 cursor，直到 nextCursor 为 null。始终使用相同的 projectId 筛选，并对查询值进行 URL 编码。
记录按稳定的 ID 升序返回。编辑项目项不会改变所在页。游标防篡改，并绑定工作区、用户、资源类型和项目筛选。每页均检查权限。无效或不匹配的游标返回 400。这是实时列表而非快照：游标之前新建的记录需重新遍历；已归档或不再可见的记录会消失。
GET /api/v1/tasks?limit=100&projectId=PROJECT_UUID&cursor=NEXT_CURSOR
创建和更新任务。
以 Content-Type: application/json 发送 JSON。创建时包含 Idempotency-Key 标头，避免相同请求重试产生重复工作。
- POST /tasks 正文：{ "title": "Review launch brief", "projectId": "PROJECT_UUID" }。
- PATCH /tasks/TASK_UUID 正文：{ "version": 1, "status": "in_progress" }。
订阅任务事件。
在“开发者工具”中创建 HTTPS 端点，选择接收的任务事件。每次 POST 包含事件 id、type、创建时间和任务数据：id、taskNumber、projectId、title、status、workflowStatusId、version、updatedAt。当前事件为 task.created、task.updated、task.completed、task.archived。
任务 webhook 由工作区所有者和管理员配置。它们向你选择的公开 HTTPS 端点发送任务标题和状态元数据；运营方按自身条款接收信息。状态变为 done 时同时发出 task.updated 和 task.completed。投递在后台运行，可能乱序到达；网络故障导致结果不确定时可能重复。网络故障、408、429 和 5xx 响应会退避重试，最多六次；其他非 2xx 响应标为失败。服务接受事件后请返回 2xx，并按事件 id 去重。
- X-MCPBinder-Event — 事件类型。
- X-MCPBinder-Event-Id — 跨重试去重使用的稳定事件 id。
- X-MCPBinder-Delivery-Id — 唯一的排队投递 id。
- X-MCPBinder-Timestamp — 以秒为单位的 Unix 时间戳。
- X-MCPBinder-Signature — t={timestamp},v1={hex HMAC-SHA256}。
检查并重新投递失败事件。
在“开发者工具”中打开“Webhook 投递”。首先显示失败事件；选择“所有投递”查看排队、运行和完成的投递。“检查事件”显示原始请求正文。刷新状态或加载更多查看较早事件。只有工作区所有者和管理员可检查负载或请求重新投递，且需近期安全验证。
修复接收端后，选择“重新投递事件”并确认。新投递使用原事件 ID 和完全相同的原始正文、新的投递 ID、更新时间戳和签名。保留原失败投递，并在审计日志记录请求。重复点击复用同一重新投递；若失败，重试新的失败投递。已撤销端点无法重新投递。始终按事件 ID 去重，因为即使发送方检测到失败，接收方也可能已接受事件。
验证 webhook 签名。
创建端点时复制签名密钥；仅显示一次。解析 JSON 前以原始字节读取请求正文。使用密钥和 UTF-8 字符串 `${timestamp}.${rawBody}` 计算 HMAC-SHA256。用恒定时间比较十六进制摘要与 v1，拒绝超出短重放窗口的时间戳。随后才解析 JSON 并处理事件。
端点 URL 在保存和投递前均被检查。请使用公开 HTTPS 地址。完整 URL 和签名密钥静态加密；设置页只显示端点来源，不显示路径或查询。撤销端点会停止未来排队发送，但无法收回已投递事件或正在发送的请求。
错误和访问。
401 表示密钥缺失、到期、撤销，或创建者不再是工作区所有者或管理员；失去该角色的创建者的密钥会自动撤销。403 表示密钥缺少所需权限，或请求项目对创建者不可见。409 表示任务版本过旧。429 包含 Retry-After。工作区项目可见性仍适用于 API 密钥。