BEEOS CLOUD / DEVELOPER REFERENCE
API 总览
BeeOS Cloud Server API 在所有 domain 上共通的行为：base URL、鉴权、通用 header、错误、分页与幂等。
本页说明 BeeOS Cloud Server API 各 domain 的共通之处：15 个 domain、103 个操作。内容由服务端 SDK 3.1.0 的 OpenAPI 文档生成，固定在 beeos-ai/beeos-cloud-sdks@702e47495f47。每个 domain 有独立的页面列出其方法；共享的对象结构与枚举取值见附录。字段说明译自 OpenAPI 文档；没有说明的字段显示“—”。
Base URL
大多数操作由 https://api.cloud.beeos.ai/v1 提供。14 个操作（responses, harnesses 的全部操作，以及 catalog.getDiscovery）由同一主机上的 https://api.cloud.beeos.ai/uhp/v1 提供。每个操作页都给出完整路径，例如 GET /v1/instances 和 POST /uhp/v1/responses。
| 类别 | Base URL | 操作数 |
|---|---|---|
| Server API | https://api.cloud.beeos.ai/v1 | 89 |
| UHP | https://api.cloud.beeos.ai/uhp/v1 | 14 |
SDK 只需要一个 base URL：https://api.cloud.beeos.ai/v1。对 UHP 操作，SDK 保留协议与主机，并把路径替换为 /uhp/v1，所以无需配置第二个 URL。直接用 HTTP 调用时，请使用操作页给出的类别。
鉴权
每个请求都携带 Authorization: Bearer <key>，其中是服务端 API Key（前缀 bsk_）。Key 只能保存在后端：不要放进浏览器或移动 App，请从配置读取（示例使用 $BEEOS_API_KEY）。catalog.getDiscovery 无需鉴权。安装、初始化与密钥模型见安装与鉴权。
curl "https://api.cloud.beeos.ai/v1/instances" \
-H "Authorization: Bearer $BEEOS_API_KEY"
通用 Header
下表列出 OpenAPI 文档中声明为参数的全部 header，以及声明它的操作数和要求必填的操作数。组织和应用来自服务端 Key。
| Header | 操作数 | 必填于 | 说明 |
|---|---|---|---|
Idempotency-Key | 22 | 19 | 重复使用同一个 key 会返回第一次请求的结果，不会再次执行该操作。 约束: minLength=1, maxLength=256. |
If-Match | 9 | 9 | 当前资源版本，带引号的字符串，例如 "3"。过期版本会被拒绝。 约束: pattern=^"[1-9][0-9]*"$. |
UHP-Version | 2 | 0 | — |
Last-Event-ID | 1 | 0 | 最后收到的事件 ID；从其之后恢复事件流。 |
X-BeeOS-Conversation-ID | 6 | 6 | — |
X-BeeOS-Platform-Agent-ID | 6 | 6 | — |
错误
非 2xx 响应使用三种错误信封之一，按操作区分（各操作页列出其文档化的状态码）。SDK 抛出同一种错误类型，保留 HTTP 状态码和解码后的错误体：TypeScript BeeOSAPIError、Python APIError、Go *APIError；见安装与鉴权。TypeScript SDK 还会把 X-Request-ID 响应头读入 requestId。
| 状态码 | Schema | 操作数 |
|---|---|---|
| 400 | ErrorResponse, UHPErrorEnvelope | 5 |
| 401 | ErrorResponse, UHPErrorEnvelope | 6 |
| 404 | ErrorResponse, UHPErrorEnvelope | 11 |
| 409 | UHPErrorEnvelope | 3 |
| 413 | UHPErrorEnvelope | 2 |
| 422 | UHPErrorEnvelope | 4 |
| 429 | ErrorResponse, UHPErrorEnvelope | 3 |
| 5XX | ErrorResponse | 2 |
| 502 | UHPErrorEnvelope | 2 |
| 503 | UHPErrorEnvelope | 3 |
| 504 | UHPErrorEnvelope | 2 |
| 其他（default） | ErrorResponse, DeviceBindingErrorResponse, UHPErrorEnvelope | 103 |
ErrorResponse
被 identity, catalog, instances, agents, conversations, messages, files, automations, canvases, a2a, usage, audio 中的 83 个操作使用。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
code | string | 是 | 稳定的、机器可读的错误码，例如 invalid_request、version_mismatch 或 instance_not_found。 |
message | string | 是 | 面向人的错误描述。请在代码中用 code 而不是此文本做分支判断。 |
request_id | string | 是 | 请求的 ID，用于支持与追踪。 |
DeviceBindingErrorResponse
被 deviceBindings 中的 6 个操作使用。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
error | string | 是 | 机器可读的错误码。设备绑定路由返回 invalid_request、unauthorized、not_found、conflict、binding_unavailable 或 bridge_unavailable。认证和实例错误还可能返回其他错误码，请忽略不认识的错误码。 |
message | string | 是 | 错误的可读说明。不要解析它。 |
UHPErrorEnvelope
被 catalog, responses, harnesses 中的 14 个操作使用。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
error | UHPError | 是 | 错误。 |
detail | string | 否 | error.message 的人类可读别名，保留给针对早于该信封的实现所编写的客户端。不携带 error 中没有的信息。 已弃用。 |
UHPError
UHPErrorEnvelope 内的错误对象。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
type | string | 是 | 错误的类别，由 HTTP 状态决定。 取值见下表 UHPError.type 取值。 |
code | string | 是 | 具体且机器可读。对于本规范未涵盖的情形，服务器可以定义额外的错误码，并且必须用厂商前缀为其命名空间，以免未来版本与之冲突。 |
message | string | 是 | 一句话，可以安全地展示给用户。不得包含凭证、内部主机名、文件路径或堆栈跟踪。 |
param | string | 否 | 指向出错字段的点分路径。 可为 null。 |
detail | map<string, JSONValue> | 否 | 错误的附加结构化详情（如果有）。 可为 null。 |
UHPError.type 取值
| 取值 | 含义 |
|---|---|
"invalid_request_error" | 请求无效，或引用了不存在的对象，或与当前状态冲突。 |
"authentication_error" | API key 缺失或无效。 |
"permission_error" | API key 没有该调用所需的 scope。 |
"rate_limit_error" | 请求过多。 |
"harness_error" | harness 未能完成所请求的操作。 |
"server_error" | 服务端无法处理该请求。 |
分页
分页方式因操作而异：按页的操作使用 page 与 page_size，按游标的操作使用 cursor 与 limit，文件列表使用 limit 与 offset。下表按 OpenAPI 文档的声明，列出每个分页操作接受的分页参数和响应里的分页字段。
| 操作 | 请求参数 | 响应字段 |
|---|---|---|
| catalog.listInstanceTemplates | page, page_size | total |
| catalog.listAgentTemplates | page, page_size | total |
| instances.list | page, page_size | total |
| agents.list | page, page_size | total |
| conversations.list | cursor, limit | next_cursor, has_more |
| messages.list | cursor, limit | next_cursor, has_more |
| files.list | limit, offset, since | total, next_since |
| automations.list | cursor, limit | data.nextCursor |
| automations.listRuns | cursor, limit | data.nextCursor |
| a2a.listTasks | cursor, limit | total, next_cursor, has_more |
幂等与带版本的写操作
变更类操作需要 Idempotency-Key 头（多数为必填，见上表）。重复使用同一个 key 会返回第一次请求的结果，不会再次执行该操作。key 的长度限制因操作而异，各操作页列出了约束。SDK 不会自动生成 key：请为每个逻辑操作传入稳定的 key，重试时复用。修改带版本资源的操作还需要把当前资源版本作为带引号的字符串通过 If-Match 传入，例如 "3"；过期版本会被拒绝。TypeScript 接受数字并自动加引号；Python 与 Go 直接传请求头的值。
Domain 列表
| Domain | 操作数 | 说明 |
|---|---|---|
| 身份 | 5 | 面向浏览器与移动端的 client session，以及 external user 的数据删除。 |
| 目录 | 8 | Provider、部署区域与模型、实例与智能体模板，以及协议 discovery 文档。 |
| 实例 | 15 | 创建、读取、更新、启停、升级与删除实例；打开终端与画布会话；执行命令；获取连接与流地址。 |
| 智能体 | 3 | 列出、读取智能体并更新其暴露设置。 |
| 会话 | 11 | 创建、列出、重命名、删除、取消、恢复与清空会话；设置模型、推理强度与审批模式。 |
| 消息 | 6 | 列出、读取会话消息并管理回复分享链接。 |
| Responses | 6 | 在已配置的 harness 上运行任务，并读取、流式获取、取消或删除（UHP）。 |
| Harness | 7 | 创建、列出、读取、更新与删除已配置的 harness，并列出其可运行的模型（UHP）。 |
| 文件 | 11 | 预签名上传、文件元数据、分享链接与文件汇总。 |
| 自动化 | 11 | 创建、更新、暂停、恢复与删除自动化；启动并读取运行；创建 webhook 自动化。 |
| 画布 | 6 | 画布分享链接、快照与会话画布会话。 |
| 设备绑定 | 6 | 智能体绑定会话与 portal 绑定会话。 |
| A2A | 6 | Agent-to-Agent 的 JSON-RPC 请求、agent card 与任务。 |
| 用量 | 1 | 用量汇总。 |
| 音频 | 1 | 音频转写。 |
在安装与鉴权安装 Cloud SDK 并配置客户端，在附录查类型与枚举，或用 OpenAPI 文档生成自己的客户端。