{"title":"Огляд API та базовий URL","slug":"overview","category":"api","summary":"Усі кінцеві точки API Synapse, базовий URL, шаблони автентифікації та формати відповідей у стислому вигляді.","audience":["human","llm"],"tags":["api","overview","endpoints"],"difficulty":"beginner","updated":"2026-06-27","word_count":553,"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":"uk","translated":true,"requested_lang":"uk","content_markdown":"\n# Огляд API та базовий URL\n\nAPI Synapse — це RESTful HTTP API. Усі кінцеві точки повертають JSON (окрім\nвипадків, де зазначено інше). Ця сторінка охоплює основи, які потрібно знати\nперед вивченням конкретних кінцевих точок.\n\n## Базовий URL\n\n```\nhttps://synapse.schaefer.zone\n```\n\nУсі шляхи у цій документації вказуються відносно цього базового URL. Для\nвласних інсталяцій замініть на ваш URL.\n\n## Автентифікація\n\nДва методи, обидва передаються через заголовок `Authorization`:\n\n```\nAuthorization: Bearer YOUR_MIND_KEY # для кінцевих точок даних\nAuthorization: Bearer YOUR_JWT # для кінцевих точок облікового запису\n```\n\nАбо через параметр запиту (з обмеженням частоти 60/хв):\n\n```\n?key=YOUR_MIND_KEY\n```\n\nДокладніше дивіться у [Автентифікації](/docs/getting-started/authentication).\n\n## Групи кінцевих точок\n\n| Група | Автентифікація | Опис |\n|-------|------|-------------|\n| Public | Немає | Головна сторінка, перевірка стану, 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` | Інтерактивний 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 (лише при 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 Server**: `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

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

\n

Базовий URL

\n
https://synapse.schaefer.zone

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

\n

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

\n

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

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

Або через параметр запиту (з обмеженням частоти 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НемаєГоловна сторінка, перевірка стану, OpenAPI, документація
MemoryMind KeyCRUD, пошук, синхронізація, ембеддинги
ChatMind Key / JWTАсинхронне спілкування між людиною та агентом
TasksMind KeyКерування завданнями
ScriptsMind Key / JWTПостійне сховище скриптів
SchedulerMind KeyCron-завдання + змінні
WebhooksMind KeyHTTP-зворотні виклики подій
ComputersMind Key / JWTВіддалене керування комп'ютерами
User/MindsJWTОбліковий запис + керування mind-ами
SharingJWTСпільний доступ до mind-ів між користувачами
PushJWTПідписки Web 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Інтерактивний 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  (лише при 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"]}