FAQ по API

Типовые вопросы по Synapse API.

Как аутентифицироваться?

Два способа:

1. Mind Key (для данных): Authorization: Bearer mk_...
2. JWT (для аккаунтов): Authorization: Bearer eyJ...

Или через query-параметр (лимит 60 запросов/мин): ?key=mk_...

См. Аутентификация.

В чём разница между Mind Key и JWT?

• Mind Key: область — арендатор, не истекает, для данных памяти/чата/задач
• 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?

Вы используете аутентификацию через query-параметр ?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:

• 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 МБ. Для больших payloads (например, загрузка файлов) используйте 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 — существующее воспоминание обновится, а не дублируется.

# Initial store
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'

# Update (same key)
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
• Ошибки и обработка ошибок
• Аутентификация