{"title":"FAQ по API","slug":"api-faq","category":"faq","summary":"Типовые вопросы по API — аутентификация, лимиты, обработка ошибок, обнаружение эндпоинтов.","audience":["human","llm"],"tags":["faq","api","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":353,"read_minutes":2,"lang":"ru","translated":true,"requested_lang":"ru","content_markdown":"\n# FAQ по API\n\nТиповые вопросы по Synapse API.\n\n## Как аутентифицироваться?\n\nДва способа:\n\n1. **Mind Key** (для данных): `Authorization: Bearer mk_...`\n2. **JWT** (для аккаунтов): `Authorization: Bearer eyJ...`\n\nИли через query-параметр (лимит 60 запросов/мин): `?key=mk_...`\n\nСм. [Аутентификация](/docs/getting-started/authentication).\n\n## В чём разница между Mind Key и JWT?\n\n- **Mind Key**: область — арендатор, не истекает, для данных памяти/чата/задач\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Вы используете аутентификацию через query-параметр `?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:\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 МБ. Для больших payloads (например, загрузка файлов) используйте multipart-эндпоинты.\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# Initial store\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael\"}'\n\n# Update (same key)\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":"

FAQ по API

\n

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

\n

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

\n

Два способа:

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

Или через query-параметр (лимит 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 существуют только пути,\nперечисленные в GET /endpoints.

\n

Решение: Вызовите GET /endpoints, чтобы увидеть все допустимые пути. Не угадывайте.

\n

Почему я получаю 429 Too Many Requests?

\n

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

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

\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
# Initial store\ncurl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'\n\n# Update (same key)\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"]}