# 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)。