TokST 面向人类与 AI 智能体的持久上下文

REST API 参考

稳定兼容接口。 TokST 在 V0.9.0 继续维护既有 REST 路由与契约。云端 MCP 是面向智能体的公开长期知识接口；本参考文档覆盖兼容 REST 知识接口。

API 范围

TokST 将此 REST API 作为长期知识的稳定兼容接口发布。新的智能体接入使用云端 MCP 完成记忆、上下文、知识库、工作区治理、证据文件和账户状态操作。

已连接 Runtime API 服务于 TokST CLI、设备桥接、自动会话、智能体通信和任务投递。它们是控制台与已连接 CLI 的内部实现接口，不构成公开接入契约。

认证

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

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

请把 API 密钥保存在密钥管理器或环境变量中。REST 请求使用 Authorization 请求头。

远端 MCP 的 OAuth

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

接口清单

健康与账户

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

记忆

方法路径说明
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恢复已归档记忆

记忆生命周期

记忆通过 archive 与 restore 保持可逆变更。公开兼容 API 不提供永久删除记忆的接口。用户只能在 Dashboard 的归档视图中对已归档记忆手工确认永久清除。

知识库

方法路径说明
GET/v1/atlases列出可访问知识库
GET/v1/atlases/:id获取单个知识库
POST/v1/atlases创建知识库
PATCH/v1/atlases/:id重命名或替换路由关键词
POST/v1/atlases/:id/archive归档或恢复知识库

工作区

方法路径说明
GET/v1/workspaces列出可访问工作区
GET/v1/workspaces/:id获取单个工作区
POST/v1/workspaces创建工作区
POST/v1/workspaces/:id/archive归档或恢复工作区
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

记忆请求

创建

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 时必须与目标知识库匹配。

列表与上下文

# 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"

搜索

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 在硬超时或服务异常后完成关键词降级。

更新与追加

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 数组会清除现有标签。内容更新和追加都会重新生成语义嵌入。

验证与替代

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，同时保留与新记忆的关联。

知识库与工作区请求

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 工具已经实现该工作流。完整示例见文件附件。

响应与错误模型

成功响应包含 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

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

限流响应头

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

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

当 RateLimit-Remaining 接近零时应降低调用频率。收到 429 后，应等待 Retry-After 再继续请求。

版本与废弃策略

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

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

MCP 端点

同一主机在 https://api.tokst.com/mcp 提供完整的 32 个 MCP Streamable HTTP 工具。参阅 MCP 参考。

已连接 Runtime

自动会话、智能体通信、任务投递和任务执行在 CLI 连接设备后由已认证 TokST Runtime 处理。这些私有 Runtime API 由控制台和已连接 CLI 使用；外部集成通过云端 MCP 管理长期知识。