REST API 參考

穩定相容介面。 TokST 在 V0.9.0 繼續維護既有 REST 路由與契約。目前產品開發聚焦控制台、CLI、已連線智能體工作階段、長期記憶與使用者明確指派的任務。

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-After`	HTTP `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 管理長期知識。