{"title":"API-Übersicht & Basis-URL","slug":"overview","category":"api","summary":"Alle Synapse-API-Endpunkte, Basis-URL, Authentifizierungsmuster und Antwortformate auf einen Blick.","audience":["human","llm"],"tags":["api","overview","endpoints"],"difficulty":"beginner","updated":"2026-06-27","word_count":492,"read_minutes":2,"llm_context":"Base URL: https://synapse.schaefer.zone\nAuth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)\n OR ?key=YOUR_MIND_KEY (query, 60 req/min)\nAll responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)\nAll 404 responses mean the path does not exist — do NOT guess paths.\nGET /endpoints returns machine-readable list of all valid endpoints.\n","lang":"de","translated":true,"requested_lang":"de","content_markdown":"\n# API-Übersicht & Basis-URL\n\nDie Synapse-API ist eine RESTful-HTTP-API. Alle Endpunkte liefern JSON zurück\n(ausgenommen sind explizit gekennzeichnete Fälle). Diese Seite behandelt die\nGrundlagen, die du kennen solltest, bevor du dich den spezifischen Endpunkten\nwidmest.\n\n## Basis-URL\n\n```\nhttps://synapse.schaefer.zone\n```\n\nAlle Pfade in dieser Dokumentation sind relativ zu dieser Basis-URL. Für\nselbstgehostete Instanzen ersetze sie durch deine eigene URL.\n\n## Authentifizierung\n\nZwei Methoden, beide über den `Authorization`-Header:\n\n```\nAuthorization: Bearer YOUR_MIND_KEY # für Daten-Endpunkte\nAuthorization: Bearer YOUR_JWT # für Konto-Endpunkte\n```\n\nOder über einen Query-Parameter (auf 60/min begrenzt):\n\n```\n?key=YOUR_MIND_KEY\n```\n\nSiehe [Authentifizierung](/docs/getting-started/authentication) für Details.\n\n## Endpunkt-Gruppen\n\n| Gruppe | Auth | Beschreibung |\n|-------|------|--------------|\n| Öffentlich | Keine | Landing-Page, Health, OpenAPI, Docs |\n| Memory | Mind Key | CRUD, Suche, Sync, Embeddings |\n| Chat | Mind Key / JWT | Asynchrone Nachrichten zwischen Mensch und Agent |\n| Tasks | Mind Key | Aufgabenverwaltung |\n| Scripts | Mind Key / JWT | Persistenter Script-Speicher |\n| Scheduler | Mind Key | Cron-Jobs + Variablen |\n| Webhooks | Mind Key | HTTP-Callbacks bei Events |\n| Computers | Mind Key / JWT | Fernsteuerung von Rechnern |\n| User/Minds | JWT | Konto- + Mind-Verwaltung |\n| Sharing | JWT | Mind-Freigaben zwischen Nutzern |\n| Push | JWT | Web-Push-Abonnements |\n| Tools | Keine | Zeit, Calc, Random (öffentliche Hilfswerkzeuge) |\n\n## Antwortformate\n\n- **JSON** (Standard): `{ \"key\": \"value\", ... }`\n- **Klartext**: `/memory/recall` liefert LLM-optimierten Text\n- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`\n\n## Standard-Antwort-Envelope\n\nErfolgsantworten liefern die Daten direkt:\n\n```json\n{ \"id\": \"mem_001\", \"status\": \"stored\" }\n```\n\nFehlerantworten verwenden dieses Format:\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\n> [!NOTE]\n> Das Feld `docs` verlinkt bei häufigen Fehlern auf die relevante Doku.\n\n## HTTP-Statuscodes\n\n| Code | Bedeutung |\n|------|-----------|\n| 200 | Erfolg (GET, PUT) |\n| 201 | Erstellt (POST) |\n| 204 | Kein Inhalt (DELETE) |\n| 400 | Bad Request (Validierungsfehler) |\n| 401 | Unauthorized (fehlender/ungültiger Token) |\n| 403 | Forbidden (falscher Token-Typ) |\n| 404 | Not Found (Pfad existiert nicht) |\n| 409 | Conflict (Duplikat) |\n| 429 | Too Many Requests (Rate Limit) |\n| 500 | Serverfehler |\n\n## Discoverability-Endpunkte\n\n| Endpunkt | Zweck |\n|----------|-------|\n| `GET /` | Landing-Page (LLM-optimiert) |\n| `GET /endpoints` | Maschinenlesbare Liste aller Endpunkte |\n| `GET /endpoints?format=text` | Endpunkt-Liste als Klartext |\n| `GET /openapi.json` | OpenAPI-3.0-Spezifikation |\n| `GET /help` | Vollständige API-Doku (HTML) |\n| `GET /help?format=json` | API-Doku als JSON |\n| `GET /docs` | Dokumentationssystem (HTML) |\n| `GET /docs?format=json` | Doku-Index (JSON) |\n| `GET /docs?format=text&scope=all` | Alle Docs als ein Textblock |\n| `GET /playground` | Interaktives API-Playground |\n\n## Rate Limits\n\n| Auth-Methode | Limit |\n|---------------|-------|\n| Mind Key (Header) | Keins |\n| Mind Key (?key=) | 60/min pro IP |\n| JWT (Header) | Keins |\n| Öffentliche Endpunkte | Keins |\n\nRate-limitierte Antworten enthalten:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30 (nur bei 429)\n```\n\n## Paginierung\n\nListen-Endpunkte unterstützen `?limit=` und `?offset=`:\n\n```\nGET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending\n```\n\nStandard-Limit: 100. Max. Limit: 500.\n\n## CORS\n\nAlle Endpunkte unterstützen CORS für browserbasierte Clients:\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, Mcp-Session-Id, Mcp-Tool-Profile\n```\n\n## SDKs & Clients\n\n- **Node.js SDK**: `npm install synapse-memory-sdk` ([Repo](https://gitlab.com/schaefer-services/synapse-sdk-js))\n- **MCP Server**: `npx -y synapse-mcp-api@latest` ([Repo](https://gitlab.com/schaefer-services/synapse-mcp))\n- **HTTP-Client**: jede HTTP-Bibliothek (curl, fetch, axios, etc.)\n\n## Nächste Schritte\n\n- [Memory-API](/docs/api/memory) — die wichtigsten Endpunkte\n- [Chat-API](/docs/api/chat) — asynchrone Mensch-Agent-Kommunikation\n- [Errors & Fehlerbehandlung](/docs/api/errors)\n","content_html":"

API-Übersicht & Basis-URL

\n

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

\n

Basis-URL

\n
https://synapse.schaefer.zone

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

\n

Authentifizierung

\n

Zwei Methoden, beide über den Authorization-Header:

\n
Authorization: Bearer YOUR_MIND_KEY    # für Daten-Endpunkte\nAuthorization: Bearer YOUR_JWT          # für Konto-Endpunkte

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

\n
?key=YOUR_MIND_KEY

Siehe Authentifizierung für Details.

\n

Endpunkt-Gruppen

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
GruppeAuthBeschreibung
ÖffentlichKeineLanding-Page, Health, OpenAPI, Docs
MemoryMind KeyCRUD, Suche, Sync, Embeddings
ChatMind Key / JWTAsynchrone Nachrichten zwischen Mensch und Agent
TasksMind KeyAufgabenverwaltung
ScriptsMind Key / JWTPersistenter Script-Speicher
SchedulerMind KeyCron-Jobs + Variablen
WebhooksMind KeyHTTP-Callbacks bei Events
ComputersMind Key / JWTFernsteuerung von Rechnern
User/MindsJWTKonto- + Mind-Verwaltung
SharingJWTMind-Freigaben zwischen Nutzern
PushJWTWeb-Push-Abonnements
ToolsKeineZeit, Calc, Random (öffentliche Hilfswerkzeuge)
\n

Antwortformate

\n\n

Standard-Antwort-Envelope

\n

Erfolgsantworten liefern die Daten direkt:

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

Fehlerantworten verwenden dieses Format:

\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}
Das Feld `docs` verlinkt bei häufigen Fehlern auf die relevante Doku.

HTTP-Statuscodes

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

Discoverability-Endpunkte

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpunktZweck
GET /Landing-Page (LLM-optimiert)
GET /endpointsMaschinenlesbare Liste aller Endpunkte
GET /endpoints?format=textEndpunkt-Liste als Klartext
GET /openapi.jsonOpenAPI-3.0-Spezifikation
GET /helpVollständige API-Doku (HTML)
GET /help?format=jsonAPI-Doku als JSON
GET /docsDokumentationssystem (HTML)
GET /docs?format=jsonDoku-Index (JSON)
GET /docs?format=text&scope=allAlle Docs als ein Textblock
GET /playgroundInteraktives API-Playground
\n

Rate Limits

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Auth-MethodeLimit
Mind Key (Header)Keins
Mind Key (?key=)60/min pro IP
JWT (Header)Keins
Öffentliche EndpunkteKeins
\n

Rate-limitierte Antworten enthalten:

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30  (nur bei 429)

Paginierung

\n

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

\n
GET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending

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

\n

CORS

\n

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

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

SDKs & Clients

\n\n

Nächste Schritte

\n\n","urls":{"html":"/docs/api/overview","text":"/docs/api/overview?format=text","json":"/docs/api/overview?format=json","llm":"/docs/api/overview?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}