# FAQ по API

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

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

Два способа:

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

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

См. [Аутентификация](/docs/getting-started/authentication).

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

- **Mind Key**: область — арендатор, не истекает, для данных памяти/чата/задач
- **JWT**: область — пользователь, истекает через 7 дней, для управления аккаунтом/mind

См. [Mind Key против JWT](/docs/getting-started/mind-key-vs-jwt).

## Почему я получаю 401 Unauthorized?

Типичные причины:

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

**Решение:** Проверьте ваш токен. См. [Аутентификация](/docs/getting-started/authentication).

## Почему я получаю 404 Not Found?

Вы использовали неверный путь эндпоинта. В Synapse существуют только пути,
перечисленные в `GET /endpoints`.

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

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

Вы используете аутентификацию через query-параметр `?key=`, лимит — 60 запросов/мин.

**Решение:** Перейдите на заголовок `Authorization: Bearer` (без лимита).

См. [Лимиты запросов](/docs/api/rate-limits).

## Как получить список всех эндпоинтов?

```bash
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:

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

См. [Ошибки и обработка ошибок](/docs/api/errors).

## Какой лимит размера тела запроса?

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](/docs/api/overview).

## Как использовать пагинацию?

Используйте `?limit=` и `?offset=`:

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

Лимит по умолчанию: 100. Максимум: 500.

## Можно ли фильтровать воспоминания по категории или тегу?

Да:

```bash
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-поиск](/docs/concepts/fts5-search) и [Семантический поиск](/docs/concepts/semantic-search).

## Как обновить воспоминание?

POST `/memory` с теми же `category` + `key` — существующее воспоминание
обновится, а не дублируется.

```bash
# 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"}'
```

## Как удалить воспоминание?

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

## Можно ли удалять массово?

Да:

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

## Следующие шаги

- [Обзор API](/docs/api/overview)
- [Ошибки и обработка ошибок](/docs/api/errors)
- [Аутентификация](/docs/getting-started/authentication)