API 认证与限流
使用正确的用户或团队凭据，区分 Basic、Bearer、分页和缓存规则。
Cloud Agents API 基址为 https://api.cursor.com。从 Dashboard > API Keys 创建用户 key，或使用服务账号 API key。企业管理数据接口要求对应管理权限，不应混用不同接口的认证规则。
HTTP 认证
Cloud Agents API 接受 Basic 和 Bearer，行为相同。Basic 把 key 作为用户名，密码为空；冒号必须保留。
curl https://api.cursor.com/v1/me -u YOUR_API_KEY:
curl https://api.cursor.com/v1/me -H 'Authorization: Bearer YOUR_API_KEY'Admin、Analytics、AI Code Tracking 和 Bugbot review/analytics 文档要求 Basic。Bugbot Admin Configuration 端点另要求 Bearer，见Bugbot API。Admin 与 AI Code Tracking key 要求 admin:* scope。Origin 使用其 CLI 交换的短期用户 token 或 App 凭据，admin:* 管理 key 不能直接认证 Origin。
官方 API 总览的 Analytics 缓存示例用了 Bearer，与该页认证规则不一致；本文以认证说明为准，不将那个示例推广为 Analytics 支持 Bearer。
常见响应
| 状态码 | 处理方向 |
|---|---|
| 400 | 检查必填字段、类型和参数组合 |
| 401 | 检查 key 是否提供、有效及格式正确 |
| 403 | 检查权限、套餐和资源范围 |
| 404 | 检查资源是否存在及对应 ID |
| 409 | 按具体冲突处理，例如 Agent 忙或 ID 已存在 |
| 429 | 遵守 Retry-After（若返回），并使用指数退避 |
| 500 | 暂时性服务问题可重试，持续失败提交诊断信息 |
不要把所有接口的错误 JSON 当成同一 schema，读取各接口实际返回的 code/message。
限流
总览规定未单独说明时默认每分钟 20 次，通常按用户、团队或组织及单端点计数；Cloud Agents 在汇总表只写 Standard rate limiting，具体端点限制优先。
GET /v1/repositories 特别严格：每用户每分钟 1 次、每小时 30 次，可能耗时数十秒。它仅列出 GitHub App 可访问的 GitHub 仓库；GitLab、Bitbucket Cloud 和 Azure DevOps 不在结果中，不代表不能用它们创建任务。
Admin 大多数端点每分钟 20 次，filtered usage events 为 60 次，单用户 spend limit 为 250 次。Analytics 多数团队端点 100 次、conversation insights 20 次、by-user 50 次。Bugbot review 为 30 次，dryRun 另外受 10 次限制。完整例外以官方表为准。
缓存与轮询
Analytics 和 AI Code Tracking 支持 ETag：首次保存响应 ETag，后续带 If-None-Match；内容未变返回无正文的 304，官方说明不计限流。缓存时间为 15 分钟，Cache-Control: public, max-age=900。不要把这项支持自动套到所有 Cloud Agents 端点。
Admin 的 daily usage、filtered usage events、organization pooled usage 等数据按小时聚合，官方建议最多每小时轮询一次。实时 Agent 进度优先读取SSE 流。