API 概览

这是 Capgo 云公共 API 的文档。你可以使用 API 以编程方式管理 Capgo 资源，包括组织、设备、频道和 bundle。它采用 RESTful 设计，并使用标准 HTTP 方法。

身份验证

所有 API 端点都需要身份验证。若要对请求进行身份验证，请在其中添加您的 API 密钥 x-api-key 在 header 中，或将其作为 Authorization: Bearer YOUR_API_KEY.

示例：

curl -H "x-api-key: YOUR_API_KEY" https://api.capgo.app/organization/

获取 API 密钥 在 Capgo dashboard 中生成您的 API 密钥

本指南中介绍的 authorization header 传入原始密钥（不带 Bearer 前缀）仍可用于旧版集成，但 x-api-key 是所有密钥类型（包括安全哈希密钥）推荐使用的 header。

AI agent 和其他 OAuth 客户端可以通过 OAuth 2.0（使用 PKCE 和动态客户端注册进行授权 code）获取密钥。发行方是 https://capgo.app，并附带以下元数据： https://capgo.app/.well-known/oauth-authorization-server。用户可以选择授权哪些组织，访问令牌是一个作为 Bearer token 发送的 Capgo API 密钥。

版本管理

API 按日期进行版本管理。可以通过以下 capgo_api 请求头来固定版本：

curl -H "x-api-key: YOUR_API_KEY" -H "capgo_api: 2025-10-01" https://api.capgo.app/organization/

如果不提供该请求头，则使用默认版本，当前为 2025-10-01。同一版本内的变更均为增量式的：例如新增 endpoint、新增可选参数或新增响应字段。破坏性变更（breaking change）会发布为新的日期版本，而固定在旧日期的客户端将保持原有行为。若版本未知或格式错误，则返回 400 unsupported_capgo_api_version 或 400 invalid_capgo_api_version.

删除操作或字段属于破坏性变更，因此仅会在新的日期版本中发生。目前没有任何功能被弃用（deprecated）。一旦某功能被弃用，该操作将被标记为 deprecated: true ，详见 OpenAPI 规范，其响应将包含 Deprecation header (RFC 9745) 以及 Sunset header (RFC 8594)，其中包含旧行为结束的日期，且变更将在 版本说明.

速率限制

API 实现了速率限制以确保公平使用。当前的限制为：

• 每个 API 密钥每分钟 2,000 次请求
• bundle upload 路由下每个 API 密钥每分钟 20,000 次请求
• 每个 IP 地址在 15 分钟内允许 20 个无效 API 密钥，超过后该 IP 将被封禁 15 分钟

每个响应都会通过以下 headers 报告配额： RateLimit-Policy 以及 RateLimit (IETF 草案):

RateLimit-Policy: "apikey";q=2000;w=60
RateLimit: "apikey";r=1995;t=42

q 是配额， w 是以秒为单位的时间窗口， r 是剩余请求数，以及 t 距离窗口重置的秒数。如果超出限制，你会收到 429（Too Many Requests）响应，并带有 Retry-After 以秒为单位的响应头。

设备频道变更

设备频道变更使用 API 插件，并有独立的防滥用限制，适用于所有套餐（包括试用）：

• 每台设备针对每种频道操作每秒最多可发起 5 次请求（set, get, delete，或 list）。该限制按 App、设备和操作分别计算。
• 在 60 秒内将同一设备重复设置到同一频道会返回 429 响应。每秒限制重置后，可以切换到其他频道。
• 每个 App 和 IP 地址还有额外限制：每分钟 1000 次频道请求。

这些限制不是账户级的。如果你的频道切换器可以回到最近选择的频道，请等待 retryAfterSeconds 429 响应中的时长后再重试。

响应格式

所有响应均为 JSON 格式。成功响应通常包含一个 data 对象或一个 status 字段。错误响应包含一个机器可读的 error code，以及一个人类可读的 message，以及可选的 moreInfo 详情。

成功响应示例：

{
  "status": "ok",
  "data": { ... }
}

错误响应示例：

{
  "error": "invalid_apikey",
  "message": "Invalid apikey",
  "moreInfo": {}
}

可用端点

组织 创建并管理组织、更新设置以及处理组织级配置

API 密钥 生成、列出并撤销 API 密钥，以安全访问 Capgo API

成员 管理组织成员、角色与权限

统计数据 获取有关 App 使用情况、存储和带宽消耗的详细分析数据

通道 控制 App 更新频道、bundle (版本) 以及更新策略

设备 跟踪并管理运行你的 App 的设备，包括 bundle（版本）和 channel 分配

Bundle 处理 App bundle，包括上传、列出和管理 bundle（版本）

最佳实践

1. 错误处理: 始终检查错误响应并妥善处理
2. 速率限制: 遇到速率限制时，实现指数退避
3. 缓存: 在适当情况下缓存响应，以减少 API 调用
4. 版本管理通过我们的更新日志追踪 API 的变更

继续阅读 API 概览

如果你正在使用 API 概览 用来规划身份验证和账户流程，并将它与 @capgo/capacitor-social-login 在 @capgo/capacitor-social-login 中查看实现细节， @capgo/capacitor-passkey 有关 @capgo/capacitor-passkey 的实现细节， @capgo/capacitor-native-biometric 有关 @capgo/capacitor-native-biometric 的实现细节， 双因素认证 有关双因素认证的实现细节，以及 SSO (企业版) 有关 SSO (Enterprise) 的实现细节。