{"title":"API FAQ","slug":"api-faq","category":"faq","summary":"Поширені питання про API — автентифікація, обмеження частоти, обробка помилок, виявлення кінцевих точок.","audience":["human","llm"],"tags":["faq","api","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":367,"read_minutes":2,"lang":"uk","translated":true,"requested_lang":"uk","content_markdown":"\n# API FAQ\n\nПоширені запитання щодо API Synapse.\n\n## Як автентифікуватися?\n\nДва методи:\n\n1. **Mind Key** (для кінцевих точок даних): `Authorization: Bearer mk_...`\n2. **JWT** (для кінцевих точок облікового запису): `Authorization: Bearer eyJ...`\n\nАбо через параметр запиту (ліміт 60 запитів/хв): `?key=mk_...`\n\nДивіться [Автентифікацію](/docs/getting-started/authentication).\n\n## У чому різниця між Mind Key та JWT?\n\n- **Mind Key**: прив'язаний до mind-у, ніколи не закінчується, для даних memory/chat/tasks\n- **JWT**: прив'язаний до користувача, термін дії 7 днів, для керування обліковим записом/mind-ами\n\nДивіться [Mind Key проти JWT](/docs/getting-started/mind-key-vs-jwt).\n\n## Чому я отримую 401 Unauthorized?\n\nПоширені причини:\n\n1. Відсутній заголовок `Authorization`\n2. Недійсний Mind Key (перевірте, що починається з `mk_`)\n3. Використання JWT там, де потрібен Mind Key (або навпаки)\n4. Mind Key відкликано\n\n**Виправлення:** Перевірте ваш токен. Дивіться [Автентифікацію](/docs/getting-started/authentication).\n\n## Чому я отримую 404 Not Found?\n\nВи використали неправильний шлях кінцевої точки. У Synapse є лише шляхи зі списку\n`GET /endpoints`.\n\n**Виправлення:** Викличте `GET /endpoints`, щоб побачити всі дійсні шляхи. Не вгадуйте.\n\n## Чому я отримую 429 Too Many Requests?\n\nВи використовуєте автентифікацію через параметр запиту `?key=`, що обмежена до 60/хв.\n\n**Виправлення:** Перейдіть на заголовок `Authorization: Bearer` (без обмеження).\n\nДивіться [Обмеження частоти](/docs/api/rate-limits).\n\n## Як вивести список усіх кінцевих точок?\n\n```bash\ncurl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text\n```\n\n## Як знайти потрібну кінцеву точку?\n\n1. Перевірте `GET /endpoints` для машиночитного списку\n2. Перевірте `GET /help` для повної документації API\n3. Перегляньте `GET /docs` для системи документації\n4. Використовуйте `GET /openapi.json` для специфікації OpenAPI 3.0\n\n## Чи можна використовувати GET замість POST?\n\nДеякі POST-кінцеві точки мають GET-аналоги для URL-only інструментів:\n\n- `POST /memory` ↔ `GET /memory/store?content=...`\n- `POST /mind/task` ↔ `GET /mind/task?title=...`\n- `POST /chat/reply` ↔ `GET /chat/reply?content=...`\n\nПеревірте `GET /endpoints` для доступних GET-варіантів.\n\n## Як обробляти помилки?\n\nУсі помилки повертають JSON:\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Дивіться [Помилки та обробка помилок](/docs/api/errors).\n\n## Який ліміт розміру тіла запиту?\n\n10 МБ. Для більших корисних навантажень (напр. завантаження файлів) використовуйте\nmultipart-кінцеві точки.\n\n## Чи підтримує API CORS?\n\nТак. Усі кінцеві точки повертають:\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\n```\n\n## Чи є SDK?\n\nТак:\n\n- **Node.js**: `npm install synapse-memory-sdk`\n- **MCP**: `npx -y synapse-mcp-api@latest`\n\nДивіться [Огляд API](/docs/api/overview) для деталей.\n\n## Як робити пагінацію?\n\nВикористовуйте `?limit=` та `?offset=`:\n\n```bash\ncurl \".../memory?limit=50&offset=100\"\n```\n\nЛіміт за замовчуванням: 100. Макс: 500.\n\n## Чи можна фільтрувати спогади за категорією або тегом?\n\nТак:\n\n```bash\ncurl \".../memory?category=project\"\ncurl \".../memory?tag=docker\"\ncurl \".../memory/by-tag?tag=production\"\n```\n\n## Як шукати спогади?\n\nДвома способами:\n\n1. **Пошук ключових слів FTS5**: `GET /memory/search?q=docker+swarm`\n2. **Семантичний пошук**: `GET /memory/semantic-search?q=container+orchestration`\n\nДивіться [Пошук FTS5](/docs/concepts/fts5-search) та [Семантичний пошук](/docs/concepts/semantic-search).\n\n## Як оновити спогад?\n\nPOST `/memory` з тією ж `category` + `key` — наявний спогад оновлюється, а не\nдублюється.\n\n```bash\n# Початкове збереження\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael\"}'\n\n# Оновлення (той самий ключ)\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael Schäfer\"}'\n```\n\n## Як видалити спогад?\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer $KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## Чи можна масово видаляти?\n\nТак:\n\n```bash\ncurl -X POST .../memory/bulk-delete \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n## Наступні кроки\n\n- [Огляд API](/docs/api/overview)\n- [Помилки та обробка помилок](/docs/api/errors)\n- [Автентифікація](/docs/getting-started/authentication)\n","content_html":"

API FAQ

\n

Поширені запитання щодо API Synapse.

\n

Як автентифікуватися?

\n

Два методи:

\n
    \n
  1. Mind Key (для кінцевих точок даних): Authorization: Bearer mk_...
    2. \n
  2. JWT (для кінцевих точок облікового запису): Authorization: Bearer eyJ...
    3. \n
\n

Або через параметр запиту (ліміт 60 запитів/хв): ?key=mk_...

\n

Дивіться Автентифікацію.

\n

У чому різниця між Mind Key та JWT?

\n\n

Дивіться Mind Key проти JWT.

\n

Чому я отримую 401 Unauthorized?

\n

Поширені причини:

\n
    \n
  1. Відсутній заголовок Authorization
    2. \n
  2. Недійсний Mind Key (перевірте, що починається з mk_)
    3. \n
  3. Використання JWT там, де потрібен Mind Key (або навпаки)
    4. \n
  4. Mind Key відкликано
    5. \n
\n

Виправлення: Перевірте ваш токен. Дивіться Автентифікацію.

\n

Чому я отримую 404 Not Found?

\n

Ви використали неправильний шлях кінцевої точки. У Synapse є лише шляхи зі списку\nGET /endpoints.

\n

Виправлення: Викличте GET /endpoints, щоб побачити всі дійсні шляхи. Не вгадуйте.

\n

Чому я отримую 429 Too Many Requests?

\n

Ви використовуєте автентифікацію через параметр запиту ?key=, що обмежена до 60/хв.

\n

Виправлення: Перейдіть на заголовок Authorization: Bearer (без обмеження).

\n

Дивіться Обмеження частоти.

\n

Як вивести список усіх кінцевих точок?

\n
curl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text

Як знайти потрібну кінцеву точку?

\n
    \n
  1. Перевірте GET /endpoints для машиночитного списку
    2. \n
  2. Перевірте GET /help для повної документації API
    3. \n
  3. Перегляньте GET /docs для системи документації
    4. \n
  4. Використовуйте GET /openapi.json для специфікації OpenAPI 3.0
    5. \n
\n

Чи можна використовувати GET замість POST?

\n

Деякі POST-кінцеві точки мають GET-аналоги для URL-only інструментів:

\n\n

Перевірте GET /endpoints для доступних GET-варіантів.

\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

10 МБ. Для більших корисних навантажень (напр. завантаження файлів) використовуйте\nmultipart-кінцеві точки.

\n

Чи підтримує API CORS?

\n

Так. Усі кінцеві точки повертають:

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

Чи є SDK?

\n

Так:

\n\n

Дивіться Огляд API для деталей.

\n

Як робити пагінацію?

\n

Використовуйте ?limit= та ?offset=:

\n
curl ".../memory?limit=50&offset=100"

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

\n

Чи можна фільтрувати спогади за категорією або тегом?

\n

Так:

\n
curl ".../memory?category=project"\ncurl ".../memory?tag=docker"\ncurl ".../memory/by-tag?tag=production"

Як шукати спогади?

\n

Двома способами:

\n
    \n
  1. Пошук ключових слів FTS5: GET /memory/search?q=docker+swarm
    2. \n
  2. Семантичний пошук: GET /memory/semantic-search?q=container+orchestration
    3. \n
\n

Дивіться Пошук FTS5 та Семантичний пошук.

\n

Як оновити спогад?

\n

POST /memory з тією ж category + key — наявний спогад оновлюється, а не\nдублюється.

\n
# Початкове збереження\ncurl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'\n\n# Оновлення (той самий ключ)\ncurl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael Schäfer"}'

Як видалити спогад?

\n
curl -X DELETE -H "Authorization: Bearer $KEY" \\\n     https://synapse.schaefer.zone/memory/mem_001

Чи можна масово видаляти?

\n

Так:

\n
curl -X POST .../memory/bulk-delete \\\n  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'

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

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