API-FAQ

Häufige Fragen zur Synapse-API.

Wie authentifiziere ich mich?

Zwei Methoden:

1. Mind Key (für Daten-Endpunkte): Authorization: Bearer mk_...
2. JWT (für Konto-Endpunkte): Authorization: Bearer eyJ...

Oder via Query-Parameter (60 req/min Limit): ?key=mk_...

Siehe Authentifizierung.

Was ist der Unterschied zwischen Mind Key und JWT?

• Mind Key: Tenant-scoped, läuft nie ab, für Memory-/Chat-/Tasks-Daten
• JWT: Nutzer-scoped, 7-Tage-Ablauf, für Konto-/Mind-Verwaltung

Siehe Mind Key vs JWT.

Warum erhalte ich 401 Unauthorized?

Häufige Ursachen:

1. Fehlender Authorization-Header
2. Ungültiger Mind Key (prüfen, ob er mit mk_ beginnt)
3. JWT verwendet, wo Mind Key erforderlich ist (oder umgekehrt)
4. Mind Key wurde widerrufen

Lösung: Token überprüfen. Siehe Authentifizierung.

Warum erhalte ich 404 Not Found?

Du hast einen falschen Endpunkt-Pfad verwendet. Synapse hat nur die Pfade, die in GET /endpoints gelistet sind.

Lösung: Rufe GET /endpoints auf, um alle gültigen Pfade zu sehen. Nicht raten.

Warum erhalte ich 429 Too Many Requests?

Du verwendest ?key=-Query-Parameter-Auth, die auf 60/min begrenzt ist.

Lösung: Wechsle zum Authorization: Bearer-Header (kein Rate Limit).

Siehe Rate Limits.

Wie liste ich alle Endpunkte auf?

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

Wie finde ich den richtigen Endpunkt?

1. Prüfe GET /endpoints für die maschinenlesbare Liste
2. Prüfe GET /help für die vollständige API-Doku
3. Durchsuche GET /docs für das Dokumentationssystem
4. Verwende GET /openapi.json für die OpenAPI-3.0-Spec

Kann ich GET statt POST verwenden?

Einige POST-Endpunkte haben GET-Äquivalente für reine URL-Tools:

• POST /memory ↔ GET /memory/store?content=...
• POST /mind/task ↔ GET /mind/task?title=...
• POST /chat/reply ↔ GET /chat/reply?content=...

Prüfe GET /endpoints für verfügbare GET-Varianten.

Wie behandle ich Fehler?

Alle Fehler liefern JSON:

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

Siehe Errors & Fehlerbehandlung.

Wie hoch ist das Request-Body-Limit?

10 MB. Für größere Payloads (z. B. Datei-Uploads) verwende die Multipart- Endpunkte.

Unterstützt die API CORS?

Ja. Alle Endpunkte liefern:

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

Gibt es ein SDK?

Ja:

• Node.js: npm install synapse-memory-sdk
• MCP: npx -y synapse-mcp-api@latest

Siehe API-Übersicht für Details.

Wie paginiere ich?

Verwende ?limit= und ?offset=:

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

Standard-Limit: 100. Max: 500.

Kann ich Memories nach Kategorie oder Tag filtern?

Ja:

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

Wie durchsuche ich Memories?

Zwei Wege:

1. FTS5-Keyword-Suche: GET /memory/search?q=docker+swarm
2. Semantische Suche: GET /memory/semantic-search?q=container+orchestration

Siehe FTS5-Suche und Semantische Suche.

Wie aktualisiere ich einen Memory?

POST /memory mit derselben category + key — der bestehende Memory wird aktualisiert, nicht dupliziert.

# Initial store
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'

# Update (same key)
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael Schäfer"}'

Wie lösche ich einen Memory?

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

Kann ich Bulk-löschen?

Ja:

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

Nächste Schritte

• API-Übersicht
• Errors & Fehlerbehandlung
• Authentifizierung