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.

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.

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.

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ń.

Jak wylistować wszystkie endpointy?

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:

{
  "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.

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.

Jak paginować?

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

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

Domyślny limit: 100. Maksymalny: 500.

Czy mogę filtrować wspomnienia po kategorii lub tagu?

Tak:

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 i Wyszukiwanie semantyczne.

Jak zaktualizować wspomnienie?

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

# 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?

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

Czy mogę usuwać masowo?

Tak:

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

Następne kroki

• Przegląd API
• Błędy i ich obsługa
• Autoryzacja