API 概览
与 Cliqer 集成的完整 API 文档
客户端 API 即 API 附加组件：Presenter、Studio HD 和 Studio 4K 需单独购买，Studio 8K 和 Enterprise 已包含。用于无人值守、服务器到服务器访问 REST 端点的长期 API 密钥在 Studio 8K 和 Enterprise 套餐中生成，请参阅 API 密钥认证。比较套餐。
Cliqer API 的完整文档，涵盖 REST 端点和 WebSocket 实时通信。
基础 URL
https://cliqer.io/api所有 API 端点均相对于您所连接的 Cliqer 服务器的基础 URL。
代码示例：在 curl/Python/Go 示例中，请将
$BASE_URL 替换为您的 Cliqer 实例 URL（例如 https://cliqer.io）。在 WebSocket 示例中，请将 $WS_URL 替换为 wss://cliqer.io。TypeScript 示例使用相对路径，无需修改即可使用。认证
Cliqer 使用 httpOnly 会话 Cookie（session_token）进行认证，该 Cookie 由 POST /api/auth/login 生成。浏览器会自动发送该 Cookie；服务器到服务器的工具则将其保存在 Cookie Jar 中。Studio 8K 和 Enterprise 团队还可以生成 API 密钥，用于服务器到服务器的 REST 请求，以 Authorization: Bearer cliqer_<key> 的形式发送（密钥管理需要 Studio 8K 或 Enterprise 套餐）。WebSocket 不接受 API 密钥：请使用会话令牌进行连接。
# The session cookie is set by /api/auth/login and sent on every subsequent request
Cookie: session_token=YOUR_SESSION_TOKEN
# Or authenticate a server-to-server REST request with a team API key
Authorization: Bearer cliqer_<key>
少数端点无需会话，例如公开的 POST /api/licenses/validate。
有关登录、会话轮换和安全最佳实践，请参阅认证。
API 章节
请求生命周期
错误响应
所有端点均返回标准错误响应：
| 状态码 | 说明 |
|---|---|
400 | 错误请求：缺少参数或参数无效 |
401 | 未授权：没有有效的会话 Cookie |
403 | 禁止访问：权限不足或来源不被允许 |
404 | 未找到：资源不存在 |
409 | 冲突：例如已达到许可证激活席位上限 |
429 | 请求过多：超出速率限制（参见 Retry-After） |
500 | 服务器内部错误 |
错误响应格式：
{
"statusCode": 400,
"statusMessage": "Description of the error"
}
速率限制
大多数端点按客户端 IP 进行速率限制，采用固定的 60 秒窗口，分为三个等级。当请求超出限制时，服务器会返回 429 Too Many Requests，并附带 Retry-After: 60 标头。不存在渐进式/指数式封禁，也不会返回 X-RateLimit-Remaining 标头。
| 标头 | 说明 |
|---|---|
Retry-After | 距窗口重置的秒数（60，仅在返回 429 时发送） |
速率限制等级
| 等级 | 请求数 / 60 秒 | 适用范围 |
|---|---|---|
| 严格 | 5 | POST /api/licenses/validate 及登录相关端点（POST /api/auth/login、注册、密码重置、通行密钥和双重验证步骤） |
| 标准 | 30 | GET /api/licenses/status、POST /api/licenses/deactivate、GET /api/auth/me、POST /api/auth/logout |
| 宽松 | 60 | 高流量读取端点 |
有两个端点额外施加第二道严格限制，以凭据而非 IP 为键，因此无法通过大量地址轮番冲击同一目标：POST /api/licenses/validate 以 license_key 为键，POST /api/auth/login 以电子邮件地址为键。
超出某一等级的限制后，在该 60 秒窗口的剩余时间内都将返回
429。速率限制由服务器自身强制执行，在端点处理请求之前即已生效。