API リファレンス（OpenAPI 3.1）

AskAIs Customer Service は、すべての公開エンドポイントを記述した完全な 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 を付加したもの

認証

2 つの方式があり、いずれも 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 イベントをリッスンします。完全なイベント構造は ウェブウィジェット を参照してください。