{"title":"FAQ API","slug":"api-faq","category":"faq","summary":"Częste pytania o API — autoryzacja, limity, obsługa błędów, wykrywanie endpointów.","audience":["human","llm"],"tags":["faq","api","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":361,"read_minutes":2,"lang":"pl","translated":true,"requested_lang":"pl","content_markdown":"\n# FAQ API\n\nCzęste pytania dotyczące API Synapse.\n\n## Jak się autoryzować?\n\nDwie metody:\n\n1. **Mind Key** (dla endpointów danych): `Authorization: Bearer mk_...`\n2. **JWT** (dla endpointów konta): `Authorization: Bearer eyJ...`\n\nLub przez parametr zapytania (limit 60 żądań/min): `?key=mk_...`\n\nPatrz [Autoryzacja](/docs/getting-started/authentication).\n\n## Jaka jest różnica między Mind Key a JWT?\n\n- **Mind Key**: zakres dzierżawcy, nigdy nie wygasa, do danych memory/chat/tasks\n- **JWT**: zakres użytkownika, wygasa po 7 dniach, do zarządzania kontem/umysłami\n\nPatrz [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt).\n\n## Dlaczego otrzymuję 401 Unauthorized?\n\nTypowe przyczyny:\n\n1. Brak nagłówka `Authorization`\n2. Nieprawidłowy Mind Key (zweryfikować, czy zaczyna się od `mk_`)\n3. Użycie JWT tam, gdzie wymagany jest Mind Key (lub odwrotnie)\n4. Mind Key został cofnięty\n\n**Rozwiązanie:** Zweryfikować token. Patrz [Autoryzacja](/docs/getting-started/authentication).\n\n## Dlaczego otrzymuję 404 Not Found?\n\nUżyto błędnej ścieżki endpointu. Synapse ma tylko ścieżki wymienione w\n`GET /endpoints`.\n\n**Rozwiązanie:** Wywołać `GET /endpoints`, aby zobaczyć wszystkie poprawne ścieżki.\nNie zgadywać.\n\n## Dlaczego otrzymuję 429 Too Many Requests?\n\nUżywana jest autoryzacja parametrem zapytania `?key=`, która ma limit 60/min.\n\n**Rozwiązanie:** Przełączyć się na nagłówek `Authorization: Bearer` (bez limitu).\n\nPatrz [Limity żądań](/docs/api/rate-limits).\n\n## Jak wylistować wszystkie endpointy?\n\n```bash\ncurl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text\n```\n\n## Jak znaleźć właściwy endpoint?\n\n1. Sprawdzić `GET /endpoints` dla listy czytelnej maszynowo\n2. Sprawdzić `GET /help` dla pełnej dokumentacji API\n3. Przeglądać `GET /docs` w systemie dokumentacji\n4. Użyć `GET /openapi.json` dla specyfikacji OpenAPI 3.0\n\n## Czy mogę użyć GET zamiast POST?\n\nNiektóre endpointy POST mają odpowiedniki GET dla narzędzi obsługujących tylko\nURL-e:\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\nSprawdzić `GET /endpoints`, aby zobaczyć dostępne warianty GET.\n\n## Jak obsługiwać błędy?\n\nWszystkie błędy zwracają 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\nPatrz [Błędy i ich obsługa](/docs/api/errors).\n\n## Jaki jest limit treści żądania?\n\n10 MB. Dla większych payloadów (np. przesyłanie plików) należy użyć endpointów\nmultipart.\n\n## Czy API obsługuje CORS?\n\nTak. Wszystkie endpointy zwracają:\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## Czy istnieje SDK?\n\nTak:\n\n- **Node.js**: `npm install synapse-memory-sdk`\n- **MCP**: `npx -y synapse-mcp-api@latest`\n\nSzczegóły w sekcji [Przegląd API](/docs/api/overview).\n\n## Jak paginować?\n\nUżyć `?limit=` i `?offset=`:\n\n```bash\ncurl \".../memory?limit=50&offset=100\"\n```\n\nDomyślny limit: 100. Maksymalny: 500.\n\n## Czy mogę filtrować wspomnienia po kategorii lub tagu?\n\nTak:\n\n```bash\ncurl \".../memory?category=project\"\ncurl \".../memory?tag=docker\"\ncurl \".../memory/by-tag?tag=production\"\n```\n\n## Jak wyszukiwać wspomnienia?\n\nDwa sposoby:\n\n1. **Wyszukiwanie słów kluczowych FTS5**: `GET /memory/search?q=docker+swarm`\n2. **Wyszukiwanie semantyczne**: `GET /memory/semantic-search?q=container+orchestration`\n\nPatrz [Wyszukiwanie FTS5](/docs/concepts/fts5-search) i [Wyszukiwanie semantyczne](/docs/concepts/semantic-search).\n\n## Jak zaktualizować wspomnienie?\n\nWykonać POST `/memory` z tym samym `category` + `key` — istniejące wspomnienie\njest aktualizowane, a nie duplikowane.\n\n```bash\n# Początkowy zapis\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael\"}'\n\n# Aktualizacja (ten sam klucz)\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael Schäfer\"}'\n```\n\n## Jak usunąć wspomnienie?\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer $KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## Czy mogę usuwać masowo?\n\nTak:\n\n```bash\ncurl -X POST .../memory/bulk-delete \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n## Następne kroki\n\n- [Przegląd API](/docs/api/overview)\n- [Błędy i ich obsługa](/docs/api/errors)\n- [Autoryzacja](/docs/getting-started/authentication)\n","content_html":"

FAQ API

\n

Częste pytania dotyczące API Synapse.

\n

Jak się autoryzować?

\n

Dwie metody:

\n
    \n
  1. Mind Key (dla endpointów danych): Authorization: Bearer mk_...
    2. \n
  2. JWT (dla endpointów konta): Authorization: Bearer eyJ...
    3. \n
\n

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

\n

Patrz Autoryzacja.

\n

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

\n\n

Patrz Mind Key vs JWT.

\n

Dlaczego otrzymuję 401 Unauthorized?

\n

Typowe przyczyny:

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

Rozwiązanie: Zweryfikować token. Patrz Autoryzacja.

\n

Dlaczego otrzymuję 404 Not Found?

\n

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

\n

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

\n

Dlaczego otrzymuję 429 Too Many Requests?

\n

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

\n

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

\n

Patrz Limity żądań.

\n

Jak wylistować wszystkie endpointy?

\n
curl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text

Jak znaleźć właściwy endpoint?

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

Czy mogę użyć GET zamiast POST?

\n

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

\n\n

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

\n

Jak obsługiwać błędy?

\n

Wszystkie błędy zwracają 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}

Patrz Błędy i ich obsługa.

\n

Jaki jest limit treści żądania?

\n

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

\n

Czy API obsługuje CORS?

\n

Tak. Wszystkie endpointy zwracają:

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

Czy istnieje SDK?

\n

Tak:

\n\n

Szczegóły w sekcji Przegląd API.

\n

Jak paginować?

\n

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

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

Domyślny limit: 100. Maksymalny: 500.

\n

Czy mogę filtrować wspomnienia po kategorii lub tagu?

\n

Tak:

\n
curl ".../memory?category=project"\ncurl ".../memory?tag=docker"\ncurl ".../memory/by-tag?tag=production"

Jak wyszukiwać wspomnienia?

\n

Dwa sposoby:

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

Patrz Wyszukiwanie FTS5 i Wyszukiwanie semantyczne.

\n

Jak zaktualizować wspomnienie?

\n

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

\n
# Początkowy zapis\ncurl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'\n\n# Aktualizacja (ten sam klucz)\ncurl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael Schäfer"}'

Jak usunąć wspomnienie?

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

Czy mogę usuwać masowo?

\n

Tak:

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

Następne kroki

\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"]}