Skip to main content

端点速查

平台 API 挂在 /v1 前缀下。基地址:
这一页是全部端点的速查表。每个端点的完整请求与响应结构见对应的 API 详情页。

认证

除少数公开端点外,所有请求都要带 API Key:
多用户场景下还要标识终端用户:
X-End-User-Id 不是可选的装饰。用 API Key 调用 /v1/chat/*/v1/agents/run/v1/sessions*/v1/files*不带这个头会直接 400,报错原文是:
之所以宁可报错也不默认合并:一个 API Key 通常前置着很多终端用户,会话历史、沙箱文件、记忆都按这个头分区。缺了它就是所有人共用一个分区——串号的代价远高于多写一个 header。走 OAuth 的应用身份(有 app 上下文)豁免此校验,因为身份已经由授权流程确定。

全部端点

运行与会话

agents/runsessions/events 底层是同一条执行流,区别只在有没有持久会话:
  • 一次性任务用 agents/run,无状态
  • 多轮对话用 sessions,服务端保留上下文

专家(Agents)

publish提交审核而不是直接上线。已上架专家发新版本时老版本保持在线,新版本进入待审队列——所以 publish 成功不代表用户看到的内容变了。用 get_submission_status(MCP)或专家详情里的待审字段确认状态。

环境(沙箱模板)

文件

上传是两步式:先拿直传 URL,把字节 PUT 到对象存储,再回来登记。这样大文件不经过 API 服务器,也不受请求体大小限制。 限额见 限额表

用量与模型

GET /v1/meters 是全站唯一免鉴权的 /v1 端点——定价信息需要在用户登录前就能展示。

OAuth 权限范围

第三方应用通过 OAuth 接入时按 scope 授权。
会话与环境的操作复用 agents:write 而不是新造 sessions:* / environments:*。原因是它们都是”以这个应用的身份操作这个应用的专家”,拆出新 scope 只会让授权页多两个用户看不懂的选项,却不带来任何真实的权限边界。

请求示例

流式响应

agents/runchat/completionssessions/:id/events 都返回 text/event-stream 事件名采用点号分层命名(对齐 OpenAI Responses API),完整词表见 SSE 事件
流结束的标记是 data: [DONE],它不是一个 JSON 事件,直接 JSON.parse 会抛异常。解析循环必须先判断这一行。

已知边界

这三条不写进文档的话,你会花几个小时排查”为什么 webhook 收不到”或”为什么技能装了没生效”,而根因是功能本身还没接线。宁可承认缺口,也不让你在不存在的东西上浪费时间。

相关页面

SSE 事件

流式事件的完整词表

错误码

全部业务码与状态推导

认证

API Key 与 OAuth

环境变量

SDK 与集成的配置项
核对日期 2026-08-11。来源:services/core/src/routes/platform-api/index.tsagents.tssessions.tsenvironments.tsfiles.ts)、services/core/src/index.ts/v1 挂载点)。