Qoder Cloud Agents API 提供完整的云端 AI Agent 管理能力，涵盖 Agent 创建、环境配置、会话管理、事件流处理等核心功能。所有接口遵循 RESTful 设计，使用 JSON 作为请求/响应格式。
当前 API 处于 Beta 阶段，部分功能可能在后续版本中调整。
Gateway URL
API 当前为 v1 版本。接口根据模式使用 /api/v1/cloud 或 /api/v1/forward 前缀，无需传递额外的版本头。
可用 API 列表
| 资源 | 说明 | 基础路径 |
|---|
| Agents | Agent 实例的增删改查与归档 | /agents |
| Environments | 运行环境配置管理 | /environments |
| Sessions | Agent 会话的创建与生命周期管理 | /sessions |
| Events | 会话事件流的读取与推送 | /events |
| Files | 文件上传与关联管理 | /files |
| Vaults | 敏感凭据的安全存储 | /vaults |
| Skills | Agent 技能的注册与管理 | /skills |
| Memory Stores | 持久化记忆存储 | /memory_stores |
| Deployments | 定时部署自动化 | /deployments |
| Work | 自托管 Environment 的 work 队列与 worker lease 生命周期 | /environments/{environment_id}/work |
| Forward Templates | Forward Agent 模板定义、版本、归档与克隆 | /api/v1/forward/templates |
| Forward Identities | Forward 身份创建、启停、删除与 Agent 查询 | /api/v1/forward/identities |
| Forward Service Account Tokens | 企业服务账号令牌的创建、Identity 绑定与吊销 | /api/v1/forward/service_account_tokens |
| Forward Identity Configs | 身份维度的模板配置与生效配置查询 | /api/v1/forward/identities/{identity_id}/templates |
| Forward Channels | Forward 渠道与二维码会话管理 | /api/v1/forward/channels、/api/v1/forward/qr_sessions |
| Forward Sessions | Forward 会话生命周期、事件与 SSE 流 | /api/v1/forward/sessions |
| Forward Environments | Forward 运行环境生命周期管理 | /api/v1/forward/environments |
| Forward Skills | Forward Skill 生命周期管理 | /api/v1/forward/skills |
| Forward Vaults | Forward Vault 生命周期管理 | /api/v1/forward/vaults |
| Forward Credentials | Vault 下的凭据管理 | /api/v1/forward/vaults/{vault_id}/credentials |
| Forward Files | Forward 文件上传、查询、下载与删除 | /api/v1/forward/files |
| Forward Schedules | Forward 定时任务与运行记录管理 | /api/v1/forward/schedules、/api/v1/forward/schedule_runs |
请求大小限制
- 单次请求 Body 最大：4 MB
- 超过限制时服务端会截断 Body，导致 JSON 解析失败并返回 400
invalid_request_error（message: "Request body must be valid JSON."）
必需请求头
每个 API 请求必须在认证头中携带 PAT 或 SAT，建议同时携带 Content-Type：
Authorization: Bearer $QODER_ACCESS_TOKEN
Content-Type: application/json # 推荐但非强制，服务端可自动推断
Beta 状态说明
- API 接口整体稳定，但签名可能在未来版本迭代中微调
- 新增功能将以新的 beta 标识发布
- 建议在生产环境中做好版本锁定与兼容处理
- 使用 Beta 功能时，请通过
x-qoder-beta 声明对应的 Beta 标识
| Beta 标识 | 覆盖范围 | 使用说明 |
|---|
browser-use-2026-07-14 | browser_toolset_20260714、浏览器工具和实时预览 | Browser Use（Beta） |
search-2026-08-31 | Agents、Sessions、Files、Skills、Memory Stores、Deployments、Environments 和 Vaults 的 Metadata Search | 按 metadata 搜索 Skills（Beta） |
快速验证连通性
# 列出当前账户下的 Agents（验证认证与连通）
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=1" \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN"
{
"data": [],
"first_id": null,
"last_id": null,
"has_more": false
}
限流说明
Metadata Search 接口默认限制同一调用方最多 10 个 CAS 在途请求。其他 API 当前没有应用层限流。网关层另有全局突发流量抑制和 DDoS 防护，触发时可能返回 429 或 503。建议客户端对 5xx/429 实施指数退避重试（1s → 2s → 4s，最多 3 次）。
下一步
