> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 概览

> Qoder Cloud Agents API 的整体说明、网关地址、资源列表与连通性验证。

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

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

## Gateway URL

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

## 版本

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

## 可用 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 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 Resources        | Forward 外部资源注册与列表                            | `/api/v1/forward/resources`                                 |
| 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 请求必须包含认证头，建议同时携带 Content-Type：

```
Authorization: Bearer $QODER_PAT
Content-Type: application/json  # 推荐但非强制，服务端可自动推断
```

## Beta 状态说明

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

## 快速验证连通性

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

成功响应示例：

```json theme={null}
{
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}
```

## 限流说明

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

## 下一步

<CardGroup cols={3}>
  <Card title="认证" icon="key" href="/zh/cloud-agents/api/conventions/authentication">
    获取和使用 PAT。
  </Card>

  <Card title="错误参考" icon="triangle-exclamation" href="/zh/cloud-agents/api/conventions/errors">
    错误码与排查。
  </Card>

  <Card title="分页" icon="list" href="/zh/cloud-agents/api/conventions/pagination">
    列表接口分页。
  </Card>
</CardGroup>