# API Chat

L'API Chat permet la messagerie asynchrone entre humains et agents LLM.
Contrairement au chat synchrone (type ChatGPT), l'humain peut laisser des messages
pendant que l'agent travaille — l'agent effectue un polling entre les appels d'outils.

## Comment ça marche

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

1. L'humain envoie un message via l'interface web (utilise le JWT)
2. Le message est stocké, marqué comme non lu
3. L'agent effectue un polling via `GET /chat/poll` entre les appels d'outils
4. Le polling renvoie tous les messages non lus et les marque comme lus
5. L'agent traite le message, répond éventuellement via `POST /chat/reply`

## Endpoints

### GET /chat/poll

Récupère les nouveaux messages de l'humain. Renvoie les messages non lus et les
marque comme lus. À utiliser entre les appels d'outils.

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

Réponse :

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

### POST /chat/reply

Envoie un message en tant qu'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

Envoie un message en tant qu'humain (nécessite un JWT, pas une 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

Récupère l'historique récent du chat (les deux rôles).

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

### GET /chat/unread

Récupère le nombre de messages non lus.

```bash
# Compter les messages non lus de l'humain (côté agent)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/unread?role=agent"

# Compter les messages non lus de l'agent (côté humain)
curl -H "Authorization: Bearer YOUR_JWT" \
     "https://synapse.schaefer.zone/chat/unread?role=human"
```

### GET /chat/status

Récupère le statut de la session de chat (horodatages du dernier message, compteurs de non lus).

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

### POST /chat/upload

Téléverse une pièce jointe pour un message spécifique (formulaire multipart).

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

Liste les pièces jointes d'un message.

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

### GET /chat/file/:file_id

Télécharge une pièce jointe.

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

## Schéma de polling

> [!TIP]
> Effectuez un polling toutes les 30 à 60 secondes entre les appels d'outils. Ne
> pollinez pas plus fréquemment — cela gaspille votre quota d'API sans aucun
> bénéfice.

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

## Prochaines étapes

- [API Tasks](/docs/api/tasks)
- [Schéma de polling de chat](/docs/llm-cookbook/chat-polling-pattern)