# REST API 参考

## 自动记忆 API

| 方法 | 路径 | 用途 |
|---|---|---|
| `GET` | `/v1/auto` | 读取当前范围的自动记忆策略 |
| `PUT` | `/v1/auto` | 开启、暂停或设置 ACP 自动记忆路由 |
| `POST` | `/v1/auto/redaction-audits` | 记录脱敏元数据，不包含源内容 |
| `POST` | `/v1/sessions/:id/events` | 本机 ACP 与原生桥接事件传递 |
| `POST` | `/v1/sessions/:id/compile` | 本机 ACP 服务整理记录 |

Auto API 保存用户与工作区策略。本机 ACP 服务负责事件传递与整理；应用接入通过显式会话生命周期接口记录任务。

## Agent 身份与消息

带 API Key 的 Agent REST 请求使用 `X-TokST-Actor: agent`。服务端绑定稳定的 `agt_...` 身份码，客户端提交的 Agent ID 会被拒绝。可使用 `GET /v1/agents?workspace_id=<uuid>`、`POST /v1/agent-messages`、`GET /v1/agent-messages/inbox`、`GET /v1/agent-messages/events`、`POST /v1/agent-messages/:id/acknowledge` 和 `POST /v1/agent-messages/:id/close`。

TokST 在 `https://api.tokst.com/v1` 提供需认证的 REST 接口，并提供一个无需认证的健康检查。生产 API 与网页控制台和远端 MCP 使用相同的用户与工作区访问规则。

机器可读的 OpenAPI 3.1 文档位于 [`https://api.tokst.com/openapi.json`](https://api.tokst.com/openapi.json)，用于程序化客户端读取认证方式、接口类型、请求参数和响应结构。

TokST Local 使用私有 CLI 与 stdio MCP 配置。Local 记忆保存在当前设备的 SQLite 中，不提供网络 REST 监听；云端 API 服务云端工作区与知识库。

决策、架构、会议纪要和任务可在记忆 `content` 字段中使用结构化 Markdown。短事实可使用纯文本。密钥、私钥、原始推理和临时工具输出保留在记忆之外。

## 响应与错误模型

成功响应会返回 OpenAPI 3.1 契约中定义的 JSON 结构。错误响应统一使用：

```json
{
  "error": "quota_exceeded",
  "code": "quota_exceeded",
  "message": "当前月度额度已用尽，请在重置时间后重试或升级容量。"
}
```

`error` 保持兼容；`code` 是机器可读的标准错误码；`message` 提供恢复建议，客户端不应依赖其文本做程序判断。

## 限流响应头

已认证 REST 响应提供以下额度窗口响应头：

| 响应头 | 含义 |
|---|---|
| `RateLimit-Limit` | 当前额度窗口允许的总调用数 |
| `RateLimit-Remaining` | 当前额度窗口剩余调用数 |
| `RateLimit-Reset` | 距离额度窗口重置的秒数 |
| `Retry-After` | HTTP `429` 时返回，表示再次请求前应等待的秒数 |

当 `RateLimit-Remaining` 接近零时应降低调用频率。收到 `429` 后，应等待 `Retry-After` 再继续请求。TokST 当前提供拉取式 REST、MCP 与会话事件接口，暂未提供公开的出站 Webhook。

## 认证

通过 `Authorization` 请求头发送 TokST API 密钥：

```bash
curl https://api.tokst.com/v1/status \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxx"
```

请把 API 密钥保存在密钥管理器或环境变量中。URL 查询认证仅用于旧版 MCP 会话兼容，REST 请求应使用请求头。

## 邀请与权益

| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/v1/referrals/me` | 读取邀请码、统计和掩码后的受邀用户记录 |
| `GET` | `/v1/benefits/me` | 读取 Pro 权益、基础套餐和当前有效套餐 |
| `POST` | `/v1/benefits/:id/activate` | 启用一笔待使用 Pro 权益 |

新账户归因仅在通过邀请链接注册时写入。经此 API、网页、CLI 或 MCP 创建的有效记忆会自动激活已验证的邀请。

## 邀请与权益

| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/v1/referrals/me` | 读取邀请码、统计和掩码后的受邀用户记录 |
| `GET` | `/v1/benefits/me` | 读取 Pro 权益、基础套餐和当前有效套餐 |
| `POST` | `/v1/benefits/:id/activate` | 启用一笔待使用 Pro 权益 |

新账户归因仅在通过邀请链接注册时写入。经此 API、网页、CLI 或 MCP 创建的有效记忆会自动激活已验证的邀请。

## 远端 MCP 的 OAuth

远端 MCP 客户端使用 OAuth 2.1 授权码流程与 PKCE。连接 `https://api.tokst.com/mcp` 后，客户端会发现 `/.well-known/oauth-protected-resource` 和 `/.well-known/oauth-authorization-server`，打开 TokST 完成账户与工作区确认，并保存可刷新的 Bearer 凭据。REST 自动化继续使用 API 密钥。

## 接口清单

### 健康与账户

| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
| `GET` | `/health` | 否 | 服务健康检查 |
| `GET` | `/v1/status` | 是 | 套餐、月用量、存储、个人工作区与知识库配额、团队工作区配额及统计 |

### 智能体与消息

| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/v1/agents` | 列出工作区可信智能体；需要 `workspace_id` |
| `POST` | `/v1/agent-messages` | 以可信智能体身份发送定向或广播消息 |
| `GET` | `/v1/agent-messages/inbox` | 读取可信智能体收件箱；可使用 `workspace_id` 过滤 |
| `GET` | `/v1/agent-messages/events` | 打开可信智能体 SSE 事件流；`workspace_id` 可过滤首次未读快照 |
| `POST` | `/v1/agent-messages/:id/acknowledge` | 确认消息回执 |
| `POST` | `/v1/agent-messages/:id/close` | 关闭消息回执 |

SSE 请求需要 `Authorization: Bearer $TOKST_API_KEY` 和 `X-TokST-Actor: agent`。事件包括 `ready`、`message.created`、`heartbeat` 与 `auth.revoked`；CLI 通过 `tokst agent listen` 处理重连和未读消息补偿。

### 记忆

| 方法 | 路径 | 说明 |
|---|---|---|
| `POST` | `/v1/memories` | 创建记忆并生成嵌入 |
| `GET` | `/v1/memories` | 列出活跃记忆 |
| `GET` | `/v1/memories/context` | 生成分组上下文快照 |
| `POST` | `/v1/memories/search` | 关键词优先搜索，必要时使用作用域语义回退 |
| `GET` | `/v1/memories/:id` | 获取单条记忆及附件元数据 |
| `PATCH` | `/v1/memories/:id` | 更新内容、标题、类型或标签 |
| `POST` | `/v1/memories/:id/verify` | 使用证据、可信度或有效期验证记忆 |
| `POST` | `/v1/memories/:id/supersede` | 将记忆标记为已被新记录替代 |
| `POST` | `/v1/memories/:id/archive` | 归档记忆 |
| `POST` | `/v1/memories/:id/append` | 追加内容并重新生成嵌入 |
| `POST` | `/v1/memories/:id/restore` | 恢复已归档记忆 |
| `DELETE` | `/v1/memories/:id` | 删除记忆及其 R2 对象 |

### 知识库

| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/v1/atlases` | 列出可访问知识库 |
| `GET` | `/v1/atlases/:id` | 获取单个知识库 |
| `POST` | `/v1/atlases` | 创建知识库 |
| `PATCH` | `/v1/atlases/:id` | 重命名或替换路由关键词 |
| `DELETE` | `/v1/atlases/:id` | 删除知识库、其中的记忆及 R2 对象 |

### 工作区

| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/v1/workspaces` | 列出可访问工作区 |
| `GET` | `/v1/workspaces/:id` | 获取单个工作区 |
| `POST` | `/v1/workspaces` | 创建工作区 |
| `DELETE` | `/v1/workspaces/:id` | 删除空工作区；仍有知识库时返回 `409` |
| `GET` | `/v1/workspaces/:id/members` | 列出工作区成员和角色 |
| `GET` | `/v1/workspaces/:id/invitations` | 列出已发出的邀请 |
| `POST` | `/v1/workspaces/:id/invitations` | 创建一个或多个邀请；使用 `emails`、`role`、`expiresInDays` |
| `PATCH` | `/v1/workspaces/:id/members/:userId` | 调整为 `admin` 或 `member`；请求体需要 `confirm: true` |
| `DELETE` | `/v1/workspaces/:id/members/:userId?confirm=true` | 移除成员 |
| `POST` | `/v1/workspaces/:id/leave` | 退出工作区；请求体需要 `confirm: true` |
| `POST` | `/v1/workspaces/:id/owner-transfer` | 转让给已有成员；请求体需要 `userId` 和 `confirm: true` |
| `GET` | `/v1/workspace-invitations` | 列出当前用户待处理的邀请 |
| `POST` | `/v1/workspace-invitations/:id/respond` | 接受或拒绝邀请；请求体需要 `accept` 和 `confirm: true` |
| `DELETE` | `/v1/workspace-invitations/:id` | 撤销待处理邀请；携带 `?confirm=true` |

## 记忆请求

### 创建

```bash
curl -X POST https://api.tokst.com/v1/memories \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "周五生产部署需要审批。",
    "type": "decision",
    "title": "发布策略",
    "tags": ["deploy", "policy"],
    "atlasId": "00000000-0000-0000-0000-000000000000"
  }'
```

`content` 为必填项，`type` 默认为 `note`。支持 `fact`、`decision`、`preference`、`task`、`architecture` 和 `note`。提供 `workspaceId` 时必须与目标知识库匹配。

### 列表与上下文

```bash
# type 支持单值或逗号分隔列表；limit 范围为 1-100
curl "https://api.tokst.com/v1/memories?atlas_id=$ATLAS_ID&type=decision,note&limit=20" \
  -H "Authorization: Bearer $TOKST_API_KEY"

curl "https://api.tokst.com/v1/memories/context?atlas_id=$ATLAS_ID&limit=10" \
  -H "Authorization: Bearer $TOKST_API_KEY"
```

### 搜索

```bash
curl -X POST https://api.tokst.com/v1/memories/search \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"发布审批规则","atlas_id":"'$ATLAS_ID'","mode":"auto","limit":10}'
```

`mode` 支持 `auto`、`keyword`、`semantic` 和 `hybrid`，默认使用 `auto`。响应同时包含 `mode` 与 `meta`，其中记录请求/最终模式、缓存层级、强关键词判定和各阶段耗时。

- `keyword` 返回标题和正文的排序结果。
- `semantic` 只返回向量结果。
- `hybrid` 始终使用 RRF 融合两路结果。
- `keyword_fallback` 表示 embedding 在硬超时或服务异常后完成关键词降级。

### 更新与追加

```bash
curl -X PATCH https://api.tokst.com/v1/memories/mem_xxx \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"更新后的策略","type":"decision","tags":[]}'

curl -X POST https://api.tokst.com/v1/memories/mem_xxx/append \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"已由发布负责人批准。"}'
```

空 `tags` 数组会清除现有标签。内容更新和追加都会重新生成语义嵌入。

### 验证与替代

```bash
curl -X POST https://api.tokst.com/v1/memories/mem_xxx/verify \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"evidence":"https://example.com/policy","confidence":0.95,"validUntil":"2027-01-01T00:00:00Z"}'

curl -X POST https://api.tokst.com/v1/memories/mem_old/supersede \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"replacementMemoryId":"mem_new"}'
```

验证会将记录标记为已审核并保存支撑元数据。替代会将旧记录标记为 `superseded`，同时保留与新记忆的关联。

## 知识库与工作区请求

```bash
curl -X POST https://api.tokst.com/v1/workspaces \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"平台团队"}'

curl -X POST https://api.tokst.com/v1/atlases \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"生产环境","workspaceId":"'$WORKSPACE_ID'","keywords":["deploy","release"]}'
```

删除知识库会级联删除记忆和附件对象。工作区删除保持非级联行为：先删除其中的知识库，再删除空工作区。

## 文件工作流

文件传输使用统一 Supabase Edge Function `/functions/v1/tokst`。这些路由接受 `POST /auth/exchange` 返回的短期用户 JWT；普通 REST 路由接受 `tk_live_...` API 密钥。

| 方法 | Edge 路径 | 用途 |
|---|---|---|
| `POST` | `/auth/exchange` | 用 API 密钥换取用户 JWT |
| `POST` | `/storage/upload-url` | 校验所有权和配额，创建待处理附件，返回签名 PUT URL |
| `POST` | `/storage/confirm-upload` | 确认 R2 对象存在，记录真实大小和 MIME，激活附件 |
| `GET` | `/storage/download-url` | 返回有效期 15 分钟的签名下载 URL |
| `POST` | `/storage/delete-objects` | 由服务器管理且校验所有权的对象清理 |

CLI、网页控制台和 MCP 工具已经实现该工作流。完整示例见[文件附件](/docs/attachments)。

## 响应与错误模型

成功响应包含 `ok: true`，错误响应包含稳定的 `error` 代码。

| 状态 | 含义 | 常见代码 |
|---|---|---|
| `400` | 请求体、查询或资源关系无效 | `invalid_query`、`atlas_workspace_mismatch` |
| `401` | 缺少或使用了无效 API 密钥 | `missing_api_key`、`invalid_key` |
| `403` | 密钥已撤销或对象访问被拒绝 | `revoked`、`forbidden` |
| `404` | 路由或可访问资源不存在 | `not_found` |
| `409` | 当前资源状态阻止操作 | `workspace_not_empty`、上传对象不存在 |
| `429` | 达到月配额或滚动频率限制 | `quota_exceeded`、`rate_limited` |
| `500` | 服务器端故障 | `internal_error` |

所有资源查询都受认证用户和工作区成员关系约束。作用域外的资源不会作为可访问资源返回。

## 版本与废弃策略

TokST 将稳定的云端 REST 路由保持在 `/v1`。新增字段、端点和可选请求参数可在
`/v1` 内发布。移除字段、改变字段语义或改变授权行为的调整会使用新的主版本路径。

TokST 会在本参考文档和版本历史中，至少提前 90 天公告端点或字段的计划退役。
公告期内，受影响的 HTTP 响应会在适用时返回 `Deprecation: true` 与 `Sunset` 日期。
客户端应将未知响应字段视为前向兼容，并使用稳定的 `error` 代码实现恢复逻辑。

## MCP 端点

同一主机在 `https://api.tokst.com/mcp` 提供完整的 46 个 MCP Streamable HTTP 工具。参阅 [MCP 参考](/docs/mcp)；部署可设置 `TOKST_MCP_TOOLSET=core` 使用聚焦的 11 个记忆工具。

## 会话记忆 API

智能体请求携带 `X-TokST-Actor: agent`，TokST 自动注入可信 `agt_...` 身份。

| 方法 | 端点 | 用途 |
|---|---|---|
| `POST` | `/v1/sessions` | 创建会话并返回范围内上下文 |
| `GET` | `/v1/sessions` | 按工作区、知识库、状态和范围列出会话 |
| `POST` | `/v1/sessions/bulk` | 批量归档、恢复或删除最多 100 条已选择会话 |
| `GET` | `/v1/sessions/candidates` | 按工作区、知识库、状态和范围列出待审核候选 |
| `GET` | `/v1/sessions/:id` | 获取会话、候选、检查点和上下文 |
| `POST` | `/v1/sessions/:id/units` | 在自动会话中创建或恢复一个持久任务单元 |
| `POST` | `/v1/sessions/:id/candidates` | 保存候选记忆 |
| `POST` | `/v1/sessions/:id/units/:unitId/finalize` | 在会话保持活动时将一个任务单元保存为关联正式记忆 |
| `POST` | `/v1/sessions/:id/complete` | 最后一个任务单元保存后关闭自动会话 |
| `POST` | `/v1/sessions/:id/checkpoints` | 保存进度摘要 |
| `POST` | `/v1/sessions/:id/finalize` | 写入快照并编译候选内容 |
| `POST` | `/v1/sessions/:id/reopen` | 恢复 ACP 会话并更新关联的自动记忆 |
| `POST` | `/v1/sessions/:id/automatic-memory/revert` | 归档关联自动记忆并保留会话审计 |
| `POST` | `/v1/sessions/:id/candidates/:candidateId/moderate` | 编译、驳回或撤销候选 |
| `POST` | `/v1/sessions/:id/archive` | 归档或恢复会话 |

自动桥接器使用任务单元：独立任务创建一条正式记忆，同一任务的追问更新对应单元。会话生命周期、幂等行为、智能体交接、审核权限、本地行为和后台治理请阅读[会话记忆指南](/docs/sessions)。