# リアルタイム API リファレンス

TaskWorks API のリアルタイム通信関連エンドポイントの詳細ドキュメントです。

## 認証方式

### ApiKey 認証（推奨）
```
Authorization: ApiKey <token>
```
- 設定 > APIキー管理 から生成
- トークンは一度しか表示されないため安全に保管
- ほとんどのエンドポイントで使用可能

### Bearer トークン認証
```
Authorization: Bearer <token>
```
- サービス間通信で使用
- 一部のエンドポイントで必須（例: /api/v1/blocks/windows）

### Cookie 認証
- 標準のセッションベース認証
- Webクライアントで使用
- Cookie専用エンドポイントで必須

## 共通レスポンス形式

すべての成功レスポンスは以下の構造に従います：
```json
{
  "data": <response_data>,
  "error": null
}
```

すべてのエラーレスポンスは以下の構造に従います：
```json
{
  "error": "<error_type>",
  "message": "<human_readable_message>",
  "code": "<optional_error_code>",
  "context": <optional_additional_context>
}
```

## HTTP ステータスコード

- 200: 成功
- 201: 作成完了
- 400: 不正なリクエスト（検証エラー）
- 401: 未認証（認証が必要）
- 403: 禁止（権限なし）
- 404: 未検出
- 409: 衝突（リソースの競合）
- 500: サーバー内部エラー

## ページネーション

一部のエンドポイントはカーソルベースのページネーションをサポート：
- cursor: 次ページの開始位置
- limit: 返す項目数（1-100、デフォルトはエンドポイントにより異なる）

レスポンス形式：
```json
{
  "data": {
    "items": [...],
    "nextCursor": "string | null",
    "hasMore": boolean
  },
  "error": null
}
```

## API エンドポイント

### リアルタイム（Realtime - WebRTC ビデオルーム）

#### POST /api/v1/realtime/rooms

新しい音声/ビデオルームを作成します（WebRTCオファー使用）。

**認証:** なし（WebRTCオファー使用）

**リクエストボディ:**
```json
{
  "offer": Object (WebRTC offer)
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "roomId": "string",
    "answer": Object (WebRTC answer)
  },
  "error": null
}
```

---

#### POST /api/v1/realtime/rooms/:roomId/session

既存のルームに参加します（WebRTCオファー使用）。

**認証:** なし（WebRTCオファー使用）

**パスパラメータ:**
- roomId: string（必須）- ルームID

**リクエストボディ:**
```json
{
  "offer": Object (WebRTC offer)
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "roomId": "string",
    "answer": Object (WebRTC answer),
    "participantId": "string"
  },
  "error": null
}
```

---

#### GET /api/v1/realtime/rooms/:roomId/state

ルーム状態を取得します。

**認証:** Cookie のみ

**パスパラメータ:**
- roomId: string（必須）- ルームID

**レスポンス スキーマ:**
```json
{
  "data": {
    "roomId": "string",
    "participants": Array<{
      "id": "string",
      "userId": "string",
      "joinedAt": "string"
    }>,
    "activeTracks": Array<Object>,
    "createdAt": "string",
    "updatedAt": "string"
  },
  "error": null
}
```

---

#### POST /api/v1/realtime/rooms/:roomId/tracks/publish

メディアトラックを公開します。

**認証:** Cookie のみ

**パスパラメータ:**
- roomId: string（必須）- ルームID

**リクエストボディ:**
```json
{
  "track": Object (WebRTC track data)
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "trackId": "string",
    "publishedAt": "string"
  },
  "error": null
}
```

---

#### POST /api/v1/realtime/rooms/:roomId/tracks/subscribe

メディアトラックを購読します。

**認証:** Cookie のみ

**パスパラメータ:**
- roomId: string（必須）- ルームID

**リクエストボディ:**
```json
{
  "trackId": "string (required)"
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "subscribed": true,
    "subscribedAt": "string"
  },
  "error": null
}
```

---

#### POST /api/v1/realtime/rooms/:roomId/renegotiate

WebRTC接続を再ネゴシエートします。

**認証:** Cookie のみ

**パスパラメータ:**
- roomId: string（必須）- ルームID

**リクエストボディ:**
```json
{
  "offer": Object (WebRTC offer)
}
```

**レスポンス スキーマ:**
```json
{
  "data": {
    "answer": Object (WebRTC answer)
  },
  "error": null
}
```

---

#### POST /api/v1/realtime/communities/:communityId/spaces

コミュニティスペース一覧を取得します。

**認証:** Cookie のみ

**パスパラメータ:**
- communityId: string（必須）- コミュニティID

**レスポンス スキーマ:**
```json
{
  "data": [
    {
      "id": "string",
      "communityId": "string",
      "name": "string",
      "roomId": "string | null",
      "createdAt": "string"
    }
  ],
  "error": null
}
```