API 概览 - PAI 文档

API 分组

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

Client API

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

Admin API

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

Webhook API

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

基础 URL

分组	前缀	示例
Client API	`/api`	`POST /api/auth/login`
Admin API	`/api/admin/v1`	`GET /api/admin/v1/dashboard`
Webhook API	`/api/webhooks/{platform}`	`POST /api/webhooks/telegram`

所有 API 均通过 HTTPS 访问。开发环境默认端口为 8000，生产环境建议通过反向代理暴露 443 端口。

鉴权方式

分组	鉴权方式	Header
Client API	JWT Bearer Token	`Authorization: Bearer {token}`
Admin API	静态管理员 Token	`X-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 协议文档。

​API 分组

Client API

Admin API

Webhook API

​基础 URL

​鉴权方式

​响应格式

​成功响应

​Token 响应

​错误处理

​常见错误码

​WebSocket 端点

API 分组

基础 URL

鉴权方式

响应格式

成功响应

Token 响应

错误处理

常见错误码

WebSocket 端点