# Przegląd API i bazowy URL

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

## Bazowy URL

```
https://synapse.schaefer.zone
```

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

## Autoryzacja

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

```
Authorization: Bearer YOUR_MIND_KEY    # dla endpointów danych
Authorization: Bearer YOUR_JWT          # dla endpointów konta
```

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

```
?key=YOUR_MIND_KEY
```

Szczegóły znajdują się w sekcji [Autoryzacja](/docs/getting-started/authentication).

## Grupy endpointów

| Grupa | Autoryzacja | Opis |
|-------|-------------|------|
| Publiczne | Brak | Strona główna, health, OpenAPI, dokumentacja |
| Memory | Mind Key | CRUD, wyszukiwanie, synchronizacja, osadzenia |
| Chat | Mind Key / JWT | Asynchroniczne wiadomości między człowiekiem a agentem |
| Tasks | Mind Key | Zarządzanie zadaniami |
| Scripts | Mind Key / JWT | Trwały magazyn skryptów |
| Scheduler | Mind Key | Zadania cron i zmienne |
| Webhooks | Mind Key | Wywołania zwrotne HTTP przy zdarzeniach |
| Computers | Mind Key / JWT | Zdalne sterowanie komputerami |
| User/Minds | JWT | Konto i zarządzanie umysłami |
| Sharing | JWT | Współdzielenie umysłów między użytkownikami |
| Push | JWT | Subskrypcje Web Push |
| Tools | Brak | Czas, kalkulator, losowość (narzędzia publiczne) |

## Formaty odpowiedzi

- **JSON** (domyślnie): `{ "key": "value", ... }`
- **Zwykły tekst**: `/memory/recall` zwraca tekst zoptymalizowany dla LLM
- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`

## Standardowa koperta odpowiedzi

Odpowiedzi pomyślne zwracają dane bezpośrednio:

```json
{ "id": "mem_001", "status": "stored" }
```

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

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

> [!NOTE]
> Pole `docs` zawiera link do dokumentacji istotnej dla częstych błędów.

## Kody stanu HTTP

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

## Endpointy wykrywalności

| Endpoint | Przeznaczenie |
|----------|---------------|
| `GET /` | Strona główna (zoptymalizowana dla LLM) |
| `GET /endpoints` | Czytelna maszynowo lista wszystkich endpointów |
| `GET /endpoints?format=text` | Lista endpointów w postaci zwykłego tekstu |
| `GET /openapi.json` | Specyfikacja OpenAPI 3.0 |
| `GET /help` | Pełna dokumentacja API (HTML) |
| `GET /help?format=json` | Dokumentacja API jako JSON |
| `GET /docs` | System dokumentacji (HTML) |
| `GET /docs?format=json` | Indeks dokumentacji (JSON) |
| `GET /docs?format=text&scope=all` | Cała dokumentacja jako jeden blok tekstowy |
| `GET /playground` | Interaktywny playground API |

## Limity żądań

| Metoda autoryzacji | Limit |
|-------------|-------|
| Mind Key (nagłówek) | Brak |
| Mind Key (?key=) | 60/min na IP |
| JWT (nagłówek) | Brak |
| Endpointy publiczne | Brak |

Odpowiedzi objęte limitem zawierają:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (tylko przy 429)
```

## Paginacja

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

```
GET /memory?limit=50&offset=100
GET /mind/tasks?status=pending
```

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

## CORS

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

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

## SDK i klienci

- **Node.js SDK**: `npm install synapse-memory-sdk` ([repozytorium](https://gitlab.com/schaefer-services/synapse-sdk-js))
- **MCP Server**: `npx -y synapse-mcp-api@latest` ([repozytorium](https://gitlab.com/schaefer-services/synapse-mcp))
- **Klient HTTP**: dowolna biblioteka HTTP (curl, fetch, axios itp.)

## Następne kroki

- [Memory API](/docs/api/memory) — najważniejsze endpointy
- [Chat API](/docs/api/chat) — asynchroniczna komunikacja człowiek-agent
- [Błędy i ich obsługa](/docs/api/errors)