{"title":"API FAQ","slug":"api-faq","category":"faq","summary":"Common API questions — auth, rate limits, error handling, endpoint discovery.","audience":["human","llm"],"tags":["faq","api","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":384,"read_minutes":2,"lang":"en","translated":true,"requested_lang":"en","content_markdown":"\n# API FAQ\n\nCommon questions about the Synapse API.\n\n## How do I authenticate?\n\nTwo methods:\n\n1. **Mind Key** (for data endpoints): `Authorization: Bearer mk_...`\n2. **JWT** (for account endpoints): `Authorization: Bearer eyJ...`\n\nOr via query parameter (60 req/min limit): `?key=mk_...`\n\nSee [Authentication](/docs/getting-started/authentication).\n\n## What's the difference between Mind Key and JWT?\n\n- **Mind Key**: tenant-scoped, never expires, for memory/chat/tasks data\n- **JWT**: user-scoped, 7-day expiry, for account/mind management\n\nSee [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt).\n\n## Why am I getting 401 Unauthorized?\n\nCommon causes:\n\n1. Missing `Authorization` header\n2. Invalid Mind Key (verify it starts with `mk_`)\n3. Using a JWT where a Mind Key is required (or vice versa)\n4. Mind Key has been revoked\n\n**Fix:** Verify your token. See [Authentication](/docs/getting-started/authentication).\n\n## Why am I getting 404 Not Found?\n\nYou used a wrong endpoint path. Synapse only has the paths listed in\n`GET /endpoints`.\n\n**Fix:** Call `GET /endpoints` to see all valid paths. Don't guess.\n\n## Why am I getting 429 Too Many Requests?\n\nYou're using `?key=` query parameter auth, which is rate-limited to 60/min.\n\n**Fix:** Switch to `Authorization: Bearer` header (no rate limit).\n\nSee [Rate Limits](/docs/api/rate-limits).\n\n## How do I list all endpoints?\n\n```bash\ncurl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text\n```\n\n## How do I find the right endpoint?\n\n1. Check `GET /endpoints` for the machine-readable list\n2. Check `GET /help` for full API docs\n3. Browse `GET /docs` for the documentation system\n4. Use `GET /openapi.json` for OpenAPI 3.0 spec\n\n## Can I use GET instead of POST?\n\nSome POST endpoints have GET equivalents for URL-only 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\nCheck `GET /endpoints` for available GET variants.\n\n## How do I handle errors?\n\nAll errors return 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\nSee [Errors & Error Handling](/docs/api/errors).\n\n## What's the request body limit?\n\n10 MB. For larger payloads (e.g. file uploads), use the multipart endpoints.\n\n## Does the API support CORS?\n\nYes. All endpoints return:\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## Is there an SDK?\n\nYes:\n\n- **Node.js**: `npm install synapse-memory-sdk`\n- **MCP**: `npx -y synapse-mcp-api@latest`\n\nSee [API Overview](/docs/api/overview) for details.\n\n## How do I paginate?\n\nUse `?limit=` and `?offset=`:\n\n```bash\ncurl \".../memory?limit=50&offset=100\"\n```\n\nDefault limit: 100. Max: 500.\n\n## Can I filter memories by category or tag?\n\nYes:\n\n```bash\ncurl \".../memory?category=project\"\ncurl \".../memory?tag=docker\"\ncurl \".../memory/by-tag?tag=production\"\n```\n\n## How do I search memories?\n\nTwo ways:\n\n1. **FTS5 keyword search**: `GET /memory/search?q=docker+swarm`\n2. **Semantic search**: `GET /memory/semantic-search?q=container+orchestration`\n\nSee [FTS5 Search](/docs/concepts/fts5-search) and [Semantic Search](/docs/concepts/semantic-search).\n\n## How do I update a memory?\n\nPOST `/memory` with the same `category` + `key` — the existing memory is\nupdated, not duplicated.\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## How do I delete a memory?\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer $KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## Can I bulk delete?\n\nYes:\n\n```bash\ncurl -X POST .../memory/bulk-delete \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n## Next Steps\n\n- [API Overview](/docs/api/overview)\n- [Errors & Error Handling](/docs/api/errors)\n- [Authentication](/docs/getting-started/authentication)\n","content_html":"

API FAQ

\n

Common questions about the Synapse API.

\n

How do I authenticate?

\n

Two methods:

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

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

\n

See Authentication.

\n

What's the difference between Mind Key and JWT?

\n\n

See Mind Key vs JWT.

\n

Why am I getting 401 Unauthorized?

\n

Common causes:

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

Fix: Verify your token. See Authentication.

\n

Why am I getting 404 Not Found?

\n

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

\n

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

\n

Why am I getting 429 Too Many Requests?

\n

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

\n

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

\n

See Rate Limits.

\n

How do I list all endpoints?

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

How do I find the right endpoint?

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

Can I use GET instead of POST?

\n

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

\n\n

Check GET /endpoints for available GET variants.

\n

How do I handle errors?

\n

All errors return 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}

See Errors & Error Handling.

\n

What's the request body limit?

\n

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

\n

Does the API support CORS?

\n

Yes. All endpoints return:

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

Is there an SDK?

\n

Yes:

\n\n

See API Overview for details.

\n

How do I paginate?

\n

Use ?limit= and ?offset=:

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

Default limit: 100. Max: 500.

\n

Can I filter memories by category or tag?

\n

Yes:

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

How do I search memories?

\n

Two ways:

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

See FTS5 Search and Semantic Search.

\n

How do I update a memory?

\n

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

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

How do I delete a memory?

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

Can I bulk delete?

\n

Yes:

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

Next Steps

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