Qoder Cloud Agents API 提供完整的云端 AI Agent 管理能力，涵盖 Agent 创建、环境配置、会话管理、事件流处理等核心功能。所有接口遵循 RESTful 设计，使用 JSON 作为请求/响应格式。
当前 API 处于 Beta 阶段，部分功能可能在后续版本中调整。
Gateway URL
环境 | URL |
生产环境 |
|
版本
API 当前为 v1 版本，所有端点通过 /v1/ 路径前缀区分版本，无需传递额外的版本头。
可用 API 列表
资源 | 说明 | 基础路径 |
Agents | Agent 实例的增删改查与归档 |
|
Environments | 运行环境配置管理 |
|
Sessions | Agent 会话的创建与生命周期管理 |
|
Events | 会话事件流的读取与推送 |
|
Files | 文件上传与关联管理 |
|
Vaults | 敏感凭据的安全存储 |
|
Skills | Agent 技能的注册与管理 |
|
Memory Stores | 持久化记忆存储 |
|
请求大小限制
单次请求 Body 最大：4 MB
超过限制时服务端会截断 Body，导致 JSON 解析失败并返回 400
invalid_request_error（message: “Request body must be valid JSON.”）
必需请求头
每个 API 请求必须包含认证头，建议同时携带 Content-Type：
Authorization: Bearer $QODER_PAT
Content-Type: application/json # 推荐但非强制，服务端可自动推断
Beta 状态说明
API 接口整体稳定，但签名可能在未来版本迭代中微调
新增功能将以新的 beta 标识发布
建议在生产环境中做好版本锁定与兼容处理
当前所有功能均可直接使用，无需额外的 Beta 头激活
快速验证连通性
# 列出当前账户下的 Agents（验证认证与连通）
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=1" \
-H "Authorization: Bearer $QODER_PAT"
成功响应示例：
{
"data": [],
"first_id": null,
"last_id": null,
"has_more": false
}
限流说明
当前 API 应用层暂无主动限流。网关层有全局突发流量抑制和 DDoS 防护，触发时可能返回 429 或 503。建议客户端对 5xx/429 实施指数退避重试（1s → 2s → 4s，最多 3 次）。