# Chat API

La Chat API permette la messaggistica asincrona tra umani e agenti LLM.
A differenza della chat sincrona (stile ChatGPT), l'umano può lasciare messaggi
mentre l'agente sta lavorando — l'agente esegue il polling tra le chiamate agli
strumenti.

## Come funziona

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

1. L'umano invia un messaggio tramite l'interfaccia web (usa JWT)
2. Il messaggio viene memorizzato e contrassegnato come non letto
3. L'agente esegue il polling con `GET /chat/poll` tra le chiamate agli strumenti
4. Il polling restituisce tutti i messaggi non letti e li contrassegna come letti
5. L'agente elabora il messaggio e, opzionalmente, risponde tramite `POST /chat/reply`

## Endpoint

### GET /chat/poll

Esegue il polling dei nuovi messaggi dall'umano. Restituisce i messaggi non letti
e li contrassegna come letti. Lo utilizzi tra una chiamata e l'altra degli
strumenti.

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

Risposta:

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

### POST /chat/reply

Invia un messaggio come agente.

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

Invia un messaggio come umano (richiede JWT, non 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

Ottiene la cronologia recente della chat (entrambi i ruoli).

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

### GET /chat/unread

Ottiene il conteggio dei messaggi non letti.

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

### GET /chat/status

Ottiene lo stato della sessione di chat (timestamp ultimo messaggio, conteggi non letti).

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

### POST /chat/upload

Carica un allegato per uno specifico messaggio (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

Elenca gli allegati di un messaggio.

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

### GET /chat/file/:file_id

Scarica un allegato.

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

## Modello di polling

> [!TIP]
> Esegua il polling ogni 30-60 secondi tra le chiamate agli strumenti. Non esegua
> il polling più frequentemente — spreca la quota API senza alcun beneficio.

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

## Prossimi passi

- [API Tasks](/docs/api/tasks)
- [Modello di polling chat](/docs/llm-cookbook/chat-polling-pattern)