{"title":"Przegląd API i bazowy URL","slug":"overview","category":"api","summary":"Wszystkie endpointy API Synapse, bazowy URL, wzorce autoryzacji i formaty odpowiedzi w jednym miejscu.","audience":["human","llm"],"tags":["api","overview","endpoints"],"difficulty":"beginner","updated":"2026-06-27","word_count":544,"read_minutes":3,"llm_context":"Base URL: https://synapse.schaefer.zone\nAuth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)\n OR ?key=YOUR_MIND_KEY (query, 60 req/min)\nAll responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)\nAll 404 responses mean the path does not exist — do NOT guess paths.\nGET /endpoints returns machine-readable list of all valid endpoints.\n","lang":"pl","translated":true,"requested_lang":"pl","content_markdown":"\n# Przegląd API i bazowy URL\n\nAPI Synapse jest RESTfulowym interfejsem HTTP. Wszystkie endpointy zwracają JSON\n(z wyjątkiem miejsc, w których zaznaczono inaczej). Niniejsza strona zawiera\npodstawowe informacje potrzebne przed przejściem do szczegółowych endpointów.\n\n## Bazowy URL\n\n```\nhttps://synapse.schaefer.zone\n```\n\nWszystkie ścieżki w niniejszej dokumentacji są względne wobec tego bazowego URL-a.\nW przypadku instancji self-hosted należy użyć własnego adresu URL.\n\n## Autoryzacja\n\nDwie metody, obie wysyłane nagłówkiem `Authorization`:\n\n```\nAuthorization: Bearer YOUR_MIND_KEY # dla endpointów danych\nAuthorization: Bearer YOUR_JWT # dla endpointów konta\n```\n\nLub przez parametr zapytania (ograniczony do 60/min):\n\n```\n?key=YOUR_MIND_KEY\n```\n\nSzczegóły znajdują się w sekcji [Autoryzacja](/docs/getting-started/authentication).\n\n## Grupy endpointów\n\n| Grupa | Autoryzacja | Opis |\n|-------|-------------|------|\n| Publiczne | Brak | Strona główna, health, OpenAPI, dokumentacja |\n| Memory | Mind Key | CRUD, wyszukiwanie, synchronizacja, osadzenia |\n| Chat | Mind Key / JWT | Asynchroniczne wiadomości między człowiekiem a agentem |\n| Tasks | Mind Key | Zarządzanie zadaniami |\n| Scripts | Mind Key / JWT | Trwały magazyn skryptów |\n| Scheduler | Mind Key | Zadania cron i zmienne |\n| Webhooks | Mind Key | Wywołania zwrotne HTTP przy zdarzeniach |\n| Computers | Mind Key / JWT | Zdalne sterowanie komputerami |\n| User/Minds | JWT | Konto i zarządzanie umysłami |\n| Sharing | JWT | Współdzielenie umysłów między użytkownikami |\n| Push | JWT | Subskrypcje Web Push |\n| Tools | Brak | Czas, kalkulator, losowość (narzędzia publiczne) |\n\n## Formaty odpowiedzi\n\n- **JSON** (domyślnie): `{ \"key\": \"value\", ... }`\n- **Zwykły tekst**: `/memory/recall` zwraca tekst zoptymalizowany dla LLM\n- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`\n\n## Standardowa koperta odpowiedzi\n\nOdpowiedzi pomyślne zwracają dane bezpośrednio:\n\n```json\n{ \"id\": \"mem_001\", \"status\": \"stored\" }\n```\n\nOdpowiedzi błędne używają następującego formatu:\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\n> [!NOTE]\n> Pole `docs` zawiera link do dokumentacji istotnej dla częstych błędów.\n\n## Kody stanu HTTP\n\n| Kod | Znaczenie |\n|------|-----------|\n| 200 | Sukces (GET, PUT) |\n| 201 | Utworzono (POST) |\n| 204 | Brak treści (DELETE) |\n| 400 | Nieprawidłowe żądanie (błąd walidacji) |\n| 401 | Brak autoryzacji (brak/nieprawidłowy token) |\n| 403 | Zabronione (nieprawidłowy typ tokena) |\n| 404 | Nie znaleziono (ścieżka nie istnieje) |\n| 409 | Konflikt (duplikat) |\n| 429 | Zbyt wiele żądań (limit) |\n| 500 | Błąd serwera |\n\n## Endpointy wykrywalności\n\n| Endpoint | Przeznaczenie |\n|----------|---------------|\n| `GET /` | Strona główna (zoptymalizowana dla LLM) |\n| `GET /endpoints` | Czytelna maszynowo lista wszystkich endpointów |\n| `GET /endpoints?format=text` | Lista endpointów w postaci zwykłego tekstu |\n| `GET /openapi.json` | Specyfikacja OpenAPI 3.0 |\n| `GET /help` | Pełna dokumentacja API (HTML) |\n| `GET /help?format=json` | Dokumentacja API jako JSON |\n| `GET /docs` | System dokumentacji (HTML) |\n| `GET /docs?format=json` | Indeks dokumentacji (JSON) |\n| `GET /docs?format=text&scope=all` | Cała dokumentacja jako jeden blok tekstowy |\n| `GET /playground` | Interaktywny playground API |\n\n## Limity żądań\n\n| Metoda autoryzacji | Limit |\n|-------------|-------|\n| Mind Key (nagłówek) | Brak |\n| Mind Key (?key=) | 60/min na IP |\n| JWT (nagłówek) | Brak |\n| Endpointy publiczne | Brak |\n\nOdpowiedzi objęte limitem zawierają:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30 (tylko przy 429)\n```\n\n## Paginacja\n\nEndpointy list obsługują `?limit=` oraz `?offset=`:\n\n```\nGET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending\n```\n\nDomyślny limit: 100. Maksymalny limit: 500.\n\n## CORS\n\nWszystkie endpointy obsługują CORS dla klientów opartych na przeglądarce:\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, Mcp-Session-Id, Mcp-Tool-Profile\n```\n\n## SDK i klienci\n\n- **Node.js SDK**: `npm install synapse-memory-sdk` ([repozytorium](https://gitlab.com/schaefer-services/synapse-sdk-js))\n- **MCP Server**: `npx -y synapse-mcp-api@latest` ([repozytorium](https://gitlab.com/schaefer-services/synapse-mcp))\n- **Klient HTTP**: dowolna biblioteka HTTP (curl, fetch, axios itp.)\n\n## Następne kroki\n\n- [Memory API](/docs/api/memory) — najważniejsze endpointy\n- [Chat API](/docs/api/chat) — asynchroniczna komunikacja człowiek-agent\n- [Błędy i ich obsługa](/docs/api/errors)\n","content_html":"

Przegląd API i bazowy URL

\n

API Synapse jest RESTfulowym interfejsem HTTP. Wszystkie endpointy zwracają JSON\n(z wyjątkiem miejsc, w których zaznaczono inaczej). Niniejsza strona zawiera\npodstawowe informacje potrzebne przed przejściem do szczegółowych endpointów.

\n

Bazowy URL

\n
https://synapse.schaefer.zone

Wszystkie ścieżki w niniejszej dokumentacji są względne wobec tego bazowego URL-a.\nW przypadku instancji self-hosted należy użyć własnego adresu URL.

\n

Autoryzacja

\n

Dwie metody, obie wysyłane nagłówkiem Authorization:

\n
Authorization: Bearer YOUR_MIND_KEY    # dla endpointów danych\nAuthorization: Bearer YOUR_JWT          # dla endpointów konta

Lub przez parametr zapytania (ograniczony do 60/min):

\n
?key=YOUR_MIND_KEY

Szczegóły znajdują się w sekcji Autoryzacja.

\n

Grupy endpointów

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
GrupaAutoryzacjaOpis
PubliczneBrakStrona główna, health, OpenAPI, dokumentacja
MemoryMind KeyCRUD, wyszukiwanie, synchronizacja, osadzenia
ChatMind Key / JWTAsynchroniczne wiadomości między człowiekiem a agentem
TasksMind KeyZarządzanie zadaniami
ScriptsMind Key / JWTTrwały magazyn skryptów
SchedulerMind KeyZadania cron i zmienne
WebhooksMind KeyWywołania zwrotne HTTP przy zdarzeniach
ComputersMind Key / JWTZdalne sterowanie komputerami
User/MindsJWTKonto i zarządzanie umysłami
SharingJWTWspółdzielenie umysłów między użytkownikami
PushJWTSubskrypcje Web Push
ToolsBrakCzas, kalkulator, losowość (narzędzia publiczne)
\n

Formaty odpowiedzi

\n\n

Standardowa koperta odpowiedzi

\n

Odpowiedzi pomyślne zwracają dane bezpośrednio:

\n
{ "id": "mem_001", "status": "stored" }

Odpowiedzi błędne używają następującego formatu:

\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}
Pole `docs` zawiera link do dokumentacji istotnej dla częstych błędów.

Kody stanu HTTP

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
KodZnaczenie
200Sukces (GET, PUT)
201Utworzono (POST)
204Brak treści (DELETE)
400Nieprawidłowe żądanie (błąd walidacji)
401Brak autoryzacji (brak/nieprawidłowy token)
403Zabronione (nieprawidłowy typ tokena)
404Nie znaleziono (ścieżka nie istnieje)
409Konflikt (duplikat)
429Zbyt wiele żądań (limit)
500Błąd serwera
\n

Endpointy wykrywalności

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointPrzeznaczenie
GET /Strona główna (zoptymalizowana dla LLM)
GET /endpointsCzytelna maszynowo lista wszystkich endpointów
GET /endpoints?format=textLista endpointów w postaci zwykłego tekstu
GET /openapi.jsonSpecyfikacja OpenAPI 3.0
GET /helpPełna dokumentacja API (HTML)
GET /help?format=jsonDokumentacja API jako JSON
GET /docsSystem dokumentacji (HTML)
GET /docs?format=jsonIndeks dokumentacji (JSON)
GET /docs?format=text&scope=allCała dokumentacja jako jeden blok tekstowy
GET /playgroundInteraktywny playground API
\n

Limity żądań

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Metoda autoryzacjiLimit
Mind Key (nagłówek)Brak
Mind Key (?key=)60/min na IP
JWT (nagłówek)Brak
Endpointy publiczneBrak
\n

Odpowiedzi objęte limitem zawierają:

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30  (tylko przy 429)

Paginacja

\n

Endpointy list obsługują ?limit= oraz ?offset=:

\n
GET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending

Domyślny limit: 100. Maksymalny limit: 500.

\n

CORS

\n

Wszystkie endpointy obsługują CORS dla klientów opartych na przeglądarce:

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

SDK i klienci

\n\n

Następne kroki

\n\n","urls":{"html":"/docs/api/overview","text":"/docs/api/overview?format=text","json":"/docs/api/overview?format=json","llm":"/docs/api/overview?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}