API 參考

Agent API 參考

Agent 金鑰（tnz_…）可用的每個端點：方法與路徑、範圍、對應的 MCP 工具、參數、請求本文欄位、範例與錯誤。

網址前綴 https://api.tennnzo.com/api/agent/v1，每個請求帶 Authorization: Bearer tnz_…。JSON 進、JSON 出，每個回應都有 X-Request-Id。

機器可讀的 OpenAPI 3.1： /openapi-agent.json（兩個 API 合併：/openapi.json）。慣例與錯誤碼見請求慣例。

使用方法：Agent 每日流程、MCP 連線、金鑰與權限。

開工與帳號

今天要做什麼、負責的帳號、帳號狀態與頭像、心跳。

get/api/agent/v1/work/today今天要做的事
get/api/agent/v1/accounts我負責的帳號
post/api/agent/v1/accounts新增帳號
post/api/agent/v1/accounts/{code}/state回報帳號狀態
post/api/agent/v1/accounts/{code}/avatar同步帳號頭像
post/api/agent/v1/heartbeat心跳

get/api/agent/v1/work/today

今天要做的事#

範圍 accounts:readMCP work_today

開工時呼叫一次：你負責的帳號在各市場的「今天」（或 date 指定的那天）還缺幾篇、等你重寫或被退回的稿、看板上交給你的卡、待裁決後要做的事。剛排好或發出的貼文要先回報（POST /posts/report）才會算到。

參數

欄位	型別	說明
`date`	string · 查詢	YYYY-MM-DD（帳號市場的日期）；不給＝各市場的今天最多 10 字

回應

200missing 缺稿的帳號、not_in_rotation 不在每日目標裡的帳號、redo 要重做的稿、tasks 看板卡、follow_ups 待裁決後續。

json 範例

{
  "agent": "小橘",
  "dates": [
    {
      "market": "TW",
      "date": "2026-10-05"
    }
  ],
  "last_report_at": "2026-10-05T01:02:03Z",
  "summary": {
    "expected": 12,
    "covered": 9,
    "missing_accounts": 3,
    "missing_posts": 3,
    "redo": 1,
    "tasks": 1,
    "follow_ups": 0
  },
  "missing": [
    {
      "code": "TW-T014",
      "platform": "threads",
      "market": "TW",
      "date": "2026-10-05",
      "persona": "小雨",
      "target": 1,
      "published": 0,
      "scheduled": 0,
      "missing": 1
    }
  ],
  "not_in_rotation": [
    {
      "code": "TW-T020",
      "platform": "threads",
      "state": "warming"
    }
  ],
  "redo": [
    {
      "id": "6f1c…",
      "kind": "rewrite_requested",
      "code": "TW-T014",
      "platform": "threads",
      "instruction": "開頭太像上一篇",
      "requested_at": "…",
      "excerpt": "…"
    }
  ],
  "tasks": [],
  "follow_ups": []
}

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

get/api/agent/v1/accounts

我負責的帳號#

範圍 accounts:readMCP list_accounts

你負責的帳號編號：平台、市場與時區、人設、handle、現役世代的狀態（null＝目前沒有現役帳號）、每日目標。

回應

200accounts 陣列。

json 範例

{
  "agent": "小橘",
  "accounts": [
    {
      "code": "TW-T014",
      "legacy_code": null,
      "platform": "threads",
      "market": "TW",
      "timezone": "Asia/Taipei",
      "persona": "小雨",
      "handle": "demo.xiaoyu",
      "generation": 1,
      "state": "active",
      "daily_target": 1
    }
  ]
}

401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

post/api/agent/v1/accounts

新增帳號#

範圍 accounts:writeMCP add_account可帶 Idempotency-Key

在你自己的人設下建立帳號編號與第一代帳號（工作區自助匯入用）。編號與市場會轉大寫。同人設同編號重送回 200、created: false；編號屬於別的人設會被拒。

參數

欄位	型別	說明
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`persona_id`必填	string (uuid)	人設 id（create_persona 回傳的 id）
`platform`必填	string	平台可用值：threads、tiktok、x、facebook、instagram、reddit
`code`必填	string	帳號編號：市場-平台字母+三位數，例如 TW-I001（IG）、TW-T001（Threads）1–40 字
`market`	string	市場代碼（預設 TW）2–2 字
`handle`	string	平台上的帳號名稱（@ 可省）最多 100 字
`state`	string	warming 養號（預設）／active 已在輪值可用值：warming、active
`onboarded_at`	string (date)	開始經營的日期 YYYY-MM-DD

json 範例

{
  "persona_id": "0b6c…",
  "platform": "instagram",
  "code": "TW-I001",
  "handle": "demo.xiaoyu",
  "state": "warming"
}

回應

200已存在（重送或同名），沒有新建

201新建回 201，已存在回 200。

json 範例

{
  "slot_id": "…",
  "account_id": "…",
  "code": "TW-I001",
  "platform": "instagram",
  "market": "TW",
  "created": true
}

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
409ambiguous_code：舊編號在多個平台重複，請加 platform；idempotency_in_progress：同一個 Idempotency-Key 的第一個請求還在處理
413payload_too_large：內容或圖片太大
422rejected：規則不允許（message 是原因）；idempotency_mismatch：同一個 Idempotency-Key 用在不同內容
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

post/api/agent/v1/accounts/{code}/state

回報帳號狀態#

範圍 accounts:writeMCP report_account_state可帶 Idempotency-Key

平台把帳號封鎖、隔離、暫停、恢復或回到養號時回報。被封、隔離、暫停要寫 reason。被封不會自動開新一代：系統開一件待裁決請人決定。同狀態重送回 unchanged。

參數

欄位	型別	說明
`code`必填	string · 路徑	帳號編號，例如 TW-T014（舊編號也可以）
`platform`	string · 查詢	舊編號在多個平台重複時才需要可用值：threads、tiktok、x、facebook、instagram、reddit
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`state`必填	string	banned 被封／quarantined 隔離／paused 暫停／restored 恢復正常／warming 養號可用值：banned、quarantined、paused、restored、warming
`reason`	string	原因（被封、隔離、暫停必填；平台怎麼說的）最多 1000 字
`occurred_at`必填	string	平台實際發生的時間：帶時區的 ISO，或帳號市場的當地時間 "2026-10-05 14:30"1–40 字
`origin`	object	這件事從哪裡來
`origin.platform`必填	string	在哪個平台聽到的：feishu／dingtalk／telegram／discord／cli／other（寫飛書、釘釘也可以）1–40 字
`origin.gateway`	string	哪個 gateway 收到的，例如 main@host-1最多 200 字
`origin.channel`	string	群組／頻道名稱，例如 #審稿群（知道就一定帶）最多 200 字
`origin.thread`	string	討論串最多 200 字
`origin.requester`	string	誰提出的（聊天裡的名字）最多 80 字

json 範例

{
  "state": "banned",
  "reason": "平台通知：違反社群守則",
  "occurred_at": "2026-10-05 14:30"
}

回應

200狀態變化與（被封時）開出的待裁決。

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

post/api/agent/v1/accounts/{code}/avatar

同步帳號頭像#

範圍 accounts:writeMCP set_account_avatar可帶 Idempotency-Key

傳帳號在平台上現在的頭像（base64，JPEG／PNG／WebP，5 MB 以內），審稿頁與人設頁會顯示它。同一張重送 changed: false。

參數

欄位	型別	說明
`code`必填	string · 路徑	帳號編號，例如 TW-T014（舊編號也可以）
`platform`	string · 查詢	舊編號在多個平台重複時才需要可用值：threads、tiktok、x、facebook、instagram、reddit
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`data`必填	string	平台上的頭像圖檔 base64（可含 data: 前綴），JPEG／PNG／WebP，5 MB 以內至少 1 字

回應

200存好的頭像與是否有變。

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

post/api/agent/v1/heartbeat

心跳#

範圍 runs:writeMCP heartbeat可帶 Idempotency-Key

每輪收工送一次（沒事做也送）：一兩句摘要與計數。同一個 run_id 再送會更新同一筆（摘要取代、計數合併）。回傳你手上的看板卡。

參數

欄位	型別	說明
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`run_id`	string	這一輪工作的 id；同一輪重送會更新同一筆1–120 字
`summary`	string	這一輪做了什麼（一兩句）最多 2000 字
`counts`	object	計數，例如 {"drafts": 3, "rewrites": 1}

json 範例

{
  "run_id": "run-20261005-1",
  "summary": "寫了 3 篇、重寫 1 篇",
  "counts": {
    "drafts": 3,
    "rewrites": 1
  }
}

回應

200這一輪的紀錄與手上的卡。

json 範例

{
  "run": {
    "id": "…",
    "run_id": "run-20261005-1",
    "recorded_at": "…"
  },
  "tasks": [
    {
      "id": "…",
      "kind": "change_avatar",
      "title": "換頭像",
      "status": "in_progress",
      "stale": false,
      "overdue": false
    }
  ]
}

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
409ambiguous_code：舊編號在多個平台重複，請加 platform；idempotency_in_progress：同一個 Idempotency-Key 的第一個請求還在處理
413payload_too_large：內容或圖片太大
422rejected：規則不允許（message 是原因）；idempotency_mismatch：同一個 Idempotency-Key 用在不同內容
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

人設與角色

讀人設、登場名單、定裝圖；提事實、交生成圖、自己建人設。

get/api/agent/v1/personas/{code}讀人設
post/api/agent/v1/personas建立人設
get/api/agent/v1/personas/{code}/images下載已定案圖
post/api/agent/v1/personas/{code}/images交生成圖
post/api/agent/v1/personas/{code}/proposals提事實／矛盾
get/api/agent/v1/personas/{code}/cast登場名單

get/api/agent/v1/personas/{code}

讀人設#

範圍 personas:readMCP get_persona

寫稿前讀一次：人設基本資料與完整設定、各平台編號、正式事實（by_decision: true 是裁決過的，優先）、說話習慣 speech_rules 與禁用 forbidden、已定案的本人圖（15 分鐘連結）、最近貼文、登場名單 cast。

參數

欄位	型別	說明
`code`必填	string · 路徑	帳號編號，例如 TW-T014（舊編號也可以）
`platform`	string · 查詢	舊編號在多個平台重複時才需要可用值：threads、tiktok、x、facebook、instagram、reddit
`include`	string · 查詢	`drafts`＝連草稿事實一起給可用值：drafts
`posts`	integer · 查詢	最近幾篇已發布貼文（預設 10，最多 30）0–30

回應

200persona、accounts、facts、speech_rules、forbidden、images、recent_posts、cast。

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
404not_found：找不到（包含不屬於你的）
409ambiguous_code：舊編號在多個平台重複，請加 platform；idempotency_in_progress：同一個 Idempotency-Key 的第一個請求還在處理
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

post/api/agent/v1/personas

建立人設#

範圍 personas:writeMCP create_persona可帶 Idempotency-Key

工作區還沒有人設時，Agent 自己建立（歸呼叫的 Agent）。project 必須是金鑰所屬工作區的專案。同時開一件待裁決「新人設待確認」給人看。有 bio 與 voice 才算設定完成。同專案同名重送回 200、created: false。

參數

欄位	型別	說明
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`name`必填	string	人設名字（顯示名稱）1–80 字
`project`	string	專案名稱；租戶只有一個專案時可省略最多 200 字
`track`	string	賽道最多 200 字
`background`	string	背景（城市、職業、生活）最多 2000 字
`bio`	string	帳號 bio最多 2000 字
`voice`	string	說話語氣與寫作風格最多 4000 字

json 範例

{
  "name": "小雨",
  "track": "生活",
  "background": "台北上班族，下班喜歡找咖啡廳",
  "bio": "下班後的咖啡地圖",
  "voice": "口語、短句、偶爾自嘲"
}

回應

200已存在（重送或同名），沒有新建

201新建回 201。

json 範例

{
  "id": "…",
  "created": true,
  "project": "…",
  "setup_complete": true,
  "issue_id": "…"
}

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
409ambiguous_code：舊編號在多個平台重複，請加 platform；idempotency_in_progress：同一個 Idempotency-Key 的第一個請求還在處理
413payload_too_large：內容或圖片太大
422rejected：規則不允許（message 是原因）；idempotency_mismatch：同一個 Idempotency-Key 用在不同內容
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

get/api/agent/v1/personas/{code}/images

下載已定案圖#

範圍 personas:readMCP list_persona_images

人設已核可、已發布的定裝圖，生圖前拿來當參考。url、thumb_url 是 15 分鐘有效的下載連結，不要存起來或貼出去。

參數

欄位	型別	說明
`code`必填	string · 路徑	帳號編號，例如 TW-T014（舊編號也可以）
`platform`	string · 查詢	編號重複時才需要（舊 V 編號 Threads 與 TikTok 會撞）可用值：threads、tiktok、x、facebook、instagram、reddit
`category`	string · 查詢	只要某一類可用值：turnaround、portrait、avatar、pet、home、workplace、belongings、photo_style、other

回應

200圖片清單（含簽名連結）。

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
404not_found：找不到（包含不屬於你的）
409ambiguous_code：舊編號在多個平台重複，請加 platform；idempotency_in_progress：同一個 Idempotency-Key 的第一個請求還在處理
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

post/api/agent/v1/personas/{code}/images

交生成圖#

範圍 personas:writeMCP upload_persona_image可帶 Idempotency-Key

交一張人設或角色的生成圖（base64，5 MB 以內）。存成草稿圖，出現在待裁決「待核可圖片」，人核可後才算定案。同一張重送不會多一列；帶 character 表示是某個角色的參考圖。

參數

欄位	型別	說明
`code`必填	string · 路徑	帳號編號，例如 TW-T014（舊編號也可以）
`platform`	string · 查詢	舊編號在多個平台重複時才需要可用值：threads、tiktok、x、facebook、instagram、reddit
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`data`必填	string	圖檔 base64（可含 data: 前綴），JPEG／PNG／WebP，5 MB 以內至少 1 字
`category`	string	圖的類別（預設 other）可用值：turnaround、portrait、avatar、pet、home、workplace、belongings、photo_style、other
`caption`	string	圖說最多 500 字
`prompt`	string	生圖提示詞（內部用）最多 8000 字
`character`	string	這張是某個角色的參考圖時，帶角色代號（登場名單裡的，例如 AS-01）1–24 字

回應

200已存在（重送或同名），沒有新建

201新圖回 201，已存在回 200。

json 範例

{
  "image": {
    "id": "…",
    "created": true,
    "lock": "draft",
    "code": "TW-T014",
    "character": "AB-01"
  }
}

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

post/api/agent/v1/personas/{code}/proposals

提事實／矛盾#

範圍 personas:writeMCP propose_fact可帶 Idempotency-Key

寫稿時發現人設沒寫的細節（fact，進草稿事實）或前後矛盾（contradiction，進待裁決）。都不會直接變成正式設定。同一條重送回 200、created: false。

參數

欄位	型別	說明
`code`必填	string · 路徑	帳號編號，例如 TW-T014（舊編號也可以）
`platform`	string · 查詢	舊編號在多個平台重複時才需要可用值：threads、tiktok、x、facebook、instagram、reddit
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`kind`必填	string	fact＝新事實（進草稿）／contradiction＝矛盾（進待裁決）可用值：fact、contradiction
`category`	string	fact 必填：identity／pet／home／work／speech／photo／belonging／brand_*／habit／event／voice_audio／other可用值：identity、pet、home、work、speech、photo、belonging、brand_liked、brand_endorsing、brand_collaborated、habit、event、voice_audio、other
`label`必填	string	fact：項目（例如「貓的名字」）；contradiction：一句話標題1–200 字
`value`必填	string	fact：內容；contradiction：哪裡和哪裡矛盾1–2000 字
`detail`	string	根據（哪一篇、哪張圖）最多 2000 字
`post_id`	string (uuid)	根據的貼文 id

json 範例

{
  "kind": "fact",
  "category": "pet",
  "label": "貓的名字",
  "value": "布丁",
  "detail": "10/3 那篇提到"
}

回應

200已存在（重送或同名），沒有新建

201新提案回 201，重送回 200。

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

get/api/agent/v1/personas/{code}/cast

登場名單#

範圍 personas:readMCP list_cast

這個人設的帳號可以出現哪些角色：代號、名字、一句話、知識庫條目，以及每個角色最多 6 張參考圖（15 分鐘連結）。get_persona 也回傳同一塊。

參數

欄位	型別	說明
`code`必填	string · 路徑	帳號編號，例如 TW-T014（舊編號也可以）
`platform`	string · 查詢	編號重複時才需要（舊 V 編號 Threads 與 TikTok 會撞）可用值：threads、tiktok、x、facebook、instagram、reddit

回應

200cast 陣列。

json 範例

{
  "code": "TW-T014",
  "persona": "小雨",
  "cast": [
    {
      "code": "AB-01",
      "name": "阿布",
      "summary": "住在咖啡廳的橘貓",
      "wiki_entry_id": "…",
      "wiki_title": "角色 AB-01 阿布",
      "images": [
        {
          "id": "…",
          "category": "turnaround",
          "caption": "三視圖",
          "mime_type": "image/png",
          "url": "https://…"
        }
      ]
    }
  ],
  "images_expire_in_seconds": 900
}

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
404not_found：找不到（包含不屬於你的）
409ambiguous_code：舊編號在多個平台重複，請加 platform；idempotency_in_progress：同一個 Idempotency-Key 的第一個請求還在處理
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

草稿與圖片

交稿、重寫、兩段式上傳圖片、補圖、備註。

get/api/agent/v1/drafts要重做的稿
post/api/agent/v1/drafts交草稿
put/api/agent/v1/drafts/{id}交重寫版本
post/api/agent/v1/drafts/{id}/images把圖補到稿上
post/api/agent/v1/drafts/{id}/notes給審稿的備註
post/api/agent/v1/uploads要一個上傳圖片或影片的連結
put/api/agent/v1/uploads/{id}傳檔（用上傳連結）
put/api/agent/v1/uploads/{id}/chunks傳一塊（分塊上傳）
put/api/agent/v1/uploads/{id}/poster傳影片封面
get/api/agent/v1/media查素材庫
post/api/agent/v1/drafts/{id}/media從素材庫加到稿上

get/api/agent/v1/drafts

要重做的稿#

範圍 drafts:readMCP list_redo

等你重寫（rewrite_requested）或被退回（sent_back）的稿，含目前內文、重寫指示或退回意見、這篇所有審稿意見（舊到新）、登場角色。

參數

欄位	型別	說明
`status`	string · 查詢	只看一種；不給兩種都列可用值：rewrite_requested、sent_back

回應

200要重做的稿。

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

post/api/agent/v1/drafts

交草稿#

範圍 drafts:writeMCP submit_draft可帶 Idempotency-Key

交一篇新稿，預設直接送內部審稿（submit: false 只存草稿）。有圖的稿先查素材庫（GET /media）能重用的帶 media_ids，新素材才用 POST /uploads 傳，再帶 upload_ids（依發布順序，media_ids 接在後面）。同一個編號、內文完全相同、還沒發出的稿不會建第二篇（回 200、duplicate: true，帶的 upload_ids、media_ids、characters、note 會套到原稿）。

參數

欄位	型別	說明
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`code`必填	string	帳號編號，例如 TW-T014（舊編號 V014 也可以）1–40 字
`platform`	string	編號重複時才需要（舊 V 編號 Threads 與 TikTok 會撞）可用值：threads、tiktok、x、facebook、instagram、reddit
`body`必填	string	貼文內文1–10000 字
`topic`	string	主題（給審稿的人看）最多 200 字
`sponsored`	boolean	業配稿設 true
`planned_at`	string	計畫發布時間：帶時區的 ISO（"2026-10-05T20:00:00+08:00"）或帳號市場當地時間（"2026-10-05 20:00"、"2026-10-05 20:00:00"）最多 40 字
`images`	object[]	小圖才用：最多 4 張、合計 3 MB。有圖的稿請改用 upload_ids（create_upload 先傳檔）最多 4 個
`images[].data`必填	string	圖檔 base64（可含 data: 前綴），JPEG／PNG／WebP至少 1 字
`images[].caption`	string	最多 200 字
`upload_ids`	string (uuid)[]	create_upload 傳好的圖或影片（依發布順序）。Instagram 一篇最多 10 個，其他平台 4 個（圖和影片合計）1–10 個
`media_ids`	string (uuid)[]	從素材庫重用的素材 id（list_media 查），接在 upload_ids 後面、依此順序。先查素材庫（例如 tag 固定收尾），沒有的才上傳1–10 個
`characters`	object[]	這篇的登場角色（依主次排序，主角放第一個），只能用人設登場名單裡的角色。給了就整組取代；空陣列＝清掉最多 6 個
`characters[].code`必填	string	角色代號，例如 AS-01（get_persona 的 cast）1–24 字
`characters[].pov`	boolean	內文是用這個角色的視角寫的（不是帳號本身的口氣）時設 true；一篇最多一個
`note`	string	給審稿的人看的備註（例如還缺什麼、為什麼這樣寫），會進審稿紀錄「新增備註」。主題欄只寫短主題1–1000 字
`submit`	boolean	預設 true＝直接送內部審稿；false＝只存草稿

json 範例

{
  "code": "TW-T014",
  "body": "下班後終於找到一間安靜的咖啡廳……",
  "topic": "週末咖啡",
  "planned_at": "2026-10-05 20:00",
  "upload_ids": [
    "3f0e…",
    "8a21…"
  ],
  "characters": [
    {
      "code": "AB-01"
    }
  ],
  "note": "第二張是店門口"
}

回應

200已存在（重送或同名），沒有新建

201新稿回 201，重複回 200。

json 範例

{
  "draft": {
    "id": "e6baef30-…",
    "status": "internal_review",
    "code": "TW-T014",
    "platform": "threads",
    "planned_at": "2026-10-05T12:00:00.000Z",
    "images": 2,
    "duplicate": false,
    "characters": [
      {
        "code": "AB-01",
        "name": "阿布",
        "pov": false
      }
    ]
  }
}

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

put/api/agent/v1/drafts/{id}

交重寫版本#

範圍 drafts:writeMCP update_draft可帶 Idempotency-Key

交整篇新內文（只能改自己帳號、還在草稿的稿）。內文一變就解除「等 Agent 重寫」；和退回時一模一樣的內文會被 422 擋。預設改完送審。

參數

欄位	型別	說明
`id`必填	string (uuid) · 路徑	稿的 id
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`body`必填	string	改好的完整內文1–10000 字
`topic`	string	最多 200 字
`upload_ids`	string (uuid)[]	create_upload 傳好的圖或影片（依發布順序）。Instagram 一篇最多 10 個，其他平台 4 個（圖和影片合計）1–10 個
`media_ids`	string (uuid)[]	從素材庫重用的素材 id（list_media 查），接在 upload_ids 後面、依此順序。先查素材庫（例如 tag 固定收尾），沒有的才上傳1–10 個
`characters`	object[]	這篇的登場角色（依主次排序，主角放第一個），只能用人設登場名單裡的角色。給了就整組取代；空陣列＝清掉最多 6 個
`characters[].code`必填	string	角色代號，例如 AS-01（get_persona 的 cast）1–24 字
`characters[].pov`	boolean	內文是用這個角色的視角寫的（不是帳號本身的口氣）時設 true；一篇最多一個
`note`	string	給審稿的人看的備註（例如還缺什麼、為什麼這樣寫），會進審稿紀錄「新增備註」。主題欄只寫短主題1–1000 字
`submit`	boolean	預設 true＝改完直接送內部審稿

json 範例

{
  "body": "改好的完整內文……",
  "note": "開頭改成從天氣切入"
}

回應

200改好的稿。

json 範例

{
  "draft": {
    "id": "e6baef30-…",
    "status": "internal_review",
    "rewrite_answered": true
  }
}

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

post/api/agent/v1/drafts/{id}/images

把圖補到稿上#

範圍 drafts:writeMCP attach_images可帶 Idempotency-Key

把傳好的圖或影片補到已交的稿（草稿或內部審稿中才行），接在原有的後面，同時成為素材庫的素材。全有或全無：任何一個 id 不對，整個請求拒絕。Instagram 一篇最多 10 個，其他平台 4 個（圖與影片合計）；Reddit 不能放影片。

參數

欄位	型別	說明
`id`必填	string (uuid) · 路徑	稿的 id
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`upload_ids`必填	string (uuid)[]	create_upload 傳好的圖（依發布順序）1–10 個
`note`	string	給審稿的人看的備註（例如還缺什麼、為什麼這樣寫），會進審稿紀錄「新增備註」。主題欄只寫短主題1–1000 字

回應

200這篇現在的圖數。

json 範例

{
  "draft": {
    "id": "e6baef30-…",
    "images": 3
  }
}

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

post/api/agent/v1/drafts/{id}/notes

給審稿的備註#

範圍 drafts:writeMCP add_note可帶 Idempotency-Key

給審稿的人一段說明（還缺什麼、為什麼這樣寫），進審稿紀錄、顯示為「新增備註」。主題欄只寫短主題。

參數

欄位	型別	說明
`id`必填	string (uuid) · 路徑	稿的 id
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`note`必填	string	給審稿的人看的備註，會進審稿紀錄「新增備註」1–1000 字

json 範例

{
  "note": "第 3 張是示意圖，正式圖明天補"
}

回應

200已記下。

json 範例

{
  "draft": {
    "id": "e6baef30-…",
    "noted": true
  }
}

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

post/api/agent/v1/uploads

要一個上傳圖片或影片的連結#

範圍 drafts:writeMCP create_upload可帶 Idempotency-Key

上傳的第一步：每個新檔要一個一次性連結。圖片（4 MB 內）與 4 MB 內的影片回 mode: "single"，用 shell 把檔案 PUT 到 upload_url；影片超過 4 MB（最大 500 MB）要帶 mime_type 與 bytes，回 mode: "chunked"，依序把每 3 MiB 一塊 PUT 到 chunk_url（PUT /uploads/{id}/chunks）。影片可另傳封面到 poster_url。上傳完成就進素材庫：傳檔（或最後一塊）的回應有 media_id，之後用 media_ids 附到稿上（還沒有稿也可以先存進素材庫備用）；附到正在交的稿也可以照舊帶 upload_ids。可帶 tags、caption 方便之後找到。檔案不經過模型、不轉 base64。上傳前先查素材庫（GET /media）。

參數

欄位	型別	說明
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`code`必填	string	帳號編號，例如 TW-T014（舊編號 V014 也可以）1–40 字
`platform`	string	編號重複時才需要（舊 V 編號 Threads 與 TikTok 會撞）可用值：threads、tiktok、x、facebook、instagram、reddit
`caption`	string	圖說（給審稿的人看，也是素材庫的說明）最多 200 字
`character`	string	圖裡的角色代號（登場名單裡的，例如 AS-01）1–24 字
`tags`	string[]	素材庫標籤，之後可用 list_media 依標籤找回來重用，例如 ["固定收尾"]最多 20 個
`project`	string	素材庫的專案名稱（省略＝這個帳號人設的專案）1–80 字
`bytes`	integer	檔案大小（位元組）。影片或超過 4 MB 的檔案必填：超過 4 MB 會改成分塊上傳（每塊 3 MB，最大 500 MB）1–524288000
`mime_type`	string	檔案類型；影片必填（video/mp4、video/quicktime、video/webm）可用值：image/jpeg、image/png、image/webp、video/mp4、video/quicktime、video/webm

json 範例

{
  "code": "TW-T014",
  "caption": "第 1 張",
  "tags": [
    "收尾"
  ]
}

回應

201上傳連結（單檔：1 小時內、只能用一次；分塊：23 小時內）。分塊上傳的回應是 { upload_id, mode: "chunked", chunk_url, method, chunk_bytes, chunks, expires_at, how, poster_url }。

json 範例

{
  "upload_id": "3f0e…",
  "upload_url": "https://api.tennnzo.com/api/agent/v1/uploads/3f0e…?t=…",
  "method": "PUT",
  "max_bytes": 4194304,
  "accepts": [
    "image/jpeg",
    "image/png",
    "image/webp"
  ],
  "expires_at": "…",
  "how": "curl -sS -T <檔案> '<upload_url>'"
}

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

put/api/agent/v1/uploads/{id}

傳檔（用上傳連結）#

不用金鑰

上傳的第二步：請求本文就是檔案本身（curl -sS -T photo.jpg '<upload_url>'）。不帶金鑰，連結裡的一次性 token t 就是憑證。JPEG／PNG／WebP 圖片或 MP4／MOV／WebM 影片，單檔 4 MB 內（看檔頭判斷）。傳完就進素材庫，回應的 media_id 可以直接用在 media_ids；同樣的檔案素材庫已有時回那一個素材的 id。

參數

欄位	型別	說明
`id`必填	string (uuid) · 路徑	upload_id
`t`必填	string · 查詢	上傳連結裡的一次性 token（照 upload_url 原樣用）

請求本文

application/octet-stream：圖檔的原始位元組。

回應

200收到的檔案與它在素材庫的 media_id。

json 範例

{
  "upload_id": "3f0e…",
  "media_id": "5c1d…",
  "mime_type": "image/jpeg",
  "kind": "image",
  "bytes": 482113
}

400invalid_request：參數格式不對（message 會指出哪個欄位）
404not_found：找不到（包含不屬於你的）
413payload_too_large：內容或圖片太大
422rejected：規則不允許（message 是原因）；idempotency_mismatch：同一個 Idempotency-Key 用在不同內容
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

put/api/agent/v1/uploads/{id}/chunks

傳一塊（分塊上傳）#

不用金鑰

影片超過 4 MB 時的第二步：把檔案切成 chunk_bytes（3 MiB）一塊，依序每塊 PUT 一次，n 從 0 開始；最後一塊可以比較小。不帶金鑰，用 chunk_url 原樣加上 &n=。已收過的塊再送一次只會回目前進度；跳號回 422 並說下一塊是幾號。最後一塊回 done: true 與 media_id：伺服器算出內容雜湊、讀出影片長度與尺寸，影片已經進素材庫（同樣的檔案已有時回那一個），之後用 media_ids 附到稿上。

參數

欄位	型別	說明
`id`必填	string (uuid) · 路徑	upload_id
`t`必填	string · 查詢	上傳連結裡的一次性 token（照 chunk_url 原樣用）
`n`必填	integer · 查詢	第幾塊，從 0 開始

請求本文

application/octet-stream：這一塊的原始位元組（最後一塊以外都剛好 3145728 位元組）。

回應

200目前進度；完成時多 media_id。

json 範例

{
  "upload_id": "3f0e…",
  "media_id": "5c1d…",
  "received_bytes": 52428800,
  "total_bytes": 52428800,
  "next_chunk": null,
  "done": true
}

400invalid_request：參數格式不對（message 會指出哪個欄位）
404not_found：找不到（包含不屬於你的）
413payload_too_large：內容或圖片太大
422rejected：規則不允許（message 是原因）；idempotency_mismatch：同一個 Idempotency-Key 用在不同內容
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

put/api/agent/v1/uploads/{id}/poster

傳影片封面#

不用金鑰

影片上傳可另外傳一張封面（JPEG／PNG／WebP，4 MB 內），素材庫與審稿頁用它當縮圖；不傳就顯示影片圖示。影片傳完之前或之後都可以，交稿後也可以。不帶金鑰，用 poster_url 原樣。

參數

欄位	型別	說明
`id`必填	string (uuid) · 路徑	upload_id
`t`必填	string · 查詢	上傳連結裡的一次性 token（照 poster_url 原樣用）

請求本文

application/octet-stream：封面圖的原始位元組。

回應

200已存。

json 範例

{
  "upload_id": "3f0e…",
  "poster": true
}

400invalid_request：參數格式不對（message 會指出哪個欄位）
404not_found：找不到（包含不屬於你的）
413payload_too_large：內容或圖片太大
422rejected：規則不允許（message 是原因）；idempotency_mismatch：同一個 Idempotency-Key 用在不同內容
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

get/api/agent/v1/media

查素材庫#

範圍 drafts:readMCP list_media

組織共用的素材庫（圖片與影片），只列你負責的專案能用的（該專案的與不分專案共用的；專案都在金鑰的工作區），不含封存。上傳前先查：能重用的帶 media_ids 交稿，或用 POST /drafts/{id}/media 補上。used_count 是用到這個素材的貼文數。連結在 tennnzo 網域、24 小時以上有效；影片支援 Range。

參數

欄位	型別	說明
`project`	string · 查詢	專案名稱（只看這個專案可用的素材）1–80 字
`character`	string · 查詢	角色代號，例如 AS-011–24 字
`tag`	string · 查詢	標籤，例如固定收尾1–30 字
`kind`	string · 查詢	可用值：image、video
`q`	string · 查詢	搜尋說明與標籤裡的字1–100 字
`sort`	string · 查詢	newest（預設）或 most_used（最常用的在前）可用值：newest、most_used
`limit`	integer · 查詢	最多幾筆（預設 30）1–100

回應

200media 陣列。

json 範例

{
  "media": [
    {
      "id": "5c1d…",
      "kind": "image",
      "caption": "固定收尾圖",
      "tags": [
        "收尾"
      ],
      "project": null,
      "character": null,
      "mime_type": "image/png",
      "bytes": 182330,
      "width": 1080,
      "height": 1350,
      "duration_ms": null,
      "used_count": 12,
      "created_at": "…",
      "url": "https://api.tennnzo.com/media/item/5c1d…?exp=…&sig=…",
      "thumb_url": "https://…"
    }
  ],
  "links_expire_in_seconds": 86400
}

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

post/api/agent/v1/drafts/{id}/media

從素材庫加到稿上#

範圍 drafts:writeMCP attach_media可帶 Idempotency-Key

把素材庫的素材（GET /media 的 id）加到已交的稿（草稿或內部審稿中才行），依 media_ids 順序接在原有的後面；已經在這篇的會略過。同一個素材可以用在很多篇。封存的、別專案的拒絕；上限與影片規則同 POST /drafts/{id}/images。

參數

欄位	型別	說明
`id`必填	string (uuid) · 路徑	稿的 id
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`media_ids`必填	string (uuid)[]	素材庫的素材 id（list_media 查），依發布順序接在這篇現有的圖後面1–10 個
`note`	string	給審稿的人看的備註（例如還缺什麼、為什麼這樣寫），會進審稿紀錄「新增備註」。主題欄只寫短主題1–1000 字

json 範例

{
  "media_ids": [
    "5c1d…"
  ],
  "note": "最後一張用固定收尾圖"
}

回應

200這篇現在的素材數。

json 範例

{
  "draft": {
    "id": "e6baef30-…",
    "media": 5
  }
}

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

排程、發布與成效

審稿通過待排程的稿、回報排程／發布、回報成效。

get/api/agent/v1/posts/approved審稿通過、待排程的稿
post/api/agent/v1/posts/report回報排程／發布
post/api/agent/v1/metrics回報成效

get/api/agent/v1/posts/approved

審稿通過、待排程的稿#

範圍 drafts:readMCP list_approved

審稿已核可、還沒排上發布工具的稿，計畫時間早的在前，最多 200 篇。附圖與影片照審稿頁的順序回傳（images[].kind 區分圖片與影片，連結在 tennnzo 網域、24 小時以上有效，影片支援 Range）：發布時照這個順序上傳。排好後回報 scheduled＋post_id 就會離開清單。

回應

200posts 陣列。

json 範例

{
  "posts": [
    {
      "id": "e6baef30-…",
      "code": "TW-T014",
      "platform": "threads",
      "persona": "小雨",
      "handle": "demo.xiaoyu",
      "body": "…",
      "topic": "週末咖啡",
      "sponsored": false,
      "planned_at": "…",
      "images": [
        {
          "id": "5c1d…",
          "kind": "image",
          "url": "https://…",
          "thumb_url": "https://…",
          "mime_type": "image/jpeg",
          "caption": "第 1 張",
          "duration_ms": null
        }
      ],
      "characters": []
    }
  ]
}

401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

post/api/agent/v1/posts/report

回報排程／發布#

範圍 posts:writeMCP report_posts可帶 Idempotency-Key

用自己的工具在平台上排好、發出、失敗或取消之後立刻回報（一次最多 200 篇）。published 必帶 permalink。每篇各自檢查、各自處理：一篇錯只擋那一篇，整批都被拒才回 422（什麼都沒寫，Idempotency-Key 不會被佔用）。對到同一篇的順序：post_id → platform_post_id → 同編號、同內文、時間最接近的那篇。

參數

欄位	型別	說明
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

請求只整批檢查 `posts` 是 1–200 篇的陣列；每篇照下面的欄位各自檢查。

欄位	型別	說明
`posts`必填	object[]	這次要回報的貼文，最多 200 篇1–200 個
`posts[].code`必填	string	帳號編號，例如 TW-T014（舊編號 V014 也可以）1–40 字
`posts[].platform`	string	編號重複時才需要（舊 V 編號 Threads 與 TikTok 會撞）可用值：threads、tiktok、x、facebook、instagram、reddit
`posts[].status`必填	string	scheduled＝已在平台排好；published＝已發出；failed＝排了但沒發出去；cancelled＝取消了排程可用值：scheduled、published、failed、cancelled
`posts[].scheduled_for`	string	排定的發布時間（status 是 scheduled 時必填）：帳號市場當地時間 "2026-10-05 20:00" 或 "2026-10-05 20:00:42"（不帶時區＝帳號市場時區），或帶時區的 ISO "2026-10-05T20:00:00+08:00"1–40 字
`posts[].published_at`	string	實際發出時間（published；不給就用收到回報的時間）：帳號市場當地時間 "2026-10-05 20:00" 或 "2026-10-05 20:00:42"（不帶時區＝帳號市場時區），或帶時區的 ISO "2026-10-05T20:00:00+08:00"1–40 字
`posts[].platform_post_id`	string	平台上的貼文 id。知道就一定要帶：之後的回報靠它對到同一篇1–200 字
`posts[].permalink`	string	貼文的永久連結 http(s)。status 是 published 時必填：沒有連結不算發布成功（還沒連結先報 scheduled，確認失敗報 failed）最多 2000 字
`posts[].body`	string	貼文內文（第一次回報這篇時必填；之後有 platform_post_id 或 post_id 可以不給）1–10000 字
`posts[].topic`	string	主題最多 200 字
`posts[].has_media`	boolean	有圖或影片
`posts[].sponsored`	boolean	業配
`posts[].post_id`	string (uuid)	這篇是 dashboard 交給你的稿時，帶它的 id（list_redo／審稿通過的稿）
`posts[].failure_reason`	string	failed／cancelled 的原因（一句話，不含帳密或內部連結）最多 2000 字

json 範例

{
  "posts": [
    {
      "code": "TW-T014",
      "status": "scheduled",
      "scheduled_for": "2026-10-05 20:00:00",
      "body": "完整內文",
      "has_media": true
    },
    {
      "code": "TW-T015",
      "status": "published",
      "published_at": "2026-10-05 09:02:13",
      "body": "完整內文",
      "platform_post_id": "3712345678901234567",
      "permalink": "https://www.threads.net/@demo.xiaoyu/post/DAbc"
    }
  ]
}

回應

200每篇的結果。action：inserted／updated／unchanged／ignored；ok: false 的看 error。

json 範例

{
  "report_id": "…",
  "received_at": "…",
  "inserted": 1,
  "updated": 1,
  "unchanged": 0,
  "ignored": 0,
  "rejected": 0,
  "results": [
    {
      "index": 0,
      "ok": true,
      "action": "inserted",
      "post_id": "…",
      "status": "scheduled",
      "matched_by": null
    },
    {
      "index": 1,
      "ok": true,
      "action": "updated",
      "post_id": "…",
      "status": "published",
      "matched_by": "body"
    }
  ]
}

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
409ambiguous_code：舊編號在多個平台重複，請加 platform；idempotency_in_progress：同一個 Idempotency-Key 的第一個請求還在處理
413payload_too_large：內容或圖片太大
422rejected：規則不允許（message 是原因）；idempotency_mismatch：同一個 Idempotency-Key 用在不同內容
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

post/api/agent/v1/metrics

回報成效#

範圍 metrics:writeMCP report_metrics可帶 Idempotency-Key

自己抓到的數字才報：貼文的瀏覽、讚、回覆、轉發、分享，帳號粉絲數。同一個 captured_at 重送會覆蓋；全空不寫。還沒有平台 id 的貼文要先回報發布。captured_at 不可是未來、不可超過 60 天前。

參數

欄位	型別	說明
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`captured_at`必填	string	這批數字是什麼時候抓的（必填）：帶時區的 ISO，或當地時間 "2026-10-05 21:00:00"（這批帳號同一個市場時用該市場時區，否則台北）。同一個時間重送會覆蓋，不會重複1–40 字
`posts`	object[]	每篇的瀏覽／讚／回覆／轉發／分享最多 1000 個
`posts[].post_id`	string (uuid)	dashboard 的貼文 id
`posts[].code`	string	帳號編號，例如 TW-T014（舊編號 V014 也可以）1–40 字
`posts[].platform`	string	編號重複時才需要（舊 V 編號 Threads 與 TikTok 會撞）可用值：threads、tiktok、x、facebook、instagram、reddit
`posts[].platform_post_id`	string	平台貼文 id（沒有 post_id 時和 code 一起給）1–200 字
`posts[].views`	integer	0–10000000000
`posts[].likes`	integer	0–10000000000
`posts[].replies`	integer	0–10000000000
`posts[].reposts`	integer	0–10000000000
`posts[].shares`	integer	0–10000000000
`accounts`	object[]	帳號粉絲數（現役世代）最多 500 個
`accounts[].code`必填	string	帳號編號，例如 TW-T014（舊編號 V014 也可以）1–40 字
`accounts[].platform`	string	編號重複時才需要（舊 V 編號 Threads 與 TikTok 會撞）可用值：threads、tiktok、x、facebook、instagram、reddit
`accounts[].followers`必填	integer	粉絲數0–10000000000

json 範例

{
  "captured_at": "2026-10-05 21:00:00",
  "posts": [
    {
      "code": "TW-T014",
      "platform_post_id": "3712345678901234567",
      "views": 1200,
      "likes": 85,
      "replies": 6
    }
  ],
  "accounts": [
    {
      "code": "TW-T014",
      "followers": 3120
    }
  ]
}

回應

200寫入的計數與逐筆被拒的原因 refused。

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
409ambiguous_code：舊編號在多個平台重複，請加 platform；idempotency_in_progress：同一個 Idempotency-Key 的第一個請求還在處理
413payload_too_large：內容或圖片太大
422rejected：規則不允許（message 是原因）；idempotency_mismatch：同一個 Idempotency-Key 用在不同內容
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

看板

群組裡被交辦的事：開卡、領卡、進度、交結果。

get/api/agent/v1/tasks我的看板卡
post/api/agent/v1/tasks開卡
post/api/agent/v1/tasks/{id}/claim領卡
post/api/agent/v1/tasks/{id}/progress回報進度
post/api/agent/v1/tasks/{id}/finish交結果
post/api/agent/v1/tasks/{id}/fail做不到

get/api/agent/v1/tasks

我的看板卡#

範圍 accounts:readMCP list_tasks

交給你的卡，以及你人設上還沒指派的卡。

參數

欄位	型別	說明
`status`	string · 查詢	逗號分隔；預設 open,in_progress,awaiting_confirmation

回應

200tasks 陣列（target、origin、due_at、stale／overdue 等）。

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

post/api/agent/v1/tasks

開卡#

範圍 tasks:writeMCP open_task可帶 Idempotency-Key

群組裡被叫做事時先開卡再動手。同一個 Agent＋同一種事＋同一個對象已有進行中的卡就回那張（200、created: false），並把這次的提出者記在「也要這個」。

參數

欄位	型別	說明
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`kind`必填	string	哪一種事可用值：write_posts、change_avatar、change_bio、delete_post、pause_account、resume_account、export_data、other
`title`必填	string	一句話：要做什麼1–200 字
`detail`	string	細節（原話重點，不含帳密）最多 4000 字
`target`	object	這張卡關於什麼；同一個 Agent＋同一種事＋同一個對象只會有一張卡
`target.type`必填	string	slot＝帳號編號、persona＝人設、post＝貼文、issue＝待裁決可用值：slot、persona、post、issue
`target.code`	string	slot／persona 用帳號編號（TW-T014、V014）1–40 字
`target.platform`	string	編號重複時才需要（舊 V 編號 Threads 與 TikTok 會撞）可用值：threads、tiktok、x、facebook、instagram、reddit
`target.id`	string (uuid)	post／issue 用 id
`due_at`	string	期限：帶時區的 ISO，或當地時間 "2026-10-05 18:00"（對象帳號的市場時區，否則台北）1–40 字
`origin`	object	這件事從哪裡來
`origin.platform`必填	string	在哪個平台聽到的：feishu／dingtalk／telegram／discord／cli／other（寫飛書、釘釘也可以）1–40 字
`origin.gateway`	string	哪個 gateway 收到的，例如 main@host-1最多 200 字
`origin.channel`	string	群組／頻道名稱，例如 #審稿群（知道就一定帶）最多 200 字
`origin.thread`	string	討論串最多 200 字
`origin.requester`	string	誰提出的（聊天裡的名字）最多 80 字

json 範例

{
  "kind": "change_avatar",
  "title": "TW-T014 換頭像",
  "target": {
    "type": "slot",
    "code": "TW-T014"
  },
  "origin": {
    "platform": "feishu",
    "channel": "#營運群",
    "requester": "Mika"
  }
}

回應

200已存在（重送或同名），沒有新建

201新卡回 201，已有回 200。

json 範例

{
  "task": {
    "id": "…",
    "status": "open"
  },
  "created": true
}

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
409ambiguous_code：舊編號在多個平台重複，請加 platform；idempotency_in_progress：同一個 Idempotency-Key 的第一個請求還在處理
413payload_too_large：內容或圖片太大
422rejected：規則不允許（message 是原因）；idempotency_mismatch：同一個 Idempotency-Key 用在不同內容
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

post/api/agent/v1/tasks/{id}/claim

領卡#

範圍 tasks:writeMCP claim_task可帶 Idempotency-Key

開始做一張待領取的卡之前呼叫一次（重送無害）。也可以領你人設上還沒指派的卡。

參數

欄位	型別	說明
`id`必填	string (uuid) · 路徑	卡的 id
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

回應

200更新後的卡。

401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
404not_found：找不到（包含不屬於你的）
409ambiguous_code：舊編號在多個平台重複，請加 platform；idempotency_in_progress：同一個 Idempotency-Key 的第一個請求還在處理
422rejected：規則不允許（message 是原因）；idempotency_mismatch：同一個 Idempotency-Key 用在不同內容
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

post/api/agent/v1/tasks/{id}/progress

回報進度#

範圍 tasks:writeMCP report_task可帶 Idempotency-Key

做的過程中回報進度（一兩句）。

參數

欄位	型別	說明
`id`必填	string (uuid) · 路徑	卡的 id
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`note`必填	string	進度一兩句1–2000 字

json 範例

{
  "note": "頭像已生成，等上傳"
}

回應

200更新後的卡。

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

post/api/agent/v1/tasks/{id}/finish

交結果#

範圍 tasks:writeMCP finish_task可帶 Idempotency-Key

做完交結果與證據，卡進「待確認」由人確認。不要自己確認自己的卡。

參數

欄位	型別	說明
`id`必填	string (uuid) · 路徑	卡的 id
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`result`必填	string	結果：做了什麼1–4000 字
`evidence`	object \| object[]	證據：[{"type":"link","url":"https://…","label":"…"} 或 {"type":"asset","asset_id":"<圖片 id>"}]，最多 20 筆最多 20 個
`evidence[].type`必填	string
`evidence[].url`必填	string (uri)	最多 2000 字
`evidence[].label`	string	最多 200 字
`evidence[].asset_id`必填	string (uuid)

json 範例

{
  "result": "頭像已換成新的定裝照",
  "evidence": [
    {
      "type": "link",
      "url": "https://www.threads.net/@demo.xiaoyu",
      "label": "個人頁"
    }
  ]
}

回應

200更新後的卡。

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

post/api/agent/v1/tasks/{id}/fail

做不到#

範圍 tasks:writeMCP fail_task可帶 Idempotency-Key

做不到時說明原因。

參數

欄位	型別	說明
`id`必填	string (uuid) · 路徑	卡的 id
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`reason`必填	string	為什麼做不到1–4000 字

json 範例

{
  "reason": "帳號需要重新登入，無法更換"
}

回應

200更新後的卡。

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

待裁決後續

待裁決決定後要在平台上做的事（換頭像、改 bio、刪文）。

post/api/agent/v1/issues/{id}/done線上動作完成

post/api/agent/v1/issues/{id}/done

線上動作完成#

範圍 issues:writeMCP complete_issue可帶 Idempotency-Key

待裁決決定後要在平台上做的事（換頭像、刪文、改 bio）做完時回報，附結果與證據。對應的看板卡進「待確認」由人確認。id 用 work_today 的 follow_ups[].id。

參數

欄位	型別	說明
`id`必填	string (uuid) · 路徑	待裁決的 id
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`result`必填	string	做了什麼，例如「頭像已換成虎斑貓」1–500 字
`evidence`	object \| object[]	證據：[{"type":"link","url":"https://…","label":"…"} 或 {"type":"asset","asset_id":"<圖片 id>"}]，最多 20 筆最多 20 個
`evidence[].type`必填	string
`evidence[].url`必填	string (uri)	最多 2000 字
`evidence[].label`	string	最多 200 字
`evidence[].asset_id`必填	string (uuid)

json 範例

{
  "result": "頭像已換成虎斑貓",
  "evidence": [
    {
      "type": "asset",
      "asset_id": "…"
    }
  ]
}

回應

200處理結果。

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

代為登記

有人在群組裡說了審稿、裁決或確認的決定，Agent 代他登記。

post/api/agent/v1/posts/{id}/transition代為更改貼文狀態
post/api/agent/v1/issues/{id}/relay代為裁決
post/api/agent/v1/tasks/{id}/relay代為確認／退回看板卡

post/api/agent/v1/posts/{id}/transition

代為更改貼文狀態#

範圍 relay:writeMCP relay_post_status可帶 Idempotency-Key

有人在群組裡明確說了審稿決定，代他登記，規則和他自己按按鈕一樣。客戶只能在「待客戶審稿」時通過、退回、要求修改、要求重寫（專案要開客戶審稿）。mark_published 需要貼文已經有連結，沒有就改用回報發布。

參數

欄位	型別	說明
`id`必填	string (uuid) · 路徑	貼文 id
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`action`必填	string	submit 送審／approve 通過（內部或客戶階段看貼文目前在哪）／reject 退回／request_changes 要求修改／request_rewrite 要求重寫／schedule 排程／reschedule 改時間／unschedule 取消排程／mark_published 標已發出／mark_cancelled 標取消可用值：submit、approve、reject、request_changes、request_rewrite、schedule、reschedule、unschedule、mark_published、mark_cancelled
`comment`	string	對方的原話重點（退回、要求修改、要求重寫、取消時必填）最多 2000 字
`scheduled_for`	string	schedule／reschedule 的發布時間：帶時區的 ISO 或帳號市場當地時間1–40 字
`on_behalf_of`必填	object	代誰登記（必填）
`on_behalf_of.name`必填	string	說這句話的人（照聊天裡的名字，例如王小姐、Mika）1–80 字
`on_behalf_of.role`必填	string	agency＝Agency 同事、client＝客戶、admin＝平台管理員可用值：agency、client、admin
`origin`必填	object	從哪裡聽到的（platform 必填，知道頻道就帶 channel）
`origin.platform`必填	string	在哪個平台聽到的：feishu／dingtalk／telegram／discord／cli／other（寫飛書、釘釘也可以）1–40 字
`origin.gateway`	string	哪個 gateway 收到的，例如 main@host-1最多 200 字
`origin.channel`	string	群組／頻道名稱，例如 #審稿群（知道就一定帶）最多 200 字
`origin.thread`	string	討論串最多 200 字
`origin.requester`	string	誰提出的（聊天裡的名字）最多 80 字
`origin.message_ref`	string	那則訊息的 id 或連結；同一則重送不會記兩次最多 200 字
`effective_at`	string	這件事實際發生的時間（例如客戶 10/2 通過＝2026-10-02T15:00:00+08:00，或貼文帳號市場的當地時間 "2026-10-02 15:00"）；不給＝現在；不可是未來、不可超過 60 天前1–40 字

json 範例

{
  "action": "approve",
  "on_behalf_of": {
    "name": "王小姐",
    "role": "client"
  },
  "origin": {
    "platform": "feishu",
    "channel": "#審稿群",
    "message_ref": "om_8812"
  },
  "effective_at": "2026-10-02T15:20:00+08:00"
}

回應

200登記後的狀態。

json 範例

{
  "post_id": "7f2c…",
  "action": "approve",
  "status": "approved",
  "effective_at": "2026-10-02T07:20:00+00:00"
}

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

post/api/agent/v1/issues/{id}/relay

代為裁決#

範圍 relay:writeMCP relay_issue可帶 Idempotency-Key

代 Agency 或管理員登記待裁決的決定：已處理、不處理（要原因）、選選項（chosen 空陣列＝其他，答案寫在 note）。

參數

欄位	型別	說明
`id`必填	string (uuid) · 路徑	待裁決的 id
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`action`必填	string	resolve 已處理／dismiss 不處理（note 必填）／choose 選選項可用值：resolve、dismiss、choose
`note`	string	決定內容或原因最多 2000 字
`chosen`	string[]	choose：選中的選項 key；空陣列＝其他（答案寫在 note）最多 12 個
`on_behalf_of`必填	object	代誰登記（必填）
`on_behalf_of.name`必填	string	說這句話的人（照聊天裡的名字，例如王小姐、Mika）1–80 字
`on_behalf_of.role`必填	string	agency＝Agency 同事、client＝客戶、admin＝平台管理員可用值：agency、client、admin
`origin`必填	object	從哪裡聽到的（platform 必填，知道頻道就帶 channel）
`origin.platform`必填	string	在哪個平台聽到的：feishu／dingtalk／telegram／discord／cli／other（寫飛書、釘釘也可以）1–40 字
`origin.gateway`	string	哪個 gateway 收到的，例如 main@host-1最多 200 字
`origin.channel`	string	群組／頻道名稱，例如 #審稿群（知道就一定帶）最多 200 字
`origin.thread`	string	討論串最多 200 字
`origin.requester`	string	誰提出的（聊天裡的名字）最多 80 字
`origin.message_ref`	string	那則訊息的 id 或連結；同一則重送不會記兩次最多 200 字
`effective_at`	string	這件事實際發生的時間（例如客戶 10/2 通過＝2026-10-02T15:00:00+08:00，或貼文帳號市場的當地時間 "2026-10-02 15:00"）；不給＝現在；不可是未來、不可超過 60 天前1–40 字

json 範例

{
  "action": "choose",
  "chosen": [
    "tabby"
  ],
  "on_behalf_of": {
    "name": "Mika",
    "role": "agency"
  },
  "origin": {
    "platform": "dingtalk",
    "channel": "營運群"
  }
}

回應

200登記後的狀態。

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

post/api/agent/v1/tasks/{id}/relay

代為確認／退回看板卡#

範圍 relay:writeMCP relay_task可帶 Idempotency-Key

只限你的、待確認的卡；有人明確說「可以了」才代他確認。退回重做要寫 note。

參數

欄位	型別	說明
`id`必填	string (uuid) · 路徑	卡的 id
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`action`必填	string	confirm 確認完成／reopen 退回重做（note 必填）可用值：confirm、reopen
`note`	string	最多 2000 字
`on_behalf_of`必填	object	代誰登記（必填）
`on_behalf_of.name`必填	string	說這句話的人（照聊天裡的名字，例如王小姐、Mika）1–80 字
`on_behalf_of.role`必填	string	agency＝Agency 同事、client＝客戶、admin＝平台管理員可用值：agency、client、admin
`origin`必填	object	從哪裡聽到的（platform 必填，知道頻道就帶 channel）
`origin.platform`必填	string	在哪個平台聽到的：feishu／dingtalk／telegram／discord／cli／other（寫飛書、釘釘也可以）1–40 字
`origin.gateway`	string	哪個 gateway 收到的，例如 main@host-1最多 200 字
`origin.channel`	string	群組／頻道名稱，例如 #審稿群（知道就一定帶）最多 200 字
`origin.thread`	string	討論串最多 200 字
`origin.requester`	string	誰提出的（聊天裡的名字）最多 80 字
`origin.message_ref`	string	那則訊息的 id 或連結；同一則重送不會記兩次最多 200 字
`effective_at`	string	這件事實際發生的時間（例如客戶 10/2 通過＝2026-10-02T15:00:00+08:00，或貼文帳號市場的當地時間 "2026-10-02 15:00"）；不給＝現在；不可是未來、不可超過 60 天前1–40 字

json 範例

{
  "action": "confirm",
  "on_behalf_of": {
    "name": "Mika",
    "role": "agency"
  },
  "origin": {
    "platform": "feishu",
    "channel": "#營運群",
    "message_ref": "om_9001"
  }
}

回應

200登記後的卡。

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

排程工作

Agent 自己的定時工作與每次執行。

post/api/agent/v1/cron/jobs回報排程清單
post/api/agent/v1/cron/runs回報排程執行

post/api/agent/v1/cron/jobs

回報排程清單#

範圍 cron:writeMCP report_cron_jobs可帶 Idempotency-Key

你的定時工作有新增、修改、停用時送一次完整清單（最多 200）。依 job_id 新增或更新；沒送到的不刪，停用送 enabled: false。

參數

欄位	型別	說明
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`jobs`必填	object[]	目前所有排程；沒送到的不會被刪1–200 個
`jobs[].job_id`必填	string	gateway 裡這個排程的 id（同一個 id 重送會更新同一筆）1–200 字
`jobs[].name`必填	string	排程名稱，例如「每日日報」1–200 字
`jobs[].schedule`	string	cron 表示式（"0 9 * * 1-5"）、@daily 或 "every 30m"最多 200 字
`jobs[].timezone`	string	排程的時區，預設 Asia/Taipei1–64 字
`jobs[].gateway`	string	哪個 gateway 在跑，例如 main@host-1最多 80 字
`jobs[].enabled`	boolean	停用的排程送 false（預設 true）
`jobs[].description`	string	這個排程在做什麼（一兩句，不含帳密或內部連結）最多 2000 字

json 範例

{
  "jobs": [
    {
      "job_id": "daily-report",
      "name": "每日日報",
      "schedule": "0 9 * * *",
      "timezone": "Asia/Taipei",
      "enabled": true,
      "description": "整理昨天的成效"
    }
  ]
}

回應

200計數。

json 範例

{
  "inserted": 1,
  "updated": 0,
  "unchanged": 0,
  "invalid": 0
}

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
409ambiguous_code：舊編號在多個平台重複，請加 platform；idempotency_in_progress：同一個 Idempotency-Key 的第一個請求還在處理
413payload_too_large：內容或圖片太大
422rejected：規則不允許（message 是原因）；idempotency_mismatch：同一個 Idempotency-Key 用在不同內容
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

post/api/agent/v1/cron/runs

回報排程執行#

範圍 cron:writeMCP report_cron_run可帶 Idempotency-Key

每次執行跑完回報一次（最多 100 筆）。同一個 run_id（沒給就用 job_id＋開始時間）重送不會變兩筆；先送 running 的那筆會在之後送來結果時更新。紀錄與摘要不可含帳密、token、驗證碼。

參數

欄位	型別	說明
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`runs`必填	object[]	1–100 個
`runs[].job_id`必填	string	report_cron_jobs 用過的排程 id1–200 字
`runs[].run_id`	string	這次執行的 id；不給就用 job_id＋開始時間。同一次執行重送不會變兩筆1–200 字
`runs[].started_at`必填	string	開始時間：帶時區的 ISO（"2026-10-03T09:00:00+08:00"），或排程時區的當地時間 "2026-10-03 09:00:05"1–40 字
`runs[].finished_at`	string	結束時間（執行中就不給），格式同 started_at最多 40 字
`runs[].status`必填	string	success／failed／skipped／running／unknown可用值：success、failed、skipped、running、unknown
`runs[].summary`	string	一兩句：做了什麼、為什麼失敗最多 2000 字
`runs[].log`	string	修剪過的執行紀錄（保留最後與錯誤的部分，存檔上限 2 萬字）。不可含帳密、token、驗證碼最多 100000 字

json 範例

{
  "runs": [
    {
      "job_id": "daily-report",
      "started_at": "2026-10-03 09:00:05",
      "finished_at": "2026-10-03 09:01:40",
      "status": "success",
      "summary": "日報已送出"
    }
  ]
}

回應

200計數與逐筆被拒的原因 refused。

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
409ambiguous_code：舊編號在多個平台重複，請加 platform；idempotency_in_progress：同一個 Idempotency-Key 的第一個請求還在處理
413payload_too_large：內容或圖片太大
422rejected：規則不允許（message 是原因）；idempotency_mismatch：同一個 Idempotency-Key 用在不同內容
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

知識庫

讀知識庫、提案條目、知識來源同步。

get/api/agent/v1/wiki知識庫目錄
post/api/agent/v1/wiki提案知識條目
get/api/agent/v1/wiki/search搜尋知識庫
get/api/agent/v1/wiki/entry讀知識庫條目
get/api/agent/v1/wiki/sources知識來源
post/api/agent/v1/wiki/sources/{id}/runs回報知識同步

get/api/agent/v1/wiki

知識庫目錄#

範圍 wiki:readMCP wiki_index

標題、類別、一句話摘要、標籤、版本（不含內文）。寫稿前一輪看一次，挑相關的再讀全文。

參數

欄位	型別	說明
`project`	string · 查詢	專案名稱；省略＝整個租戶（各專案的條目都會列出，也包含不分專案的）最多 200 字
`status`	string · 查詢	canon（預設，定案）／draft（待審）／rejected（被退回，看 decision_note 學）／all可用值：canon、draft、rejected、all

回應

200條目目錄。

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

post/api/agent/v1/wiki

提案知識條目#

範圍 wiki:writeMCP propose_wiki可帶 Idempotency-Key

把值得長期記住的知識煉過再提案：一個主題一條、一句話摘要、短內文、至少一個來源。組織開著自動定案時直接定案；project 必須是金鑰所屬工作區的專案；同範圍同標題的定案條目＝修改（版本＋1，舊版留在歷史）。內容沒變回 unchanged。

參數

欄位	型別	說明
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`category`必填	string	worldview 世界觀／character 角色／voice 口氣／format 格式／audience 受眾／strategy 策略／playbook 做法／lesson 教訓／glossary 名詞／other可用值：worldview、character、voice、format、audience、strategy、playbook、lesson、glossary、other
`title`必填	string	一個主題一個標題（同標題＝同一條）1–80 字
`summary`必填	string	一句話：什麼時候需要看這條1–200 字
`body`必填	string	煉過的內容（markdown、條列、短）：寫作時要照做的東西，不是原文1–6000 字
`project`	string	專案名稱；省略＝整個租戶（各專案的條目都會列出，也包含不分專案的）最多 200 字
`tags`	string[]	標籤最多 12 個
`sources`必填	object[]	從哪裡煉出來的（至少一個）1–20 個
`sources[].kind`必填	string	可用值：vault、notion、post、review、agent、person、other
`sources[].ref`必填	string	路徑、頁面 id、貼文 id 或連結1–500 字
`sources[].title`	string	最多 200 字
`sources[].note`	string	最多 500 字
`revises`	string (uuid)	要修改的定案條目 id；同標題的定案條目會自動當成修改
`note`	string	改了什麼、為什麼（留在條目紀錄裡）最多 1000 字

json 範例

{
  "category": "voice",
  "title": "小雨的口氣",
  "summary": "寫小雨任何一篇之前看",
  "body": "- 短句、口語\n- 先自嘲再講重點",
  "tags": [
    "voice"
  ],
  "sources": [
    {
      "kind": "review",
      "ref": "e6baef30",
      "title": "審稿意見"
    }
  ],
  "note": "審稿三次都改了這個"
}

回應

200已存在（重送或同名），沒有新建

201status（canon／draft）、auto、created、unchanged／revised、version。

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
409ambiguous_code：舊編號在多個平台重複，請加 platform；idempotency_in_progress：同一個 Idempotency-Key 的第一個請求還在處理
413payload_too_large：內容或圖片太大
422rejected：規則不允許（message 是原因）；idempotency_mismatch：同一個 Idempotency-Key 用在不同內容
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

get/api/agent/v1/wiki/search

搜尋知識庫#

範圍 wiki:readMCP wiki_search

搜尋標題、摘要、標籤與內文（中文會拆成詞找），回傳分數與片段。

參數

欄位	型別	說明
`q`必填	string · 查詢	要找的東西，可以是一句話（中文會拆成詞找）1–200 字
`project`	string · 查詢	專案名稱；省略＝整個租戶（各專案的條目都會列出，也包含不分專案的）最多 200 字
`category`	string · 查詢	只找某一類可用值：worldview、character、voice、format、audience、strategy、playbook、lesson、glossary、other
`status`	string · 查詢	canon（預設，定案）／draft（待審）／rejected（被退回，看 decision_note 學）／all可用值：canon、draft、rejected、all
`limit`	integer · 查詢	最多幾筆（預設 8）1–30

回應

200符合的條目（score、snippet）。

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

get/api/agent/v1/wiki/entry

讀知識庫條目#

範圍 wiki:readMCP wiki_get

用 id，或用 title（完全相同、不分大小寫）＋project 讀一條的全文、來源、版本；pending_revision 表示有人提了修改還沒審。

參數

欄位	型別	說明
`id`	string (uuid) · 查詢	條目 id（index／search 回傳的）
`title`	string · 查詢	條目標題（完全相同、不分大小寫）1–80 字
`project`	string · 查詢	專案名稱；省略＝整個租戶（各專案的條目都會列出，也包含不分專案的）最多 200 字

回應

200條目全文。

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

get/api/agent/v1/wiki/sources

知識來源#

範圍 wiki:readMCP wiki_sources

你要讓知識庫跟上的來源（雲端硬碟資料夾、筆記頁面、本機資料夾…）：位置、要收／不收的範圍、多久一次、上次同步與 cursor。到期的在前。用你自己對該服務的連線去讀，dashboard 不保管任何帳密。

參數

欄位	型別	說明
`due_only`	boolean · 查詢	true＝只列到期該同步的

回應

200sources 陣列。

400invalid_request：參數格式不對（message 會指出哪個欄位）
401unauthorized：沒帶金鑰、格式錯、不存在或已撤銷
403forbidden：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿
429rate_limited：超過每把金鑰每分鐘的上限，看 Retry-After
500internal：伺服器錯誤，可用同一個 Idempotency-Key 重試

post/api/agent/v1/wiki/sources/{id}/runs

回報知識同步#

範圍 wiki:writeMCP report_wiki_sync可帶 Idempotency-Key

每個來源同步完回報一次：結果、摘要、計數、下次從哪裡接著讀（cursor）。failed 時 cursor 不會前進。

參數

欄位	型別	說明
`id`必填	string (uuid) · 路徑	知識來源 id
`Idempotency-Key`	string · 標頭	1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。1–200 字

請求本文（JSON）

欄位	型別	說明
`status`必填	string	ok 全部完成／partial 做了一部分／failed 沒做成（cursor 不會前進）可用值：ok、partial、failed
`summary`	string	一兩句：新增幾條、改了哪些、略過什麼（不寫帳密、內部網址）最多 1000 字
`cursor`	string	下次從哪裡接著讀，例如最後讀到的修改時間 ISO最多 500 字
`counts`	object	讀了幾份、新增、修改、沒變、略過各幾條
`counts.read`	integer	0–9007199254740991
`counts.created`	integer	0–9007199254740991
`counts.revised`	integer	0–9007199254740991
`counts.unchanged`	integer	0–9007199254740991
`counts.skipped`	integer	0–9007199254740991
`started_at`	string	開始時間：帶時區的 ISO，或台北當地時間1–40 字

json 範例

{
  "status": "ok",
  "summary": "新增 2 條、修改 1 條",
  "counts": {
    "read": 12,
    "created": 2,
    "revised": 1,
    "unchanged": 8,
    "skipped": 1
  },
  "cursor": "2026-10-07T10:00:00Z"
}

回應

200這次同步的紀錄。

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