API 概览 - Qoder

Qoder Cloud Agents API 提供完整的云端 AI Agent 管理能力，涵盖 Agent 创建、环境配置、会话管理、事件流处理等核心功能。所有接口遵循 RESTful 设计，使用 JSON 作为请求/响应格式。

当前 API 处于 Beta 阶段，部分功能可能在后续版本中调整。

Gateway URL

环境	URL
生产环境（Managed Mode）	`https://api.qoder.com/api/v1/cloud`
生产环境（Forward Mode）	`https://api.qoder.com/api/v1/forward`

版本

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 和吊销企业 Service Account Token	`/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）

快速验证连通性

# 列出当前账户下的 Agents（验证认证与连通）
curl -s "https://api.qoder.com/api/v1/cloud/agents?limit=1" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

成功响应示例：

{
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

限流说明

当前 API 应用层暂无主动限流。网关层有全局突发流量抑制和 DDoS 防护，触发时可能返回 429 或 503。建议客户端对 5xx/429 实施指数退避重试（1s → 2s → 4s，最多 3 次）。

下一步

认证

获取和使用 PAT 或 SAT。

错误参考

错误码与排查。

分页

列表接口分页。

​Gateway URL

​版本

​可用 API 列表

​请求大小限制

​必需请求头

​Beta 状态说明

​快速验证连通性

​限流说明

​下一步

认证

错误参考

分页

Gateway URL

版本

可用 API 列表

请求大小限制

必需请求头

Beta 状态说明

快速验证连通性

限流说明

下一步