REST API 参考

自动记忆 API

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，用于程序化客户端读取认证方式、接口类型、请求参数和响应结构。

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

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

响应与错误模型

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

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

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

限流响应头

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

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

认证

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

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

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

邀请与权益

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

邀请与权益

新账户归因仅在通过邀请链接注册时写入。经此 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 密钥。

接口清单

健康与账户

智能体与消息

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

记忆

知识库

工作区

记忆请求

创建

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 密钥。

CLI、网页控制台和 MCP 工具已经实现该工作流。完整示例见文件附件。

响应与错误模型

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

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

版本与废弃策略

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

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

MCP 端点

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

会话记忆 API

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

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