API 概述

外脑编辑器后端 API 基于 Hono 框架构建，提供文档运行、部署发布、定时任务等核心功能。

Base URL

https://block2-api.wainao.chat

请求格式

所有请求体使用 JSON 格式，请设置请求头：

Content-Type: application/json

认证方式

API 支持三种认证方式，详见 认证文档：

方式	格式	适用场景
JWT Token	Bearer <jwt>	前端用户会话
API Key	Bearer wn-xxx	外部 API 调用
Schedule Token	Bearer <schedule-jwt>	定时任务触发

响应格式

JSON 响应

标准 JSON 格式，适用于大多数端点：

{
  "runId": "uuid",
  "documentId": "uuid",
  "sessions": [...],
  "duration": 1234
}

SSE 流式响应（Server-Sent Events）

用于文档运行的实时状态推送，浏览器原生支持：

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

event: block_start
data: {"blockId":"uuid","blockType":"code"}

event: block_chunk
data: {"blockId":"uuid","delta":"部分内容"}

event: block_complete
data: {"blockId":"uuid","output":{...}}

event: block_end
data: {"blockId":"uuid"}

event: block_error
data: {"blockId":"uuid","error":"错误信息"}

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

NDJSON 流式响应（Newline Delimited JSON）

每行一个完整 JSON 对象，跨语言通用，适用于 API 调用：

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

错误处理

所有错误响应均为 JSON 格式：

{
  "error": "错误标识或描述",
  "message": "用户可读的错误信息（可选）",
  "details": ["详细错误列表（可选）"]
}

通用 HTTP 状态码

状态码	说明
200	请求成功
201	创建成功
400	请求参数错误
401	未认证或认证失败
402	积分余额不足
403	无权限访问
404	资源不存在
409	资源冲突（如名称重复）
500	服务器内部错误

限流

API 采用分层限流策略，所有限流均为内存滑动窗口，配置可通过 site_settings 动态调整。

全局限流（pre-auth，按 IP）

范围	限制	说明
全局	300 请求/分钟	所有路由，包括 /api/released-app/*
支付相关	10 请求/分钟	/payment/*
Admin 接口	30 请求/分钟	/admin/*
认证接口	10 请求/分钟	/auth/*

API Key 路由限流（post-auth，按 Key/Schedule）

/api/released-app/* 路由在全局 IP 限流之外，还有独立的 per-identity 限流：

认证方式	限流 Key	限制
API Key	apiKeyId	600 请求/分钟
Schedule Token	scheduleId	600 请求/分钟

两层限流独立计数：单 IP 受全局 300/min 限制，单 Key 受 per-key 600/min 限制。多 IP 使用同一 Key 时，per-key 限流生效。

分页参数

支持分页的端点使用以下查询参数：

参数	类型	默认值	说明
page	number	1	页码，最小为 1
pageSize	number	20	每页数量，最大 100

分页响应格式：

{
  "data": [...],
  "total": 100,
  "page": 1,
  "pageSize": 20
}

部分端点使用 limit / offset 分页：

参数	类型	默认值	说明
limit	number	50	返回数量
offset	number	0	偏移量

API 模块索引

模块	路径前缀	文档	说明
健康检查	/health	health.md	服务状态检测
当前用户	/my	my.md	获取当前认证用户信息
文档操作	/documents	documents.md	文档运行、Yjs 状态、复制
运行记录	/runs	runs.md	查询运行历史
部署	/deployments	deployments.md	文档发布
API 运行	/api/released-app	api-run.md	已发布应用的 API 调用
定时任务	/projects/:projectId/schedules	schedules.md	CRUD + 触发 + 日志
项目成员	/projects/:projectId/members	project-members.md	成员权限管理
认证	-	authentication.md	认证方式详解