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

# API 参考

> Cyberun 平台暴露的 REST 端点。由 OpenAPI 规范自动生成。

Cyberun API 是平台的 HTTP 接口层。每个客户端 —— Cloud、Studio、[CLI](/zh/cloud/guides/cli)、合作伙伴集成、MCP 服务器 —— 都调用这些端点。

**端点**下的端点页由平台的 OpenAPI 规范自动生成 —— 仅暴露公开的、面向用户的接口。

## 基础 URL

```
https://core.cyberun.cloud/api/v1
```

自托管部署使用各自的域名。此前缀下的所有内容遵循同样的鉴权规则。

## 身份验证

三类凭证:

| 类型          | 请求头                            | 团队范围                                                  |
| ----------- | ------------------------------ | ----------------------------------------------------- |
| User JWT    | `Authorization: Bearer eyJ...` | 对团队范围的端点发送 `X-Team-ID: team_01HX...` —— 一个用户可能属于多个团队。 |
| 集成凭证(`sk-`) | `Authorization: Bearer sk-...` | 团队在签发时**绑定到凭证**。不要发送 `X-Team-ID` —— 会被忽略。             |
| 设备凭证(`dk-`) | `Authorization: Bearer dk-...` | 团队绑定到凭证。不要发送 `X-Team-ID`。                             |

唯一规则:`X-Team-ID` **仅**用于 JWT。在 `sk-` 或 `dk-` 凭证上发送它无效 —— 团队从凭证记录中读取。

`sk-` 签发流程见[生成 API 密钥](/zh/cloud/guides/api-key);完整凭证家族参考见[凭证](/zh/cloud/concepts/credentials)。

## 接口分类

端点列表按 OpenAPI 标签(Auth、Team、Workflow、Task、Webhook、Container 等)分组。跨这些标签的逻辑接口有三类:

* **Management** —— 列出并修改团队资源。需要 User JWT(带 `X-Team-ID`)或设备凭证 `dk-`。Team、Member、Workflow、Webhook 等标签下的大多数端点归属此类。
* **Runtime**(`/r/...`)—— 提交和观察任务。接受 JWT、`sk-` 或 `dk-`。脚本和 CI 最常打到这条路径。
* **MCP**(`/api/v1/mcp`)—— Streamable HTTP MCP 端点,把运行时操作封装为 MCP 工具。仅接受 `sk-`。完整参考:[Cloud MCP](/zh/mcp/cloud)。

## 分页

列表端点接收 `current_page`(默认 `1`)和 `per_page`(默认 `20`,最大 `100`)查询参数。响应包含 `page_meta` 块,内含 `current_page`、`per_page` 和 `total_count`。

## 任务生命周期

每个任务依次经过以下状态：

| 状态             | 含义                                            |
| -------------- | --------------------------------------------- |
| `pending`      | 平台已接受。调度器尚未拾取。                                |
| `waiting`      | 调度器已拾取，但暂无可用的合格代理。                            |
| `provisioning` | 正在准备代理来接手任务。                                  |
| `queued`       | 已选定代理。等待代理确认。                                 |
| `running`      | 代理正在执行工作流。                                    |
| `completed`    | 干净完成。可通过 `GET /r/tasks/{taskId}/result` 获取输出。 |
| `failed`       | 出错、超时或代理断开。                                   |
| `cancelled`    | 在进入终态前被取消。                                    |

`completed`、`failed`、`cancelled` 是终态 —— 任务不会再发生变化。
实时跟随状态转换见
[订阅任务事件流（SSE）](/zh/api-reference/streaming-events)。

## 状态码

提交任务返回 `202 Accepted` 和任务 ID —— 任务异步执行，所以请轮询或订阅以获取结果。其他读写操作成功时返回 `200 OK`。

错误为 JSON，仅含单个 `error_message` 字段：

```json theme={null}
{
	"error_message": "resource not found"
}
```

| 状态码           | 出现时机                                              |
| ------------- | ------------------------------------------------- |
| `400`         | 错误请求 —— 格式错误的 JSON、缺失或无效的参数值。                     |
| `401`         | 凭证无效、已撤销或已过期。不要重试。                                |
| `403`         | 凭证有效但缺少权限（或资源团队不符）。                               |
| `404`         | 此团队中找不到该资源。                                       |
| `409`         | 冲突 —— 例如 slug 已被占用、资源当前状态不允许此操作。                  |
| `429`         | 被限速。退避后重试。                                        |
| `500`         | 意外服务端错误。幂等请求可以重试。                                 |
| `502` / `503` | 容器服务网关错误（仅出现在 `/r/containers/*` 和 `/r/invoke/*`）。 |

## 接下来读什么

<CardGroup cols={2}>
  <Card title="快速开始" icon="rocket" href="/zh/api-reference/quickstart">
    提交任务、订阅事件、取回输出 —— 三次调用，三种语言。
  </Card>

  <Card title="生成 API 密钥" icon="key" href="/zh/cloud/guides/api-key">
    签发 `sk-` 凭证并调用你的第一个端点。
  </Card>

  <Card title="订阅任务事件流（SSE）" icon="radio" href="/zh/api-reference/streaming-events">
    事件类型参考、字段说明、轮询兜底。
  </Card>

  <Card title="上传输入文件" icon="upload" href="/zh/api-reference/file-upload">
    含文件参数的工作流采用三步预签名上传。
  </Card>

  <Card title="调用容器服务" icon="container" href="/zh/api-reference/containers">
    访问托管在团队代理上的长时运行服务。
  </Card>

  <Card title="Cloud MCP" icon="plug" href="/zh/mcp/cloud">
    Streamable HTTP 端点,提供 15 个工具封装运行时 API。
  </Card>

  <Card title="使用 CLI" icon="terminal" href="/zh/cloud/guides/cli">
    这些端点由 `cyberun` CLI 封装 —— 在你的 shell 里驱动运行时 API,不必直接发 HTTP。
  </Card>
</CardGroup>