# FAQ API

Częste pytania dotyczące API Synapse.

## Jak się autoryzować?

Dwie metody:

1. **Mind Key** (dla endpointów danych): `Authorization: Bearer mk_...`
2. **JWT** (dla endpointów konta): `Authorization: Bearer eyJ...`

Lub przez parametr zapytania (limit 60 żądań/min): `?key=mk_...`

Patrz [Autoryzacja](/docs/getting-started/authentication).

## Jaka jest różnica między Mind Key a JWT?

- **Mind Key**: zakres dzierżawcy, nigdy nie wygasa, do danych memory/chat/tasks
- **JWT**: zakres użytkownika, wygasa po 7 dniach, do zarządzania kontem/umysłami

Patrz [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt).

## Dlaczego otrzymuję 401 Unauthorized?

Typowe przyczyny:

1. Brak nagłówka `Authorization`
2. Nieprawidłowy Mind Key (zweryfikować, czy zaczyna się od `mk_`)
3. Użycie JWT tam, gdzie wymagany jest Mind Key (lub odwrotnie)
4. Mind Key został cofnięty

**Rozwiązanie:** Zweryfikować token. Patrz [Autoryzacja](/docs/getting-started/authentication).

## Dlaczego otrzymuję 404 Not Found?

Użyto błędnej ścieżki endpointu. Synapse ma tylko ścieżki wymienione w
`GET /endpoints`.

**Rozwiązanie:** Wywołać `GET /endpoints`, aby zobaczyć wszystkie poprawne ścieżki.
Nie zgadywać.

## Dlaczego otrzymuję 429 Too Many Requests?

Używana jest autoryzacja parametrem zapytania `?key=`, która ma limit 60/min.

**Rozwiązanie:** Przełączyć się na nagłówek `Authorization: Bearer` (bez limitu).

Patrz [Limity żądań](/docs/api/rate-limits).

## Jak wylistować wszystkie endpointy?

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

## Jak znaleźć właściwy endpoint?

1. Sprawdzić `GET /endpoints` dla listy czytelnej maszynowo
2. Sprawdzić `GET /help` dla pełnej dokumentacji API
3. Przeglądać `GET /docs` w systemie dokumentacji
4. Użyć `GET /openapi.json` dla specyfikacji OpenAPI 3.0

## Czy mogę użyć GET zamiast POST?

Niektóre endpointy POST mają odpowiedniki GET dla narzędzi obsługujących tylko
URL-e:

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

Sprawdzić `GET /endpoints`, aby zobaczyć dostępne warianty GET.

## Jak obsługiwać błędy?

Wszystkie błędy zwracają JSON:

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

Patrz [Błędy i ich obsługa](/docs/api/errors).

## Jaki jest limit treści żądania?

10 MB. Dla większych payloadów (np. przesyłanie plików) należy użyć endpointów
multipart.

## Czy API obsługuje CORS?

Tak. Wszystkie endpointy zwracają:

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

## Czy istnieje SDK?

Tak:

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

Szczegóły w sekcji [Przegląd API](/docs/api/overview).

## Jak paginować?

Użyć `?limit=` i `?offset=`:

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

Domyślny limit: 100. Maksymalny: 500.

## Czy mogę filtrować wspomnienia po kategorii lub tagu?

Tak:

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

## Jak wyszukiwać wspomnienia?

Dwa sposoby:

1. **Wyszukiwanie słów kluczowych FTS5**: `GET /memory/search?q=docker+swarm`
2. **Wyszukiwanie semantyczne**: `GET /memory/semantic-search?q=container+orchestration`

Patrz [Wyszukiwanie FTS5](/docs/concepts/fts5-search) i [Wyszukiwanie semantyczne](/docs/concepts/semantic-search).

## Jak zaktualizować wspomnienie?

Wykonać POST `/memory` z tym samym `category` + `key` — istniejące wspomnienie
jest aktualizowane, a nie duplikowane.

```bash
# Początkowy zapis
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'

# Aktualizacja (ten sam klucz)
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael Schäfer"}'
```

## Jak usunąć wspomnienie?

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

## Czy mogę usuwać masowo?

Tak:

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

## Następne kroki

- [Przegląd API](/docs/api/overview)
- [Błędy i ich obsługa](/docs/api/errors)
- [Autoryzacja](/docs/getting-started/authentication)