跳转到主要内容
Qoder Cloud Agents API 提供完整的云端 AI Agent 管理能力，涵盖 Agent 创建、环境配置、会话管理、事件流处理等核心功能。所有接口遵循 RESTful 设计，使用 JSON 作为请求/响应格式。
当前 API 处于 Beta 阶段，部分功能可能在后续版本中调整。

​
Gateway URL

环境URL
生产环境https://api.qoder.com/api/v1/cloud

​
版本

API 当前为 v1 版本，所有端点通过 URL 前缀 /api/v1/cloud 中的 v1 段区分版本，无需传递额外的版本头。

​
可用 API 列表

资源说明基础路径
AgentsAgent 实例的增删改查与归档/agents
Environments运行环境配置管理/environments
SessionsAgent 会话的创建与生命周期管理/sessions
Events会话事件流的读取与推送/events
Files文件上传与关联管理/files
Vaults敏感凭据的安全存储/vaults
SkillsAgent 技能的注册与管理/skills
Memory Stores持久化记忆存储/memory_stores
Deployments定时部署自动化/deployments
Work自托管 Environment 的 work 队列与 worker lease 生命周期/environments/{environment_id}/work
Forward TemplatesForward Agent 模板定义、版本、归档与克隆/api/v1/forward/templates
Forward IdentitiesForward 身份创建、启停、删除与 Agent 查询/api/v1/forward/identities
Forward Identity Configs身份维度的模板配置与生效配置查询/api/v1/forward/identities/{identity_id}/templates
Forward ChannelsForward 渠道与二维码会话管理/api/v1/forward/channels、/api/v1/forward/qr_sessions
Forward SessionsForward 会话生命周期、事件与 SSE 流/api/v1/forward/sessions
Forward ResourcesForward 外部资源注册与列表/api/v1/forward/resources
Forward SchedulesForward 定时任务与运行记录管理/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 请求必须包含认证头，建议同时携带 Content-Type： 
Authorization: Bearer $QODER_PAT
Content-Type: application/json  # 推荐但非强制，服务端可自动推断

​
Beta 状态说明

  1. API 接口整体稳定，但签名可能在未来版本迭代中微调
  2. 新增功能将以新的 beta 标识发布
  3. 建议在生产环境中做好版本锁定与兼容处理
  4. 当前所有功能均可直接使用，无需额外的 Beta 头激活

​
快速验证连通性

# 列出当前账户下的 Agents（验证认证与连通）
curl -s "https://api.qoder.com/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 次）。

​
下一步

认证

获取和使用 PAT。

错误参考

错误码与排查。

分页

列表接口分页。