Chat API

The Chat API enables asynchronous messaging between humans and LLM agents. Unlike synchronous chat (ChatGPT-style), the human can leave messages while the agent is working — the agent polls between tool calls.

How It Works

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

1. Human sends a message via the web UI (uses JWT)
2. Message is stored, marked as unread
3. Agent polls GET /chat/poll between tool calls
4. Poll returns all unread messages and marks them as read
5. Agent processes the message, optionally replies via POST /chat/reply

Endpoints

GET /chat/poll

Poll for new messages from the human. Returns unread messages and marks them as read. Use this between tool calls.

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

Response:

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

POST /chat/reply

Send a message as the agent.

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

Send a message as the human (requires JWT, not Mind Key).

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

Get recent chat history (both roles). v1.23.3: full pagination — ALL historic messages are reachable, not just the newest window.

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

# Exact single message by id (even very old, incl. quoted_* + files)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/history?id=9606"

# id-window around a message (±25) — e.g. for #id references
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/history?around_id=9606"

# Older page: everything before id N (descending walk, has_more flag)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/history?before_id=9000&limit=200"

# Ascending catch-up from id N (iterate gaplessly until count < limit)
# since_id and after_id are aliases of since
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/history?since=8800&limit=200"

# Classic pagination backwards from the newest end (offset + next_offset)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/history?limit=200&offset=200"

Parameters: limit 1..500 (default 50) · id · around_id · before_id · since/since_id/after_id · offset · q (fulltext) · mine · mentions · from/to (epoch seconds). Responses include count, has_more and next_offset (NULL = end).

files[] window semantics (poll vs history)

/chat/history attaches files[] in ALL branches (id, since, around_id, before_id, offset, q) — but every call only covers its OWN window. A window without file messages returns files: [], while /chat/poll may simultaneously re-deliver old file messages (24h first-poll fallback, 10-min recent-read window, edit re-delivery). Comparing "poll shows files" against "history?limit=40 shows none" is therefore NOT a lost-files bug — the two windows simply differ. Truth test for a single message: GET /chat/history?id=N (live-verified 2026-10-14 against messages 10120/10187/10235/12952 — poll and history files[] identical in every branch; task 81bcb9f8, report 46b4d6c8 was a window artifact, same finding as v1.30.4).

GET /chat/unread

Get unread message count.

# 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"

POST /chat/read

Declare messages as read. Mind key: mind-scoped consumption (chat_read_status table) — same semantics as /chat/poll. JWT (human): legacy path (chat_messages.read_at, agent messages).

curl -X POST https://synapse.schaefer.zone/chat/read \
  -H "Authorization: Bearer MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"up_to": 12345}'

Response: { "status": "read", "marked": <count>, "scope": "mind", "mind_id": "..." } (human path without scope/mind_id). Without up_to: mark everything up to the current state.

GET /chat/status

Get chat session status (last message timestamps, unread counts).

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

POST /chat/upload

Upload a file attachment for a specific message (multipart form).

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

List file attachments for a message.

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

GET /chat/file/:file_id

Download a file attachment.

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

Polling Pattern

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

Next Steps

• Tasks API
• Chat Polling Pattern