Chat API

Chat API は人間と LLM エージェント間の非同期メッセージングを実現します。同期型チャット（ChatGPT 形式）とは異なり、エージェントが作業中でも人間はメッセージを残すことができ、エージェントはツール呼び出しの間にポーリングします。

仕組み

Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)
                                     │
                                     └── marks messages as read on poll

1. 人間が Web UI 経由でメッセージを送信（JWT を使用）
2. メッセージが保存され、未読としてマークされる
3. エージェントがツール呼び出しの間に GET /chat/poll を実行
4. ポーリングがすべての未読メッセージを返し、既読にする
5. エージェントがメッセージを処理し、必要に応じて POST /chat/reply で返信

エンドポイント

GET /chat/poll

人間からの新規メッセージをポーリングします。未読メッセージを返し、既読に変更します。ツール呼び出しの間に使用してください。

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/chat/poll

レスポンス：

{
  "messages": [
    {
      "id": "msg_001",
      "role": "human",
      "content": "How's the deployment going?",
      "created_at": "2026-06-27T..."
    }
  ]
}

POST /chat/reply

エージェントとしてメッセージを送信します。

curl -X POST https://synapse.schaefer.zone/chat/reply \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Deployment is 80% done. CI is green, just waiting for Docker push."}'

POST /chat/send

人間としてメッセージを送信します（Mind Key ではなく JWT が必要）。

curl -X POST https://synapse.schaefer.zone/chat/send \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"content": "Can you check the logs?"}'

GET /chat/history

最近のチャット履歴（両ロール）を取得します。

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/history?limit=50"

GET /chat/unread

未読メッセージ数を取得します。

# Count unread messages from human (for agent)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/unread?role=agent"

# Count unread messages from agent (for human)
curl -H "Authorization: Bearer YOUR_JWT" \
     "https://synapse.schaefer.zone/chat/unread?role=human"

GET /chat/status

チャットセッションのステータス（最終メッセージのタイムスタンプ、未読数）を取得します。

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/chat/status

POST /chat/upload

特定のメッセージに対するファイル添付をアップロードします（multipart 形式）。

curl -X POST https://synapse.schaefer.zone/chat/upload \
  -H "Authorization: Bearer YOUR_JWT" \
  -F "message_id=msg_001" \
  -F "file=@screenshot.png"

GET /chat/files/:message_id

メッセージのファイル添付一覧を取得します。

curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/chat/files/msg_001

GET /chat/file/:file_id

ファイル添付をダウンロードします。

curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/chat/file/file_001 --output download.png

ポーリングパターン

# Pseudo-code
while working:
    messages = poll_chat()
    for msg in messages:
        process_message(msg)
        reply(f"Acknowledged: {msg.content}")
    do_one_tool_call()

次のステップ

• Tasks API
• Chat Polling Pattern