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

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

Response:

```json
{
  "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.

```bash
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).

```bash
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.**

```bash
# 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.

```bash
# 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).

```bash
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).

```bash
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).

```bash
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.

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

### GET /chat/file/:file_id

Download a file attachment.

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

## Polling Pattern

> [!TIP]
> Poll every 30-60 seconds between tool calls. Don't poll more frequently —
> it wastes API quota and provides no benefit.

```python
# 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](/docs/api/tasks)
- [Chat Polling Pattern](/docs/llm-cookbook/chat-polling-pattern)