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 / OAuth Access Token

API Key：Authorization: Bearer wn-...
Schedule Token：JWT 格式
OAuth Token：Authorization: Bearer wno-...（需要 chat:completions scope）

请求参数

Path 参数

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

Body 参数

json

{
  "inputs": { "text": "hello world" },
  "version": "^1.0",
  "stream": true,
  "format": "ndjson",
  "timeout": 60,
  "requestId": "my-event-000042",
  "sessionId": "session-abc",
  "causationId": "message-42",
  "parentRunId": "0f0e0d0c-0b0a-4a09-8807-060504030201"
}

参数	类型	默认值	说明
`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	-	超时时间（秒），不超过管理后台配置的最大值
`requestId`	string	-	OAuth 兼容的 body 幂等键，≤128 字符；API Key 放在 body 中仅用于审计，跨请求防重应使用 `Idempotency-Key` 请求头
`sessionId`	string	-	外部系统会话归组键（≤128 字符），仅存储供调用方回查
`causationId`	string	-	外部系统因果链定位键（≤128 字符），仅存储供调用方回查
`parentRunId`	string	-	关联的父运行 UUID（必须已存在，否则 `404 parent_run_not_found`）

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

运行生命周期（长时运行协议）

创建的 run 遵循与编辑器一致的长时运行协议：

断开连接不会取消执行。客户端断开只停止响应写出，执行继续并把事件写入事件流与运行记录；重连后可用 GET /runs/:runId/events?after=<id> 游标续读，或 GET /runs/:runId/globalctx-events?sinceSequence=<n> 补读持久化增量。OAuth 调用他人的公开 Flow 时，读取这两类追踪还需对发布者项目具有 read 权限；缺权限返回 403 oauth_run_trace_requires_project_read。
取消：POST /runs/:runId/cancel 对执行中的 run 返回 cancelling，执行侧在约 1 秒内消费信号并终止，终态 cancelled（cancelledReason: cancel_requested）。
恢复：run 在 ask 等待点以 success 结束并保存执行快照（envelope）后，POST /runs/:runId/resume 可继续执行（此前发布 run 一律 409 resume_unavailable）。

requestId 与 runId 的区别：runId 由服务器生成并放在响应里，断线时调用方可能拿不到；body requestId（OAuth）或 Idempotency-Key 请求头（已验证调用方）由调用方在首次请求前生成，用于安全重试。请求头最多 200 字符，存在时优先于 body requestId。同一已验证身份与键、相同请求语义的新版本已受理 run 返回 200 { runId, status, idempotentReplay: true } 与 X-Wainao-Request-Id，不重复执行或扣费；同键语义不同，或旧 run 缺少可核验的请求指纹时返回 409 idempotency_conflict，不重新执行。status 是原 run 当前状态，不表示执行已成功。Release 网关（/r/:alias/...）的 body 是业务输入，不支持这些保留字段；其认证调用可通过请求头传幂等键。

现有数据库还保留 (oauth_app_id, request_id) 唯一索引；同一 App 的不同用户若复用 body requestId，后创建者可能收到 409。请为每次新运行生成全局唯一 requestId，仅在重试时复用。详见 OAuth 资源权限。

活动 Input 校验

服务端会在创建 run 和启动执行器之前，根据发布快照识别工作流实际会消费的 Input Block，并校验必填与类型：

正文、代码与条件提示词的活动引用先核对公开名称和稳定绑定；合法的空 id mention 可通过唯一公开名称恢复目标，内部 ID 不是正文名称别名。
ValueSource 数组与 Structure/Output 内部绑定继续使用稳定 Block ID；旧字符串型 ValueSource 仍兼容 input name 或 input id，这是该配置协议的兼容行为，不适用于正文 @{}。
被引用的必填 input 缺失时返回 400 Input validation failed，details 包含字段级错误；不会创建或启动 run。
未被工作流引用的 input 不参与校验；请求中的未知 input key 继续被忽略，以兼容新旧客户端。
Release /r/:alias/:version/* 会先执行公开字段到工作流字段的 input mapping，再校验映射后的输入。

Schedule 与 Webhook 复用同一 deployment 运行管线，因此也遵循上述校验。历史 deployment 的固化 API Schema 不会被自动改写；如果旧页面没有展示后端已要求的字段，请重新发布对应 deployment 以刷新表单与 API 文档。

活动变量引用校验失败时，在创建 run、启动执行器及发送成功的 SSE/NDJSON 响应之前返回 400 { error: "workflow_reference_invalid", message, details }。details 为引用诊断数组，包含 code/reference/path，适用时带 blockId/nearBlockId。deployment ID、文档最新 deployment、Release 网关及 Schedule/Webhook 共享这一检查；应修正文档并重新部署，不能靠传入内部 ID 字段绕过。

触发上下文 _trigger（issue #691）：服务端会按调用来源构造 _trigger 对象并注入 inputs._trigger（API 调用为 { source: 'api', triggered_at }；定时任务/Webhook 触发分别为 source: 'schedule' / 'webhook' 并附 schedule_id / webhook_id 等）。该字段为保留字：调用方在 inputs 或 body 顶层传入的 _trigger 会被服务端覆写，无法伪造。工作流绑定触发器模板后可通过 _trigger 输入读取，详见 /api/webhook-triggers。

Query 参数

参数	类型	默认值	说明
`trace`	string	-	设为 `full` 时返回完整执行轨迹 `globalCtx`（调试用）。默认不返回，详见下文「响应体大小上限与 trace 开关」。

输出声明（Output Schema）对响应的影响

工作流在编辑器里配置了 Output 声明后，所有对外出口的响应形状由声明决定：

运行 API、发布 API、Release 网关、公开文档与子流程引用拿到的都是声明的字段，文档内部块的过程数据不再出现在输出里。
必填字段缺失或类型不匹配时，本次运行明确失败（不会回退到全量输出）；提前 Exit 返回与正常跑完使用同一份字段结构。
未配置 Output 的工作流行为与旧版完全一致（全量输出）。

响应体大小上限与 trace 开关

行为变更（Breaking Change）

为防止内联大文件（如大 base64 图片）经子流程放大撑爆响应体打垮平台，自本次起：

裸部署 run 端点（/:deploymentId/run、/d/:documentId/run）默认不再返回 globalCtx（完整执行轨迹）。只返回最终输出（通常几 KB）：配置了 Output 的部署返回 output，未配置的返回 sessions。
需要完整轨迹用于调试时，显式加查询参数 ?trace=full。globalCtx 中的超大字符串（如大 base64）会被替换为占位 { "__truncated": true, "originalBytes": N, "preview": "..." }，避免多份内联副本。
整个响应体受大小上限保护（默认约 8 MiB，可由管理后台 run.response_limit 配置）。超限时：
- JSON 一次性模式（stream:false）→ 返回 HTTP 413 + { "error": "response_too_large", ... }，不会尝试序列化超大对象到 OOM。
- 流式模式（NDJSON / SSE）→ HTTP 状态码已发出无法更改，故返回 200，并以终态事件 run_error（error: "response_too_large"，含 executionStatus）结束，不发送超大的 run_complete / globalCtx。
Release 网关端点（/r/:alias/:version/*）行为不变（本就通过输出映射只返回精简输出，不含 globalCtx）。

迁移建议：依赖 globalCtx 的调用方请改加 ?trace=full；更稳妥的做法是改用 /r/ 网关端点 + 输出映射，或用 wnfile 句柄传入大文件而非内联 base64。

请求体 / 输入大小上限（issue #664）

行为变更（Breaking Change）

为根治输入侧 OOM（超大 prompt / 内联大 base64 图纸撑爆平台内存），所有 run 入口（/:deploymentId/run、/d/:documentId/run、Release /r/:alias/:version/*）在解析输入后、执行前加分层硬上限，超限明确报错（4xx），不静默放行。

维度	默认上限	超限错误码	HTTP
请求体总大小	4 MiB	`request_body_too_large`	413
单个输入字段	1 MiB	`input_field_too_large`	400
内联 data URI base64 负载	1 MiB	`inline_base64_too_large`	400
全部文本输入聚合字节	1 MiB	`prompt_too_large_bytes`	400
全部文本输入聚合 token	200,000	`prompt_too_large_tokens`	400
输入结构嵌套深度	32	`input_structure_too_deep`	400
输入结构节点数	100,000	`input_structure_too_large`	400

所有阈值热可调：管理后台 site_settings 的 run.input_limit 配置（缺失/非法走上表安全默认，5 分钟缓存）。回归较大时可临时调大对应项。
请求体总大小上限远小于网关 client_max_body_size（512m）——run 输入应走文件句柄而非内联文件。
错误响应体形如 { "error": "<code>", "message": "...", "field": "inputs.xxx", "actual": <字节/token>, "limit": <上限> }。
wnfile: / storage:// 文件句柄不计入上述字段/聚合限制（仅当引用串短于 256 字符、形如「协议 + ID」时豁免；超长的伪句柄不豁免，照常计入文本限制）。
只精确拦截 data URI（data:...;base64,...）形态的内联 base64；裸 base64（无 data: 前缀）不做启发式识别（避免误伤普通长文本），由单字段 / 聚合字节限兜底。

内联 base64 → wnfile 句柄迁移示例

不要把图片 base64 内联进 inputs：

jsonc

// ❌ 会被 inline_base64_too_large 拒绝（超过 base64 上限时）
{ "inputs": { "image": "data:image/png;base64,iVBORw0KGgoAAAANS...（很长）" } }

改为先上传文件拿到 wnfile: 句柄，再把句柄作为输入传入：

jsonc

// ✅ 先调上传接口得到 file id，再传句柄（不受 base64/字段大小限制）
{ "inputs": { "image": "wnfile:550e8400-e29b-41d4-a716-446655440000" } }

PDF 输入处理（base64 / data URL，issue #677 / #678）

PDF 类型输入（{"_type":"pdf","value":...}）支持三种 value 形态，行为统一：

value 形态	处理
`wnfile:<id>` / `storage://<id>` 句柄	服务端下载并走 PDF→文字预处理（转 Markdown 注入 prompt），任意模型可读，不要求模型有 `pdf` 能力
`data:application/pdf;base64,<...>`	服务端直接解码并走同一套 PDF→文字预处理，无需先上传（API Key 无法走 `/storage` 上传，故由服务端代解码）
裸 base64（无 `data:` 前缀）	自动按 `%PDF-` 文件头识别为 PDF，走同样的预处理；非 PDF 内容（无 `%PDF-` 头）则按原样文本处理

要点：

任意模型可读：经预处理转文字后，识别块即使配置的模型没有 pdf 原生能力也能正常跑通（这正是「编辑器手动上传 PDF 能跑通、而早期 base64 直传报错」的根因修复）。
裸 base64 自动补前缀：未走预处理而直达模型原生通道的内联 PDF/图片，服务端按文件魔数自动补 data:application/pdf;base64, / data:image/<png|jpeg|webp|gif>;base64, 前缀，调用方无需自己拼 data URL。
降级不再爆上下文：若模型既无 pdf 能力又未走预处理，PDF 输入会被替换为简短提示文本（而非把整串 base64 当文本注入 prompt），避免撑爆上下文。
体积上限：内联 PDF base64 仍受输入层 inline_base64_too_large（默认 1 MiB）限制；大文件请改用 wnfile: 句柄。

jsonc

// ✅ 直接内联 base64 PDF（自动预处理，任意模型可读）
{ "inputs": { "doc": { "_type": "pdf", "value": "data:application/pdf;base64,JVBERi0xLjQK..." } } }
// ✅ 裸 base64 也可（自动识别 %PDF- 并补前缀）
{ "inputs": { "doc": { "_type": "pdf", "value": "JVBERi0xLjQK..." } } }

响应格式

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","sessions":[...],"completedBlocks":1,"duration":1234}

run_complete 默认不含 globalCtx；加 ?trace=full 后才追加（大 blob 已截断）。若响应体超限，最后一行改为 {"type":"run_error","runId":"uuid","error":"response_too_large","executionStatus":"completed",...}。

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","sessions":[...],"completedBlocks":1,"duration":1234}

同 NDJSON：默认不含 globalCtx，?trace=full 才追加；超限时以 event: run_error（error: "response_too_large"）终止。

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

状态码: 200

json

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

正常执行结束时 status 为 completed；在 ask 等待点正常暂停时可能为 success。默认不含 globalCtx。加 ?trace=full 后，响应额外包含 globalCtx 数组（完整执行轨迹，大 blob 已截断为占位）。

失败时保留实际输出（#1575）

失败响应的 JSON 根节点默认包含脱敏的 error，无需新增 scope 或 ?trace=full。已经执行的失败 session 在原位置同时包含 status: "error"、原始 output 和独立的脱敏 error；之前成功的输出保持原结构。只返回实际执行产生的记录，不推算总步数，也不补充未运行步骤。错误摘要剥离凭据、连接串、服务器路径、堆栈和大 base64，最多 500 字符；已有业务输出继续按原有权限返回。

json

{
  "runId": "uuid",
  "status": "error",
  "error": "计算失败",
  "sessions": [
    { "blockId": "step-1", "blockName": "前序结果", "blockType": "codeBlock", "status": "completed", "output": { "value": 42 } },
    { "blockId": "step-2", "blockName": "失败步骤", "blockType": "codeBlock", "status": "error", "output": { "output": null, "logs": [{ "level": "log", "message": "报错前日志", "timestamp": "2026-10-03T00:00:00.000Z" }] }, "error": "计算失败" }
  ]
}

代码步骤在抛错前已经产生的日志保留在 output.logs（以及 output.extra.codeRun.logs）；未正常返回的函数结果仍为 null，不会补造。失败 output.errors 的首项为本次实际异常，其后的既有错误记录也脱敏并剥离 stack，保留原有级别和时间。这里只返回执行宿主已取得的记录，不承诺追回进程被杀或从未记录的内容。

WASM 代码步骤的每次 console 调用只产生一条记录，保留原始级别、消息和时间。log、info、warn、debug 进入 output.logs；console.error 只进入 output.errors（日志面板的 Errors 标签），不会再复制到 Logs。相同内容调用两次仍保留两条业务记录。

NDJSON 和 SSE 失败终态为 run_error，包含根 error 和原有权限内的实际 sessions，超时也只发送一次失败终态；成功仍使用 run_complete。消费者须监听两种终态并结束订阅。?trace=full 继续仅控制额外的 globalCtx，响应大小上限仍适用。

Release 输出映射仍过滤未声明的步骤；配置 Output 节点的发布接口继续只返回允许的最终输出信封。失败时不生成最终 Output，也不向公开调用者补充内部 sessions/trace。只读完整追踪仍需现有项目读权限，Run/App 隔离不变。

响应体超限（`stream: false`）

状态码: 413

json

{
  "runId": "uuid",
  "error": "response_too_large",
  "message": "响应体超过大小上限，已拒绝返回完整结果",
  "actualBytes": 8389000,
  "limitBytes": 8388608,
  "executionStatus": "completed",
  "hint": "请改用 wnfile 句柄输入以避免内联大 base64；或通过 /r/ 网关端点 + 输出映射获取精简输出；或减小工作流输出体积。"
}

hint 默认建议改用 wnfile 句柄 / /r/ 网关 / 减小输出；仅当本次请求确实带了 ?trace=full 时，才额外提示「去掉 ?trace=full 重试」（避免误导未带该参数的调用方）。

actualBytes 是 fail-fast 在「首次累计超过上限」那一刻的字节数，是真实响应大小的下界（不会继续序列化以求精确值），语义为「至少这么大、已超限」。

权限规则

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

请求示例

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`	活动 input 缺少必填值或类型不匹配，`details` 含字段级错误
400	`input_field_too_large`	单个输入字段超大小上限（见「请求体 / 输入大小上限」）
400	`inline_base64_too_large`	内联 data URI base64 超上限，请改用 `wnfile:` 句柄
400	`prompt_too_large_bytes` / `prompt_too_large_tokens`	全部文本输入聚合字节 / token 超上限
400	`input_structure_too_deep` / `input_structure_too_large`	输入结构嵌套过深 / 节点过多
401	`Unauthorized`	认证失败或认证方式不支持
402	`insufficient_credits`	积分余额不足
403	`Permission denied: This is a private app...`	无权访问私有应用
403	`Deployment ID mismatch`	Schedule Token 中的 deploymentId 不匹配
404	`Deployment not found`	部署不存在或版本未找到
409	`idempotency_conflict`	同键请求语义不同，或旧 run 缺少可核验的请求指纹；不重新执行
503	`run_replay_lookup_unavailable`	重试查询暂不可用，无法安全确认原运行
413	`request_body_too_large`	请求体总大小超上限（见「请求体 / 输入大小上限」）
413	`response_too_large`	响应体超过大小上限（仅 `stream:false`；流式模式以终态 `run_error` 表达，状态码仍 200）
500	`Invalid deployment snapshot: missing content`	部署快照数据损坏

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

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

认证方式

API Key、OAuth Access Token（需 chat:completions scope）或 Agent 绑定授权。

请求参数

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, OAuth, or Agent authentication`	未提供受支持的认证方式

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

Release 别名网关（/r/ 路由）。通过应用别名 + 版本号 + 路径匹配已发布的端点并执行，支持任意 HTTP 方法（按端点定义分派）。

认证方式

接受 API Key、OAuth Access Token 或 Agent 绑定授权（路由链 releaseGatewayResolve → oauthAuth → oauthScopeGuard → apiKeyAuth）。是否强制鉴权由 Release 配置决定（REL-001，fail-closed）：

默认要鉴权：releaseConfig.requireAuth !== false 时，调用必须携带有效凭据（API Key / OAuth Access Token / Agent 绑定授权），否则 401。配置缺失或解析失败一律按「要鉴权」。
端点级豁免：端点配置 skipAuth: true 可让单个端点公开（覆盖全局 requireAuth），此时无需凭据即可调用。
防 401 绕过：只要请求带了任一凭据 header（Authorization / X-API-Key / X-Internal-Secret / X-Internal-Api-Key-Id，即便值非法或为空），都会强制走鉴权，不会被当匿名放行。
私有部署：匿名访问私有部署返回 403，即使该端点免鉴权。
计费主体：有效 wn- API Key 同时决定调用方和付款团队。允许匿名的端点只有在请求完全不带凭据时才使用发布配置 Key；若客户端主动附带自己的有效 Key，则由该 Key 团队自付，不再消耗发布者配置 Key。工作流 Secrets 仍按部署所属项目解析。

限流（REL-002）

Release 可配置 rateLimit（windowSeconds 正整数 ≤ 3600、maxRequests 正整数 ≤ 100000）；配置非法时回落全局限流。按调用方分桶（API Key 按 apiKeyId、Agent 按 bindingId，OAuth 与匿名公开端点按 release + 客户端 IP）。超过限流返回 429（附 Retry-After 头），响应体 { "error": "Too many requests, please try again later" }。

请求参数

Path 参数

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

Body / Query 参数

非 GET 请求: 从请求体解析 inputs
GET 请求: 从 query 参数构建 inputs
幂等请求头：带有效 API Key、OAuth Token 或 Agent 绑定授权的调用可使用 Idempotency-Key（≤200 字符）。相同身份、键与请求内容的新版本已受理 run 返回原 runId/status（HTTP 200、idempotentReplay: true）；同键语义不同或旧 run 缺少可核验指纹时返回 409 idempotency_conflict，不重新执行。匿名赞助调用不提供客户端幂等定位。请求体的 requestId 始终是业务输入，不是此网关的幂等元数据。
Release 版本边界：重试须使用固定版本 URL。latest 指向新发布版本后，即使 URL 和请求键相同，解析出的 Release 版本已变化，旧键返回 409 idempotency_conflict；调用方应使用原固定版本 URL 重试。

匹配规则

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

响应格式

默认使用 JSON 一次性响应；传入 stream: true 时可使用 SSE（默认）或 NDJSON（format: "ndjson"）。响应不包含裸部署端点的 documentId。

配置了 Output 的部署：非流式成功响应为 { runId, status, duration, timedOut, output: { endpointId, endpointName, value } }，不含 sessions。value 是 Output 声明的字段；端点使用自定义输出映射时，value 内只保留映射的字段并按映射名改名（inherit 原样返回）。流式模式不发送过程块事件，只在终态事件中带 output。
未配置 Output 的部署：非流式成功响应为 { runId, status, duration, timedOut, sessions: [...] }，sessions 中的 blockName 按发布配置过滤或映射，不会返回扁平的输出字段。

配置了 Output 的部署，公开 Release OpenAPI 的 200 schema 已按上述 output 信封生成（value 为声明字段）。未配置 Output、且端点使用自定义输出映射时，OpenAPI 仍按映射字段生成顶层属性，与运行时的 sessions 响应结构未对齐；调用方应按实际响应结构解析，不能据该 schema 假设响应顶层有映射后的字段。这个差异不代表 OAuth 权限错误。

请求示例

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`	认证失败；或要求鉴权（`requireAuth`）时未携带有效凭据
403	`Permission denied`	无权访问私有应用（含匿名访问私有部署）
429	`Too many requests, please try again later`	触发 Release 限流（`rateLimit`），见 `Retry-After` 头
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`	关联的部署不存在
413	`request_body_too_large`	请求体总大小超上限（见「请求体 / 输入大小上限」，与裸部署端点同一套阈值）
400	`input_field_too_large` / `inline_base64_too_large` / `prompt_too_large_bytes` / `prompt_too_large_tokens` / `input_structure_too_deep` / `input_structure_too_large`	输入分层硬上限（见「请求体 / 输入大小上限」）；内联 base64 超限请改用 `wnfile:` 句柄

补充端点

本节补充 plans/need-update-api.md 中尚未覆盖到 docs-site 的接口。端点标题保持严格的 METHOD /path 格式，便于后台文档覆盖率服务识别。

GET /api/released-app/cross-team/bindings

列出当前调用方可用的跨团队 released app 绑定。

认证：API Key、Schedule Token、OAuth Access Token 或跨团队绑定授权。请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。

响应：成功时返回目标资源详情、状态或配置对象。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

POST /api/released-app/cross-team/proxy

通过跨团队绑定代理调用目标 released app。

认证：API Key、Schedule Token、OAuth Access Token 或跨团队绑定授权。请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

API 运行接口 ​

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

认证方式 ​

请求参数 ​

Path 参数 ​

Body 参数 ​

运行生命周期（长时运行协议） ​

活动 Input 校验 ​

Query 参数 ​

输出声明（Output Schema）对响应的影响 ​

响应体大小上限与 trace 开关 ​

请求体 / 输入大小上限（issue #664） ​

内联 base64 → wnfile 句柄迁移示例 ​

PDF 输入处理（base64 / data URL，issue #677 / #678） ​

响应格式 ​

NDJSON 流式响应（默认） ​

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

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

失败时保留实际输出（#1575） ​

响应体超限（stream: false） ​

权限规则 ​

请求示例 ​

错误码 ​

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

认证方式 ​

请求参数 ​

Path 参数 ​

Body 参数 ​

响应格式 ​

请求示例 ​

错误码 ​

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

认证方式 ​

限流（REL-002） ​

请求参数 ​

Path 参数 ​

Body / Query 参数 ​

匹配规则 ​

响应格式 ​

请求示例 ​

错误码 ​

补充端点 ​

GET /api/released-app/cross-team/bindings ​

POST /api/released-app/cross-team/proxy ​

API 运行接口

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

认证方式

请求参数

Path 参数

Body 参数

运行生命周期（长时运行协议）

活动 Input 校验

Query 参数

输出声明（Output Schema）对响应的影响

响应体大小上限与 trace 开关

请求体 / 输入大小上限（issue #664）

内联 base64 → wnfile 句柄迁移示例

PDF 输入处理（base64 / data URL，issue #677 / #678）

响应格式

NDJSON 流式响应（默认）

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

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

失败时保留实际输出（#1575）

响应体超限（`stream: false`）

权限规则

请求示例

错误码

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

认证方式

请求参数

Path 参数

Body 参数

响应格式

请求示例

错误码

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

认证方式

限流（REL-002）

请求参数

Path 参数

Body / Query 参数

匹配规则

响应格式

请求示例

错误码

补充端点

GET /api/released-app/cross-team/bindings

POST /api/released-app/cross-team/proxy