API 参考 - Cyberun

Cyberun API 是平台的 HTTP 接口层。每个客户端 —— Cloud、Studio、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 密钥;完整凭证家族参考见凭证。

接口分类

端点列表按 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。

分页

列表端点接收 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）。

状态码

提交任务返回 202 Accepted 和任务 ID —— 任务异步执行，所以请轮询或订阅以获取结果。其他读写操作成功时返回 200 OK。错误为 JSON，仅含单个 error_message 字段：

{
	"error_message": "resource not found"
}

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

接下来读什么

快速开始

提交任务、订阅事件、取回输出 —— 三次调用，三种语言。

生成 API 密钥

签发 sk- 凭证并调用你的第一个端点。

订阅任务事件流（SSE）

事件类型参考、字段说明、轮询兜底。

上传输入文件

含文件参数的工作流采用三步预签名上传。

调用容器服务

访问托管在团队代理上的长时运行服务。

Cloud MCP

Streamable HTTP 端点,提供 15 个工具封装运行时 API。

使用 CLI

这些端点由 cyberun CLI 封装 —— 在你的 shell 里驱动运行时 API,不必直接发 HTTP。

Documentation Index

​基础 URL

​身份验证

​接口分类

​分页

​任务生命周期

​状态码

​接下来读什么