# API FAQ

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

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

Два методи:

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

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

Дивіться [Автентифікацію](/docs/getting-started/authentication).

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

- **Mind Key**: прив'язаний до mind-у, ніколи не закінчується, для даних memory/chat/tasks
- **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?

Ви використовуєте автентифікацію через параметр запиту `?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-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:

```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 МБ. Для більших корисних навантажень (напр. завантаження файлів) використовуйте
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
# Початкове збереження
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"}'
```

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

```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)