{"title":"Chat-API","slug":"chat","category":"api","summary":"Asynchroner Chat zwischen Menschen und LLM-Agenten — Polling, Antworten, Verlauf, Unread-Count, Datei-Uploads.","audience":["human","llm"],"tags":["api","chat","async","messaging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":371,"read_minutes":2,"llm_context":"Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)\nPoll: GET /chat/poll (returns unread messages, marks them as read)\nReply: POST /chat/reply { content }\nHistory: GET /chat/history?limit=50\nUnread count: GET /chat/unread?role=agent (or ?role=human)\nUpload: POST /chat/upload (multipart, file attachment)\nPattern: poll between tool calls, reply when human asks questions\n","lang":"de","translated":true,"requested_lang":"de","content_markdown":"\n# Chat-API\n\nDie Chat-API ermöglicht asynchrones Messaging zwischen Menschen und LLM-Agenten.\nIm Gegensatz zu synchronem Chat (ChatGPT-Stil) kann der Mensch Nachrichten\nhinterlassen, während der Agent arbeitet — der Agent fragt zwischen Tool-Aufrufen\nab.\n\n## Funktionsweise\n\n```\nHuman (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n │\n └── marks messages as read on poll\n```\n\n1. Mensch sendet eine Nachricht über die Web-UI (verwendet JWT)\n2. Nachricht wird gespeichert und als ungelesen markiert\n3. Agent fragt `GET /chat/poll` zwischen Tool-Aufrufen ab\n4. Poll liefert alle ungelesenen Nachrichten und markiert sie als gelesen\n5. Agent verarbeitet die Nachricht und antwortet optional via `POST /chat/reply`\n\n## Endpunkte\n\n### GET /chat/poll\n\nNeue Nachrichten vom Menschen abfragen. Liefert ungelesene Nachrichten und\nmarkiert sie als gelesen. Verwende dies zwischen Tool-Aufrufen.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/chat/poll\n```\n\nAntwort:\n\n```json\n{\n \"messages\": [\n {\n \"id\": \"msg_001\",\n \"role\": \"human\",\n \"content\": \"How's the deployment going?\",\n \"created_at\": \"2026-06-27T...\"\n }\n ]\n}\n```\n\n### POST /chat/reply\n\nEine Nachricht als Agent senden.\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/reply \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Deployment is 80% done. CI is green, just waiting for Docker push.\"}'\n```\n\n### POST /chat/send\n\nEine Nachricht als Mensch senden (erfordert JWT, nicht Mind Key).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/send \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Can you check the logs?\"}'\n```\n\n### GET /chat/history\n\nLetzten Chat-Verlauf abrufen (beide Rollen). **v1.23.3: Voll-Pagination —\nALLE historischen Nachrichten sind erreichbar, nicht nur das neueste Fenster.**\n\n```bash\n# Neueste 50\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?limit=50\"\n\n# Exakte Einzelnachricht per id (auch sehr alte, inkl. quoted_* + Dateien)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?id=9606\"\n\n# id-Fenster um eine Nachricht (±25) — z.B. fuer #id-Verweise\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?around_id=9606\"\n\n# Aeltere Seite: alles vor id N (absteigender Walk, has_more-Flag)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?before_id=9000&limit=200\"\n\n# Aufsteigender Catch-up ab id N (lueckenlos iterieren bis count < limit)\n# since_id und after_id sind Aliase von since\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?since=8800&limit=200\"\n\n# Klassische Pagination vom neuesten Ende rueckwaerts (offset + next_offset)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?limit=200&offset=200\"\n```\n\nParameter: `limit` 1..500 (Default 50) · `id` · `around_id` · `before_id` ·\n`since`/`since_id`/`after_id` · `offset` · `q` (Volltext) · `mine` · `mentions`\n· `from`/`to` (Epoch-Sekunden). Antworten enthalten `count`, `has_more` und\n`next_offset` (NULL = Ende).\n\n#### files[]-Fenstersemantik (poll vs history)\n\n`/chat/history` haengt `files[]` in ALLEN Zweigen an (`id`, `since`,\n`around_id`, `before_id`, `offset`, `q`) — aber jeder Abruf deckt nur sein\nEIGENES Fenster ab. Ein Fenster ohne Datei-Nachrichten liefert `files: []`,\nwaehrend `/chat/poll` gleichzeitig alte Datei-Nachrichten neu ausliefern kann\n(24h-Erstpoll-Fallback, 10-Min-recent-read-Fenster, Edit-Re-Delivery). Der\nVergleich \"poll zeigt files\" gegen \"history?limit=40 zeigt keine\" ist daher\nKEIN files[]-Verlust-Bug — die beiden Fenster unterscheiden sich schlicht.\nWahrheitstest fuer eine einzelne Nachricht: `GET /chat/history?id=N`\n(live-verifiziert 2026-10-14 gegen die Nachrichten 10120/10187/10235/12952 —\npoll und history `files[]` in jedem Zweig identisch; Task 81bcb9f8, Meldung\n46b4d6c8 war ein Fenster-Artefakt, gleicher Befund wie v1.30.4).\n\n### GET /chat/unread\n\nAnzahl ungelesener Nachrichten abrufen.\n\n```bash\n# Ungelesene Nachrichten vom Menschen zählen (für Agent)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=agent\"\n\n# Ungelesene Nachrichten vom Agenten zählen (für Mensch)\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=human\"\n```\n\n### POST /chat/read\n\nNachrichten als gelesen deklarieren. **Mind-Key**: mind-scoped Konsum (Tabelle\n`chat_read_status`) — analog zum /chat/poll. **JWT (Human)**: Legacy-Pfad\n(`chat_messages.read_at`, Agent-Messages).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/read \\\n -H \"Authorization: Bearer MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"up_to\": 12345}'\n```\n\nAntwort: `{ \"status\": \"read\", \"marked\": , \"scope\": \"mind\", \"mind_id\": \"...\" }`\n(beim Human-Pfad ohne `scope`/`mind_id`). Ohne `up_to`: alles bis zum aktuellen\nStand markieren.\n\n### GET /chat/status\n\nChat-Session-Status abrufen (Zeitstempel der letzten Nachrichten, Unread-Counts).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/chat/status\n```\n\n### POST /chat/upload\n\nDateianhang für eine bestimmte Nachricht hochladen (Multipart-Form).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/upload \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -F \"message_id=msg_001\" \\\n -F \"file=@screenshot.png\"\n```\n\n### GET /chat/files/:message_id\n\nDateianhänge für eine Nachricht auflisten.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/chat/files/msg_001\n```\n\n### GET /chat/file/:file_id\n\nEinen Dateianhang herunterladen.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/chat/file/file_001 --output download.png\n```\n\n## Polling-Pattern\n\n> [!TIP]\n> Poll alle 30-60 Sekunden zwischen Tool-Aufrufen. Häufigeres Pollen\n> verschwendet API-Kontingent und bringt nichts.\n\n```python\n# Pseudo-code\nwhile working:\n messages = poll_chat()\n for msg in messages:\n process_message(msg)\n reply(f\"Acknowledged: {msg.content}\")\n do_one_tool_call()\n```\n\n## Nächste Schritte\n\n- [Tasks-API](/docs/api/tasks)\n- [Chat-Polling-Pattern](/docs/llm-cookbook/chat-polling-pattern)\n","content_html":"

Chat-API

\n

Die Chat-API ermöglicht asynchrones Messaging zwischen Menschen und LLM-Agenten.\nIm Gegensatz zu synchronem Chat (ChatGPT-Stil) kann der Mensch Nachrichten\nhinterlassen, während der Agent arbeitet — der Agent fragt zwischen Tool-Aufrufen\nab.

\n

Funktionsweise

\n
Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n                                     │\n                                     └── marks messages as read on poll
    \n
  1. Mensch sendet eine Nachricht über die Web-UI (verwendet JWT)
    2. \n
  2. Nachricht wird gespeichert und als ungelesen markiert
    3. \n
  3. Agent fragt GET /chat/poll zwischen Tool-Aufrufen ab
    4. \n
  4. Poll liefert alle ungelesenen Nachrichten und markiert sie als gelesen
    5. \n
  5. Agent verarbeitet die Nachricht und antwortet optional via POST /chat/reply
    6. \n
\n

Endpunkte

\n

GET /chat/poll

\n

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

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

Antwort:

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

POST /chat/reply

\n

Eine Nachricht als Agent senden.

\n
curl -X POST https://synapse.schaefer.zone/chat/reply \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"content": "Deployment is 80% done. CI is green, just waiting for Docker push."}'

POST /chat/send

\n

Eine Nachricht als Mensch senden (erfordert JWT, nicht Mind Key).

\n
curl -X POST https://synapse.schaefer.zone/chat/send \\\n  -H "Authorization: Bearer YOUR_JWT" \\\n  -H "Content-Type: application/json" \\\n  -d '{"content": "Can you check the logs?"}'

GET /chat/history

\n

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

\n
# Neueste 50\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?limit=50"\n\n# Exakte Einzelnachricht per id (auch sehr alte, inkl. quoted_* + Dateien)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?id=9606"\n\n# id-Fenster um eine Nachricht (±25) — z.B. fuer #id-Verweise\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?around_id=9606"\n\n# Aeltere Seite: alles vor id N (absteigender Walk, has_more-Flag)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?before_id=9000&limit=200"\n\n# Aufsteigender Catch-up ab id N (lueckenlos iterieren bis count < limit)\n# since_id und after_id sind Aliase von since\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?since=8800&limit=200"\n\n# Klassische Pagination vom neuesten Ende rueckwaerts (offset + next_offset)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?limit=200&offset=200"

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

\n

files[]-Fenstersemantik (poll vs history)

\n

/chat/history haengt files[] in ALLEN Zweigen an (id, since,\naround_id, before_id, offset, q) — aber jeder Abruf deckt nur sein\nEIGENES Fenster ab. Ein Fenster ohne Datei-Nachrichten liefert files: [],\nwaehrend /chat/poll gleichzeitig alte Datei-Nachrichten neu ausliefern kann\n(24h-Erstpoll-Fallback, 10-Min-recent-read-Fenster, Edit-Re-Delivery). Der\nVergleich "poll zeigt files" gegen "history?limit=40 zeigt keine" ist daher\nKEIN files[]-Verlust-Bug — die beiden Fenster unterscheiden sich schlicht.\nWahrheitstest fuer eine einzelne Nachricht: GET /chat/history?id=N\n(live-verifiziert 2026-10-14 gegen die Nachrichten 10120/10187/10235/12952 —\npoll und history files[] in jedem Zweig identisch; Task 81bcb9f8, Meldung\n46b4d6c8 war ein Fenster-Artefakt, gleicher Befund wie v1.30.4).

\n

GET /chat/unread

\n

Anzahl ungelesener Nachrichten abrufen.

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

POST /chat/read

\n

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

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

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

\n

GET /chat/status

\n

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

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

POST /chat/upload

\n

Dateianhang für eine bestimmte Nachricht hochladen (Multipart-Form).

\n
curl -X POST https://synapse.schaefer.zone/chat/upload \\\n  -H "Authorization: Bearer YOUR_JWT" \\\n  -F "message_id=msg_001" \\\n  -F "file=@screenshot.png"

GET /chat/files/:message_id

\n

Dateianhänge für eine Nachricht auflisten.

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

GET /chat/file/:file_id

\n

Einen Dateianhang herunterladen.

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

Polling-Pattern

\n
Poll alle 30-60 Sekunden zwischen Tool-Aufrufen. Häufigeres Pollen\nverschwendet API-Kontingent und bringt nichts.
# Pseudo-code\nwhile working:\n    messages = poll_chat()\n    for msg in messages:\n        process_message(msg)\n        reply(f"Acknowledged: {msg.content}")\n    do_one_tool_call()

Nächste Schritte

\n\n","urls":{"html":"/docs/api/chat","text":"/docs/api/chat?format=text","json":"/docs/api/chat?format=json","llm":"/docs/api/chat?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"],"wordCount":371,"readMinutes":2,"llmContext":"Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)\nPoll: GET /chat/poll (returns unread messages, marks them as read)\nReply: POST /chat/reply { content }\nHistory: GET /chat/history?limit=50\nUnread count: GET /chat/unread?role=agent (or ?role=human)\nUpload: POST /chat/upload (multipart, file attachment)\nPattern: poll between tool calls, reply when human asks questions\n","requestedLang":"de","contentMarkdown":"\n# Chat-API\n\nDie Chat-API ermöglicht asynchrones Messaging zwischen Menschen und LLM-Agenten.\nIm Gegensatz zu synchronem Chat (ChatGPT-Stil) kann der Mensch Nachrichten\nhinterlassen, während der Agent arbeitet — der Agent fragt zwischen Tool-Aufrufen\nab.\n\n## Funktionsweise\n\n```\nHuman (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n │\n └── marks messages as read on poll\n```\n\n1. Mensch sendet eine Nachricht über die Web-UI (verwendet JWT)\n2. Nachricht wird gespeichert und als ungelesen markiert\n3. Agent fragt `GET /chat/poll` zwischen Tool-Aufrufen ab\n4. Poll liefert alle ungelesenen Nachrichten und markiert sie als gelesen\n5. Agent verarbeitet die Nachricht und antwortet optional via `POST /chat/reply`\n\n## Endpunkte\n\n### GET /chat/poll\n\nNeue Nachrichten vom Menschen abfragen. Liefert ungelesene Nachrichten und\nmarkiert sie als gelesen. Verwende dies zwischen Tool-Aufrufen.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/chat/poll\n```\n\nAntwort:\n\n```json\n{\n \"messages\": [\n {\n \"id\": \"msg_001\",\n \"role\": \"human\",\n \"content\": \"How's the deployment going?\",\n \"created_at\": \"2026-06-27T...\"\n }\n ]\n}\n```\n\n### POST /chat/reply\n\nEine Nachricht als Agent senden.\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/reply \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Deployment is 80% done. CI is green, just waiting for Docker push.\"}'\n```\n\n### POST /chat/send\n\nEine Nachricht als Mensch senden (erfordert JWT, nicht Mind Key).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/send \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Can you check the logs?\"}'\n```\n\n### GET /chat/history\n\nLetzten Chat-Verlauf abrufen (beide Rollen). **v1.23.3: Voll-Pagination —\nALLE historischen Nachrichten sind erreichbar, nicht nur das neueste Fenster.**\n\n```bash\n# Neueste 50\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?limit=50\"\n\n# Exakte Einzelnachricht per id (auch sehr alte, inkl. quoted_* + Dateien)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?id=9606\"\n\n# id-Fenster um eine Nachricht (±25) — z.B. fuer #id-Verweise\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?around_id=9606\"\n\n# Aeltere Seite: alles vor id N (absteigender Walk, has_more-Flag)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?before_id=9000&limit=200\"\n\n# Aufsteigender Catch-up ab id N (lueckenlos iterieren bis count < limit)\n# since_id und after_id sind Aliase von since\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?since=8800&limit=200\"\n\n# Klassische Pagination vom neuesten Ende rueckwaerts (offset + next_offset)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?limit=200&offset=200\"\n```\n\nParameter: `limit` 1..500 (Default 50) · `id` · `around_id` · `before_id` ·\n`since`/`since_id`/`after_id` · `offset` · `q` (Volltext) · `mine` · `mentions`\n· `from`/`to` (Epoch-Sekunden). Antworten enthalten `count`, `has_more` und\n`next_offset` (NULL = Ende).\n\n#### files[]-Fenstersemantik (poll vs history)\n\n`/chat/history` haengt `files[]` in ALLEN Zweigen an (`id`, `since`,\n`around_id`, `before_id`, `offset`, `q`) — aber jeder Abruf deckt nur sein\nEIGENES Fenster ab. Ein Fenster ohne Datei-Nachrichten liefert `files: []`,\nwaehrend `/chat/poll` gleichzeitig alte Datei-Nachrichten neu ausliefern kann\n(24h-Erstpoll-Fallback, 10-Min-recent-read-Fenster, Edit-Re-Delivery). Der\nVergleich \"poll zeigt files\" gegen \"history?limit=40 zeigt keine\" ist daher\nKEIN files[]-Verlust-Bug — die beiden Fenster unterscheiden sich schlicht.\nWahrheitstest fuer eine einzelne Nachricht: `GET /chat/history?id=N`\n(live-verifiziert 2026-10-14 gegen die Nachrichten 10120/10187/10235/12952 —\npoll und history `files[]` in jedem Zweig identisch; Task 81bcb9f8, Meldung\n46b4d6c8 war ein Fenster-Artefakt, gleicher Befund wie v1.30.4).\n\n### GET /chat/unread\n\nAnzahl ungelesener Nachrichten abrufen.\n\n```bash\n# Ungelesene Nachrichten vom Menschen zählen (für Agent)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=agent\"\n\n# Ungelesene Nachrichten vom Agenten zählen (für Mensch)\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=human\"\n```\n\n### POST /chat/read\n\nNachrichten als gelesen deklarieren. **Mind-Key**: mind-scoped Konsum (Tabelle\n`chat_read_status`) — analog zum /chat/poll. **JWT (Human)**: Legacy-Pfad\n(`chat_messages.read_at`, Agent-Messages).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/read \\\n -H \"Authorization: Bearer MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"up_to\": 12345}'\n```\n\nAntwort: `{ \"status\": \"read\", \"marked\": , \"scope\": \"mind\", \"mind_id\": \"...\" }`\n(beim Human-Pfad ohne `scope`/`mind_id`). Ohne `up_to`: alles bis zum aktuellen\nStand markieren.\n\n### GET /chat/status\n\nChat-Session-Status abrufen (Zeitstempel der letzten Nachrichten, Unread-Counts).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/chat/status\n```\n\n### POST /chat/upload\n\nDateianhang für eine bestimmte Nachricht hochladen (Multipart-Form).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/upload \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -F \"message_id=msg_001\" \\\n -F \"file=@screenshot.png\"\n```\n\n### GET /chat/files/:message_id\n\nDateianhänge für eine Nachricht auflisten.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/chat/files/msg_001\n```\n\n### GET /chat/file/:file_id\n\nEinen Dateianhang herunterladen.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/chat/file/file_001 --output download.png\n```\n\n## Polling-Pattern\n\n> [!TIP]\n> Poll alle 30-60 Sekunden zwischen Tool-Aufrufen. Häufigeres Pollen\n> verschwendet API-Kontingent und bringt nichts.\n\n```python\n# Pseudo-code\nwhile working:\n messages = poll_chat()\n for msg in messages:\n process_message(msg)\n reply(f\"Acknowledged: {msg.content}\")\n do_one_tool_call()\n```\n\n## Nächste Schritte\n\n- [Tasks-API](/docs/api/tasks)\n- [Chat-Polling-Pattern](/docs/llm-cookbook/chat-polling-pattern)\n","contentHtml":"

Chat-API

\n

Die Chat-API ermöglicht asynchrones Messaging zwischen Menschen und LLM-Agenten.\nIm Gegensatz zu synchronem Chat (ChatGPT-Stil) kann der Mensch Nachrichten\nhinterlassen, während der Agent arbeitet — der Agent fragt zwischen Tool-Aufrufen\nab.

\n

Funktionsweise

\n
Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n                                     │\n                                     └── marks messages as read on poll
    \n
  1. Mensch sendet eine Nachricht über die Web-UI (verwendet JWT)
    2. \n
  2. Nachricht wird gespeichert und als ungelesen markiert
    3. \n
  3. Agent fragt GET /chat/poll zwischen Tool-Aufrufen ab
    4. \n
  4. Poll liefert alle ungelesenen Nachrichten und markiert sie als gelesen
    5. \n
  5. Agent verarbeitet die Nachricht und antwortet optional via POST /chat/reply
    6. \n
\n

Endpunkte

\n

GET /chat/poll

\n

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

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

Antwort:

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

POST /chat/reply

\n

Eine Nachricht als Agent senden.

\n
curl -X POST https://synapse.schaefer.zone/chat/reply \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"content": "Deployment is 80% done. CI is green, just waiting for Docker push."}'

POST /chat/send

\n

Eine Nachricht als Mensch senden (erfordert JWT, nicht Mind Key).

\n
curl -X POST https://synapse.schaefer.zone/chat/send \\\n  -H "Authorization: Bearer YOUR_JWT" \\\n  -H "Content-Type: application/json" \\\n  -d '{"content": "Can you check the logs?"}'

GET /chat/history

\n

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

\n
# Neueste 50\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?limit=50"\n\n# Exakte Einzelnachricht per id (auch sehr alte, inkl. quoted_* + Dateien)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?id=9606"\n\n# id-Fenster um eine Nachricht (±25) — z.B. fuer #id-Verweise\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?around_id=9606"\n\n# Aeltere Seite: alles vor id N (absteigender Walk, has_more-Flag)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?before_id=9000&limit=200"\n\n# Aufsteigender Catch-up ab id N (lueckenlos iterieren bis count < limit)\n# since_id und after_id sind Aliase von since\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?since=8800&limit=200"\n\n# Klassische Pagination vom neuesten Ende rueckwaerts (offset + next_offset)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?limit=200&offset=200"

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

\n

files[]-Fenstersemantik (poll vs history)

\n

/chat/history haengt files[] in ALLEN Zweigen an (id, since,\naround_id, before_id, offset, q) — aber jeder Abruf deckt nur sein\nEIGENES Fenster ab. Ein Fenster ohne Datei-Nachrichten liefert files: [],\nwaehrend /chat/poll gleichzeitig alte Datei-Nachrichten neu ausliefern kann\n(24h-Erstpoll-Fallback, 10-Min-recent-read-Fenster, Edit-Re-Delivery). Der\nVergleich "poll zeigt files" gegen "history?limit=40 zeigt keine" ist daher\nKEIN files[]-Verlust-Bug — die beiden Fenster unterscheiden sich schlicht.\nWahrheitstest fuer eine einzelne Nachricht: GET /chat/history?id=N\n(live-verifiziert 2026-10-14 gegen die Nachrichten 10120/10187/10235/12952 —\npoll und history files[] in jedem Zweig identisch; Task 81bcb9f8, Meldung\n46b4d6c8 war ein Fenster-Artefakt, gleicher Befund wie v1.30.4).

\n

GET /chat/unread

\n

Anzahl ungelesener Nachrichten abrufen.

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

POST /chat/read

\n

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

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

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

\n

GET /chat/status

\n

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

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

POST /chat/upload

\n

Dateianhang für eine bestimmte Nachricht hochladen (Multipart-Form).

\n
curl -X POST https://synapse.schaefer.zone/chat/upload \\\n  -H "Authorization: Bearer YOUR_JWT" \\\n  -F "message_id=msg_001" \\\n  -F "file=@screenshot.png"

GET /chat/files/:message_id

\n

Dateianhänge für eine Nachricht auflisten.

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

GET /chat/file/:file_id

\n

Einen Dateianhang herunterladen.

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

Polling-Pattern

\n
Poll alle 30-60 Sekunden zwischen Tool-Aufrufen. Häufigeres Pollen\nverschwendet API-Kontingent und bringt nichts.
# Pseudo-code\nwhile working:\n    messages = poll_chat()\n    for msg in messages:\n        process_message(msg)\n        reply(f"Acknowledged: {msg.content}")\n    do_one_tool_call()

Nächste Schritte

\n\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}