{"title":"Обзор API и базовый URL","slug":"overview","category":"api","summary":"Все эндпоинты Synapse API, базовый URL, паттерны аутентификации и форматы ответов — кратко в одном месте.","audience":["human","llm"],"tags":["api","overview","endpoints"],"difficulty":"beginner","updated":"2026-06-27","word_count":536,"read_minutes":3,"llm_context":"Base URL: https://synapse.schaefer.zone\nAuth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)\n OR ?key=YOUR_MIND_KEY (query, 60 req/min)\nAll responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)\nAll 404 responses mean the path does not exist — do NOT guess paths.\nGET /endpoints returns machine-readable list of all valid endpoints.\n","lang":"ru","translated":true,"requested_lang":"ru","content_markdown":"\n# Обзор API и базовый URL\n\nSynapse API — это RESTful HTTP API. Все эндпоинты возвращают JSON (кроме\nотмеченных случаев). На этой странице описано всё необходимое перед переходом\nк конкретным эндпоинтам.\n\n## Базовый URL\n\n```\nhttps://synapse.schaefer.zone\n```\n\nВсе пути в этой документации указаны относительно этого базового URL. Для\nself-hosted экземпляров замените на ваш собственный URL.\n\n## Аутентификация\n\nДва способа, оба передаются через заголовок `Authorization`:\n\n```\nAuthorization: Bearer YOUR_MIND_KEY # for data endpoints\nAuthorization: Bearer YOUR_JWT # for account endpoints\n```\n\nИли через query-параметр (с лимитом 60 запросов в минуту):\n\n```\n?key=YOUR_MIND_KEY\n```\n\nПодробнее см. [Аутентификация](/docs/getting-started/authentication).\n\n## Группы эндпоинтов\n\n| Группа | Аутентификация | Описание |\n|-------|------|-------------|\n| Public | Нет | Главная страница, health, OpenAPI, документация |\n| Memory | Mind Key | CRUD, поиск, синхронизация, эмбеддинги |\n| Chat | Mind Key / JWT | Асинхронные сообщения между человеком и агентом |\n| Tasks | Mind Key | Управление задачами |\n| Scripts | Mind Key / JWT | Постоянное хранилище скриптов |\n| Scheduler | Mind Key | Cron-задачи + переменные |\n| Webhooks | Mind Key | HTTP-колбэки на события |\n| Computers | Mind Key / JWT | Удалённое управление компьютерами |\n| User/Minds | JWT | Аккаунт + управление mind |\n| Sharing | JWT | Совместное использование mind между пользователями |\n| Push | JWT | Web Push-подписки |\n| Tools | Нет | Время, калькулятор, случайные числа (публичные утилиты) |\n\n## Форматы ответов\n\n- **JSON** (по умолчанию): `{ \"key\": \"value\", ... }`\n- **Простой текст**: `/memory/recall` возвращает текст, оптимизированный для LLM\n- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`\n\n## Стандартная обёртка ответа\n\nУспешные ответы возвращают данные напрямую:\n\n```json\n{ \"id\": \"mem_001\", \"status\": \"stored\" }\n```\n\nОтветы с ошибкой используют следующий формат:\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\n> [!NOTE]\n> Поле `docs` содержит ссылку на соответствующую документацию для типичных ошибок.\n\n## HTTP-коды состояния\n\n| Код | Значение |\n|------|---------|\n| 200 | Успех (GET, PUT) |\n| 201 | Создано (POST) |\n| 204 | Нет содержимого (DELETE) |\n| 400 | Некорректный запрос (ошибка валидации) |\n| 401 | Не авторизован (отсутствует/неверный токен) |\n| 403 | Доступ запрещён (неверный тип токена) |\n| 404 | Не найдено (путь не существует) |\n| 409 | Конфликт (дубликат) |\n| 429 | Слишком много запросов (лимит) |\n| 500 | Ошибка сервера |\n\n## Эндпоинты обнаружения\n\n| Эндпоинт | Назначение |\n|----------|---------|\n| `GET /` | Главная страница (оптимизирована для LLM) |\n| `GET /endpoints` | Машиночитаемый список всех эндпоинтов |\n| `GET /endpoints?format=text` | Список эндпоинтов простым текстом |\n| `GET /openapi.json` | Спецификация OpenAPI 3.0 |\n| `GET /help` | Полная документация API (HTML) |\n| `GET /help?format=json` | Документация API в JSON |\n| `GET /docs` | Система документации (HTML) |\n| `GET /docs?format=json` | Индекс документации (JSON) |\n| `GET /docs?format=text&scope=all` | Вся документация одним текстовым блоком |\n| `GET /playground` | Интерактивная песочница API |\n\n## Лимиты запросов\n\n| Способ аутентификации | Лимит |\n|-------------|-------|\n| Mind Key (заголовок) | Нет |\n| Mind Key (?key=) | 60/мин на IP |\n| JWT (заголовок) | Нет |\n| Публичные эндпоинты | Нет |\n\nОтветы с лимитом включают:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30 (only when 429)\n```\n\n## Пагинация\n\nСписочные эндпоинты поддерживают `?limit=` и `?offset=`:\n\n```\nGET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending\n```\n\nЛимит по умолчанию: 100. Максимальный лимит: 500.\n\n## CORS\n\nВсе эндпоинты поддерживают CORS для браузерных клиентов:\n\n```\nAccess-Control-Allow-Origin: *\nAccess-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS\nAccess-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT, Mcp-Session-Id, Mcp-Tool-Profile\n```\n\n## SDK и клиенты\n\n- **Node.js SDK**: `npm install synapse-memory-sdk` ([репозиторий](https://gitlab.com/schaefer-services/synapse-sdk-js))\n- **MCP-сервер**: `npx -y synapse-mcp-api@latest` ([репозиторий](https://gitlab.com/schaefer-services/synapse-mcp))\n- **HTTP-клиент**: любая HTTP-библиотека (curl, fetch, axios и т. д.)\n\n## Следующие шаги\n\n- [Memory API](/docs/api/memory) — самые важные эндпоинты\n- [Chat API](/docs/api/chat) — асинхронное общение человека и агента\n- [Ошибки и обработка ошибок](/docs/api/errors)\n","content_html":"

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

\n

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

\n

Базовый URL

\n
https://synapse.schaefer.zone

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

\n

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

\n

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

\n
Authorization: Bearer YOUR_MIND_KEY    # for data endpoints\nAuthorization: Bearer YOUR_JWT          # for account endpoints

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

\n
?key=YOUR_MIND_KEY

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

\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ГруппаАутентификацияОписание
PublicНетГлавная страница, health, OpenAPI, документация
MemoryMind KeyCRUD, поиск, синхронизация, эмбеддинги
ChatMind Key / JWTАсинхронные сообщения между человеком и агентом
TasksMind KeyУправление задачами
ScriptsMind Key / JWTПостоянное хранилище скриптов
SchedulerMind KeyCron-задачи + переменные
WebhooksMind KeyHTTP-колбэки на события
ComputersMind Key / JWTУдалённое управление компьютерами
User/MindsJWTАккаунт + управление mind
SharingJWTСовместное использование mind между пользователями
PushJWTWeb Push-подписки
ToolsНетВремя, калькулятор, случайные числа (публичные утилиты)
\n

Форматы ответов

\n\n

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

\n

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

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

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

\n
{\n  "statusCode": 401,\n  "error": "Unauthorized",\n  "message": "Mind Key fehlt oder ungültig.",\n  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"\n}
Поле `docs` содержит ссылку на соответствующую документацию для типичных ошибок.

HTTP-коды состояния

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
КодЗначение
200Успех (GET, PUT)
201Создано (POST)
204Нет содержимого (DELETE)
400Некорректный запрос (ошибка валидации)
401Не авторизован (отсутствует/неверный токен)
403Доступ запрещён (неверный тип токена)
404Не найдено (путь не существует)
409Конфликт (дубликат)
429Слишком много запросов (лимит)
500Ошибка сервера
\n

Эндпоинты обнаружения

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ЭндпоинтНазначение
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
\n

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

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

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

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30  (only when 429)

Пагинация

\n

Списочные эндпоинты поддерживают ?limit= и ?offset=:

\n
GET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending

Лимит по умолчанию: 100. Максимальный лимит: 500.

\n

CORS

\n

Все эндпоинты поддерживают CORS для браузерных клиентов:

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

SDK и клиенты

\n\n

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

\n\n","urls":{"html":"/docs/api/overview","text":"/docs/api/overview?format=text","json":"/docs/api/overview?format=json","llm":"/docs/api/overview?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}