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

beginner 🤖 LLM-дружелюбно 3 мин · 536 слов Обновлено: 2026-06-27 Русский

Все эндпоинты Synapse API, базовый URL, паттерны аутентификации и форматы ответов — кратко в одном месте.

Читать эту статью как: 📄 Простой текст ⚡ JSON 🤖 LLM-формат

Обзор 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

Подробнее см. Аутентификация.

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

Группа	Аутентификация	Описание
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

Стандартная обёртка ответа

Успешные ответы возвращают данные напрямую:

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

Ответы с ошибкой используют следующий формат:

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

Поле `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 (репозиторий)
MCP-сервер: npx -y synapse-mcp-api@latest (репозиторий)
HTTP-клиент: любая HTTP-библиотека (curl, fetch, axios и т. д.)

Следующие шаги

Memory API — самые важные эндпоинты
Chat API — асинхронное общение человека и агента
Ошибки и обработка ошибок