# Chat API

De Chat API maakt asynchrone berichtenuitwisseling mogelijk tussen mensen en LLM-agents.
In tegenstelling tot synchrone chat (ChatGPT-stijl) kan de mens berichten achterlaten
terwijl de agent aan het werk is — de agent pollt tussen tool-aanroepen door.

## Hoe het werkt

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

1. De mens stuurt een bericht via de web-UI (gebruikt JWT)
2. Het bericht wordt opgeslagen en gemarkeerd als ongelezen
3. De agent pollt `GET /chat/poll` tussen tool-aanroepen
4. De poll retourneert alle ongelezen berichten en markeert deze als gelezen
5. De agent verwerkt het bericht en antwoordt optioneel via `POST /chat/reply`

## Eindpunten

### GET /chat/poll

Poll voor nieuwe berichten van de mens. Retourneert ongelezen berichten en markeert
ze als gelezen. Gebruik dit tussen tool-aanroepen.

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

Respons:

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

### POST /chat/reply

Stuur een bericht als de 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

Stuur een bericht als de mens (vereist JWT, niet 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

Haal recente chatgeschiedenis op (beide rollen).

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

### GET /chat/unread

Haal het aantal ongelezen berichten op.

```bash
# Tel ongelezen berichten van de mens (voor de agent)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/unread?role=agent"

# Tel ongelezen berichten van de agent (voor de mens)
curl -H "Authorization: Bearer YOUR_JWT" \
     "https://synapse.schaefer.zone/chat/unread?role=human"
```

### GET /chat/status

Haal de status van de chatsessie op (laatste bericht-tijdstempels, ongelezen tellers).

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

### POST /chat/upload

Upload een bestandsbijlage voor een specifiek bericht (multipart-formulier).

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

Bekijk bestandsbijlagen voor een bericht.

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

### GET /chat/file/:file_id

Download een bestandsbijlage.

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

## Polling-patroon

> [!TIP]
> Poll elke 30-60 seconden tussen tool-aanroepen. Poll niet vaker —
> dat verspilt API-quota en levert geen voordeel op.

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

## Volgende stappen

- [Tasks API](/docs/api/tasks)
- [Chat Polling Pattern](/docs/llm-cookbook/chat-polling-pattern)