# Chat API
SUMMARY: 人間と LLM エージェント間の非同期チャット — ポーリング、返信、履歴、未読数、ファイルアップロード。

KEY CONTEXT:
Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)
Poll: GET /chat/poll (returns unread messages, marks them as read)
Reply: POST /chat/reply { content }
History: GET /chat/history?limit=50
Unread count: GET /chat/unread?role=agent (or ?role=human)
Upload: POST /chat/upload (multipart, file attachment)
Pattern: poll between tool calls, reply when human asks questions

Chat API
Chat API は人間と LLM エージェント間の非同期メッセージングを実現します。同期型チャット（ChatGPT 形式）とは異なり、エージェントが作業中でも人間はメッセージを残すことができ、エージェントはツール呼び出しの間にポーリングします。
仕組み
[CODE BLOCK]
1. 人間が Web UI 経由でメッセージを送信（JWT を使用）
2. メッセージが保存され、未読としてマークされる
3. エージェントがツール呼び出しの間に  を実行
4. ポーリングがすべての未読メッセージを返し、既読にする
5. エージェントがメッセージを処理し、必要に応じて  で返信
エンドポイント
GET /chat/poll
人間からの新規メッセージをポーリングします。未読メッセージを返し、既読に変更します。ツール呼び出しの間に使用してください。
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
POST /chat/reply
エージェントとしてメッセージを送信します。
[CODE BLOCK]
POST /chat/send
人間としてメッセージを送信します（Mind Key ではなく JWT が必要）。
[CODE BLOCK]
GET /chat/history
最近のチャット履歴（両ロール）を取得します。
[CODE BLOCK]
GET /chat/unread
未読メッセージ数を取得します。
[CODE BLOCK]
GET /chat/status
チャットセッションのステータス（最終メッセージのタイムスタンプ、未読数）を取得します。
[CODE BLOCK]
POST /chat/upload
特定のメッセージに対するファイル添付をアップロードします（multipart 形式）。
[CODE BLOCK]
GET /chat/files/:messageid
メッセージのファイル添付一覧を取得します。
[CODE BLOCK]
GET /chat/file/:fileid
ファイル添付をダウンロードします。
[CODE BLOCK]
ポーリングパターン
> [!TIP]
> ツール呼び出しの間に 30〜60 秒ごとにポーリングしてください。これより頻繁なポーリングは API クォータを無駄に消費するだけで、メリットはありません。
[CODE BLOCK]
次のステップ
- Tasks API
- Chat Polling Pattern