# API-Übersicht & Basis-URL

Die Synapse-API ist eine RESTful-HTTP-API. Alle Endpunkte liefern JSON zurück
(ausgenommen sind explizit gekennzeichnete Fälle). Diese Seite behandelt die
Grundlagen, die du kennen solltest, bevor du dich den spezifischen Endpunkten
widmest.

## Basis-URL

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

Alle Pfade in dieser Dokumentation sind relativ zu dieser Basis-URL. Für
selbstgehostete Instanzen ersetze sie durch deine eigene URL.

## Authentifizierung

Zwei Methoden, beide über den `Authorization`-Header:

```
Authorization: Bearer YOUR_MIND_KEY    # für Daten-Endpunkte
Authorization: Bearer YOUR_JWT          # für Konto-Endpunkte
```

Oder über einen Query-Parameter (auf 60/min begrenzt):

```
?key=YOUR_MIND_KEY
```

Siehe [Authentifizierung](/docs/getting-started/authentication) für Details.

## Endpunkt-Gruppen

| Gruppe | Auth | Beschreibung |
|-------|------|--------------|
| Öffentlich | Keine | Landing-Page, Health, OpenAPI, Docs |
| Memory | Mind Key | CRUD, Suche, Sync, Embeddings |
| Chat | Mind Key / JWT | Asynchrone Nachrichten zwischen Mensch und Agent |
| Tasks | Mind Key | Aufgabenverwaltung |
| Scripts | Mind Key / JWT | Persistenter Script-Speicher |
| Scheduler | Mind Key | Cron-Jobs + Variablen |
| Webhooks | Mind Key | HTTP-Callbacks bei Events |
| Computers | Mind Key / JWT | Fernsteuerung von Rechnern |
| User/Minds | JWT | Konto- + Mind-Verwaltung |
| Sharing | JWT | Mind-Freigaben zwischen Nutzern |
| Push | JWT | Web-Push-Abonnements |
| Tools | Keine | Zeit, Calc, Random (öffentliche Hilfswerkzeuge) |

## Antwortformate

- **JSON** (Standard): `{ "key": "value", ... }`
- **Klartext**: `/memory/recall` liefert LLM-optimierten Text
- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`

## Standard-Antwort-Envelope

Erfolgsantworten liefern die Daten direkt:

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

Fehlerantworten verwenden dieses Format:

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

> [!NOTE]
> Das Feld `docs` verlinkt bei häufigen Fehlern auf die relevante Doku.

## HTTP-Statuscodes

| Code | Bedeutung |
|------|-----------|
| 200 | Erfolg (GET, PUT) |
| 201 | Erstellt (POST) |
| 204 | Kein Inhalt (DELETE) |
| 400 | Bad Request (Validierungsfehler) |
| 401 | Unauthorized (fehlender/ungültiger Token) |
| 403 | Forbidden (falscher Token-Typ) |
| 404 | Not Found (Pfad existiert nicht) |
| 409 | Conflict (Duplikat) |
| 429 | Too Many Requests (Rate Limit) |
| 500 | Serverfehler |

## Discoverability-Endpunkte

| Endpunkt | Zweck |
|----------|-------|
| `GET /` | Landing-Page (LLM-optimiert) |
| `GET /endpoints` | Maschinenlesbare Liste aller Endpunkte |
| `GET /endpoints?format=text` | Endpunkt-Liste als Klartext |
| `GET /openapi.json` | OpenAPI-3.0-Spezifikation |
| `GET /help` | Vollständige API-Doku (HTML) |
| `GET /help?format=json` | API-Doku als JSON |
| `GET /docs` | Dokumentationssystem (HTML) |
| `GET /docs?format=json` | Doku-Index (JSON) |
| `GET /docs?format=text&scope=all` | Alle Docs als ein Textblock |
| `GET /playground` | Interaktives API-Playground |

## Rate Limits

| Auth-Methode | Limit |
|---------------|-------|
| Mind Key (Header) | Keins |
| Mind Key (?key=) | 60/min pro IP |
| JWT (Header) | Keins |
| Öffentliche Endpunkte | Keins |

Rate-limitierte Antworten enthalten:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (nur bei 429)
```

## Paginierung

Listen-Endpunkte unterstützen `?limit=` und `?offset=`:

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

Standard-Limit: 100. Max. Limit: 500.

## CORS

Alle Endpunkte unterstützen CORS für browserbasierte Clients:

```
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
```

## SDKs & Clients

- **Node.js SDK**: `npm install synapse-memory-sdk` ([Repo](https://gitlab.com/schaefer-services/synapse-sdk-js))
- **MCP Server**: `npx -y synapse-mcp-api@latest` ([Repo](https://gitlab.com/schaefer-services/synapse-mcp))
- **HTTP-Client**: jede HTTP-Bibliothek (curl, fetch, axios, etc.)

## Nächste Schritte

- [Memory-API](/docs/api/memory) — die wichtigsten Endpunkte
- [Chat-API](/docs/api/chat) — asynchrone Mensch-Agent-Kommunikation
- [Errors & Fehlerbehandlung](/docs/api/errors)