API 参考（OpenAPI 3.1）

AskAIs 智能客服系统 提供完整的 OpenAPI 3.1 规范，描述每一个公开端点。它为我们自动生成的 SDK 提供支持，并可与 OpenAPI 生态中的任意工具配合使用（Insomnia、Postman、Swagger UI、Hoppscotch 等）。

获取规范

# Live (cached 5 min, CORS open)
curl https://cs.askais.com/api/v1/openapi.json

# Save to disk
curl https://cs.askais.com/api/v1/openapi.json -o singlink-openapi.json

基础 URL

• 云端：https://cs.askais.com/api/v1
• 自托管：你的 APP_URL 解析到的地址，并加上后缀 /api/v1

鉴权

两种方案，均通过 Authorization: Bearer <value>：

• 联系人 JWT —— 由 POST /auth/identify 签发。仅限单个 联系人。供 web / 移动端 SDK 使用。
• 工作区 API key —— sk_live_...，在 设置 → API Keys 中生成。作用于整个工作区。用于服务器到服务器调用。

端点一览

• POST /auth/identify —— 签发联系人 JWT
• POST /conversations —— 发起新会话
• GET /conversations —— 列出你的会话
• GET /conversations/{id}
• GET /conversations/{id}/messages?before=&limit=
• POST /conversations/{id}/messages
• POST /upload —— 获取预签名的 S3 POST URL
• POST /upload/{id}/confirm

错误

所有非 2xx 响应都使用统一的稳定结构：

{
  "error": {
    "code": "validation_error",
    "message": "content or attachments required",
    "field": "content"
  }
}

错误码：validation_error、unauthorized、forbidden、 not_found、conflict、unprocessable、 rate_limit_exceeded、internal_error。

实时配套

REST 适合一次性调用。对于实时消息，请连接到 wss://<wsUrl>/v1/ws?token=<jwt>，并监听 message:new、ai:stream:delta、ai:stream:end、 typing 和 presence 事件。完整的事件结构参见 网页挂件。