# 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).
[CODE BLOCK]
GET /chat/unread
Get unread message count.
[CODE BLOCK]
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