{"title":"API 概览与基础 URL","slug":"overview","category":"api","summary":"一目了然地查看所有 Synapse API 端点、基础 URL、认证模式与响应格式。","audience":["human","llm"],"tags":["api","overview","endpoints"],"difficulty":"beginner","updated":"2026-06-27","word_count":364,"read_minutes":2,"llm_context":"Base URL: https://synapse.schaefer.zone\nAuth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)\n OR ?key=YOUR_MIND_KEY (query, 60 req/min)\nAll responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)\nAll 404 responses mean the path does not exist — do NOT guess paths.\nGET /endpoints returns machine-readable list of all valid endpoints.\n","lang":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# API 概览与基础 URL\n\nSynapse API 是一个 RESTful HTTP API。所有端点均返回 JSON（除非另有说明）。本页面涵盖了在深入具体端点之前所需的基础知识。\n\n## 基础 URL\n\n```\nhttps://synapse.schaefer.zone\n```\n\n本指南中所有路径均相对于此基础 URL。对于自托管实例，请替换为你自己的 URL。\n\n## 认证\n\n两种方式，均通过 `Authorization` 头发送：\n\n```\nAuthorization: Bearer YOUR_MIND_KEY # 用于数据端点\nAuthorization: Bearer YOUR_JWT # 用于账户端点\n```\n\n或通过查询参数发送（限速 60 次/分钟）：\n\n```\n?key=YOUR_MIND_KEY\n```\n\n详情请参阅 [Authentication](/docs/getting-started/authentication)。\n\n## 端点分组\n\n| 分组 | 认证 | 说明 |\n|-------|------|-------------|\n| Public | 无 | 落地页、健康检查、OpenAPI、文档 |\n| Memory | Mind Key | CRUD、搜索、同步、向量嵌入 |\n| Chat | Mind Key / JWT | 人与 Agent 之间的异步消息 |\n| Tasks | Mind Key | 任务管理 |\n| Scripts | Mind Key / JWT | 持久化脚本存储 |\n| Scheduler | Mind Key | Cron 任务与变量 |\n| Webhooks | Mind Key | 事件触发的 HTTP 回调 |\n| Computers | Mind Key / JWT | 远程计算机控制 |\n| User/Minds | JWT | 账户与 Mind 管理 |\n| Sharing | JWT | 用户之间的 Mind 共享 |\n| Push | JWT | Web Push 订阅 |\n| Tools | 无 | 时间、计算、随机（公共工具） |\n\n## 响应格式\n\n- **JSON**（默认）：`{ \"key\": \"value\", ... }`\n- **纯文本**：`/memory/recall` 返回为 LLM 优化的文本\n- **HTML**：`/`、`/docs`、`/human`、`/support`、`/playground`\n\n## 标准响应封装\n\n成功响应直接返回数据：\n\n```json\n{ \"id\": \"mem_001\", \"status\": \"stored\" }\n```\n\n错误响应采用以下格式：\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\n> [!NOTE]\n> `docs` 字段会针对常见错误链接到相关文档。\n\n## HTTP 状态码\n\n| 状态码 | 含义 |\n|------|---------|\n| 200 | 成功（GET、PUT） |\n| 201 | 已创建（POST） |\n| 204 | 无内容（DELETE） |\n| 400 | 错误请求（校验错误） |\n| 401 | 未授权（令牌缺失或无效） |\n| 403 | 禁止访问（令牌类型错误） |\n| 404 | 未找到（路径不存在） |\n| 409 | 冲突（重复） |\n| 429 | 请求过多（触发限速） |\n| 500 | 服务器错误 |\n\n## 可发现性端点\n\n| 端点 | 用途 |\n|----------|---------|\n| `GET /` | 落地页（为 LLM 优化） |\n| `GET /endpoints` | 所有端点的机器可读列表 |\n| `GET /endpoints?format=text` | 纯文本端点列表 |\n| `GET /openapi.json` | OpenAPI 3.0 规范 |\n| `GET /help` | 完整 API 文档（HTML） |\n| `GET /help?format=json` | JSON 格式 API 文档 |\n| `GET /docs` | 文档系统（HTML） |\n| `GET /docs?format=json` | 文档索引（JSON） |\n| `GET /docs?format=text&scope=all` | 全部文档作为一个文本块 |\n| `GET /playground` | 交互式 API 调试页面 |\n\n## 限速\n\n| 认证方式 | 限制 |\n|-------------|-------|\n| Mind Key（header） | 无限制 |\n| Mind Key（?key=） | 每个 IP 60 次/分钟 |\n| JWT（header） | 无限制 |\n| 公共端点 | 无限制 |\n\n受限速影响的响应会包含：\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30 (仅 429 时)\n```\n\n## 分页\n\n列表端点支持 `?limit=` 与 `?offset=`：\n\n```\nGET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending\n```\n\n默认 limit：100。最大 limit：500。\n\n## CORS\n\n所有端点都为浏览器客户端支持 CORS：\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, Mcp-Session-Id, Mcp-Tool-Profile\n```\n\n## SDK 与客户端\n\n- **Node.js SDK**：`npm install synapse-memory-sdk`（[仓库](https://gitlab.com/schaefer-services/synapse-sdk-js)）\n- **MCP Server**：`npx -y synapse-mcp-api@latest`（[仓库](https://gitlab.com/schaefer-services/synapse-mcp)）\n- **HTTP 客户端**：任意 HTTP 库（curl、fetch、axios 等）\n\n## 下一步\n\n- [Memory API](/docs/api/memory) — 最重要的端点\n- [Chat API](/docs/api/chat) — 人类与 Agent 之间的异步通信\n- [Errors & Error Handling](/docs/api/errors)\n","content_html":"

API 概览与基础 URL

\n

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

\n

基础 URL

\n
https://synapse.schaefer.zone

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

\n

认证

\n

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

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

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

\n
?key=YOUR_MIND_KEY

详情请参阅 Authentication。

\n

端点分组

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
分组认证说明
Public无落地页、健康检查、OpenAPI、文档
MemoryMind KeyCRUD、搜索、同步、向量嵌入
ChatMind Key / JWT人与 Agent 之间的异步消息
TasksMind Key任务管理
ScriptsMind Key / JWT持久化脚本存储
SchedulerMind KeyCron 任务与变量
WebhooksMind Key事件触发的 HTTP 回调
ComputersMind Key / JWT远程计算机控制
User/MindsJWT账户与 Mind 管理
SharingJWT用户之间的 Mind 共享
PushJWTWeb Push 订阅
Tools无时间、计算、随机（公共工具）
\n

响应格式

\n\n

标准响应封装

\n

成功响应直接返回数据：

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

错误响应采用以下格式：

\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}
`docs` 字段会针对常见错误链接到相关文档。

HTTP 状态码

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

可发现性端点

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

限速

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

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

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30  (仅 429 时)

分页

\n

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

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

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

\n

CORS

\n

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

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

SDK 与客户端

\n\n

下一步

\n\n","urls":{"html":"/docs/api/overview","text":"/docs/api/overview?format=text","json":"/docs/api/overview?format=json","llm":"/docs/api/overview?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}