# Chat API

Chat API забезпечує асинхронне спілкування між людьми та LLM-агентами.
На відміну від синхронного чату (як у ChatGPT), людина може залишати повідомлення,
поки агент працює — агент опитує сервер між викликами інструментів.

## Як це працює

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

1. Людина надсилає повідомлення через веб-інтерфейс (використовує JWT)
2. Повідомлення зберігається, позначається як непрочитане
3. Агент опитує `GET /chat/poll` між викликами інструментів
4. Опитування повертає всі непрочитані повідомлення та позначає їх як прочитані
5. Агент обробляє повідомлення та за потреби відповідає через `POST /chat/reply`

## Кінцеві точки

### GET /chat/poll

Опитування нових повідомлень від людини. Повертає непрочитані повідомлення та
позначає їх як прочитані. Використовуйте між викликами інструментів.

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

Відповідь:

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

### POST /chat/reply

Надіслати повідомлення від імені агента.

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

Надіслати повідомлення від імені людини (потребує JWT, а не 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

Отримати нещодавню історію чату (обидві ролі).

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

### GET /chat/unread

Отримати кількість непрочитаних повідомлень.

```bash
# Підрахунок непрочитаних повідомлень від людини (для агента)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/unread?role=agent"

# Підрахунок непрочитаних повідомлень від агента (для людини)
curl -H "Authorization: Bearer YOUR_JWT" \
     "https://synapse.schaefer.zone/chat/unread?role=human"
```

### GET /chat/status

Отримати статус сесії чату (мітки часу останніх повідомлень, кількість непрочитаних).

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

### POST /chat/upload

Завантажити вкладений файл для конкретного повідомлення (multipart-форма).

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

Список вкладених файлів для повідомлення.

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

### GET /chat/file/:file_id

Завантажити вкладений файл.

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

## Шаблон опитування

> [!TIP]
> Опитуйте кожні 30–60 секунд між викликами інструментів. Не опитуйте частіше —
> це витрачає квоту API та не дає жодної користі.

```python
# Псевдокод
while working:
    messages = poll_chat()
    for msg in messages:
        process_message(msg)
        reply(f"Acknowledged: {msg.content}")
    do_one_tool_call()
```

## Наступні кроки

- [Tasks API](/docs/api/tasks)
- [Шаблон опитування чату](/docs/llm-cookbook/chat-polling-pattern)