# Обзор API и базовый URL

Synapse API — это RESTful HTTP API. Все эндпоинты возвращают JSON (кроме
отмеченных случаев). На этой странице описано всё необходимое перед переходом
к конкретным эндпоинтам.

## Базовый URL

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

Все пути в этой документации указаны относительно этого базового URL. Для
self-hosted экземпляров замените на ваш собственный URL.

## Аутентификация

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

```
Authorization: Bearer YOUR_MIND_KEY    # for data endpoints
Authorization: Bearer YOUR_JWT          # for account endpoints
```

Или через query-параметр (с лимитом 60 запросов в минуту):

```
?key=YOUR_MIND_KEY
```

Подробнее см. [Аутентификация](/docs/getting-started/authentication).

## Группы эндпоинтов

| Группа | Аутентификация | Описание |
|-------|------|-------------|
| Public | Нет | Главная страница, health, 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` | Интерактивная песочница API |

## Лимиты запросов

| Способ аутентификации | Лимит |
|-------------|-------|
| Mind Key (заголовок) | Нет |
| Mind Key (?key=) | 60/мин на IP |
| JWT (заголовок) | Нет |
| Публичные эндпоинты | Нет |

Ответы с лимитом включают:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (only when 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-сервер**: `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)