API FAQ

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

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

Два методи:

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

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

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

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

• Mind Key: прив'язаний до mind-у, ніколи не закінчується, для даних memory/chat/tasks
• JWT: прив'язаний до користувача, термін дії 7 днів, для керування обліковим записом/mind-ами

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• POST /memory ↔ GET /memory/store?content=...
• POST /mind/task ↔ GET /mind/task?title=...
• POST /chat/reply ↔ GET /chat/reply?content=...

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

Як обробляти помилки?

Усі помилки повертають JSON:

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

Дивіться Помилки та обробка помилок.

Який ліміт розміру тіла запиту?

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

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

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

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

Чи є SDK?

Так:

• Node.js: npm install synapse-memory-sdk
• MCP: npx -y synapse-mcp-api@latest

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

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

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

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

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

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

Так:

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

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

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

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

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

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

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

# Початкове збереження
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'

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

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

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

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

Так:

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

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

• Огляд API
• Помилки та обробка помилок
• Автентифікація