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 事件。完整的事件結構參見 網頁元件。