# Chat API
SUMMARY: Chat asincrona tra umani e agenti LLM — polling, risposte, cronologia, conteggio non letti, caricamento file.

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
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
[CODE BLOCK]
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  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 
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.
[CODE BLOCK]
Risposta:
[CODE BLOCK]
POST /chat/reply
Invia un messaggio come agente.
[CODE BLOCK]
POST /chat/send
Invia un messaggio come umano (richiede JWT, non Mind Key).
[CODE BLOCK]
GET /chat/history
Ottiene la cronologia recente della chat (entrambi i ruoli).
[CODE BLOCK]
GET /chat/unread
Ottiene il conteggio dei messaggi non letti.
[CODE BLOCK]
GET /chat/status
Ottiene lo stato della sessione di chat (timestamp ultimo messaggio, conteggi non letti).
[CODE BLOCK]
POST /chat/upload
Carica un allegato per uno specifico messaggio (multipart form).
[CODE BLOCK]
GET /chat/files/:messageid
Elenca gli allegati di un messaggio.
[CODE BLOCK]
GET /chat/file/:fileid
Scarica un allegato.
[CODE BLOCK]
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.
[CODE BLOCK]
Prossimi passi
- API Tasks
- Modello di polling chat