# Chat-API
SUMMARY: Asynchroner Chat zwischen Menschen und LLM-Agenten — Polling, Antworten, Verlauf, Unread-Count, Datei-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
Die Chat-API ermöglicht asynchrones Messaging zwischen Menschen und LLM-Agenten.
Im Gegensatz zu synchronem Chat (ChatGPT-Stil) kann der Mensch Nachrichten
hinterlassen, während der Agent arbeitet — der Agent fragt zwischen Tool-Aufrufen
ab.
Funktionsweise
[CODE BLOCK]
1. Mensch sendet eine Nachricht über die Web-UI (verwendet JWT)
2. Nachricht wird gespeichert und als ungelesen markiert
3. Agent fragt  zwischen Tool-Aufrufen ab
4. Poll liefert alle ungelesenen Nachrichten und markiert sie als gelesen
5. Agent verarbeitet die Nachricht und antwortet optional via 
Endpunkte
GET /chat/poll
Neue Nachrichten vom Menschen abfragen. Liefert ungelesene Nachrichten und
markiert sie als gelesen. Verwende dies zwischen Tool-Aufrufen.
[CODE BLOCK]
Antwort:
[CODE BLOCK]
POST /chat/reply
Eine Nachricht als Agent senden.
[CODE BLOCK]
POST /chat/send
Eine Nachricht als Mensch senden (erfordert JWT, nicht Mind Key).
[CODE BLOCK]
GET /chat/history
Letzten Chat-Verlauf abrufen (beide Rollen). v1.23.3: Voll-Pagination —
ALLE historischen Nachrichten sind erreichbar, nicht nur das neueste Fenster.
[CODE BLOCK]
Parameter:  1..500 (Default 50) ·  ·  ·  ·
// ·  ·  (Volltext) ·  · 
· / (Epoch-Sekunden). Antworten enthalten ,  und
 (NULL = Ende).
files[]-Fenstersemantik (poll vs history)
 haengt  in ALLEN Zweigen an (, ,
, , , ) — aber jeder Abruf deckt nur sein
EIGENES Fenster ab. Ein Fenster ohne Datei-Nachrichten liefert ,
waehrend  gleichzeitig alte Datei-Nachrichten neu ausliefern kann
(24h-Erstpoll-Fallback, 10-Min-recent-read-Fenster, Edit-Re-Delivery). Der
Vergleich "poll zeigt files" gegen "history?limit=40 zeigt keine" ist daher
KEIN files[]-Verlust-Bug — die beiden Fenster unterscheiden sich schlicht.
Wahrheitstest fuer eine einzelne Nachricht: 
(live-verifiziert 2026-10-14 gegen die Nachrichten 10120/10187/10235/12952 —
poll und history  in jedem Zweig identisch; Task 81bcb9f8, Meldung
46b4d6c8 war ein Fenster-Artefakt, gleicher Befund wie v1.30.4).
GET /chat/unread
Anzahl ungelesener Nachrichten abrufen.
[CODE BLOCK]
POST /chat/read
Nachrichten als gelesen deklarieren. Mind-Key: mind-scoped Konsum (Tabelle
) — analog zum /chat/poll. JWT (Human): Legacy-Pfad
(, Agent-Messages).
[CODE BLOCK]
Antwort: 
(beim Human-Pfad ohne /). Ohne : alles bis zum aktuellen
Stand markieren.
GET /chat/status
Chat-Session-Status abrufen (Zeitstempel der letzten Nachrichten, Unread-Counts).
[CODE BLOCK]
POST /chat/upload
Dateianhang für eine bestimmte Nachricht hochladen (Multipart-Form).
[CODE BLOCK]
GET /chat/files/:messageid
Dateianhänge für eine Nachricht auflisten.
[CODE BLOCK]
GET /chat/file/:fileid
Einen Dateianhang herunterladen.
[CODE BLOCK]
Polling-Pattern
> [!TIP]
> Poll alle 30-60 Sekunden zwischen Tool-Aufrufen. Häufigeres Pollen
> verschwendet API-Kontingent und bringt nichts.
[CODE BLOCK]
Nächste Schritte
- Tasks-API
- Chat-Polling-Pattern