API-Übersicht & Basis-URL

beginner 🤖 LLM-freundlich 2 Min · 492 Wörter Aktualisiert: 2026-06-27 Deutsch

Alle Synapse-API-Endpunkte, Basis-URL, Authentifizierungsmuster und Antwortformate auf einen Blick.

Diesen Artikel lesen als: 📄 Plain Text ⚡ JSON 🤖 LLM-Format

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

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

Fehlerantworten verwenden dieses Format:

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

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)
MCP Server: npx -y synapse-mcp-api@latest (Repo)
HTTP-Client: jede HTTP-Bibliothek (curl, fetch, axios, etc.)

Nächste Schritte

Memory-API — die wichtigsten Endpunkte
Chat-API — asynchrone Mensch-Agent-Kommunikation
Errors & Fehlerbehandlung