Skip to main content

​
API 分组

PAI 后端提供三组 API，面向不同调用场景：

Client API

面向终端用户（Web / 小程序），JWT Bearer 鉴权。

Admin API

面向管理后台，静态 Token 鉴权。

Webhook API

面向第三方平台回调（Telegram、微信、飞书等），各平台独立验签。

​
基础 URL

分组前缀示例
Client API/apiPOST /api/auth/login
Admin API/api/admin/v1GET /api/admin/v1/dashboard
Webhook API/api/webhooks/{platform}POST /api/webhooks/telegram
所有 API 均通过 HTTPS 访问。开发环境默认端口为 8000，生产环境建议通过反向代理暴露 443 端口。

​
鉴权方式

分组鉴权方式Header
Client APIJWT Bearer TokenAuthorization: Bearer {token}
Admin API静态管理员 TokenX-Admin-Token: {token}
Webhook API平台验签各平台独立机制
详细鉴权流程请参考 鉴权指南。

​
响应格式

​
成功响应

所有接口返回 JSON，成功时 HTTP 状态码为 200。常见响应结构： 操作类接口： 
{
  "ok": true,
  "message": "操作成功"
}
资源类接口： 
{
  "id": 1,
  "content": "...",
  "created_at": "2026-03-28T10:00:00+08:00"
}
列表类接口（Client）： 直接返回数组： 
[
  { "id": 1, "title": "..." },
  { "id": 2, "title": "..." }
]
分页列表（Admin）： 
{
  "page": 1,
  "size": 20,
  "total": 100,
  "items": [...]
}

​
Token 响应

登录 / 注册成功后返回： 
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

​
错误处理

错误响应使用对应的 HTTP 状态码，Body 格式统一为： 
{
  "detail": "错误描述信息"
}

​
常见错误码

状态码含义典型场景
400请求参数错误邮箱已注册、密码太短、参数格式不合法
401未授权Token 缺失、过期或无效；Admin Token 不匹配
403禁止访问Admin Token 未配置
404资源不存在账本、日程、对话、技能不存在
429请求过于频繁验证码发送冷却中
502上游服务错误MCP 工具调用失败
503服务不可用邮件服务未配置
所有时间字段均以用户所在时区的 ISO 8601 格式返回（如 2026-03-28T10:00:00+08:00），服务端根据 TIMEZONE 环境变量（默认 Asia/Shanghai）自动转换。

​
WebSocket 端点

除 REST API 外，PAI 还提供两个 WebSocket 端点用于实时通信：
端点路径用途
Chat WS/api/chat/ws?token={jwt}实时对话，双向通信
Notifications WS/api/notifications/ws?token={jwt}服务端推送通知
详见 WebSocket 协议文档。