API 常见问题

关于 Synapse API 的常见问题。

如何认证？

两种方式：

1. Mind Key（用于数据端点）：Authorization: Bearer mk_...
2. JWT（用于账户端点）：Authorization: Bearer eyJ...

或通过查询参数（限速 60 次/分钟）：?key=mk_...

参见 Authentication。

Mind Key 和 JWT 有何区别？

• Mind Key：租户范围，永不过期，用于记忆/聊天/任务数据
• JWT：用户范围，7 天过期，用于账户/Mind 管理

参见 Mind Key 与 JWT。

为什么收到 401 Unauthorized？

常见原因：

1. 缺少 Authorization 头
2. Mind Key 无效（确认它以 mk_ 开头）
3. 在需要 Mind Key 的地方用了 JWT（或反之）
4. Mind Key 已被吊销

修复： 校验你的令牌。参见 Authentication。

为什么收到 404 Not Found？

你用了错误的端点路径。Synapse 只有 GET /endpoints 中列出的路径。

修复： 调用 GET /endpoints 查看所有有效路径。不要猜测。

为什么收到 429 Too Many Requests？

你使用了 ?key= 查询参数认证，它被限速到 60 次/分钟。

修复： 改用 Authorization: Bearer 头（无限制）。

参见 限速。

如何列出所有端点？

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

如何找到正确的端点？

1. 查看 GET /endpoints 获取机器可读列表
2. 查看 GET /help 获取完整 API 文档
3. 浏览 GET /docs 查看文档系统
4. 使用 GET /openapi.json 获取 OpenAPI 3.0 规范

能用 GET 代替 POST 吗？

部分 POST 端点有对应的 GET 版本，供只能使用 URL 的工具使用：

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

通过 GET /endpoints 查看可用的 GET 变体。

如何处理错误？

所有错误都返回 JSON：

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

参见 错误与错误处理。

请求体大小限制是多少？

10 MB。对于更大的 payload（例如文件上传），请使用 multipart 端点。

API 支持 CORS 吗？

支持。所有端点都返回：

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

有 SDK 吗？

有：

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

详见 API 概览。

如何分页？

使用 ?limit= 和 ?offset=：

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

默认 limit：100。最大：500。

能按分类或标签过滤记忆吗？

可以：

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

如何搜索记忆？

两种方式：

1. FTS5 关键词搜索：GET /memory/search?q=docker+swarm
2. 语义搜索：GET /memory/semantic-search?q=container+orchestration

参见 FTS5 搜索 与 语义搜索。

如何更新记忆？

用相同的 category + key 发起 POST /memory — 已存在的记忆会被更新，不会重复。

# 初始存储
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'

# 更新（相同 key）
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael Schäfer"}'

如何删除记忆？

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

能批量删除吗？

可以：

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

下一步

• API 概览
• 错误与错误处理
• Authentication