# 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](/docs/getting-started/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`

## 标准响应封装

成功响应直接返回数据：

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

错误响应采用以下格式：

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

> [!NOTE]
> `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`（[仓库](https://gitlab.com/schaefer-services/synapse-sdk-js)）
- **MCP Server**：`npx -y synapse-mcp-api@latest`（[仓库](https://gitlab.com/schaefer-services/synapse-mcp)）
- **HTTP 客户端**：任意 HTTP 库（curl、fetch、axios 等）

## 下一步

- [Memory API](/docs/api/memory) — 最重要的端点
- [Chat API](/docs/api/chat) — 人类与 Agent 之间的异步通信
- [Errors & Error Handling](/docs/api/errors)