Skip to main content

API 概览与基础 URL

beginner 🤖 LLM 友好 2 分钟 · 364 字 更新于： 2026-06-27 中文

一目了然地查看所有 Synapse API 端点、基础 URL、认证模式与响应格式。

阅读本文： 📄 纯文本 ⚡ JSON 🤖 LLM 格式
语言: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

API 概览与基础 URL

Synapse API 是一个 RESTful HTTP API。所有端点均返回 JSON（除非另有说明）。本页面涵盖了在深入具体端点之前所需的基础知识。

基础 URL

https://synapse.schaefer.zone

本指南中所有路径均相对于此基础 URL。对于自托管实例，请替换为你自己的 URL。

认证

两种方式，均通过 Authorization 头发送：

Authorization: Bearer YOUR_MIND_KEY    # 用于数据端点
Authorization: Bearer YOUR_JWT          # 用于账户端点

或通过查询参数发送（限速 60 次/分钟）：

?key=YOUR_MIND_KEY

详情请参阅 Authentication。

端点分组

分组 认证 说明
Public 无 落地页、健康检查、OpenAPI、文档
Memory Mind Key CRUD、搜索、同步、向量嵌入
Chat Mind Key / JWT 人与 Agent 之间的异步消息
Tasks Mind Key 任务管理
Scripts Mind Key / JWT 持久化脚本存储
Scheduler Mind Key Cron 任务与变量
Webhooks Mind Key 事件触发的 HTTP 回调
Computers Mind Key / JWT 远程计算机控制
User/Minds JWT 账户与 Mind 管理
Sharing JWT 用户之间的 Mind 共享
Push JWT Web Push 订阅
Tools 无 时间、计算、随机（公共工具）

响应格式

  • JSON（默认）：{ "key": "value", ... }
  • 纯文本：/memory/recall 返回为 LLM 优化的文本
  • HTML：/、/docs、/human、/support、/playground

标准响应封装

成功响应直接返回数据：

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

错误响应采用以下格式：

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}
`docs` 字段会针对常见错误链接到相关文档。

HTTP 状态码

状态码 含义
200 成功（GET、PUT）
201 已创建（POST）
204 无内容（DELETE）
400 错误请求（校验错误）
401 未授权（令牌缺失或无效）
403 禁止访问（令牌类型错误）
404 未找到（路径不存在）
409 冲突（重复）
429 请求过多（触发限速）
500 服务器错误

可发现性端点

端点 用途
GET / 落地页（为 LLM 优化）
GET /endpoints 所有端点的机器可读列表
GET /endpoints?format=text 纯文本端点列表
GET /openapi.json OpenAPI 3.0 规范
GET /help 完整 API 文档（HTML）
GET /help?format=json JSON 格式 API 文档
GET /docs 文档系统（HTML）
GET /docs?format=json 文档索引（JSON）
GET /docs?format=text&scope=all 全部文档作为一个文本块
GET /playground 交互式 API 调试页面

限速

认证方式 限制
Mind Key（header） 无限制
Mind Key（?key=） 每个 IP 60 次/分钟
JWT（header） 无限制
公共端点 无限制

受限速影响的响应会包含：

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (仅 429 时)

分页

列表端点支持 ?limit= 与 ?offset=：

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

默认 limit：100。最大 limit：500。

CORS

所有端点都为浏览器客户端支持 CORS：

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

SDK 与客户端

  • Node.js SDK：npm install synapse-memory-sdk（仓库）
  • MCP Server：npx -y synapse-mcp-api@latest（仓库）
  • HTTP 客户端：任意 HTTP 库（curl、fetch、axios 等）

下一步

← 返回 API 参考