{"title":"API-FAQ","slug":"api-faq","category":"faq","summary":"Häufige API-Fragen — Auth, Rate Limits, Fehlerbehandlung, Endpunkt-Discovery.","audience":["human","llm"],"tags":["faq","api","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":347,"read_minutes":2,"lang":"de","translated":true,"requested_lang":"de","content_markdown":"\n# API-FAQ\n\nHäufige Fragen zur Synapse-API.\n\n## Wie authentifiziere ich mich?\n\nZwei Methoden:\n\n1. **Mind Key** (für Daten-Endpunkte): `Authorization: Bearer mk_...`\n2. **JWT** (für Konto-Endpunkte): `Authorization: Bearer eyJ...`\n\nOder via Query-Parameter (60 req/min Limit): `?key=mk_...`\n\nSiehe [Authentifizierung](/docs/getting-started/authentication).\n\n## Was ist der Unterschied zwischen Mind Key und JWT?\n\n- **Mind Key**: Tenant-scoped, läuft nie ab, für Memory-/Chat-/Tasks-Daten\n- **JWT**: Nutzer-scoped, 7-Tage-Ablauf, für Konto-/Mind-Verwaltung\n\nSiehe [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt).\n\n## Warum erhalte ich 401 Unauthorized?\n\nHäufige Ursachen:\n\n1. Fehlender `Authorization`-Header\n2. Ungültiger Mind Key (prüfen, ob er mit `mk_` beginnt)\n3. JWT verwendet, wo Mind Key erforderlich ist (oder umgekehrt)\n4. Mind Key wurde widerrufen\n\n**Lösung:** Token überprüfen. Siehe [Authentifizierung](/docs/getting-started/authentication).\n\n## Warum erhalte ich 404 Not Found?\n\nDu hast einen falschen Endpunkt-Pfad verwendet. Synapse hat nur die Pfade, die in\n`GET /endpoints` gelistet sind.\n\n**Lösung:** Rufe `GET /endpoints` auf, um alle gültigen Pfade zu sehen. Nicht\nraten.\n\n## Warum erhalte ich 429 Too Many Requests?\n\nDu verwendest `?key=`-Query-Parameter-Auth, die auf 60/min begrenzt ist.\n\n**Lösung:** Wechsle zum `Authorization: Bearer`-Header (kein Rate Limit).\n\nSiehe [Rate Limits](/docs/api/rate-limits).\n\n## Wie liste ich alle Endpunkte auf?\n\n```bash\ncurl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text\n```\n\n## Wie finde ich den richtigen Endpunkt?\n\n1. Prüfe `GET /endpoints` für die maschinenlesbare Liste\n2. Prüfe `GET /help` für die vollständige API-Doku\n3. Durchsuche `GET /docs` für das Dokumentationssystem\n4. Verwende `GET /openapi.json` für die OpenAPI-3.0-Spec\n\n## Kann ich GET statt POST verwenden?\n\nEinige POST-Endpunkte haben GET-Äquivalente für reine URL-Tools:\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\nPrüfe `GET /endpoints` für verfügbare GET-Varianten.\n\n## Wie behandle ich Fehler?\n\nAlle Fehler liefern 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\nSiehe [Errors & Fehlerbehandlung](/docs/api/errors).\n\n## Wie hoch ist das Request-Body-Limit?\n\n10 MB. Für größere Payloads (z. B. Datei-Uploads) verwende die Multipart-\nEndpunkte.\n\n## Unterstützt die API CORS?\n\nJa. Alle Endpunkte liefern:\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## Gibt es ein SDK?\n\nJa:\n\n- **Node.js**: `npm install synapse-memory-sdk`\n- **MCP**: `npx -y synapse-mcp-api@latest`\n\nSiehe [API-Übersicht](/docs/api/overview) für Details.\n\n## Wie paginiere ich?\n\nVerwende `?limit=` und `?offset=`:\n\n```bash\ncurl \".../memory?limit=50&offset=100\"\n```\n\nStandard-Limit: 100. Max: 500.\n\n## Kann ich Memories nach Kategorie oder Tag filtern?\n\nJa:\n\n```bash\ncurl \".../memory?category=project\"\ncurl \".../memory?tag=docker\"\ncurl \".../memory/by-tag?tag=production\"\n```\n\n## Wie durchsuche ich Memories?\n\nZwei Wege:\n\n1. **FTS5-Keyword-Suche**: `GET /memory/search?q=docker+swarm`\n2. **Semantische Suche**: `GET /memory/semantic-search?q=container+orchestration`\n\nSiehe [FTS5-Suche](/docs/concepts/fts5-search) und [Semantische Suche](/docs/concepts/semantic-search).\n\n## Wie aktualisiere ich einen Memory?\n\nPOST `/memory` mit derselben `category` + `key` — der bestehende Memory wird\naktualisiert, nicht dupliziert.\n\n```bash\n# Initial store\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael\"}'\n\n# Update (same key)\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael Schäfer\"}'\n```\n\n## Wie lösche ich einen Memory?\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer $KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## Kann ich Bulk-löschen?\n\nJa:\n\n```bash\ncurl -X POST .../memory/bulk-delete \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n## Nächste Schritte\n\n- [API-Übersicht](/docs/api/overview)\n- [Errors & Fehlerbehandlung](/docs/api/errors)\n- [Authentifizierung](/docs/getting-started/authentication)\n","content_html":"

API-FAQ

\n

Häufige Fragen zur Synapse-API.

\n

Wie authentifiziere ich mich?

\n

Zwei Methoden:

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

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

\n

Siehe Authentifizierung.

\n

Was ist der Unterschied zwischen Mind Key und JWT?

\n\n

Siehe Mind Key vs JWT.

\n

Warum erhalte ich 401 Unauthorized?

\n

Häufige Ursachen:

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

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

\n

Warum erhalte ich 404 Not Found?

\n

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

\n

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

\n

Warum erhalte ich 429 Too Many Requests?

\n

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

\n

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

\n

Siehe Rate Limits.

\n

Wie liste ich alle Endpunkte auf?

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

Wie finde ich den richtigen Endpunkt?

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

Kann ich GET statt POST verwenden?

\n

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

\n\n

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

\n

Wie behandle ich Fehler?

\n

Alle Fehler liefern 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}

Siehe Errors & Fehlerbehandlung.

\n

Wie hoch ist das Request-Body-Limit?

\n

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

\n

Unterstützt die API CORS?

\n

Ja. Alle Endpunkte liefern:

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

Gibt es ein SDK?

\n

Ja:

\n\n

Siehe API-Übersicht für Details.

\n

Wie paginiere ich?

\n

Verwende ?limit= und ?offset=:

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

Standard-Limit: 100. Max: 500.

\n

Kann ich Memories nach Kategorie oder Tag filtern?

\n

Ja:

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

Wie durchsuche ich Memories?

\n

Zwei Wege:

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

Siehe FTS5-Suche und Semantische Suche.

\n

Wie aktualisiere ich einen Memory?

\n

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

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

Wie lösche ich einen Memory?

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

Kann ich Bulk-löschen?

\n

Ja:

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

Nächste Schritte

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