# 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

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

1. Mensch sendet eine Nachricht über die Web-UI (verwendet JWT)
2. Nachricht wird gespeichert und als ungelesen markiert
3. Agent fragt `GET /chat/poll` zwischen Tool-Aufrufen ab
4. Poll liefert alle ungelesenen Nachrichten und markiert sie als gelesen
5. Agent verarbeitet die Nachricht und antwortet optional via `POST /chat/reply`

## Endpunkte

### GET /chat/poll

Neue Nachrichten vom Menschen abfragen. Liefert ungelesene Nachrichten und
markiert sie als gelesen. Verwende dies zwischen Tool-Aufrufen.

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

Antwort:

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

### POST /chat/reply

Eine Nachricht als Agent senden.

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

Eine Nachricht als Mensch senden (erfordert JWT, nicht 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

Letzten Chat-Verlauf abrufen (beide Rollen). **v1.23.3: Voll-Pagination —
ALLE historischen Nachrichten sind erreichbar, nicht nur das neueste Fenster.**

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

# Exakte Einzelnachricht per id (auch sehr alte, inkl. quoted_* + Dateien)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/history?id=9606"

# id-Fenster um eine Nachricht (±25) — z.B. fuer #id-Verweise
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/history?around_id=9606"

# Aeltere Seite: alles vor id N (absteigender Walk, has_more-Flag)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/history?before_id=9000&limit=200"

# Aufsteigender Catch-up ab id N (lueckenlos iterieren bis count < limit)
# since_id und after_id sind Aliase von since
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/history?since=8800&limit=200"

# Klassische Pagination vom neuesten Ende rueckwaerts (offset + next_offset)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/history?limit=200&offset=200"
```

Parameter: `limit` 1..500 (Default 50) · `id` · `around_id` · `before_id` ·
`since`/`since_id`/`after_id` · `offset` · `q` (Volltext) · `mine` · `mentions`
· `from`/`to` (Epoch-Sekunden). Antworten enthalten `count`, `has_more` und
`next_offset` (NULL = Ende).

#### files[]-Fenstersemantik (poll vs history)

`/chat/history` haengt `files[]` in ALLEN Zweigen an (`id`, `since`,
`around_id`, `before_id`, `offset`, `q`) — aber jeder Abruf deckt nur sein
EIGENES Fenster ab. Ein Fenster ohne Datei-Nachrichten liefert `files: []`,
waehrend `/chat/poll` 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: `GET /chat/history?id=N`
(live-verifiziert 2026-10-14 gegen die Nachrichten 10120/10187/10235/12952 —
poll und history `files[]` 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.

```bash
# Ungelesene Nachrichten vom Menschen zählen (für Agent)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/unread?role=agent"

# Ungelesene Nachrichten vom Agenten zählen (für Mensch)
curl -H "Authorization: Bearer YOUR_JWT" \
     "https://synapse.schaefer.zone/chat/unread?role=human"
```

### POST /chat/read

Nachrichten als gelesen deklarieren. **Mind-Key**: mind-scoped Konsum (Tabelle
`chat_read_status`) — analog zum /chat/poll. **JWT (Human)**: Legacy-Pfad
(`chat_messages.read_at`, Agent-Messages).

```bash
curl -X POST https://synapse.schaefer.zone/chat/read \
  -H "Authorization: Bearer MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"up_to": 12345}'
```

Antwort: `{ "status": "read", "marked": <Anzahl>, "scope": "mind", "mind_id": "..." }`
(beim Human-Pfad ohne `scope`/`mind_id`). Ohne `up_to`: alles bis zum aktuellen
Stand markieren.

### GET /chat/status

Chat-Session-Status abrufen (Zeitstempel der letzten Nachrichten, Unread-Counts).

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

### POST /chat/upload

Dateianhang für eine bestimmte Nachricht hochladen (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

Dateianhänge für eine Nachricht auflisten.

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

### GET /chat/file/:file_id

Einen Dateianhang herunterladen.

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

## Polling-Pattern

> [!TIP]
> Poll alle 30-60 Sekunden zwischen Tool-Aufrufen. Häufigeres Pollen
> verschwendet API-Kontingent und bringt nichts.

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

## Nächste Schritte

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