# Огляд API та базовий URL

API Synapse — це RESTful HTTP API. Усі кінцеві точки повертають JSON (окрім
випадків, де зазначено інше). Ця сторінка охоплює основи, які потрібно знати
перед вивченням конкретних кінцевих точок.

## Базовий URL

```
https://synapse.schaefer.zone
```

Усі шляхи у цій документації вказуються відносно цього базового URL. Для
власних інсталяцій замініть на ваш URL.

## Автентифікація

Два методи, обидва передаються через заголовок `Authorization`:

```
Authorization: Bearer YOUR_MIND_KEY    # для кінцевих точок даних
Authorization: Bearer YOUR_JWT          # для кінцевих точок облікового запису
```

Або через параметр запиту (з обмеженням частоти 60/хв):

```
?key=YOUR_MIND_KEY
```

Докладніше дивіться у [Автентифікації](/docs/getting-started/authentication).

## Групи кінцевих точок

| Група | Автентифікація | Опис |
|-------|------|-------------|
| Public | Немає | Головна сторінка, перевірка стану, OpenAPI, документація |
| Memory | Mind Key | CRUD, пошук, синхронізація, ембеддинги |
| Chat | Mind Key / JWT | Асинхронне спілкування між людиною та агентом |
| Tasks | Mind Key | Керування завданнями |
| Scripts | Mind Key / JWT | Постійне сховище скриптів |
| Scheduler | Mind Key | Cron-завдання + змінні |
| Webhooks | Mind Key | HTTP-зворотні виклики подій |
| Computers | Mind Key / JWT | Віддалене керування комп'ютерами |
| User/Minds | JWT | Обліковий запис + керування mind-ами |
| Sharing | JWT | Спільний доступ до mind-ів між користувачами |
| Push | JWT | Підписки Web Push |
| Tools | Немає | Час, калькулятор, випадкові значення (публічні утиліти) |

## Формати відповідей

- **JSON** (за замовчуванням): `{ "key": "value", ... }`
- **Звичайний текст**: `/memory/recall` повертає текст, оптимізований для LLM
- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`

## Стандартна обгортка відповіді

Успішні відповіді повертають дані безпосередньо:

```json
{ "id": "mem_001", "status": "stored" }
```

Відповіді з помилками використовують такий формат:

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}
```

> [!NOTE]
> Поле `docs` містить посилання на відповідну документацію для поширених помилок.

## Коди стану HTTP

| Код | Значення |
|------|---------|
| 200 | Успіх (GET, PUT) |
| 201 | Створено (POST) |
| 204 | Немає вмісту (DELETE) |
| 400 | Некоректний запит (помилка валідації) |
| 401 | Не автентифіковано (відсутній/недійсний токен) |
| 403 | Заборонено (неправильний тип токена) |
| 404 | Не знайдено (шлях не існує) |
| 409 | Конфлікт (дублікат) |
| 429 | Забагато запитів (обмеження частоти) |
| 500 | Помилка сервера |

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

| Кінцева точка | Призначення |
|----------|---------|
| `GET /` | Головна сторінка (оптимізована для LLM) |
| `GET /endpoints` | Машиночитний список усіх кінцевих точок |
| `GET /endpoints?format=text` | Список кінцевих точок у вигляді звичайного тексту |
| `GET /openapi.json` | Специфікація OpenAPI 3.0 |
| `GET /help` | Повна документація API (HTML) |
| `GET /help?format=json` | Документація API у форматі JSON |
| `GET /docs` | Система документації (HTML) |
| `GET /docs?format=json` | Індекс документації (JSON) |
| `GET /docs?format=text&scope=all` | Уся документація одним текстовим блоком |
| `GET /playground` | Інтерактивний playground API |

## Обмеження частоти

| Метод автентифікації | Ліміт |
|-------------|-------|
| Mind Key (заголовок) | Немає |
| Mind Key (?key=) | 60/хв на IP |
| JWT (заголовок) | Немає |
| Публічні кінцеві точки | Немає |

Відповіді з обмеженням частоти містять:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (лише при 429)
```

## Пагінація

Кінцеві точки списків підтримують `?limit=` та `?offset=`:

```
GET /memory?limit=50&offset=100
GET /mind/tasks?status=pending
```

Ліміт за замовчуванням: 100. Максимальний ліміт: 500.

## CORS

Усі кінцеві точки підтримують CORS для браузерних клієнтів:

```
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT, Mcp-Session-Id, Mcp-Tool-Profile
```

## SDK та клієнти

- **Node.js SDK**: `npm install synapse-memory-sdk` ([репозиторій](https://gitlab.com/schaefer-services/synapse-sdk-js))
- **MCP Server**: `npx -y synapse-mcp-api@latest` ([репозиторій](https://gitlab.com/schaefer-services/synapse-mcp))
- **HTTP-клієнт**: будь-яка HTTP-бібліотека (curl, fetch, axios тощо)

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

- [Memory API](/docs/api/memory) — найважливіші кінцеві точки
- [Chat API](/docs/api/chat) — асинхронне спілкування людина-агент
- [Помилки та обробка помилок](/docs/api/errors)