API 运行接口

已发布应用的外部 API 调用入口。支持通过 Deployment ID、Document ID 或 Release 别名三种方式调用。

源码: apps/backend/src/routes/api-run.ts

POST /api/released-app/:deploymentId/run

通过 Deployment ID 运行已发布的应用。

认证方式

API Key / Schedule Token（apiKeyAuth）

请求参数

Path 参数

参数	类型	必填	说明
`deploymentId`	string	是	部署 UUID

Body 参数

json

{
  "inputs": { "text": "hello world" },
  "version": "^1.0",
  "stream": true,
  "format": "ndjson",
  "timeout": 60
}

参数	类型	默认值	说明
`inputs`	object	`{}`	Input Block 的输入值
`version`	string	-	版本号。`"1.0"`：精确匹配；`"^1.0"`：major=1 的最新 minor；省略：最新版本
`stream`	boolean	`true`	是否流式响应
`format`	`"sse"` \| `"ndjson"`	`"ndjson"`	流式响应格式（注意：API 调用默认 NDJSON，与编辑器默认 SSE 不同）
`timeout`	number	-	超时时间（秒），不超过管理后台配置的最大值

允许空 body（使用默认值）。

响应格式

NDJSON 流式响应（默认）

Content-Type: application/x-ndjson

API 模式下仅输出数据类 Block 的事件，过滤掉 prompt 等内部 Block 信息：

{"type":"run_start","runId":"uuid","documentId":"uuid"}
{"type":"block_start","blockId":"uuid","blockType":"code"}
{"type":"block_chunk","blockId":"uuid","delta":"部分输出"}
{"type":"block_complete","blockId":"uuid","output":"完整输出"}
{"type":"block_end","blockId":"uuid"}
{"type":"run_complete","runId":"uuid","globalCtx":[...],"sessions":[...],"duration":1234}

SSE 流式响应（`format: "sse"`）

Content-Type: text/event-stream

事件类型与 NDJSON 一致，但使用 SSE 格式：

event: run_start
data: {"runId":"uuid","documentId":"uuid"}

event: block_complete
data: {"blockId":"uuid","output":"完整输出"}

event: run_complete
data: {"runId":"uuid","globalCtx":[...],"sessions":[...],"duration":1234}

JSON 一次性响应（`stream: false`）

状态码: 200

json

{
  "runId": "uuid",
  "documentId": "uuid",
  "globalCtx": [
    {
      "blockId": "uuid",
      "blockType": "code",
      "blockName": "处理数据",
      "output": "处理结果"
    }
  ],
  "sessions": [
    {
      "blockId": "uuid",
      "blockType": "code",
      "blockName": "处理数据",
      "status": "completed",
      "output": "处理结果"
    }
  ],
  "duration": 1234,
  "status": "success",
  "timedOut": false
}

权限规则

部署可见性	API Key 认证	Schedule 认证
`public`	任意有效 API Key	已通过 Token 验证
`private`	API Key 所属团队必须与部署所属团队一致	已通过 Token 验证（跳过权限检查）

请求示例

bash

# JSON 一次性响应
curl -X POST \
  -H "Authorization: Bearer wn-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"text": "hello"}, "stream": false}' \
  https://block2-api.wainao.chat/api/released-app/DEPLOYMENT_UUID/run

# NDJSON 流式响应
curl -X POST \
  -H "Authorization: Bearer wn-your-api-key" \
  -d '{"inputs": {"text": "hello"}}' \
  https://block2-api.wainao.chat/api/released-app/DEPLOYMENT_UUID/run

# 指定版本
curl -X POST \
  -H "Authorization: Bearer wn-your-api-key" \
  -d '{"inputs": {"text": "hello"}, "version": "^1.0"}' \
  https://block2-api.wainao.chat/api/released-app/DEPLOYMENT_UUID/run

错误码

状态码	错误	说明
400	`Input validation failed`	输入参数验证失败
401	`Unauthorized`	认证失败或认证方式不支持
402	`insufficient_credits`	积分余额不足
403	`Permission denied: This is a private app...`	无权访问私有应用
403	`Deployment ID mismatch`	Schedule Token 中的 deploymentId 不匹配
404	`Deployment not found`	部署不存在或版本未找到
500	`Invalid deployment snapshot: missing content`	部署快照数据损坏

POST /api/released-app/d/:documentId/run

通过 Document ID 运行已发布的应用。Document ID 是稳定的标识符，不会因重新发布而改变。

认证方式

API Key（仅 API Key，apiKeyAuth）

请求参数

Path 参数

参数	类型	必填	说明
`documentId`	string	是	文档 UUID（稳定标识）

Body 参数

与 /:deploymentId/run 一致。

响应格式

与 /:deploymentId/run 一致。

请求示例

bash

curl -X POST \
  -H "Authorization: Bearer wn-your-api-key" \
  -d '{"inputs": {"text": "hello"}, "stream": false}' \
  https://block2-api.wainao.chat/api/released-app/d/DOCUMENT_UUID/run

错误码

与 /:deploymentId/run 一致，额外包含：

状态码	错误	说明
401	`Unauthorized: Document ID route only supports API key authentication`	仅支持 API Key 认证

ALL /api/released-app/r/:alias/:version/*

Release 网关路由。通过应用别名 + 版本号 + 路径匹配已发布的端点并执行。

认证方式

API Key（仅 API Key，apiKeyAuth）

请求参数

Path 参数

参数	类型	必填	说明
`alias`	string	是	Release 别名
`version`	string	是	版本号字符串
`*`	string	是	路由路径（匹配 routerTree 中的端点）

Body / Query 参数

非 GET 请求: 从请求体解析 inputs
GET 请求: 从 query 参数构建 inputs

匹配规则

通过 alias 在 release_aliases 表中查找 release_document_id
根据版本号解析匹配的已发布版本
在版本的 routerTree 中按 path + HTTP method 匹配端点
找到端点关联的 deploymentId 并执行

响应格式

固定使用 JSON 一次性响应（runWithJSON），格式与上述 JSON 响应一致。

请求示例

bash

# GET 请求（参数通过 query 传递）
curl -H "Authorization: Bearer wn-your-api-key" \
  "https://block2-api.wainao.chat/api/released-app/r/my-app/v1/users?name=test"

# POST 请求（参数通过 body 传递）
curl -X POST \
  -H "Authorization: Bearer wn-your-api-key" \
  -d '{"name": "test"}' \
  "https://block2-api.wainao.chat/api/released-app/r/my-app/v1/users"

错误码

状态码	错误	说明
401	`Unauthorized`	认证失败或非 API Key 认证
403	`Permission denied`	无权访问私有应用
404	`Release alias 'xxx' not found`	别名不存在
404	`No published version matching 'xxx' found`	版本不存在
404	`No endpoint matching METHOD /path`	端点未匹配
400	`Endpoint 'xxx' has no deployment configured`	端点未配置部署
404	`Deployment not found`	关联的部署不存在

API 运行接口 ​

POST /api/released-app/:deploymentId/run ​

认证方式 ​

请求参数 ​

Path 参数 ​

Body 参数 ​

响应格式 ​

NDJSON 流式响应（默认） ​

SSE 流式响应（format: "sse"） ​

JSON 一次性响应（stream: false） ​

权限规则 ​

请求示例 ​

错误码 ​

POST /api/released-app/d/:documentId/run ​

认证方式 ​

请求参数 ​

Path 参数 ​

Body 参数 ​

响应格式 ​

请求示例 ​

错误码 ​

ALL /api/released-app/r/:alias/:version/* ​

认证方式 ​

请求参数 ​

Path 参数 ​

Body / Query 参数 ​

匹配规则 ​

响应格式 ​

请求示例 ​

错误码 ​

API 运行接口

POST /api/released-app/:deploymentId/run

认证方式

请求参数

Path 参数

Body 参数

响应格式

NDJSON 流式响应（默认）

SSE 流式响应（`format: "sse"`）

JSON 一次性响应（`stream: false`）

权限规则

请求示例

错误码

POST /api/released-app/d/:documentId/run

认证方式

请求参数

Path 参数

Body 参数

响应格式

请求示例

错误码

ALL /api/released-app/r/:alias/:version/*

认证方式

请求参数

Path 参数

Body / Query 参数

匹配规则

响应格式

请求示例

错误码