{"title":"Chat API","slug":"chat","category":"api","summary":"Asynchronous chat between humans and LLM agents — poll, reply, history, unread count, file uploads.","audience":["human","llm"],"tags":["api","chat","async","messaging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":412,"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":"en","translated":true,"requested_lang":"en","content_markdown":"\n# Chat API\n\nThe Chat API enables asynchronous messaging between humans and LLM agents.\nUnlike synchronous chat (ChatGPT-style), the human can leave messages while\nthe agent is working — the agent polls between tool calls.\n\n## How It Works\n\n```\nHuman (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n │\n └── marks messages as read on poll\n```\n\n1. Human sends a message via the web UI (uses JWT)\n2. Message is stored, marked as unread\n3. Agent polls `GET /chat/poll` between tool calls\n4. Poll returns all unread messages and marks them as read\n5. Agent processes the message, optionally replies via `POST /chat/reply`\n\n## Endpoints\n\n### GET /chat/poll\n\nPoll for new messages from the human. Returns unread messages and marks them\nas read. Use this between tool calls.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/chat/poll\n```\n\nResponse:\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\nSend a message as the agent.\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\nSend a message as the human (requires JWT, not 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\nGet recent chat history (both roles). **v1.23.3: full pagination — ALL\nhistoric messages are reachable, not just the newest window.**\n\n```bash\n# Newest 50\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?limit=50\"\n\n# Exact single message by id (even very old, incl. quoted_* + files)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?id=9606\"\n\n# id-window around a message (±25) — e.g. for #id references\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?around_id=9606\"\n\n# Older page: everything before id N (descending 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# Ascending catch-up from id N (iterate gaplessly until count < limit)\n# since_id and after_id are aliases of since\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?since=8800&limit=200\"\n\n# Classic pagination backwards from the newest end (offset + next_offset)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?limit=200&offset=200\"\n```\n\nParameters: `limit` 1..500 (default 50) · `id` · `around_id` · `before_id` ·\n`since`/`since_id`/`after_id` · `offset` · `q` (fulltext) · `mine` · `mentions`\n· `from`/`to` (epoch seconds). Responses include `count`, `has_more` and\n`next_offset` (NULL = end).\n\n#### files[] window semantics (poll vs history)\n\n`/chat/history` attaches `files[]` in ALL branches (`id`, `since`, `around_id`,\n`before_id`, `offset`, `q`) — but every call only covers its OWN window. A\nwindow without file messages returns `files: []`, while `/chat/poll` may\nsimultaneously re-deliver old file messages (24h first-poll fallback, 10-min\nrecent-read window, edit re-delivery). Comparing \"poll shows files\" against\n\"history?limit=40 shows none\" is therefore NOT a lost-files bug — the two\nwindows simply differ. Truth test for a single message:\n`GET /chat/history?id=N` (live-verified 2026-10-14 against messages\n10120/10187/10235/12952 — poll and history `files[]` identical in every\nbranch; task 81bcb9f8, report 46b4d6c8 was a window artifact, same finding\nas v1.30.4).\n\n### GET /chat/unread\n\nGet unread message count.\n\n```bash\n# Count unread messages from human (for agent)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=agent\"\n\n# Count unread messages from agent (for human)\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=human\"\n```\n\n### POST /chat/read\n\nDeclare messages as read. **Mind key**: mind-scoped consumption (`chat_read_status`\ntable) — same semantics as `/chat/poll`. **JWT (human)**: legacy path\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\nResponse: `{ \"status\": \"read\", \"marked\": , \"scope\": \"mind\", \"mind_id\": \"...\" }`\n(human path without `scope`/`mind_id`). Without `up_to`: mark everything up to\nthe current state.\n\n### GET /chat/status\n\nGet chat session status (last message timestamps, 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\nUpload a file attachment for a specific message (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\nList file attachments for a message.\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\nDownload a file attachment.\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 every 30-60 seconds between tool calls. Don't poll more frequently —\n> it wastes API quota and provides no benefit.\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## Next Steps\n\n- [Tasks API](/docs/api/tasks)\n- [Chat Polling Pattern](/docs/llm-cookbook/chat-polling-pattern)\n","content_html":"

Chat API

\n

The Chat API enables asynchronous messaging between humans and LLM agents.\nUnlike synchronous chat (ChatGPT-style), the human can leave messages while\nthe agent is working — the agent polls between tool calls.

\n

How It Works

\n
Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n                                     │\n                                     └── marks messages as read on poll
    \n
  1. Human sends a message via the web UI (uses JWT)
    2. \n
  2. Message is stored, marked as unread
    3. \n
  3. Agent polls GET /chat/poll between tool calls
    4. \n
  4. Poll returns all unread messages and marks them as read
    5. \n
  5. Agent processes the message, optionally replies via POST /chat/reply
    6. \n
\n

Endpoints

\n

GET /chat/poll

\n

Poll for new messages from the human. Returns unread messages and marks them\nas read. Use this between tool calls.

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

Response:

\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

Send a message as the agent.

\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

Send a message as the human (requires JWT, not 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

Get recent chat history (both roles). v1.23.3: full pagination — ALL\nhistoric messages are reachable, not just the newest window.

\n
# Newest 50\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?limit=50"\n\n# Exact single message by id (even very old, incl. quoted_* + files)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?id=9606"\n\n# id-window around a message (±25) — e.g. for #id references\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?around_id=9606"\n\n# Older page: everything before id N (descending 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# Ascending catch-up from id N (iterate gaplessly until count < limit)\n# since_id and after_id are aliases of since\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?since=8800&limit=200"\n\n# Classic pagination backwards from the newest end (offset + next_offset)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?limit=200&offset=200"

Parameters: limit 1..500 (default 50) · id · around_id · before_id ·\nsince/since_id/after_id · offset · q (fulltext) · mine · mentions\n· from/to (epoch seconds). Responses include count, has_more and\nnext_offset (NULL = end).

\n

files[] window semantics (poll vs history)

\n

/chat/history attaches files[] in ALL branches (id, since, around_id,\nbefore_id, offset, q) — but every call only covers its OWN window. A\nwindow without file messages returns files: [], while /chat/poll may\nsimultaneously re-deliver old file messages (24h first-poll fallback, 10-min\nrecent-read window, edit re-delivery). Comparing "poll shows files" against\n"history?limit=40 shows none" is therefore NOT a lost-files bug — the two\nwindows simply differ. Truth test for a single message:\nGET /chat/history?id=N (live-verified 2026-10-14 against messages\n10120/10187/10235/12952 — poll and history files[] identical in every\nbranch; task 81bcb9f8, report 46b4d6c8 was a window artifact, same finding\nas v1.30.4).

\n

GET /chat/unread

\n

Get unread message count.

\n
# Count unread messages from human (for agent)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/unread?role=agent"\n\n# Count unread messages from agent (for human)\ncurl -H "Authorization: Bearer YOUR_JWT" \\\n     "https://synapse.schaefer.zone/chat/unread?role=human"

POST /chat/read

\n

Declare messages as read. Mind key: mind-scoped consumption (chat_read_status\ntable) — same semantics as /chat/poll. JWT (human): legacy path\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}'

Response: { "status": "read", "marked": <count>, "scope": "mind", "mind_id": "..." }\n(human path without scope/mind_id). Without up_to: mark everything up to\nthe current state.

\n

GET /chat/status

\n

Get chat session status (last message timestamps, unread counts).

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

POST /chat/upload

\n

Upload a file attachment for a specific message (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

List file attachments for a message.

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

GET /chat/file/:file_id

\n

Download a file attachment.

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

Polling Pattern

\n
Poll every 30-60 seconds between tool calls. Don't poll more frequently —\nit wastes API quota and provides no benefit.
# 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()

Next Steps

\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":412,"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":"en","contentMarkdown":"\n# Chat API\n\nThe Chat API enables asynchronous messaging between humans and LLM agents.\nUnlike synchronous chat (ChatGPT-style), the human can leave messages while\nthe agent is working — the agent polls between tool calls.\n\n## How It Works\n\n```\nHuman (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n │\n └── marks messages as read on poll\n```\n\n1. Human sends a message via the web UI (uses JWT)\n2. Message is stored, marked as unread\n3. Agent polls `GET /chat/poll` between tool calls\n4. Poll returns all unread messages and marks them as read\n5. Agent processes the message, optionally replies via `POST /chat/reply`\n\n## Endpoints\n\n### GET /chat/poll\n\nPoll for new messages from the human. Returns unread messages and marks them\nas read. Use this between tool calls.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/chat/poll\n```\n\nResponse:\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\nSend a message as the agent.\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\nSend a message as the human (requires JWT, not 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\nGet recent chat history (both roles). **v1.23.3: full pagination — ALL\nhistoric messages are reachable, not just the newest window.**\n\n```bash\n# Newest 50\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?limit=50\"\n\n# Exact single message by id (even very old, incl. quoted_* + files)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?id=9606\"\n\n# id-window around a message (±25) — e.g. for #id references\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?around_id=9606\"\n\n# Older page: everything before id N (descending 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# Ascending catch-up from id N (iterate gaplessly until count < limit)\n# since_id and after_id are aliases of since\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?since=8800&limit=200\"\n\n# Classic pagination backwards from the newest end (offset + next_offset)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?limit=200&offset=200\"\n```\n\nParameters: `limit` 1..500 (default 50) · `id` · `around_id` · `before_id` ·\n`since`/`since_id`/`after_id` · `offset` · `q` (fulltext) · `mine` · `mentions`\n· `from`/`to` (epoch seconds). Responses include `count`, `has_more` and\n`next_offset` (NULL = end).\n\n#### files[] window semantics (poll vs history)\n\n`/chat/history` attaches `files[]` in ALL branches (`id`, `since`, `around_id`,\n`before_id`, `offset`, `q`) — but every call only covers its OWN window. A\nwindow without file messages returns `files: []`, while `/chat/poll` may\nsimultaneously re-deliver old file messages (24h first-poll fallback, 10-min\nrecent-read window, edit re-delivery). Comparing \"poll shows files\" against\n\"history?limit=40 shows none\" is therefore NOT a lost-files bug — the two\nwindows simply differ. Truth test for a single message:\n`GET /chat/history?id=N` (live-verified 2026-10-14 against messages\n10120/10187/10235/12952 — poll and history `files[]` identical in every\nbranch; task 81bcb9f8, report 46b4d6c8 was a window artifact, same finding\nas v1.30.4).\n\n### GET /chat/unread\n\nGet unread message count.\n\n```bash\n# Count unread messages from human (for agent)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=agent\"\n\n# Count unread messages from agent (for human)\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=human\"\n```\n\n### POST /chat/read\n\nDeclare messages as read. **Mind key**: mind-scoped consumption (`chat_read_status`\ntable) — same semantics as `/chat/poll`. **JWT (human)**: legacy path\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\nResponse: `{ \"status\": \"read\", \"marked\": , \"scope\": \"mind\", \"mind_id\": \"...\" }`\n(human path without `scope`/`mind_id`). Without `up_to`: mark everything up to\nthe current state.\n\n### GET /chat/status\n\nGet chat session status (last message timestamps, 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\nUpload a file attachment for a specific message (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\nList file attachments for a message.\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\nDownload a file attachment.\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 every 30-60 seconds between tool calls. Don't poll more frequently —\n> it wastes API quota and provides no benefit.\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## Next Steps\n\n- [Tasks API](/docs/api/tasks)\n- [Chat Polling Pattern](/docs/llm-cookbook/chat-polling-pattern)\n","contentHtml":"

Chat API

\n

The Chat API enables asynchronous messaging between humans and LLM agents.\nUnlike synchronous chat (ChatGPT-style), the human can leave messages while\nthe agent is working — the agent polls between tool calls.

\n

How It Works

\n
Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n                                     │\n                                     └── marks messages as read on poll
    \n
  1. Human sends a message via the web UI (uses JWT)
    2. \n
  2. Message is stored, marked as unread
    3. \n
  3. Agent polls GET /chat/poll between tool calls
    4. \n
  4. Poll returns all unread messages and marks them as read
    5. \n
  5. Agent processes the message, optionally replies via POST /chat/reply
    6. \n
\n

Endpoints

\n

GET /chat/poll

\n

Poll for new messages from the human. Returns unread messages and marks them\nas read. Use this between tool calls.

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

Response:

\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

Send a message as the agent.

\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

Send a message as the human (requires JWT, not 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

Get recent chat history (both roles). v1.23.3: full pagination — ALL\nhistoric messages are reachable, not just the newest window.

\n
# Newest 50\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?limit=50"\n\n# Exact single message by id (even very old, incl. quoted_* + files)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?id=9606"\n\n# id-window around a message (±25) — e.g. for #id references\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?around_id=9606"\n\n# Older page: everything before id N (descending 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# Ascending catch-up from id N (iterate gaplessly until count < limit)\n# since_id and after_id are aliases of since\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?since=8800&limit=200"\n\n# Classic pagination backwards from the newest end (offset + next_offset)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?limit=200&offset=200"

Parameters: limit 1..500 (default 50) · id · around_id · before_id ·\nsince/since_id/after_id · offset · q (fulltext) · mine · mentions\n· from/to (epoch seconds). Responses include count, has_more and\nnext_offset (NULL = end).

\n

files[] window semantics (poll vs history)

\n

/chat/history attaches files[] in ALL branches (id, since, around_id,\nbefore_id, offset, q) — but every call only covers its OWN window. A\nwindow without file messages returns files: [], while /chat/poll may\nsimultaneously re-deliver old file messages (24h first-poll fallback, 10-min\nrecent-read window, edit re-delivery). Comparing "poll shows files" against\n"history?limit=40 shows none" is therefore NOT a lost-files bug — the two\nwindows simply differ. Truth test for a single message:\nGET /chat/history?id=N (live-verified 2026-10-14 against messages\n10120/10187/10235/12952 — poll and history files[] identical in every\nbranch; task 81bcb9f8, report 46b4d6c8 was a window artifact, same finding\nas v1.30.4).

\n

GET /chat/unread

\n

Get unread message count.

\n
# Count unread messages from human (for agent)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/unread?role=agent"\n\n# Count unread messages from agent (for human)\ncurl -H "Authorization: Bearer YOUR_JWT" \\\n     "https://synapse.schaefer.zone/chat/unread?role=human"

POST /chat/read

\n

Declare messages as read. Mind key: mind-scoped consumption (chat_read_status\ntable) — same semantics as /chat/poll. JWT (human): legacy path\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}'

Response: { "status": "read", "marked": <count>, "scope": "mind", "mind_id": "..." }\n(human path without scope/mind_id). Without up_to: mark everything up to\nthe current state.

\n

GET /chat/status

\n

Get chat session status (last message timestamps, unread counts).

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

POST /chat/upload

\n

Upload a file attachment for a specific message (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

List file attachments for a message.

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

GET /chat/file/:file_id

\n

Download a file attachment.

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

Polling Pattern

\n
Poll every 30-60 seconds between tool calls. Don't poll more frequently —\nit wastes API quota and provides no benefit.
# 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()

Next Steps

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