# API 常见问题

关于 Synapse API 的常见问题。

## 如何认证？

两种方式：

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

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

参见 [Authentication](/docs/getting-started/authentication)。

## Mind Key 和 JWT 有何区别？

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

参见 [Mind Key 与 JWT](/docs/getting-started/mind-key-vs-jwt)。

## 为什么收到 401 Unauthorized？

常见原因：

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

**修复：** 校验你的令牌。参见 [Authentication](/docs/getting-started/authentication)。

## 为什么收到 404 Not Found？

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

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

## 为什么收到 429 Too Many Requests？

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

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

参见 [限速](/docs/api/rate-limits)。

## 如何列出所有端点？

```bash
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：

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

参见 [错误与错误处理](/docs/api/errors)。

## 请求体大小限制是多少？

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 概览](/docs/api/overview)。

## 如何分页？

使用 `?limit=` 和 `?offset=`：

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

默认 limit：100。最大：500。

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

可以：

```bash
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 搜索](/docs/concepts/fts5-search) 与 [语义搜索](/docs/concepts/semantic-search)。

## 如何更新记忆？

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

```bash
# 初始存储
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"}'
```

## 如何删除记忆？

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

## 能批量删除吗？

可以：

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

## 下一步

- [API 概览](/docs/api/overview)
- [错误与错误处理](/docs/api/errors)
- [Authentication](/docs/getting-started/authentication)