Skip to main content

API FAQ

beginner 🤖 LLM-friendly 2 min · 384 words Updated: 2026-06-27 English

Common API questions — auth, rate limits, error handling, endpoint discovery.

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 FAQ

Common questions about the Synapse API.

How do I authenticate?

Two methods:

  1. Mind Key (for data endpoints): Authorization: Bearer mk_...
  2. JWT (for account endpoints): Authorization: Bearer eyJ...

Or via query parameter (60 req/min limit): ?key=mk_...

See Authentication.

What's the difference between Mind Key and JWT?

  • Mind Key: tenant-scoped, never expires, for memory/chat/tasks data
  • JWT: user-scoped, 7-day expiry, for account/mind management

See Mind Key vs JWT.

Why am I getting 401 Unauthorized?

Common causes:

  1. Missing Authorization header
  2. Invalid Mind Key (verify it starts with mk_)
  3. Using a JWT where a Mind Key is required (or vice versa)
  4. Mind Key has been revoked

Fix: Verify your token. See Authentication.

Why am I getting 404 Not Found?

You used a wrong endpoint path. Synapse only has the paths listed in GET /endpoints.

Fix: Call GET /endpoints to see all valid paths. Don't guess.

Why am I getting 429 Too Many Requests?

You're using ?key= query parameter auth, which is rate-limited to 60/min.

Fix: Switch to Authorization: Bearer header (no rate limit).

See Rate Limits.

How do I list all endpoints?

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

How do I find the right endpoint?

  1. Check GET /endpoints for the machine-readable list
  2. Check GET /help for full API docs
  3. Browse GET /docs for the documentation system
  4. Use GET /openapi.json for OpenAPI 3.0 spec

Can I use GET instead of POST?

Some POST endpoints have GET equivalents for URL-only tools:

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

Check GET /endpoints for available GET variants.

How do I handle errors?

All errors return JSON:

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

See Errors & Error Handling.

What's the request body limit?

10 MB. For larger payloads (e.g. file uploads), use the multipart endpoints.

Does the API support CORS?

Yes. All endpoints return:

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

Is there an SDK?

Yes:

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

See API Overview for details.

How do I paginate?

Use ?limit= and ?offset=:

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

Default limit: 100. Max: 500.

Can I filter memories by category or tag?

Yes:

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

How do I search memories?

Two ways:

  1. FTS5 keyword search: GET /memory/search?q=docker+swarm
  2. Semantic search: GET /memory/semantic-search?q=container+orchestration

See FTS5 Search and Semantic Search.

How do I update a memory?

POST /memory with the same category + key — the existing memory is updated, not duplicated.

# 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"}'

How do I delete a memory?

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

Can I bulk delete?

Yes:

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

Next Steps

← Back to FAQ