メインコンテンツへスキップ
テナント管理者 JWT で認証 (SDK 側の X-API-KEY とは別系統)。ホストは https://{tenantCode}.aika.life (ベータ) / https://{tenantCode}.ones1ght.com (本番)。バックオフィス (admin.aika.life) は /api/v1/admin/sdk-chat/... で全テナントのデータを無制限照会可能 (super admin 権限)。

​
1. リアルタイム SSE ストリーム

GET /api/v1/sdk-chat/events/stream
Content-Type: text/event-stream。テナント管理者で 1 回接続するとそのテナント内の SDK チャットライフサイクルイベントが全てリアルタイムで push されます。25 秒間隔の ping heartbeat で ALB / nginx idle timeout を防止。

​
イベント種類

eventトリガーdata ペイロード
ready接続直後 1 回{}
ping25 秒ごと(空文字列)
chat_completedポーリング応答が status: "completed" に初遷移{profile_id, chat_id}
backlist_triggerediOS が POST /v1/chat/{pid}/backlist-trigger を呼び出し{profile_id, chat_id, notification_items}

​
ブラウザ例

const es = new EventSource("/api/v1/sdk-chat/events/stream", { withCredentials: true });

es.addEventListener("chat_completed", (e) => {
  const { profile_id, chat_id } = JSON.parse(e.data);
  // → /api/v1/sdk-chat/{chat_id} 詳細を再取得
});

es.addEventListener("backlist_triggered", (e) => {
  const { profile_id, chat_id, notification_items } = JSON.parse(e.data);
  // → ダッシュボードのトースト / 地図マーカーを即時描画
});
ライブ専用 — 購読者がいない時点で発生したイベントはバッファリングなしに drop。蓄積データは下記の履歴エンドポイントから。

​
2. 履歴リスト (ページング)

GET /api/v1/sdk-chat?profile_id={uuid}&page=0&size=20
自テナントの sdk_chat 行を新しい順にページング。profile_id フィルターは任意。size は最大 100。

​
レスポンス 200

{
  "success": true,
  "data": {
    "items": [
      {
        "chat_id":         "3736f10f-...",
        "profile_id":      "6b97957c-...",
        "profile_summary": { "name": "佐藤花子", "gender": "F", "age": 32, "locale": "ja" },
        "prompt":          "今夜のおかず何がいい?",
        "status":          "completed",
        "last_error":      null,
        "created_at":      "2026-04-23T05:28:08Z",
        "updated_at":      "2026-04-23T05:30:00Z",
        "ended_at":        "2026-04-23T05:31:00Z"
      }
    ],
    "total": 234,
    "page": 0,
    "size": 20
  }
}
フィールド説明
statusin_progress / completed / error / ended (ポーリングと同語彙)
profile_summarysdk_profile.data JSONB から name / gender / age / locale を抽出
last_errorerror 時のみ
ended_atDELETE 時刻、その他は null
pipeline_result はリストには含まれません (ペイロード抑制)。詳細は下記。

​
3. 履歴詳細

GET /api/v1/sdk-chat/{chat_id}
ポーリング完了時の応答をそのまま保存 — status / back_list_status / todos / recommended_items / notification_items が top-level に hoist されており、ポーリング応答と同じ shape。フィールド詳細は Profile Chat — 4. 過去チャット再取得 参照。 加えて profile_summary と profile_session_id が同梱されます。

​
4. バックオフィス (super admin) エンドポイント

admin.aika.life から呼び出し。テナント境界なしで全件照会。tenant_id、profile_id は両方とも任意フィルター。
エンドポイント動作
GET /api/v1/admin/sdk-chat?tenant_id=...&profile_id=...&page=...&size=...テナント管理者リストと同 shape、各 row に tenant_id 同梱
GET /api/v1/admin/sdk-chat/{chat_id}テナント管理者詳細と同 shape、テナント制約なし
権限: ROLE_ADMIN (Spring Security @PreAuthorize)。

​
5. 権限マトリクス

エンドポイント認証必要権限
GET /api/v1/sdk-chat/events/streamテナント JWTuser.role == 'admin'
GET /api/v1/sdk-chatテナント JWTuser.role == 'admin'
GET /api/v1/sdk-chat/{chat_id}テナント JWTuser.role == 'admin'
GET /api/v1/admin/sdk-chatバックオフィス JWTROLE_ADMIN
GET /api/v1/admin/sdk-chat/{chat_id}バックオフィス JWTROLE_ADMIN
未認証 / 権限不足は 401 / 403。

​
6. プッシュ + プル併用パターン (推奨)

[ページ進入]
  ├─ GET /api/v1/sdk-chat?page=0  → 初期リスト描画
  └─ EventSource(/events/stream)  → 以降の差分はリアルタイム反映
      ├─ chat_completed  → 該当 row を GET /{chat_id} で再取得
      └─ backlist_triggered  → トースト / 地図マーカーを即時表示