開始

請求慣例

tennnzo API 的共通規則：網址、標頭、錯誤格式與錯誤碼、每把金鑰每分鐘的速率上限、Idempotency-Key 冪等重送、時間格式、請求大小上限、重複稿，以及系統記錄哪些請求資訊。

Agent API 與個人 API 共用大部分的規則。這頁一次說清楚，各頁就不再重複。

網址與格式#

	網址前綴
Agent API	`https://api.tennnzo.com/api/agent/v1`
個人 API	`https://api.tennnzo.com/api/user/v1`
MCP	`https://api.tennnzo.com/api/mcp`

任何 tennnzo 網域都可以打，組織與工作區只看金鑰。
JSON 進、JSON 出。送內容時帶 Content-Type: application/json。
唯一的例外是上傳圖檔本身：請求本文就是檔案，見圖片上傳與順序。

標頭#

標頭	方向	說明
`Authorization: Bearer <金鑰>`	請求	每個請求都要帶
`Idempotency-Key`	請求	Agent API 的寫入請求可以帶，見下方「冪等」
`X-Request-Id`	回應	每個回應都有，回報問題時附上它
`Retry-After`	回應	被限速（429）時，要等幾秒
`Idempotent-Replayed: true`	回應	這是同一個 `Idempotency-Key` 第一次的結果重播

錯誤格式#

錯誤一律長這樣，message 寫原因，request_id 和回應標頭的 X-Request-Id 相同：

json

{ "error": { "code": "rejected", "message": "the draft is waiting for a rewrite", "request_id": "req_…" } }

Agent API 的錯誤#

HTTP	code	意思
400	`invalid_request`	參數格式不對，`message` 會指出哪個欄位
401	`unauthorized`	沒帶金鑰、格式錯、不存在或已撤銷
403	`forbidden`	金鑰的角色沒有這個範圍，或不是你負責的帳號、稿
404	`not_found`	找不到，包含不屬於你的
409	`ambiguous_code`	舊編號在多個平台重複，請加 `platform`
409	`idempotency_in_progress`	同一個 `Idempotency-Key` 的第一個請求還在處理
413	`payload_too_large`	內容或圖片太大
422	`rejected`	規則不允許，`message` 是原因，例如稿在等重寫、新內文和退回時一樣
422	`idempotency_mismatch`	同一個 `Idempotency-Key` 用在不同內容
429	`rate_limited`	超過每把金鑰每分鐘的上限，看 `Retry-After`
500	`internal`	伺服器錯誤，可以用同一個 `Idempotency-Key` 重試

個人 API 的錯誤#

HTTP	code	意思
400	`invalid_request`	參數格式不對，`message` 會指出哪個欄位
401	`unauthorized`	沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員
403	`forbidden`	你的角色不能做這件事
404	`not_found`	找不到，或你看不到（不會說是哪一種）
413	`payload_too_large`	請求內容太大
422	`rejected`	規則不允許，`message` 是原因
429	`rate_limited`	太快了，看 `Retry-After` 秒數再試
500	`internal`	伺服器錯誤

遇到錯誤怎麼辦#

422：讀 message，照原因改。不要換個方式硬送。
403、404：那不是你的帳號或稿，停手回報。
429：等 Retry-After 秒再繼續，不要狂重試。
500：用同一個 Idempotency-Key（MCP 用同一個 request_id）重試，最多兩次，還不行就停下回報。

速率上限#

金鑰	預設上限
Agent 金鑰	每把每分鐘 120 次
個人金鑰	每把每分鐘 60 次

MCP 的請求也算在同一把金鑰的額度裡。超過時回 429 rate_limited，Retry-After 是要等的秒數（到這一分鐘結束）。

冪等#

Agent API 的 POST 與 PUT 可以帶 Idempotency-Key，網路斷了重送也不會多寫一筆。MCP 的寫入工具用參數 request_id，作用完全一樣。

值是 1 到 200 個可見 ASCII 字元。建議用 <run_id>-<編號>-<序號>，例如 run-20261005-TW-T014-1。
範圍是同一個 Agent、同一個鍵，24 小時內有效。
同一個鍵、同樣內容重送：回第一次的結果，標頭帶 Idempotent-Replayed: true。
同一個鍵、不同內容：422 idempotency_mismatch。
第一次還沒跑完又送一次：409 idempotency_in_progress。

只有成功（2xx）才佔用這個鍵。 批次裡只要有一筆寫入成功也算成功。整個被拒（4xx，什麼都沒寫）、5xx 與 429 都不佔用，修好內容後可以用同一個鍵重送。

bash

curl -s https://api.tennnzo.com/api/agent/v1/drafts \
  -H "Authorization: Bearer $TNZ_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: run-20261005-TW-T014-1" \
  -d '{"code":"TW-T014","body":"內文……","topic":"週末","planned_at":"2026-10-05 20:00"}'

提示不要為了「確認有沒有成功」再呼叫一次。看回傳就好；網路真的斷了，才用同一個鍵重送。

時間格式#

Agent 送來的所有時間都收兩種寫法：planned_at、scheduled_for、published_at、排程執行的 started_at 與 finished_at、成效的 captured_at、帳號狀態的 occurred_at、代為登記的 effective_at、卡片的 due_at。

寫法	例子	怎麼解讀
帶時區的 ISO	`2026-10-05T20:00:00+08:00`、`2026-10-05T12:00Z`、`2026-10-05 20:00:00+08`	照寫的時區
不帶時區	`2026-10-05 20:00`、`2026-10-05 20:00:42`、`2026-10-05T20:00`	帳號市場的當地時間

秒與毫秒可有可無。日期會檢查，2/30、24:00 這種不存在的時間會被擋。

不帶時區、又沒有對應帳號時：

排程執行用該排程登記的 timezone。
成效用這批帳號共同的市場；不同市場混在一批時用台北時間。
代為登記待裁決、看板卡，以及卡片期限沒有對應帳號時，用台北時間。
知識同步的 started_at 用台北時間。

格式錯的時間只擋那一筆：回報貼文、排程執行會逐筆告訴你原因，訊息裡會列出可用的格式。

注意個人 API 的時間（例如排程的 scheduled_for）只收帶時區的 ISO，例如 2026-10-05T20:00:00+08:00。

請求大小#

Agent API 一個請求的本文上限是 4.5 MB，超過回 413 payload_too_large。圖片請用兩段式上傳，不要把大圖轉成 base64 塞進請求，見圖片上傳與順序。

重複的稿#

同一個帳號編號、內文完全相同、還沒發出去的稿不會建第二篇。這時回 200，duplicate: true，指向原本那篇。

系統記錄什麼#

每個請求（包括每次 MCP 工具呼叫）記一筆：誰、哪個路徑或工具、狀態碼、耗時。不記內容，不記標頭，也不記金鑰。