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

KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)
      OR ?key=YOUR_MIND_KEY (query, 60 req/min)
All responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)
All 404 responses mean the path does not exist — do NOT guess paths.
GET /endpoints returns machine-readable list of all valid endpoints.

API 概览与基础 URL
Synapse API 是一个 RESTful HTTP API。所有端点均返回 JSON（除非另有说明）。本页面涵盖了在深入具体端点之前所需的基础知识。
基础 URL
[CODE BLOCK]
本指南中所有路径均相对于此基础 URL。对于自托管实例，请替换为你自己的 URL。
认证
两种方式，均通过  头发送：
[CODE BLOCK]
或通过查询参数发送（限速 60 次/分钟）：
[CODE BLOCK]
详情请参阅 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（默认）：
- 纯文本： 返回为 LLM 优化的文本
- HTML：、、、、
标准响应封装
成功响应直接返回数据：
[CODE BLOCK]
错误响应采用以下格式：
[CODE BLOCK]
> [!NOTE]
>  字段会针对常见错误链接到相关文档。
HTTP 状态码
| 状态码 | 含义 |
|------|---------|
| 200 | 成功（GET、PUT） |
| 201 | 已创建（POST） |
| 204 | 无内容（DELETE） |
| 400 | 错误请求（校验错误） |
| 401 | 未授权（令牌缺失或无效） |
| 403 | 禁止访问（令牌类型错误） |
| 404 | 未找到（路径不存在） |
| 409 | 冲突（重复） |
| 429 | 请求过多（触发限速） |
| 500 | 服务器错误 |
可发现性端点
| 端点 | 用途 |
|----------|---------|
|  | 落地页（为 LLM 优化） |
|  | 所有端点的机器可读列表 |
|  | 纯文本端点列表 |
|  | OpenAPI 3.0 规范 |
|  | 完整 API 文档（HTML） |
|  | JSON 格式 API 文档 |
|  | 文档系统（HTML） |
|  | 文档索引（JSON） |
|  | 全部文档作为一个文本块 |
|  | 交互式 API 调试页面 |
限速
| 认证方式 | 限制 |
|-------------|-------|
| Mind Key（header） | 无限制 |
| Mind Key（?key=） | 每个 IP 60 次/分钟 |
| JWT（header） | 无限制 |
| 公共端点 | 无限制 |
受限速影响的响应会包含：
[CODE BLOCK]
分页
列表端点支持  与 ：
[CODE BLOCK]
默认 limit：100。最大 limit：500。
CORS
所有端点都为浏览器客户端支持 CORS：
[CODE BLOCK]
SDK 与客户端
- Node.js SDK：（仓库）
- MCP Server：（仓库）
- HTTP 客户端：任意 HTTP 库（curl、fetch、axios 等）
下一步
- Memory API — 最重要的端点
- Chat API — 人类与 Agent 之间的异步通信
- Errors & Error Handling