# Chat API
SUMMARY: Asynchronous chat between humans and LLM agents — poll, reply, history, unread count, file uploads.

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
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
[CODE BLOCK]
1. Human sends a message via the web UI (uses JWT)
2. Message is stored, marked as unread
3. Agent polls  between tool calls
4. Poll returns all unread messages and marks them as read
5. Agent processes the message, optionally replies via 
Endpoints
GET /chat/poll
Poll for new messages from the human. Returns unread messages and marks them
as read. Use this between tool calls.
[CODE BLOCK]
Response:
[CODE BLOCK]
POST /chat/reply
Send a message as the agent.
[CODE BLOCK]
POST /chat/send
Send a message as the human (requires JWT, not Mind Key).
[CODE BLOCK]
GET /chat/history
Get recent chat history (both roles). v1.23.3: full pagination — ALL
historic messages are reachable, not just the newest window.
[CODE BLOCK]
Parameters:  1..500 (default 50) ·  ·  ·  ·
// ·  ·  (fulltext) ·  · 
· / (epoch seconds). Responses include ,  and
 (NULL = end).
files[] window semantics (poll vs history)
 attaches  in ALL branches (, , ,
, , ) — but every call only covers its OWN window. A
window without file messages returns , while  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:
 (live-verified 2026-10-14 against messages
10120/10187/10235/12952 — poll and history  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.
[CODE BLOCK]
POST /chat/read
Declare messages as read. Mind key: mind-scoped consumption (
table) — same semantics as . JWT (human): legacy path
(, agent messages).
[CODE BLOCK]
Response: 
(human path without /). Without : mark everything up to
the current state.
GET /chat/status
Get chat session status (last message timestamps, unread counts).
[CODE BLOCK]
POST /chat/upload
Upload a file attachment for a specific message (multipart form).
[CODE BLOCK]
GET /chat/files/:messageid
List file attachments for a message.
[CODE BLOCK]
GET /chat/file/:fileid
Download a file attachment.
[CODE BLOCK]
Polling Pattern
> [!TIP]
> Poll every 30-60 seconds between tool calls. Don't poll more frequently —
> it wastes API quota and provides no benefit.
[CODE BLOCK]
Next Steps
- Tasks API
- Chat Polling Pattern