Api Introduction

API 介绍

StackPanel 提供 RESTful 风格的 API。前端（Next.js Web）与后端的交互全部通过 API 完成。

在线文档

启动 API 后，访问 Swagger UI：

http://127.0.0.1:3001/docs

Swagger UI 包含所有内核路由和插件路由的文档。插件路由出现在 plugins 标签下。

API 分组

分组	认证	说明
公开接口	无	健康、主题、平台信息、SEO 等
认证接口	会话（Bearer/Cookie）	当前用户、通知、权限检查等
管理接口	platform.admin 权限	用户、插件、主题、设置、备份、开发者等
开放平台	会话或 API Token（sp_ 前缀）	/api/v1、/mcp，按 scope 与权限鉴权
渠道接口	Ed25519 请求签名	/sp/v1，面向渠道伙伴
插件接口	视路由声明	由插件定义

开放平台契约（路径 / 方法 / 鉴权 / 必填参数）以 @stackpanel/spec 的投影为单一来源， 内核 app.ts 与契约快照共用同一实现（packages/spec/src/{version,openapi,contract}.ts）。

基础信息

项	值
Base URL	http://127.0.0.1:3001
API 版本	0.4.0（KERNEL_API_VERSION，@stackpanel/spec 单一来源）
开放平台	/api/v1（OPEN_API_NAMESPACE）
内容类型	application/json（文件上传为 multipart/form-data）
错误类型	application/problem+json（RFC 7807 / RFC 9457）
字符编码	UTF-8

响应格式

成功响应

返回 JSON 或空响应（204）。

错误响应

所有错误统一为 RFC 7807 / RFC 9457 problem details，Content-Type 为 application/problem+json：

{
  "type": "https://errors.stackpanel.dev/auth/unauthenticated",
  "title": "Unauthorized",
  "status": 401,
  "detail": "未登录或会话已过期",
  "instance": "/auth/me",
  "code": "auth.unauthenticated",
  "requestId": "req-1"
}

稳定契约是 code；type / title / detail 为中性英文或原始文案兜底。 详见 错误处理。

速率限制

限流由中央策略表 apps/api/src/lib/rate-limit-policy.ts 定义（跨副本计数走 Redis）：

接口	限制
POST /login、/register	5 次/分钟/IP（插件内置限流，LOGIN_RATE_LIMIT_MAX / REGISTER_RATE_LIMIT_MAX）
OAuth 接口	10 次/分钟/IP（oauth 预设）
API Token 签发 / 轮换	30 次/分钟/IP（credentialWrite）
管理端写入（密钥 / 签名 / 平台身份等）	60 次/分钟/IP（adminWrite）
插件 / 主题 / 媒体上传	20 次/分钟/IP（upload）
前端审计等用户写入	120 次/分钟/IP（userWrite）
开放平台 API Token	每 token RPM（OPEN_API_TOKEN_RPM，默认 240）与并发上限（OPEN_API_TOKEN_CONCURRENCY，默认关闭）

API_RATE_LIMIT_MULTIPLIER 可整体放大限额（仅放宽，不会关闭）。

安全头

所有响应包含以下安全头：

头	值
X-Content-Type-Options	nosniff
X-Frame-Options	DENY
Referrer-Policy	strict-origin-when-cross-origin
Permissions-Policy	camera=(), microphone=(), geolocation=()
Content-Security-Policy	default-src 'self'; frame-ancestors 'none'; ...

CORS

默认禁用 CORS。只有显式配置 API_CORS_ORIGINS 环境变量才允许指定源跨域访问。

BFF 模式下，浏览器只与 Web 服务通信，Web 服务服务端转发到 API，因此通常不需要 CORS。

接下来

• Open Platform API v1 — Token、契约与调用模型
• Capability Discovery — 按凭证发现可调用操作
• 幂等与重试 — 写操作的安全重试
• MCP — HTTP 与 stdio 工具接入
• StackPanel Partner API v1 — 渠道/合作方签名协议
• 认证方式 — 会话、API Token、OAuth、渠道签名
• API 路由参考 — 全部端点
• SDK 客户端 — 类型安全客户端
• 错误处理 — problem+json 与状态码