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_... 身分。

自動橋接器使用任務單元：獨立任務建立一筆正式記憶，同一任務的追問更新對應單元。工作階段生命週期、冪等行為、智能體交接、審核權限、本機行為和後台治理請閱讀工作階段記憶指南。