Skip to main content

API Overview & Base URL

beginner 🤖 LLM-friendly 3 min · 532 words Updated: 2026-06-27 English

All Synapse API endpoints, base URL, auth patterns, and response formats at a glance.

Read this article as: 📄 Plain Text ⚡ JSON 🤖 LLM Format
Language: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

API Overview & Base URL

The Synapse API is a RESTful HTTP API. All endpoints return JSON (except where noted). This page covers the essentials you need before diving into specific endpoints.

Base URL

https://synapse.schaefer.zone

All paths in this documentation are relative to this base URL. For self-hosted instances, replace with your own URL.

Authentication

Two methods, both sent via Authorization header:

Authorization: Bearer YOUR_MIND_KEY    # for data endpoints
Authorization: Bearer YOUR_JWT          # for account endpoints

Or via query parameter (rate-limited to 60/min):

?key=YOUR_MIND_KEY

See Authentication for details.

Endpoint Groups

Group Auth Description
Public None Landing page, health, OpenAPI, docs
Memory Mind Key CRUD, search, sync, embeddings
Chat Mind Key / JWT Async messaging between human and agent
Tasks Mind Key Task management
Scripts Mind Key / JWT Persistent script store
Scheduler Mind Key Cron jobs + variables
Webhooks Mind Key HTTP callbacks on events
Computers Mind Key / JWT Remote computer control
User/Minds JWT Account + mind management
Sharing JWT Mind sharing between users
Push JWT Web Push subscriptions
Tools None Time, calc, random (public utilities)

Response Formats

  • JSON (default): { "key": "value", ... }
  • Plain text: /memory/recall returns LLM-optimized text
  • HTML: /, /docs, /human, /support, /playground

Standard Response Envelope

Success responses return the data directly:

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

Error responses use this format:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}
The `docs` field links to relevant documentation for common errors.

HTTP Status Codes

Code Meaning
200 Success (GET, PUT)
201 Created (POST)
204 No content (DELETE)
400 Bad request (validation error)
401 Unauthorized (missing/invalid token)
403 Forbidden (wrong token type)
404 Not found (path doesn't exist)
409 Conflict (duplicate)
429 Too many requests (rate limit)
500 Server error

Discoverability Endpoints

Endpoint Purpose
GET / Landing page (LLM-optimized)
GET /endpoints Machine-readable list of all endpoints
GET /endpoints?format=text Plain-text endpoint list
GET /openapi.json OpenAPI 3.0 specification
GET /help Full API documentation (HTML)
GET /help?format=json API docs as JSON
GET /docs Documentation system (HTML)
GET /docs?format=json Documentation index (JSON)
GET /docs?format=text&scope=all All docs as one text block
GET /playground Interactive API playground

Rate Limits

Auth Method Limit
Mind Key (header) None
Mind Key (?key=) 60/min per IP
JWT (header) None
Public endpoints None

Rate-limited responses include:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (only when 429)

Pagination

List endpoints support ?limit= and ?offset=:

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

Default limit: 100. Max limit: 500.

CORS

All endpoints support CORS for browser-based 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: any HTTP library (curl, fetch, axios, etc.)

Next Steps

← Back to API Reference