{"openapi":"3.1.0","info":{"title":"tennnzo API","version":"2026-10-07","summary":"社群帳號艦隊的審稿、排程與 Agent 協作平台","description":"Agent API（/api/agent/v1，Agent 金鑰 tnz_…）讓 Agent 讀人設、交稿、回報排程與成效；個人 API（/api/user/v1，個人金鑰 tnu_…）讓成員用自己的助理或工具做和 dashboard 一樣的事。兩種金鑰也都能用 MCP：POST https://api.tennnzo.com/api/mcp。使用方法見 https://openapi.tennnzo.com 。"},"servers":[{"url":"https://api.tennnzo.com","description":"任何 tennnzo 網域都可以呼叫；組織與工作區由金鑰決定，不看網址"}],"tags":[{"name":"agent-work","x-displayName":"開工與帳號","description":"今天要做什麼、負責的帳號、帳號狀態與頭像、心跳。"},{"name":"agent-personas","x-displayName":"人設與角色","description":"讀人設、登場名單、定裝圖；提事實、交生成圖、自己建人設。"},{"name":"agent-drafts","x-displayName":"草稿與圖片","description":"交稿、重寫、兩段式上傳圖片、補圖、備註。"},{"name":"agent-posts","x-displayName":"排程、發布與成效","description":"審稿通過待排程的稿、回報排程／發布、回報成效。"},{"name":"agent-tasks","x-displayName":"看板","description":"群組裡被交辦的事：開卡、領卡、進度、交結果。"},{"name":"agent-issues","x-displayName":"待裁決後續","description":"待裁決決定後要在平台上做的事（換頭像、改 bio、刪文）。"},{"name":"agent-relay","x-displayName":"代為登記","description":"有人在群組裡說了審稿、裁決或確認的決定，Agent 代他登記。"},{"name":"agent-cron","x-displayName":"排程工作","description":"Agent 自己的定時工作與每次執行。"},{"name":"agent-wiki","x-displayName":"知識庫","description":"讀知識庫、提案條目、知識來源同步。"},{"name":"user-me","x-displayName":"身分","description":"金鑰是誰、在哪個組織、什麼角色。"},{"name":"user-review","x-displayName":"審稿","description":"審稿佇列、單篇、審稿動作。"},{"name":"user-published","x-displayName":"已發布與報告","description":"已發布的貼文與報告。"},{"name":"user-decisions","x-displayName":"待裁決","description":"Agency 與管理員：看待裁決、裁決、回答選項題。"},{"name":"user-tasks","x-displayName":"Agent 看板","description":"Agency 與管理員：看板卡、交辦、確認、退回重做。"},{"name":"user-today","x-displayName":"今日與成效","description":"Agency 與管理員：今日摘要與成效數字。"},{"name":"user-keys","x-displayName":"金鑰管理","description":"平台管理員：這個組織所有金鑰、撤銷。"},{"name":"user-media","x-displayName":"圖片連結","description":"佇列與單篇回傳的簽名圖片連結。"}],"x-tagGroups":[{"name":"Agent API","tags":["agent-work","agent-personas","agent-drafts","agent-posts","agent-tasks","agent-issues","agent-relay","agent-cron","agent-wiki"]},{"name":"個人 API","tags":["user-me","user-review","user-published","user-decisions","user-tasks","user-today","user-keys","user-media"]}],"paths":{"/api/agent/v1/work/today":{"get":{"tags":["agent-work"],"operationId":"agent_work_today","summary":"今天要做的事","description":"開工時呼叫一次：你負責的帳號在各市場的「今天」（或 `date` 指定的那天）還缺幾篇、等你重寫或被退回的稿、看板上交給你的卡、待裁決後要做的事。剛排好或發出的貼文要先回報（`POST /posts/report`）才會算到。","parameters":[{"name":"date","in":"query","required":false,"description":"YYYY-MM-DD（帳號市場的日期）；不給＝各市場的今天","schema":{"type":"string","maxLength":10}}],"responses":{"200":{"description":"`missing` 缺稿的帳號、`not_in_rotation` 不在每日目標裡的帳號、`redo` 要重做的稿、`tasks` 看板卡、`follow_ups` 待裁決後續。","content":{"application/json":{"schema":{"type":"object"},"example":{"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":[]}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"accounts:read","x-mcp-tool":"work_today"}},"/api/agent/v1/accounts":{"get":{"tags":["agent-work"],"operationId":"agent_list_accounts","summary":"我負責的帳號","description":"你負責的帳號編號：平台、市場與時區、人設、handle、現役世代的狀態（`null`＝目前沒有現役帳號）、每日目標。","responses":{"200":{"description":"`accounts` 陣列。","content":{"application/json":{"schema":{"type":"object"},"example":{"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}]}}}},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"accounts:read","x-mcp-tool":"list_accounts"},"post":{"tags":["agent-work"],"operationId":"agent_add_account","summary":"新增帳號","description":"在你自己的人設下建立帳號編號與第一代帳號（工作區自助匯入用）。編號與市場會轉大寫。同人設同編號重送回 200、`created: false`；編號屬於別的人設會被拒。","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountAddInput"},"example":{"persona_id":"0b6c…","platform":"instagram","code":"TW-I001","handle":"demo.xiaoyu","state":"warming"}}}},"responses":{"200":{"description":"已存在（重送或同名），沒有新建","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"新建回 201，已存在回 200。","content":{"application/json":{"schema":{"type":"object"},"example":{"slot_id":"…","account_id":"…","code":"TW-I001","platform":"instagram","market":"TW","created":true}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"accounts:write","x-mcp-tool":"add_account","x-idempotent":true}},"/api/agent/v1/accounts/{code}/state":{"post":{"tags":["agent-work"],"operationId":"agent_report_account_state","summary":"回報帳號狀態","description":"平台把帳號封鎖、隔離、暫停、恢復或回到養號時回報。被封、隔離、暫停要寫 `reason`。被封**不會**自動開新一代：系統開一件待裁決請人決定。同狀態重送回 `unchanged`。","parameters":[{"name":"code","in":"path","required":true,"description":"帳號編號，例如 TW-T014（舊編號也可以）","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"description":"舊編號在多個平台重複時才需要","schema":{"type":"string","enum":["threads","tiktok","x","facebook","instagram","reddit"]}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountStateInput"},"example":{"state":"banned","reason":"平台通知：違反社群守則","occurred_at":"2026-10-05 14:30"}}}},"responses":{"200":{"description":"狀態變化與（被封時）開出的待裁決。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"accounts:write","x-mcp-tool":"report_account_state","x-idempotent":true}},"/api/agent/v1/accounts/{code}/avatar":{"post":{"tags":["agent-work"],"operationId":"agent_set_account_avatar","summary":"同步帳號頭像","description":"傳帳號在平台上**現在的**頭像（base64，JPEG／PNG／WebP，5 MB 以內），審稿頁與人設頁會顯示它。同一張重送 `changed: false`。","parameters":[{"name":"code","in":"path","required":true,"description":"帳號編號，例如 TW-T014（舊編號也可以）","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"description":"舊編號在多個平台重複時才需要","schema":{"type":"string","enum":["threads","tiktok","x","facebook","instagram","reddit"]}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountAvatarInput"}}}},"responses":{"200":{"description":"存好的頭像與是否有變。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"accounts:write","x-mcp-tool":"set_account_avatar","x-idempotent":true}},"/api/agent/v1/heartbeat":{"post":{"tags":["agent-work"],"operationId":"agent_heartbeat","summary":"心跳","description":"每輪收工送一次（沒事做也送）：一兩句摘要與計數。同一個 `run_id` 再送會更新同一筆（摘要取代、計數合併）。回傳你手上的看板卡。","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HeartbeatInput"},"example":{"run_id":"run-20261005-1","summary":"寫了 3 篇、重寫 1 篇","counts":{"drafts":3,"rewrites":1}}}}},"responses":{"200":{"description":"這一輪的紀錄與手上的卡。","content":{"application/json":{"schema":{"type":"object"},"example":{"run":{"id":"…","run_id":"run-20261005-1","recorded_at":"…"},"tasks":[{"id":"…","kind":"change_avatar","title":"換頭像","status":"in_progress","stale":false,"overdue":false}]}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"runs:write","x-mcp-tool":"heartbeat","x-idempotent":true}},"/api/agent/v1/personas/{code}":{"get":{"tags":["agent-personas"],"operationId":"agent_get_persona","summary":"讀人設","description":"寫稿前讀一次：人設基本資料與完整設定、各平台編號、正式事實（`by_decision: true` 是裁決過的，優先）、說話習慣 `speech_rules` 與禁用 `forbidden`、已定案的本人圖（15 分鐘連結）、最近貼文、登場名單 `cast`。","parameters":[{"name":"code","in":"path","required":true,"description":"帳號編號，例如 TW-T014（舊編號也可以）","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"description":"舊編號在多個平台重複時才需要","schema":{"type":"string","enum":["threads","tiktok","x","facebook","instagram","reddit"]}},{"name":"include","in":"query","required":false,"description":"`drafts`＝連草稿事實一起給","schema":{"type":"string","enum":["drafts"]}},{"name":"posts","in":"query","required":false,"description":"最近幾篇已發布貼文（預設 10，最多 30）","schema":{"type":"integer","minimum":0,"maximum":30}}],"responses":{"200":{"description":"`persona`、`accounts`、`facts`、`speech_rules`、`forbidden`、`images`、`recent_posts`、`cast`。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"personas:read","x-mcp-tool":"get_persona"}},"/api/agent/v1/personas":{"post":{"tags":["agent-personas"],"operationId":"agent_create_persona","summary":"建立人設","description":"工作區還沒有人設時，Agent 自己建立（歸呼叫的 Agent）。`project` 必須是金鑰所屬工作區的專案。同時開一件待裁決「新人設待確認」給人看。有 bio 與 voice 才算設定完成。同專案同名重送回 200、`created: false`。","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonaCreateInput"},"example":{"name":"小雨","track":"生活","background":"台北上班族，下班喜歡找咖啡廳","bio":"下班後的咖啡地圖","voice":"口語、短句、偶爾自嘲"}}}},"responses":{"200":{"description":"已存在（重送或同名），沒有新建","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"新建回 201。","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"…","created":true,"project":"…","setup_complete":true,"issue_id":"…"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"personas:write","x-mcp-tool":"create_persona","x-idempotent":true}},"/api/agent/v1/personas/{code}/images":{"get":{"tags":["agent-personas"],"operationId":"agent_list_persona_images","summary":"下載已定案圖","description":"人設已核可、已發布的定裝圖，生圖前拿來當參考。`url`、`thumb_url` 是 15 分鐘有效的下載連結，不要存起來或貼出去。","parameters":[{"name":"code","in":"path","required":true,"description":"帳號編號，例如 TW-T014（舊編號也可以）","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"description":"編號重複時才需要（舊 V 編號 Threads 與 TikTok 會撞）","schema":{"type":"string","enum":["threads","tiktok","x","facebook","instagram","reddit"]}},{"name":"category","in":"query","required":false,"description":"只要某一類","schema":{"type":"string","enum":["turnaround","portrait","avatar","pet","home","workplace","belongings","photo_style","other"]}}],"responses":{"200":{"description":"圖片清單（含簽名連結）。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"personas:read","x-mcp-tool":"list_persona_images"},"post":{"tags":["agent-personas"],"operationId":"agent_upload_persona_image","summary":"交生成圖","description":"交一張人設或角色的生成圖（base64，5 MB 以內）。存成**草稿圖**，出現在待裁決「待核可圖片」，人核可後才算定案。同一張重送不會多一列；帶 `character` 表示是某個角色的參考圖。","parameters":[{"name":"code","in":"path","required":true,"description":"帳號編號，例如 TW-T014（舊編號也可以）","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"description":"舊編號在多個平台重複時才需要","schema":{"type":"string","enum":["threads","tiktok","x","facebook","instagram","reddit"]}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonaImageInput"}}}},"responses":{"200":{"description":"已存在（重送或同名），沒有新建","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"新圖回 201，已存在回 200。","content":{"application/json":{"schema":{"type":"object"},"example":{"image":{"id":"…","created":true,"lock":"draft","code":"TW-T014","character":"AB-01"}}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"personas:write","x-mcp-tool":"upload_persona_image","x-idempotent":true}},"/api/agent/v1/personas/{code}/proposals":{"post":{"tags":["agent-personas"],"operationId":"agent_propose_fact","summary":"提事實／矛盾","description":"寫稿時發現人設沒寫的細節（`fact`，進草稿事實）或前後矛盾（`contradiction`，進待裁決）。都不會直接變成正式設定。同一條重送回 200、`created: false`。","parameters":[{"name":"code","in":"path","required":true,"description":"帳號編號，例如 TW-T014（舊編號也可以）","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"description":"舊編號在多個平台重複時才需要","schema":{"type":"string","enum":["threads","tiktok","x","facebook","instagram","reddit"]}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalInput"},"example":{"kind":"fact","category":"pet","label":"貓的名字","value":"布丁","detail":"10/3 那篇提到"}}}},"responses":{"200":{"description":"已存在（重送或同名），沒有新建","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"新提案回 201，重送回 200。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"personas:write","x-mcp-tool":"propose_fact","x-idempotent":true}},"/api/agent/v1/personas/{code}/cast":{"get":{"tags":["agent-personas"],"operationId":"agent_list_cast","summary":"登場名單","description":"這個人設的帳號可以出現哪些角色：代號、名字、一句話、知識庫條目，以及每個角色最多 6 張參考圖（15 分鐘連結）。`get_persona` 也回傳同一塊。","parameters":[{"name":"code","in":"path","required":true,"description":"帳號編號，例如 TW-T014（舊編號也可以）","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"description":"編號重複時才需要（舊 V 編號 Threads 與 TikTok 會撞）","schema":{"type":"string","enum":["threads","tiktok","x","facebook","instagram","reddit"]}}],"responses":{"200":{"description":"`cast` 陣列。","content":{"application/json":{"schema":{"type":"object"},"example":{"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}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"personas:read","x-mcp-tool":"list_cast"}},"/api/agent/v1/drafts":{"get":{"tags":["agent-drafts"],"operationId":"agent_list_redo","summary":"要重做的稿","description":"等你重寫（`rewrite_requested`）或被退回（`sent_back`）的稿，含目前內文、重寫指示或退回意見、這篇所有審稿意見（舊到新）、登場角色。","parameters":[{"name":"status","in":"query","required":false,"description":"只看一種；不給兩種都列","schema":{"type":"string","enum":["rewrite_requested","sent_back"]}}],"responses":{"200":{"description":"要重做的稿。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"drafts:read","x-mcp-tool":"list_redo"},"post":{"tags":["agent-drafts"],"operationId":"agent_submit_draft","summary":"交草稿","description":"交一篇新稿，預設直接送內部審稿（`submit: false` 只存草稿）。有圖的稿先查素材庫（`GET /media`）能重用的帶 `media_ids`，新素材才用 `POST /uploads` 傳，再帶 `upload_ids`（依發布順序，`media_ids` 接在後面）。同一個編號、內文完全相同、還沒發出的稿不會建第二篇（回 200、`duplicate: true`，帶的 `upload_ids`、`media_ids`、`characters`、`note` 會套到原稿）。","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftInput"},"example":{"code":"TW-T014","body":"下班後終於找到一間安靜的咖啡廳……","topic":"週末咖啡","planned_at":"2026-10-05 20:00","upload_ids":["3f0e…","8a21…"],"characters":[{"code":"AB-01"}],"note":"第二張是店門口"}}}},"responses":{"200":{"description":"已存在（重送或同名），沒有新建","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"新稿回 201，重複回 200。","content":{"application/json":{"schema":{"type":"object"},"example":{"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}]}}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"drafts:write","x-mcp-tool":"submit_draft","x-idempotent":true}},"/api/agent/v1/drafts/{id}":{"put":{"tags":["agent-drafts"],"operationId":"agent_update_draft","summary":"交重寫版本","description":"交整篇新內文（只能改自己帳號、還在草稿的稿）。內文一變就解除「等 Agent 重寫」；和退回時一模一樣的內文會被 422 擋。預設改完送審。","parameters":[{"name":"id","in":"path","required":true,"description":"稿的 id","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftUpdate"},"example":{"body":"改好的完整內文……","note":"開頭改成從天氣切入"}}}},"responses":{"200":{"description":"改好的稿。","content":{"application/json":{"schema":{"type":"object"},"example":{"draft":{"id":"e6baef30-…","status":"internal_review","rewrite_answered":true}}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"drafts:write","x-mcp-tool":"update_draft","x-idempotent":true}},"/api/agent/v1/drafts/{id}/images":{"post":{"tags":["agent-drafts"],"operationId":"agent_attach_images","summary":"把圖補到稿上","description":"把傳好的圖或影片補到已交的稿（草稿或內部審稿中才行），接在原有的後面，同時成為素材庫的素材。全有或全無：任何一個 id 不對，整個請求拒絕。Instagram 一篇最多 10 個，其他平台 4 個（圖與影片合計）；Reddit 不能放影片。","parameters":[{"name":"id","in":"path","required":true,"description":"稿的 id","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImagesAttach"}}}},"responses":{"200":{"description":"這篇現在的圖數。","content":{"application/json":{"schema":{"type":"object"},"example":{"draft":{"id":"e6baef30-…","images":3}}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"drafts:write","x-mcp-tool":"attach_images","x-idempotent":true}},"/api/agent/v1/drafts/{id}/notes":{"post":{"tags":["agent-drafts"],"operationId":"agent_add_note","summary":"給審稿的備註","description":"給審稿的人一段說明（還缺什麼、為什麼這樣寫），進審稿紀錄、顯示為「新增備註」。主題欄只寫短主題。","parameters":[{"name":"id","in":"path","required":true,"description":"稿的 id","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteInput"},"example":{"note":"第 3 張是示意圖，正式圖明天補"}}}},"responses":{"200":{"description":"已記下。","content":{"application/json":{"schema":{"type":"object"},"example":{"draft":{"id":"e6baef30-…","noted":true}}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"drafts:write","x-mcp-tool":"add_note","x-idempotent":true}},"/api/agent/v1/uploads":{"post":{"tags":["agent-drafts"],"operationId":"agent_create_upload","summary":"要一個上傳圖片或影片的連結","description":"上傳的第一步：每個新檔要一個一次性連結。圖片（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`）。","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadCreate"},"example":{"code":"TW-T014","caption":"第 1 張","tags":["收尾"]}}}},"responses":{"201":{"description":"上傳連結（單檔：1 小時內、只能用一次；分塊：23 小時內）。分塊上傳的回應是 `{ upload_id, mode: \"chunked\", chunk_url, method, chunk_bytes, chunks, expires_at, how, poster_url }`。","content":{"application/json":{"schema":{"type":"object"},"example":{"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>'"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"drafts:write","x-mcp-tool":"create_upload","x-idempotent":true}},"/api/agent/v1/uploads/{id}":{"put":{"tags":["agent-drafts"],"operationId":"agent_put_upload_file","summary":"傳檔（用上傳連結）","description":"上傳的第二步：請求本文就是檔案本身（`curl -sS -T photo.jpg '<upload_url>'`）。**不帶金鑰**，連結裡的一次性 token `t` 就是憑證。JPEG／PNG／WebP 圖片或 MP4／MOV／WebM 影片，單檔 4 MB 內（看檔頭判斷）。傳完就進素材庫，回應的 `media_id` 可以直接用在 `media_ids`；同樣的檔案素材庫已有時回那一個素材的 id。","parameters":[{"name":"id","in":"path","required":true,"description":"upload_id","schema":{"type":"string","format":"uuid"}},{"name":"t","in":"query","required":true,"description":"上傳連結裡的一次性 token（照 upload_url 原樣用）","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"圖檔的原始位元組。","content":{"application/octet-stream":{"schema":{"type":"string","contentMediaType":"image/*"}}}},"responses":{"200":{"description":"收到的檔案與它在素材庫的 `media_id`。","content":{"application/json":{"schema":{"type":"object"},"example":{"upload_id":"3f0e…","media_id":"5c1d…","mime_type":"image/jpeg","kind":"image","bytes":482113}}}},"400":{"$ref":"#/components/responses/Agent400"},"404":{"$ref":"#/components/responses/Agent404"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[]}},"/api/agent/v1/uploads/{id}/chunks":{"put":{"tags":["agent-drafts"],"operationId":"agent_put_upload_chunk","summary":"傳一塊（分塊上傳）","description":"影片超過 4 MB 時的第二步：把檔案切成 `chunk_bytes`（3 MiB）一塊，**依序**每塊 PUT 一次，`n` 從 0 開始；最後一塊可以比較小。不帶金鑰，用 `chunk_url` 原樣加上 `&n=`。已收過的塊再送一次只會回目前進度；跳號回 422 並說下一塊是幾號。最後一塊回 `done: true` 與 `media_id`：伺服器算出內容雜湊、讀出影片長度與尺寸，影片已經進素材庫（同樣的檔案已有時回那一個），之後用 `media_ids` 附到稿上。","parameters":[{"name":"id","in":"path","required":true,"description":"upload_id","schema":{"type":"string","format":"uuid"}},{"name":"t","in":"query","required":true,"description":"上傳連結裡的一次性 token（照 chunk_url 原樣用）","schema":{"type":"string"}},{"name":"n","in":"query","required":true,"description":"第幾塊，從 0 開始","schema":{"type":"integer","minimum":0}}],"requestBody":{"required":true,"description":"這一塊的原始位元組（最後一塊以外都剛好 3145728 位元組）。","content":{"application/octet-stream":{"schema":{"type":"string","contentMediaType":"image/*"}}}},"responses":{"200":{"description":"目前進度；完成時多 `media_id`。","content":{"application/json":{"schema":{"type":"object"},"example":{"upload_id":"3f0e…","media_id":"5c1d…","received_bytes":52428800,"total_bytes":52428800,"next_chunk":null,"done":true}}}},"400":{"$ref":"#/components/responses/Agent400"},"404":{"$ref":"#/components/responses/Agent404"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[]}},"/api/agent/v1/uploads/{id}/poster":{"put":{"tags":["agent-drafts"],"operationId":"agent_put_upload_poster","summary":"傳影片封面","description":"影片上傳可另外傳一張封面（JPEG／PNG／WebP，4 MB 內），素材庫與審稿頁用它當縮圖；不傳就顯示影片圖示。影片傳完之前或之後都可以，交稿後也可以。不帶金鑰，用 `poster_url` 原樣。","parameters":[{"name":"id","in":"path","required":true,"description":"upload_id","schema":{"type":"string","format":"uuid"}},{"name":"t","in":"query","required":true,"description":"上傳連結裡的一次性 token（照 poster_url 原樣用）","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"封面圖的原始位元組。","content":{"application/octet-stream":{"schema":{"type":"string","contentMediaType":"image/*"}}}},"responses":{"200":{"description":"已存。","content":{"application/json":{"schema":{"type":"object"},"example":{"upload_id":"3f0e…","poster":true}}}},"400":{"$ref":"#/components/responses/Agent400"},"404":{"$ref":"#/components/responses/Agent404"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[]}},"/api/agent/v1/media":{"get":{"tags":["agent-drafts"],"operationId":"agent_list_media","summary":"查素材庫","description":"組織共用的素材庫（圖片與影片），只列你負責的專案能用的（該專案的與不分專案共用的；專案都在金鑰的工作區），不含封存。上傳前先查：能重用的帶 `media_ids` 交稿，或用 `POST /drafts/{id}/media` 補上。`used_count` 是用到這個素材的貼文數。連結在 tennnzo 網域、24 小時以上有效；影片支援 Range。","parameters":[{"name":"project","in":"query","required":false,"description":"專案名稱（只看這個專案可用的素材）","schema":{"type":"string","minLength":1,"maxLength":80}},{"name":"character","in":"query","required":false,"description":"角色代號，例如 AS-01","schema":{"type":"string","minLength":1,"maxLength":24}},{"name":"tag","in":"query","required":false,"description":"標籤，例如 固定收尾","schema":{"type":"string","minLength":1,"maxLength":30}},{"name":"kind","in":"query","required":false,"description":"","schema":{"type":"string","enum":["image","video"]}},{"name":"q","in":"query","required":false,"description":"搜尋說明與標籤裡的字","schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"sort","in":"query","required":false,"description":"newest（預設）或 most_used（最常用的在前）","schema":{"type":"string","enum":["newest","most_used"]}},{"name":"limit","in":"query","required":false,"description":"最多幾筆（預設 30）","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"`media` 陣列。","content":{"application/json":{"schema":{"type":"object"},"example":{"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}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"drafts:read","x-mcp-tool":"list_media"}},"/api/agent/v1/drafts/{id}/media":{"post":{"tags":["agent-drafts"],"operationId":"agent_attach_media","summary":"從素材庫加到稿上","description":"把素材庫的素材（`GET /media` 的 id）加到已交的稿（草稿或內部審稿中才行），依 `media_ids` 順序接在原有的後面；已經在這篇的會略過。同一個素材可以用在很多篇。封存的、別專案的拒絕；上限與影片規則同 `POST /drafts/{id}/images`。","parameters":[{"name":"id","in":"path","required":true,"description":"稿的 id","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaAttach"},"example":{"media_ids":["5c1d…"],"note":"最後一張用固定收尾圖"}}}},"responses":{"200":{"description":"這篇現在的素材數。","content":{"application/json":{"schema":{"type":"object"},"example":{"draft":{"id":"e6baef30-…","media":5}}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"drafts:write","x-mcp-tool":"attach_media","x-idempotent":true}},"/api/agent/v1/posts/approved":{"get":{"tags":["agent-posts"],"operationId":"agent_list_approved","summary":"審稿通過、待排程的稿","description":"審稿已核可、還沒排上發布工具的稿，計畫時間早的在前，最多 200 篇。附圖與影片照審稿頁的順序回傳（`images[].kind` 區分圖片與影片，連結在 tennnzo 網域、24 小時以上有效，影片支援 Range）：發布時照這個順序上傳。排好後回報 `scheduled`＋`post_id` 就會離開清單。","responses":{"200":{"description":"`posts` 陣列。","content":{"application/json":{"schema":{"type":"object"},"example":{"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":[]}]}}}},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"drafts:read","x-mcp-tool":"list_approved"}},"/api/agent/v1/posts/report":{"post":{"tags":["agent-posts"],"operationId":"agent_report_posts","summary":"回報排程／發布","description":"用自己的工具在平台上排好、發出、失敗或取消之後**立刻**回報（一次最多 200 篇）。`published` 必帶 `permalink`。每篇各自檢查、各自處理：一篇錯只擋那一篇，整批都被拒才回 422（什麼都沒寫，Idempotency-Key 不會被佔用）。對到同一篇的順序：`post_id` → `platform_post_id` → 同編號、同內文、時間最接近的那篇。","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"description":"請求只整批檢查 `posts` 是 1–200 篇的陣列；每篇照下面的欄位各自檢查。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostsReportInput"},"example":{"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"}]}}}},"responses":{"200":{"description":"每篇的結果。`action`：inserted／updated／unchanged／ignored；`ok: false` 的看 `error`。","content":{"application/json":{"schema":{"type":"object"},"example":{"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"}]}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"posts:write","x-mcp-tool":"report_posts","x-idempotent":true}},"/api/agent/v1/metrics":{"post":{"tags":["agent-posts"],"operationId":"agent_report_metrics","summary":"回報成效","description":"自己抓到的數字才報：貼文的瀏覽、讚、回覆、轉發、分享，帳號粉絲數。同一個 `captured_at` 重送會覆蓋；全空不寫。還沒有平台 id 的貼文要先回報發布。`captured_at` 不可是未來、不可超過 60 天前。","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsInput"},"example":{"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}]}}}},"responses":{"200":{"description":"寫入的計數與逐筆被拒的原因 `refused`。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"metrics:write","x-mcp-tool":"report_metrics","x-idempotent":true}},"/api/agent/v1/tasks":{"get":{"tags":["agent-tasks"],"operationId":"agent_list_tasks","summary":"我的看板卡","description":"交給你的卡，以及你人設上還沒指派的卡。","parameters":[{"name":"status","in":"query","required":false,"description":"逗號分隔；預設 open,in_progress,awaiting_confirmation","schema":{"type":"string","example":"open,in_progress"}}],"responses":{"200":{"description":"`tasks` 陣列（`target`、`origin`、`due_at`、`stale`／`overdue` 等）。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"accounts:read","x-mcp-tool":"list_tasks"},"post":{"tags":["agent-tasks"],"operationId":"agent_open_task","summary":"開卡","description":"群組裡被叫做事時先開卡再動手。同一個 Agent＋同一種事＋同一個對象已有進行中的卡就回那張（200、`created: false`），並把這次的提出者記在「也要這個」。","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenTaskInput"},"example":{"kind":"change_avatar","title":"TW-T014 換頭像","target":{"type":"slot","code":"TW-T014"},"origin":{"platform":"feishu","channel":"#營運群","requester":"Mika"}}}}},"responses":{"200":{"description":"已存在（重送或同名），沒有新建","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"新卡回 201，已有回 200。","content":{"application/json":{"schema":{"type":"object"},"example":{"task":{"id":"…","status":"open"},"created":true}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"tasks:write","x-mcp-tool":"open_task","x-idempotent":true}},"/api/agent/v1/tasks/{id}/claim":{"post":{"tags":["agent-tasks"],"operationId":"agent_claim_task","summary":"領卡","description":"開始做一張待領取的卡之前呼叫一次（重送無害）。也可以領你人設上還沒指派的卡。","parameters":[{"name":"id","in":"path","required":true,"description":"卡的 id","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"更新後的卡。","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"tasks:write","x-mcp-tool":"claim_task","x-idempotent":true}},"/api/agent/v1/tasks/{id}/progress":{"post":{"tags":["agent-tasks"],"operationId":"agent_report_task","summary":"回報進度","description":"做的過程中回報進度（一兩句）。","parameters":[{"name":"id","in":"path","required":true,"description":"卡的 id","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskProgress"},"example":{"note":"頭像已生成，等上傳"}}}},"responses":{"200":{"description":"更新後的卡。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"tasks:write","x-mcp-tool":"report_task","x-idempotent":true}},"/api/agent/v1/tasks/{id}/finish":{"post":{"tags":["agent-tasks"],"operationId":"agent_finish_task","summary":"交結果","description":"做完交結果與證據，卡進「待確認」由人確認。不要自己確認自己的卡。","parameters":[{"name":"id","in":"path","required":true,"description":"卡的 id","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskFinish"},"example":{"result":"頭像已換成新的定裝照","evidence":[{"type":"link","url":"https://www.threads.net/@demo.xiaoyu","label":"個人頁"}]}}}},"responses":{"200":{"description":"更新後的卡。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"tasks:write","x-mcp-tool":"finish_task","x-idempotent":true}},"/api/agent/v1/tasks/{id}/fail":{"post":{"tags":["agent-tasks"],"operationId":"agent_fail_task","summary":"做不到","description":"做不到時說明原因。","parameters":[{"name":"id","in":"path","required":true,"description":"卡的 id","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskFail"},"example":{"reason":"帳號需要重新登入，無法更換"}}}},"responses":{"200":{"description":"更新後的卡。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"tasks:write","x-mcp-tool":"fail_task","x-idempotent":true}},"/api/agent/v1/issues/{id}/done":{"post":{"tags":["agent-issues"],"operationId":"agent_complete_issue","summary":"線上動作完成","description":"待裁決決定後要在平台上做的事（換頭像、刪文、改 bio）做完時回報，附結果與證據。對應的看板卡進「待確認」由人確認。id 用 `work_today` 的 `follow_ups[].id`。","parameters":[{"name":"id","in":"path","required":true,"description":"待裁決的 id","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueDoneInput"},"example":{"result":"頭像已換成虎斑貓","evidence":[{"type":"asset","asset_id":"…"}]}}}},"responses":{"200":{"description":"處理結果。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"issues:write","x-mcp-tool":"complete_issue","x-idempotent":true}},"/api/agent/v1/posts/{id}/transition":{"post":{"tags":["agent-relay"],"operationId":"agent_relay_post_status","summary":"代為更改貼文狀態","description":"有人在群組裡明確說了審稿決定，代他登記，規則和他自己按按鈕一樣。客戶只能在「待客戶審稿」時通過、退回、要求修改、要求重寫（專案要開客戶審稿）。`mark_published` 需要貼文已經有連結，沒有就改用回報發布。","parameters":[{"name":"id","in":"path","required":true,"description":"貼文 id","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostTransitionInput"},"example":{"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"}}}},"responses":{"200":{"description":"登記後的狀態。","content":{"application/json":{"schema":{"type":"object"},"example":{"post_id":"7f2c…","action":"approve","status":"approved","effective_at":"2026-10-02T07:20:00+00:00"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"relay:write","x-mcp-tool":"relay_post_status","x-idempotent":true}},"/api/agent/v1/issues/{id}/relay":{"post":{"tags":["agent-relay"],"operationId":"agent_relay_issue","summary":"代為裁決","description":"代 Agency 或管理員登記待裁決的決定：已處理、不處理（要原因）、選選項（`chosen` 空陣列＝其他，答案寫在 note）。","parameters":[{"name":"id","in":"path","required":true,"description":"待裁決的 id","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueRelayInput"},"example":{"action":"choose","chosen":["tabby"],"on_behalf_of":{"name":"Mika","role":"agency"},"origin":{"platform":"dingtalk","channel":"營運群"}}}}},"responses":{"200":{"description":"登記後的狀態。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"relay:write","x-mcp-tool":"relay_issue","x-idempotent":true}},"/api/agent/v1/tasks/{id}/relay":{"post":{"tags":["agent-relay"],"operationId":"agent_relay_task","summary":"代為確認／退回看板卡","description":"只限你的、待確認的卡；有人明確說「可以了」才代他確認。退回重做要寫 note。","parameters":[{"name":"id","in":"path","required":true,"description":"卡的 id","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskRelayInput"},"example":{"action":"confirm","on_behalf_of":{"name":"Mika","role":"agency"},"origin":{"platform":"feishu","channel":"#營運群","message_ref":"om_9001"}}}}},"responses":{"200":{"description":"登記後的卡。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"relay:write","x-mcp-tool":"relay_task","x-idempotent":true}},"/api/agent/v1/cron/jobs":{"post":{"tags":["agent-cron"],"operationId":"agent_report_cron_jobs","summary":"回報排程清單","description":"你的定時工作有新增、修改、停用時送一次完整清單（最多 200）。依 `job_id` 新增或更新；沒送到的不刪，停用送 `enabled: false`。","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CronJobsInput"},"example":{"jobs":[{"job_id":"daily-report","name":"每日日報","schedule":"0 9 * * *","timezone":"Asia/Taipei","enabled":true,"description":"整理昨天的成效"}]}}}},"responses":{"200":{"description":"計數。","content":{"application/json":{"schema":{"type":"object"},"example":{"inserted":1,"updated":0,"unchanged":0,"invalid":0}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"cron:write","x-mcp-tool":"report_cron_jobs","x-idempotent":true}},"/api/agent/v1/cron/runs":{"post":{"tags":["agent-cron"],"operationId":"agent_report_cron_run","summary":"回報排程執行","description":"每次執行跑完回報一次（最多 100 筆）。同一個 `run_id`（沒給就用 `job_id`＋開始時間）重送不會變兩筆；先送 `running` 的那筆會在之後送來結果時更新。紀錄與摘要不可含帳密、token、驗證碼。","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CronRunsInput"},"example":{"runs":[{"job_id":"daily-report","started_at":"2026-10-03 09:00:05","finished_at":"2026-10-03 09:01:40","status":"success","summary":"日報已送出"}]}}}},"responses":{"200":{"description":"計數與逐筆被拒的原因 `refused`。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"cron:write","x-mcp-tool":"report_cron_run","x-idempotent":true}},"/api/agent/v1/wiki":{"get":{"tags":["agent-wiki"],"operationId":"agent_wiki_index","summary":"知識庫目錄","description":"標題、類別、一句話摘要、標籤、版本（不含內文）。寫稿前一輪看一次，挑相關的再讀全文。","parameters":[{"name":"project","in":"query","required":false,"description":"專案名稱；省略＝整個租戶（各專案的條目都會列出，也包含不分專案的）","schema":{"type":"string","maxLength":200}},{"name":"status","in":"query","required":false,"description":"canon（預設，定案）／draft（待審）／rejected（被退回，看 decision_note 學）／all","schema":{"type":"string","enum":["canon","draft","rejected","all"]}}],"responses":{"200":{"description":"條目目錄。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"wiki:read","x-mcp-tool":"wiki_index"},"post":{"tags":["agent-wiki"],"operationId":"agent_propose_wiki","summary":"提案知識條目","description":"把值得長期記住的知識煉過再提案：一個主題一條、一句話摘要、短內文、至少一個來源。組織開著自動定案時直接定案；`project` 必須是金鑰所屬工作區的專案；同範圍同標題的定案條目＝修改（版本＋1，舊版留在歷史）。內容沒變回 `unchanged`。","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WikiProposeInput"},"example":{"category":"voice","title":"小雨的口氣","summary":"寫小雨任何一篇之前看","body":"- 短句、口語\n- 先自嘲再講重點","tags":["voice"],"sources":[{"kind":"review","ref":"e6baef30","title":"審稿意見"}],"note":"審稿三次都改了這個"}}}},"responses":{"200":{"description":"已存在（重送或同名），沒有新建","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"`status`（canon／draft）、`auto`、`created`、`unchanged`／`revised`、`version`。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"wiki:write","x-mcp-tool":"propose_wiki","x-idempotent":true}},"/api/agent/v1/wiki/search":{"get":{"tags":["agent-wiki"],"operationId":"agent_wiki_search","summary":"搜尋知識庫","description":"搜尋標題、摘要、標籤與內文（中文會拆成詞找），回傳分數與片段。","parameters":[{"name":"q","in":"query","required":true,"description":"要找的東西，可以是一句話（中文會拆成詞找）","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"project","in":"query","required":false,"description":"專案名稱；省略＝整個租戶（各專案的條目都會列出，也包含不分專案的）","schema":{"type":"string","maxLength":200}},{"name":"category","in":"query","required":false,"description":"只找某一類","schema":{"type":"string","enum":["worldview","character","voice","format","audience","strategy","playbook","lesson","glossary","other"]}},{"name":"status","in":"query","required":false,"description":"canon（預設，定案）／draft（待審）／rejected（被退回，看 decision_note 學）／all","schema":{"type":"string","enum":["canon","draft","rejected","all"]}},{"name":"limit","in":"query","required":false,"description":"最多幾筆（預設 8）","schema":{"type":"integer","minimum":1,"maximum":30}}],"responses":{"200":{"description":"符合的條目（`score`、`snippet`）。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"wiki:read","x-mcp-tool":"wiki_search"}},"/api/agent/v1/wiki/entry":{"get":{"tags":["agent-wiki"],"operationId":"agent_wiki_get","summary":"讀知識庫條目","description":"用 `id`，或用 `title`（完全相同、不分大小寫）＋`project` 讀一條的全文、來源、版本；`pending_revision` 表示有人提了修改還沒審。","parameters":[{"name":"id","in":"query","required":false,"description":"條目 id（index／search 回傳的）","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"title","in":"query","required":false,"description":"條目標題（完全相同、不分大小寫）","schema":{"type":"string","minLength":1,"maxLength":80}},{"name":"project","in":"query","required":false,"description":"專案名稱；省略＝整個租戶（各專案的條目都會列出，也包含不分專案的）","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"條目全文。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"wiki:read","x-mcp-tool":"wiki_get"}},"/api/agent/v1/wiki/sources":{"get":{"tags":["agent-wiki"],"operationId":"agent_wiki_sources","summary":"知識來源","description":"你要讓知識庫跟上的來源（雲端硬碟資料夾、筆記頁面、本機資料夾…）：位置、要收／不收的範圍、多久一次、上次同步與 cursor。到期的在前。用你自己對該服務的連線去讀，dashboard 不保管任何帳密。","parameters":[{"name":"due_only","in":"query","required":false,"description":"true＝只列到期該同步的","schema":{"type":"boolean"}}],"responses":{"200":{"description":"`sources` 陣列。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"wiki:read","x-mcp-tool":"wiki_sources"}},"/api/agent/v1/wiki/sources/{id}/runs":{"post":{"tags":["agent-wiki"],"operationId":"agent_report_wiki_sync","summary":"回報知識同步","description":"每個來源同步完回報一次：結果、摘要、計數、下次從哪裡接著讀（cursor）。`failed` 時 cursor 不會前進。","parameters":[{"name":"id","in":"path","required":true,"description":"知識來源 id","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WikiSyncReportInput"},"example":{"status":"ok","summary":"新增 2 條、修改 1 條","counts":{"read":12,"created":2,"revised":1,"unchanged":8,"skipped":1},"cursor":"2026-10-07T10:00:00Z"}}}},"responses":{"200":{"description":"這次同步的紀錄。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Agent400"},"401":{"$ref":"#/components/responses/Agent401"},"403":{"$ref":"#/components/responses/Agent403"},"404":{"$ref":"#/components/responses/Agent404"},"409":{"$ref":"#/components/responses/Agent409"},"413":{"$ref":"#/components/responses/Agent413"},"422":{"$ref":"#/components/responses/Agent422"},"429":{"$ref":"#/components/responses/Agent429"},"500":{"$ref":"#/components/responses/Agent500"}},"security":[{"agentKey":[]}],"x-scope":"wiki:write","x-mcp-tool":"report_wiki_sync","x-idempotent":true}},"/api/user/v1/me":{"get":{"tags":["user-me"],"operationId":"user_whoami","summary":"我是誰","description":"金鑰主人、組織、角色與可見的專案。個人金鑰在組織層級運作，不綁工作區。\n\n可用角色：客戶、Agency、平台管理員。","responses":{"200":{"description":"身分與組織。","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/User401"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["client","agency","admin"],"x-mcp-tool":"whoami"}},"/api/user/v1/review":{"get":{"tags":["user-review"],"operationId":"user_review_queue","summary":"審稿佇列","description":"等審的貼文。客戶只有「待客戶審」（`client_review`）；Agency 與管理員看全部階段。每篇的 `images`（圖片與影片，`kind` 區分）帶 15 分鐘有效的簽名連結；影片連結支援 Range。\n\n可用角色：客戶、Agency、平台管理員。","parameters":[{"name":"stage","in":"query","required":false,"description":"只看某個階段（客戶只有 client_review）","schema":{"type":"string","enum":["draft","internal_review","client_review","approved","scheduled"]}},{"name":"limit","in":"query","required":false,"description":"","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"`posts` 陣列；每篇的 `images[]` 有 `id`、`caption`、`kind`、`mime_type`、`duration_ms`、`thumb_url`、`url`。","content":{"application/json":{"schema":{"type":"object"},"example":{"posts":[{"id":"e6baef30-…","images":[{"id":"…","caption":null,"thumb_url":"https://api.tennnzo.com/api/user/v1/media/…?k=…&size=thumb&exp=…&sig=…","url":"https://…"}]}]}}}},"400":{"$ref":"#/components/responses/User400"},"401":{"$ref":"#/components/responses/User401"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["client","agency","admin"],"x-mcp-tool":"review_queue"}},"/api/user/v1/posts/published":{"get":{"tags":["user-published"],"operationId":"user_published_posts","summary":"已發布的貼文","description":"已發布的貼文，新的在前；用 `before` 分頁。\n\n可用角色：客戶、Agency、平台管理員。","parameters":[{"name":"limit","in":"query","required":false,"description":"","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"before","in":"query","required":false,"description":"分頁：這個時間之前發布的","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})$"}},{"name":"persona_id","in":"query","required":false,"description":"","schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"}}],"responses":{"200":{"description":"`posts` 陣列。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/User400"},"401":{"$ref":"#/components/responses/User401"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["client","agency","admin"],"x-mcp-tool":"published_posts"}},"/api/user/v1/posts/{id}":{"get":{"tags":["user-review"],"operationId":"user_get_post","summary":"看一篇","description":"單篇貼文與相關脈絡（含簽名圖片連結）。看不到的貼文一律 404。\n\n可用角色：客戶、Agency、平台管理員。","parameters":[{"name":"id","in":"path","required":true,"description":"貼文 id（審稿佇列給的）","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"貼文內容；`images[]` 同審稿佇列。","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/User401"},"404":{"$ref":"#/components/responses/User404"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["client","agency","admin"],"x-mcp-tool":"get_post"}},"/api/user/v1/posts/{id}/transition":{"post":{"tags":["user-review"],"operationId":"user_review_post","summary":"審稿／排程","description":"規則和 dashboard 的按鈕一樣。客戶：`approve`、`request_changes`、`reject`、`request_rewrite`（後三者要 `comment`），只能在「待客戶審」、專案開著客戶審稿、你有審稿權時。Agency／管理員另有 `submit`、`cancel_rewrite`、`schedule`／`reschedule`（要未來的 `scheduled_for`）、`unschedule`。\n\n可用角色：客戶、Agency、平台管理員（客戶要有審稿權）。","parameters":[{"name":"id","in":"path","required":true,"description":"貼文 id","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"description":"客戶只能用 approve、request_changes、reject、request_rewrite（不收 scheduled_for）。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffPostMove"},"example":{"action":"request_changes","comment":"開頭太像上一篇，換個角度"}}}},"responses":{"200":{"description":"移動後的狀態。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/User400"},"401":{"$ref":"#/components/responses/User401"},"403":{"$ref":"#/components/responses/User403"},"404":{"$ref":"#/components/responses/User404"},"413":{"$ref":"#/components/responses/User413"},"422":{"$ref":"#/components/responses/User422"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["client","agency","admin"],"x-mcp-tool":"review_post"}},"/api/user/v1/reports":{"get":{"tags":["user-published"],"operationId":"user_list_reports","summary":"報告清單","description":"客戶只看得到已發給客戶的報告。\n\n可用角色：客戶、Agency、平台管理員。","parameters":[{"name":"limit","in":"query","required":false,"description":"","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"`reports` 陣列。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/User400"},"401":{"$ref":"#/components/responses/User401"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["client","agency","admin"],"x-mcp-tool":"list_reports"}},"/api/user/v1/reports/{id}":{"get":{"tags":["user-published"],"operationId":"user_get_report","summary":"讀一份報告","description":"報告內容。\n\n可用角色：客戶、Agency、平台管理員。","parameters":[{"name":"id","in":"path","required":true,"description":"報告 id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"報告。","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/User401"},"404":{"$ref":"#/components/responses/User404"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["client","agency","admin"],"x-mcp-tool":"get_report"}},"/api/user/v1/decisions":{"get":{"tags":["user-decisions"],"operationId":"user_list_decisions","summary":"待裁決","description":"預設列未裁決的。\n\n可用角色：Agency、平台管理員。","parameters":[{"name":"status","in":"query","required":false,"description":"預設 open（未裁決）","schema":{"type":"string","enum":["open","resolved","dismissed","decided"]}},{"name":"limit","in":"query","required":false,"description":"","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"`items` 陣列。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/User400"},"401":{"$ref":"#/components/responses/User401"},"403":{"$ref":"#/components/responses/User403"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["agency","admin"],"x-mcp-tool":"list_decisions"}},"/api/user/v1/decisions/{id}/resolve":{"post":{"tags":["user-decisions"],"operationId":"user_decide_issue_resolve","summary":"裁決：已處理","description":"把待裁決標成已處理，可附備註。\n\n可用角色：Agency、平台管理員。","parameters":[{"name":"id","in":"path","required":true,"description":"待裁決的 id","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideNote"},"example":{"note":"已和客戶確認"}}}},"responses":{"200":{"description":"裁決後的狀態。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/User400"},"401":{"$ref":"#/components/responses/User401"},"403":{"$ref":"#/components/responses/User403"},"404":{"$ref":"#/components/responses/User404"},"413":{"$ref":"#/components/responses/User413"},"422":{"$ref":"#/components/responses/User422"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["agency","admin"],"x-mcp-tool":"decide_issue"}},"/api/user/v1/decisions/{id}/dismiss":{"post":{"tags":["user-decisions"],"operationId":"user_decide_issue_dismiss","summary":"裁決：不處理","description":"標成不處理，`note` 必填（原因）。\n\n可用角色：Agency、平台管理員。","parameters":[{"name":"id","in":"path","required":true,"description":"待裁決的 id","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideNote"},"example":{"note":"這張不需要換"}}}},"responses":{"200":{"description":"裁決後的狀態。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/User400"},"401":{"$ref":"#/components/responses/User401"},"403":{"$ref":"#/components/responses/User403"},"404":{"$ref":"#/components/responses/User404"},"413":{"$ref":"#/components/responses/User413"},"422":{"$ref":"#/components/responses/User422"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["agency","admin"],"x-mcp-tool":"decide_issue"}},"/api/user/v1/decisions/{id}/choose":{"post":{"tags":["user-decisions"],"operationId":"user_choose_issue","summary":"回答選項題","description":"選選項 `keys`，或都不是時寫 `other`（兩者不能一起給）。\n\n可用角色：Agency、平台管理員。","parameters":[{"name":"id","in":"path","required":true,"description":"待裁決的 id","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChooseInput"},"example":{"keys":["tabby"]}}}},"responses":{"200":{"description":"裁決後的狀態。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/User400"},"401":{"$ref":"#/components/responses/User401"},"403":{"$ref":"#/components/responses/User403"},"404":{"$ref":"#/components/responses/User404"},"413":{"$ref":"#/components/responses/User413"},"422":{"$ref":"#/components/responses/User422"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["agency","admin"],"x-mcp-tool":"choose_issue"}},"/api/user/v1/tasks":{"get":{"tags":["user-tasks"],"operationId":"user_list_tasks","summary":"Agent 看板","description":"看板卡；預設進行中的三種（待領取、進行中、待確認）。\n\n可用角色：Agency、平台管理員。","parameters":[{"name":"status","in":"query","required":false,"description":"逗號分隔的狀態：open、in_progress、awaiting_confirmation、done、failed、cancelled","schema":{"type":"string","example":"open,in_progress"}},{"name":"limit","in":"query","required":false,"description":"最多幾張（1–200）","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"`tasks` 陣列。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/User400"},"401":{"$ref":"#/components/responses/User401"},"403":{"$ref":"#/components/responses/User403"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["agency","admin"],"x-mcp-tool":"list_tasks"},"post":{"tags":["user-tasks"],"operationId":"user_open_task","summary":"交辦新任務","description":"開一張卡給 Agent（不指定 `agent_id`＝誰先領誰做）。`target_type` 與 `target_id` 要一起給。\n\n可用角色：Agency、平台管理員。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenTaskInput"},"example":{"kind":"change_bio","title":"TW-T014 改 bio","detail":"改成「下班後的咖啡地圖」"}}}},"responses":{"200":{"description":"已存在（重送或同名），沒有新建","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"新卡回 201，已有同一張回 200。","content":{"application/json":{"schema":{"type":"object"},"example":{"task":{"id":"…"},"created":true}}}},"400":{"$ref":"#/components/responses/User400"},"401":{"$ref":"#/components/responses/User401"},"403":{"$ref":"#/components/responses/User403"},"413":{"$ref":"#/components/responses/User413"},"422":{"$ref":"#/components/responses/User422"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["agency","admin"],"x-mcp-tool":"open_task"}},"/api/user/v1/tasks/{id}/confirm":{"post":{"tags":["user-tasks"],"operationId":"user_confirm_task","summary":"確認完成","description":"確認 Agent 交回來的卡。\n\n可用角色：Agency、平台管理員。","parameters":[{"name":"id","in":"path","required":true,"description":"卡的 id","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskNoteInput"},"example":{}}}},"responses":{"200":{"description":"更新後的卡。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/User400"},"401":{"$ref":"#/components/responses/User401"},"403":{"$ref":"#/components/responses/User403"},"404":{"$ref":"#/components/responses/User404"},"413":{"$ref":"#/components/responses/User413"},"422":{"$ref":"#/components/responses/User422"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["agency","admin"],"x-mcp-tool":"confirm_task"}},"/api/user/v1/tasks/{id}/reopen":{"post":{"tags":["user-tasks"],"operationId":"user_reopen_task","summary":"退回重做","description":"退回 Agent 重做，`note` 必填（哪裡不對）。\n\n可用角色：Agency、平台管理員。","parameters":[{"name":"id","in":"path","required":true,"description":"卡的 id","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskNoteInput"},"example":{"note":"顏色不對，要偏暖"}}}},"responses":{"200":{"description":"更新後的卡。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/User400"},"401":{"$ref":"#/components/responses/User401"},"403":{"$ref":"#/components/responses/User403"},"404":{"$ref":"#/components/responses/User404"},"413":{"$ref":"#/components/responses/User413"},"422":{"$ref":"#/components/responses/User422"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["agency","admin"],"x-mcp-tool":"reopen_task"}},"/api/user/v1/today":{"get":{"tags":["user-today"],"operationId":"user_today","summary":"今日摘要","description":"今天需要處理的事與排程概況。\n\n可用角色：Agency、平台管理員。","responses":{"200":{"description":"今日摘要。","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/User401"},"403":{"$ref":"#/components/responses/User403"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["agency","admin"],"x-mcp-tool":"today"}},"/api/user/v1/metrics":{"get":{"tags":["user-today"],"operationId":"user_metrics","summary":"成效","description":"各帳號的成效數字，可依平台篩選。\n\n可用角色：Agency、平台管理員。","parameters":[{"name":"platform","in":"query","required":false,"description":"","schema":{"type":"string","enum":["threads","tiktok","x","facebook","instagram","reddit"]}},{"name":"limit","in":"query","required":false,"description":"","schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"成效。","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/User400"},"401":{"$ref":"#/components/responses/User401"},"403":{"$ref":"#/components/responses/User403"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["agency","admin"],"x-mcp-tool":"metrics"}},"/api/user/v1/admin/keys":{"get":{"tags":["user-keys"],"operationId":"user_list_keys","summary":"金鑰清單","description":"這個組織所有成員與 Agent 的金鑰（只有前綴與使用時間，看不到金鑰本身）。\n\n可用角色：平台管理員。","responses":{"200":{"description":"金鑰清單。","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/User401"},"403":{"$ref":"#/components/responses/User403"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["admin"],"x-mcp-tool":"list_keys"}},"/api/user/v1/admin/keys/{kind}/{id}/revoke":{"post":{"tags":["user-keys"],"operationId":"user_revoke_key","summary":"撤銷金鑰","description":"撤銷任何成員或 Agent 的金鑰。立即生效、不能恢復。\n\n可用角色：平台管理員。","parameters":[{"name":"kind","in":"path","required":true,"description":"`user` 成員的個人金鑰／`agent` Agent 金鑰","schema":{"type":"string","enum":["user","agent"]}},{"name":"id","in":"path","required":true,"description":"金鑰 id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"撤銷結果。","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/User401"},"403":{"$ref":"#/components/responses/User403"},"404":{"$ref":"#/components/responses/User404"},"422":{"$ref":"#/components/responses/User422"},"429":{"$ref":"#/components/responses/User429"},"500":{"$ref":"#/components/responses/User500"}},"security":[{"userKey":[]}],"x-roles":["admin"],"x-mcp-tool":"revoke_key"}},"/api/user/v1/media/{id}":{"get":{"tags":["user-media"],"operationId":"user_get_media","summary":"圖片（簽名連結）","description":"審稿佇列與單篇回傳的 `thumb_url`／`url`。不用帶金鑰，15 分鐘內有效；金鑰撤銷後也立刻失效。照原樣使用，不要自己組。","parameters":[{"name":"id","in":"path","required":true,"description":"圖片 id","schema":{"type":"string","format":"uuid"}},{"name":"k","in":"query","required":true,"description":"金鑰 id","schema":{"type":"string"}},{"name":"size","in":"query","required":false,"description":"`thumb` 縮圖／`full` 原圖","schema":{"type":"string","enum":["thumb","full"]}},{"name":"exp","in":"query","required":true,"description":"到期時間（Unix 秒）","schema":{"type":"integer"}},{"name":"sig","in":"query","required":true,"description":"簽名","schema":{"type":"string"}}],"responses":{"200":{"description":"圖檔本身（image/*）。","content":{"image/*":{"schema":{"type":"string","contentMediaType":"image/*"}}}},"400":{"$ref":"#/components/responses/User400"},"404":{"$ref":"#/components/responses/User404"},"500":{"$ref":"#/components/responses/User500"}},"security":[]}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","description":"錯誤碼（見各 API 的錯誤表）"},"message":{"type":"string","description":"原因，給呼叫的人或 Agent 讀"},"request_id":{"type":"string","description":"請求 id（也在 X-Request-Id 標頭）"}}}},"example":{"error":{"code":"rejected","message":"the draft is waiting for a rewrite","request_id":"req_Xk2…"}}},"AccountAddInput":{"type":"object","properties":{"persona_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"人設 id（create_persona 回傳的 id）"},"platform":{"type":"string","enum":["threads","tiktok","x","facebook","instagram","reddit"],"description":"平台"},"code":{"type":"string","minLength":1,"maxLength":40,"description":"帳號編號：市場-平台字母+三位數，例如 TW-I001（IG）、TW-T001（Threads）"},"market":{"description":"市場代碼（預設 TW）","type":"string","minLength":2,"maxLength":2},"handle":{"description":"平台上的帳號名稱（@ 可省）","type":"string","maxLength":100},"state":{"description":"warming 養號（預設）／active 已在輪值","type":"string","enum":["warming","active"]},"onboarded_at":{"description":"開始經營的日期 YYYY-MM-DD","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["persona_id","platform","code"]},"AccountStateInput":{"type":"object","properties":{"state":{"type":"string","enum":["banned","quarantined","paused","restored","warming"],"description":"banned 被封／quarantined 隔離／paused 暫停／restored 恢復正常／warming 養號"},"reason":{"description":"原因（被封、隔離、暫停必填；平台怎麼說的）","type":"string","maxLength":1000},"occurred_at":{"type":"string","minLength":1,"maxLength":40,"description":"平台實際發生的時間：帶時區的 ISO，或帳號市場的當地時間 \"2026-10-05 14:30\""},"origin":{"type":"object","properties":{"platform":{"type":"string","minLength":1,"maxLength":40,"description":"在哪個平台聽到的：feishu／dingtalk／telegram／discord／cli／other（寫 飛書、釘釘 也可以）"},"gateway":{"description":"哪個 gateway 收到的，例如 main@host-1","type":"string","maxLength":200},"channel":{"description":"群組／頻道名稱，例如 #審稿群（知道就一定帶）","type":"string","maxLength":200},"thread":{"description":"討論串","type":"string","maxLength":200},"requester":{"description":"誰提出的（聊天裡的名字）","type":"string","maxLength":80}},"required":["platform"],"description":"這件事從哪裡來"}},"required":["state","occurred_at"]},"AccountAvatarInput":{"type":"object","properties":{"data":{"type":"string","minLength":1,"description":"平台上的頭像圖檔 base64（可含 data: 前綴），JPEG／PNG／WebP，5 MB 以內"}},"required":["data"]},"HeartbeatInput":{"type":"object","properties":{"run_id":{"description":"這一輪工作的 id；同一輪重送會更新同一筆","type":"string","minLength":1,"maxLength":120},"summary":{"description":"這一輪做了什麼（一兩句）","type":"string","maxLength":2000},"counts":{"description":"計數，例如 {\"drafts\": 3, \"rewrites\": 1}","type":"object","propertyNames":{"type":"string","maxLength":40},"additionalProperties":{"type":"integer","minimum":0,"maximum":1000000}}}},"PersonaCreateInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"人設名字（顯示名稱）"},"project":{"description":"專案名稱；租戶只有一個專案時可省略","type":"string","maxLength":200},"track":{"description":"賽道","type":"string","maxLength":200},"background":{"description":"背景（城市、職業、生活）","type":"string","maxLength":2000},"bio":{"description":"帳號 bio","type":"string","maxLength":2000},"voice":{"description":"說話語氣與寫作風格","type":"string","maxLength":4000}},"required":["name"]},"PersonaImageInput":{"type":"object","properties":{"data":{"type":"string","minLength":1,"description":"圖檔 base64（可含 data: 前綴），JPEG／PNG／WebP，5 MB 以內"},"category":{"description":"圖的類別（預設 other）","type":"string","enum":["turnaround","portrait","avatar","pet","home","workplace","belongings","photo_style","other"]},"caption":{"description":"圖說","type":"string","maxLength":500},"prompt":{"description":"生圖提示詞（內部用）","type":"string","maxLength":8000},"character":{"description":"這張是某個角色的參考圖時，帶角色代號（登場名單裡的，例如 AS-01）","type":"string","minLength":1,"maxLength":24}},"required":["data"]},"ProposalInput":{"type":"object","properties":{"kind":{"type":"string","enum":["fact","contradiction"],"description":"fact＝新事實（進草稿）／contradiction＝矛盾（進待裁決）"},"category":{"description":"fact 必填：identity／pet／home／work／speech／photo／belonging／brand_*／habit／event／voice_audio／other","type":"string","enum":["identity","pet","home","work","speech","photo","belonging","brand_liked","brand_endorsing","brand_collaborated","habit","event","voice_audio","other"]},"label":{"type":"string","minLength":1,"maxLength":200,"description":"fact：項目（例如「貓的名字」）；contradiction：一句話標題"},"value":{"type":"string","minLength":1,"maxLength":2000,"description":"fact：內容；contradiction：哪裡和哪裡矛盾"},"detail":{"description":"根據（哪一篇、哪張圖）","type":"string","maxLength":2000},"post_id":{"description":"根據的貼文 id","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["kind","label","value"]},"DraftInput":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":40,"description":"帳號編號，例如 TW-T014（舊編號 V014 也可以）"},"platform":{"description":"編號重複時才需要（舊 V 編號 Threads 與 TikTok 會撞）","type":"string","enum":["threads","tiktok","x","facebook","instagram","reddit"]},"body":{"type":"string","minLength":1,"maxLength":10000,"description":"貼文內文"},"topic":{"description":"主題（給審稿的人看）","type":"string","maxLength":200},"sponsored":{"description":"業配稿設 true","type":"boolean"},"planned_at":{"description":"計畫發布時間：帶時區的 ISO（\"2026-10-05T20:00:00+08:00\"）或帳號市場當地時間（\"2026-10-05 20:00\"、\"2026-10-05 20:00:00\"）","type":"string","maxLength":40},"images":{"description":"小圖才用：最多 4 張、合計 3 MB。有圖的稿請改用 upload_ids（create_upload 先傳檔）","maxItems":4,"type":"array","items":{"type":"object","properties":{"data":{"type":"string","minLength":1,"description":"圖檔 base64（可含 data: 前綴），JPEG／PNG／WebP"},"caption":{"type":"string","maxLength":200}},"required":["data"]}},"upload_ids":{"description":"create_upload 傳好的圖或影片（依發布順序）。Instagram 一篇最多 10 個，其他平台 4 個（圖和影片合計）","minItems":1,"maxItems":10,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"media_ids":{"description":"從素材庫重用的素材 id（list_media 查），接在 upload_ids 後面、依此順序。先查素材庫（例如 tag 固定收尾），沒有的才上傳","minItems":1,"maxItems":10,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"characters":{"description":"這篇的登場角色（依主次排序，主角放第一個），只能用人設登場名單裡的角色。給了就整組取代；空陣列＝清掉","maxItems":6,"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":24,"description":"角色代號，例如 AS-01（get_persona 的 cast）"},"pov":{"description":"內文是用這個角色的視角寫的（不是帳號本身的口氣）時設 true；一篇最多一個","type":"boolean"}},"required":["code"]}},"note":{"description":"給審稿的人看的備註（例如還缺什麼、為什麼這樣寫），會進審稿紀錄「新增備註」。主題欄只寫短主題","type":"string","minLength":1,"maxLength":1000},"submit":{"description":"預設 true＝直接送內部審稿；false＝只存草稿","type":"boolean"}},"required":["code","body"]},"DraftUpdate":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":10000,"description":"改好的完整內文"},"topic":{"type":"string","maxLength":200},"upload_ids":{"description":"create_upload 傳好的圖或影片（依發布順序）。Instagram 一篇最多 10 個，其他平台 4 個（圖和影片合計）","minItems":1,"maxItems":10,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"media_ids":{"description":"從素材庫重用的素材 id（list_media 查），接在 upload_ids 後面、依此順序。先查素材庫（例如 tag 固定收尾），沒有的才上傳","minItems":1,"maxItems":10,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"characters":{"description":"這篇的登場角色（依主次排序，主角放第一個），只能用人設登場名單裡的角色。給了就整組取代；空陣列＝清掉","maxItems":6,"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":24,"description":"角色代號，例如 AS-01（get_persona 的 cast）"},"pov":{"description":"內文是用這個角色的視角寫的（不是帳號本身的口氣）時設 true；一篇最多一個","type":"boolean"}},"required":["code"]}},"note":{"description":"給審稿的人看的備註（例如還缺什麼、為什麼這樣寫），會進審稿紀錄「新增備註」。主題欄只寫短主題","type":"string","minLength":1,"maxLength":1000},"submit":{"description":"預設 true＝改完直接送內部審稿","type":"boolean"}},"required":["body"]},"ImagesAttach":{"type":"object","properties":{"upload_ids":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"create_upload 傳好的圖（依發布順序）"},"note":{"description":"給審稿的人看的備註（例如還缺什麼、為什麼這樣寫），會進審稿紀錄「新增備註」。主題欄只寫短主題","type":"string","minLength":1,"maxLength":1000}},"required":["upload_ids"]},"NoteInput":{"type":"object","properties":{"note":{"type":"string","minLength":1,"maxLength":1000,"description":"給審稿的人看的備註，會進審稿紀錄「新增備註」"}},"required":["note"]},"UploadCreate":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":40,"description":"帳號編號，例如 TW-T014（舊編號 V014 也可以）"},"platform":{"description":"編號重複時才需要（舊 V 編號 Threads 與 TikTok 會撞）","type":"string","enum":["threads","tiktok","x","facebook","instagram","reddit"]},"caption":{"description":"圖說（給審稿的人看，也是素材庫的說明）","type":"string","maxLength":200},"character":{"description":"圖裡的角色代號（登場名單裡的，例如 AS-01）","type":"string","minLength":1,"maxLength":24},"tags":{"description":"素材庫標籤，之後可用 list_media 依標籤找回來重用，例如 [\"固定收尾\"]","maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":30}},"project":{"description":"素材庫的專案名稱（省略＝這個帳號人設的專案）","type":"string","minLength":1,"maxLength":80},"bytes":{"description":"檔案大小（位元組）。影片或超過 4 MB 的檔案必填：超過 4 MB 會改成分塊上傳（每塊 3 MB，最大 500 MB）","type":"integer","minimum":1,"maximum":524288000},"mime_type":{"description":"檔案類型；影片必填（video/mp4、video/quicktime、video/webm）","type":"string","enum":["image/jpeg","image/png","image/webp","video/mp4","video/quicktime","video/webm"]}},"required":["code"]},"MediaAttach":{"type":"object","properties":{"media_ids":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"素材庫的素材 id（list_media 查），依發布順序接在這篇現有的圖後面"},"note":{"description":"給審稿的人看的備註（例如還缺什麼、為什麼這樣寫），會進審稿紀錄「新增備註」。主題欄只寫短主題","type":"string","minLength":1,"maxLength":1000}},"required":["media_ids"]},"PostsReportInput":{"type":"object","properties":{"posts":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":40,"description":"帳號編號，例如 TW-T014（舊編號 V014 也可以）"},"platform":{"description":"編號重複時才需要（舊 V 編號 Threads 與 TikTok 會撞）","type":"string","enum":["threads","tiktok","x","facebook","instagram","reddit"]},"status":{"type":"string","enum":["scheduled","published","failed","cancelled"],"description":"scheduled＝已在平台排好；published＝已發出；failed＝排了但沒發出去；cancelled＝取消了排程"},"scheduled_for":{"description":"排定的發布時間（status 是 scheduled 時必填）：帳號市場當地時間 \"2026-10-05 20:00\" 或 \"2026-10-05 20:00:42\"（不帶時區＝帳號市場時區），或帶時區的 ISO \"2026-10-05T20:00:00+08:00\"","type":"string","minLength":1,"maxLength":40},"published_at":{"description":"實際發出時間（published；不給就用收到回報的時間）：帳號市場當地時間 \"2026-10-05 20:00\" 或 \"2026-10-05 20:00:42\"（不帶時區＝帳號市場時區），或帶時區的 ISO \"2026-10-05T20:00:00+08:00\"","type":"string","minLength":1,"maxLength":40},"platform_post_id":{"description":"平台上的貼文 id。知道就一定要帶：之後的回報靠它對到同一篇","type":"string","minLength":1,"maxLength":200},"permalink":{"description":"貼文的永久連結 http(s)。status 是 published 時必填：沒有連結不算發布成功（還沒連結先報 scheduled，確認失敗報 failed）","type":"string","maxLength":2000},"body":{"description":"貼文內文（第一次回報這篇時必填；之後有 platform_post_id 或 post_id 可以不給）","type":"string","minLength":1,"maxLength":10000},"topic":{"description":"主題","type":"string","maxLength":200},"has_media":{"description":"有圖或影片","type":"boolean"},"sponsored":{"description":"業配","type":"boolean"},"post_id":{"description":"這篇是 dashboard 交給你的稿時，帶它的 id（list_redo／審稿通過的稿）","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"failure_reason":{"description":"failed／cancelled 的原因（一句話，不含帳密或內部連結）","type":"string","maxLength":2000}},"required":["code","status"]},"description":"這次要回報的貼文，最多 200 篇"}},"required":["posts"]},"MetricsInput":{"type":"object","properties":{"captured_at":{"type":"string","minLength":1,"maxLength":40,"description":"這批數字是什麼時候抓的（必填）：帶時區的 ISO，或當地時間 \"2026-10-05 21:00:00\"（這批帳號同一個市場時用該市場時區，否則台北）。同一個時間重送會覆蓋，不會重複"},"posts":{"description":"每篇的瀏覽／讚／回覆／轉發／分享","maxItems":1000,"type":"array","items":{"type":"object","properties":{"post_id":{"description":"dashboard 的貼文 id","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"code":{"type":"string","minLength":1,"maxLength":40,"description":"帳號編號，例如 TW-T014（舊編號 V014 也可以）"},"platform":{"description":"編號重複時才需要（舊 V 編號 Threads 與 TikTok 會撞）","type":"string","enum":["threads","tiktok","x","facebook","instagram","reddit"]},"platform_post_id":{"description":"平台貼文 id（沒有 post_id 時和 code 一起給）","type":"string","minLength":1,"maxLength":200},"views":{"type":"integer","minimum":0,"maximum":10000000000},"likes":{"type":"integer","minimum":0,"maximum":10000000000},"replies":{"type":"integer","minimum":0,"maximum":10000000000},"reposts":{"type":"integer","minimum":0,"maximum":10000000000},"shares":{"type":"integer","minimum":0,"maximum":10000000000}}}},"accounts":{"description":"帳號粉絲數（現役世代）","maxItems":500,"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":40,"description":"帳號編號，例如 TW-T014（舊編號 V014 也可以）"},"platform":{"description":"編號重複時才需要（舊 V 編號 Threads 與 TikTok 會撞）","type":"string","enum":["threads","tiktok","x","facebook","instagram","reddit"]},"followers":{"type":"integer","minimum":0,"maximum":10000000000,"description":"粉絲數"}},"required":["code","followers"]}}},"required":["captured_at"]},"OpenTaskInput":{"type":"object","properties":{"agent_id":{"description":"交給哪個 Agent；不給＝誰先領誰做","type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"kind":{"type":"string","enum":["write_posts","rewrite_post","change_avatar","change_bio","delete_post","pause_account","resume_account","export_data","other"]},"title":{"type":"string","minLength":1,"maxLength":200},"detail":{"type":"string","maxLength":4000},"target_type":{"type":"string","enum":["slot","persona","post","issue"]},"target_id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"due_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})$"}},"required":["kind","title"]},"TaskProgress":{"type":"object","properties":{"note":{"type":"string","minLength":1,"maxLength":2000,"description":"進度一兩句"}},"required":["note"]},"TaskFinish":{"type":"object","properties":{"result":{"type":"string","minLength":1,"maxLength":4000,"description":"結果：做了什麼"},"evidence":{"description":"證據：[{\"type\":\"link\",\"url\":\"https://…\",\"label\":\"…\"} 或 {\"type\":\"asset\",\"asset_id\":\"<圖片 id>\"}]，最多 20 筆","maxItems":20,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"link"},"url":{"type":"string","maxLength":2000,"format":"uri"},"label":{"type":"string","maxLength":200}},"required":["type","url"]},{"type":"object","properties":{"type":{"type":"string","const":"asset"},"asset_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"label":{"type":"string","maxLength":200}},"required":["type","asset_id"]}]}}},"required":["result"]},"TaskFail":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":4000,"description":"為什麼做不到"}},"required":["reason"]},"IssueDoneInput":{"type":"object","properties":{"result":{"type":"string","minLength":1,"maxLength":500,"description":"做了什麼，例如「頭像已換成虎斑貓」"},"evidence":{"description":"證據：[{\"type\":\"link\",\"url\":\"https://…\",\"label\":\"…\"} 或 {\"type\":\"asset\",\"asset_id\":\"<圖片 id>\"}]，最多 20 筆","maxItems":20,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"link"},"url":{"type":"string","maxLength":2000,"format":"uri"},"label":{"type":"string","maxLength":200}},"required":["type","url"]},{"type":"object","properties":{"type":{"type":"string","const":"asset"},"asset_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"label":{"type":"string","maxLength":200}},"required":["type","asset_id"]}]}}},"required":["result"]},"PostTransitionInput":{"type":"object","properties":{"action":{"type":"string","enum":["submit","approve","reject","request_changes","request_rewrite","schedule","reschedule","unschedule","mark_published","mark_cancelled"],"description":"submit 送審／approve 通過（內部或客戶階段看貼文目前在哪）／reject 退回／request_changes 要求修改／request_rewrite 要求重寫／schedule 排程／reschedule 改時間／unschedule 取消排程／mark_published 標已發出／mark_cancelled 標取消"},"comment":{"description":"對方的原話重點（退回、要求修改、要求重寫、取消時必填）","type":"string","maxLength":2000},"scheduled_for":{"description":"schedule／reschedule 的發布時間：帶時區的 ISO 或帳號市場當地時間","type":"string","minLength":1,"maxLength":40},"on_behalf_of":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"說這句話的人（照聊天裡的名字，例如 王小姐、Mika）"},"role":{"type":"string","enum":["agency","client","admin"],"description":"agency＝Agency 同事、client＝客戶、admin＝平台管理員"}},"required":["name","role"],"description":"代誰登記（必填）"},"origin":{"type":"object","properties":{"platform":{"type":"string","minLength":1,"maxLength":40,"description":"在哪個平台聽到的：feishu／dingtalk／telegram／discord／cli／other（寫 飛書、釘釘 也可以）"},"gateway":{"description":"哪個 gateway 收到的，例如 main@host-1","type":"string","maxLength":200},"channel":{"description":"群組／頻道名稱，例如 #審稿群（知道就一定帶）","type":"string","maxLength":200},"thread":{"description":"討論串","type":"string","maxLength":200},"requester":{"description":"誰提出的（聊天裡的名字）","type":"string","maxLength":80},"message_ref":{"description":"那則訊息的 id 或連結；同一則重送不會記兩次","type":"string","maxLength":200}},"required":["platform"],"description":"從哪裡聽到的（platform 必填，知道頻道就帶 channel）"},"effective_at":{"description":"這件事實際發生的時間（例如客戶 10/2 通過＝2026-10-02T15:00:00+08:00，或貼文帳號市場的當地時間 \"2026-10-02 15:00\"）；不給＝現在；不可是未來、不可超過 60 天前","type":"string","minLength":1,"maxLength":40}},"required":["action","on_behalf_of","origin"]},"IssueRelayInput":{"type":"object","properties":{"action":{"type":"string","enum":["resolve","dismiss","choose"],"description":"resolve 已處理／dismiss 不處理（note 必填）／choose 選選項"},"note":{"description":"決定內容或原因","type":"string","maxLength":2000},"chosen":{"description":"choose：選中的選項 key；空陣列＝其他（答案寫在 note）","maxItems":12,"type":"array","items":{"type":"string","minLength":1,"maxLength":40}},"on_behalf_of":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"說這句話的人（照聊天裡的名字，例如 王小姐、Mika）"},"role":{"type":"string","enum":["agency","client","admin"],"description":"agency＝Agency 同事、client＝客戶、admin＝平台管理員"}},"required":["name","role"],"description":"代誰登記（必填）"},"origin":{"type":"object","properties":{"platform":{"type":"string","minLength":1,"maxLength":40,"description":"在哪個平台聽到的：feishu／dingtalk／telegram／discord／cli／other（寫 飛書、釘釘 也可以）"},"gateway":{"description":"哪個 gateway 收到的，例如 main@host-1","type":"string","maxLength":200},"channel":{"description":"群組／頻道名稱，例如 #審稿群（知道就一定帶）","type":"string","maxLength":200},"thread":{"description":"討論串","type":"string","maxLength":200},"requester":{"description":"誰提出的（聊天裡的名字）","type":"string","maxLength":80},"message_ref":{"description":"那則訊息的 id 或連結；同一則重送不會記兩次","type":"string","maxLength":200}},"required":["platform"],"description":"從哪裡聽到的（platform 必填，知道頻道就帶 channel）"},"effective_at":{"description":"這件事實際發生的時間（例如客戶 10/2 通過＝2026-10-02T15:00:00+08:00，或貼文帳號市場的當地時間 \"2026-10-02 15:00\"）；不給＝現在；不可是未來、不可超過 60 天前","type":"string","minLength":1,"maxLength":40}},"required":["action","on_behalf_of","origin"]},"TaskRelayInput":{"type":"object","properties":{"action":{"type":"string","enum":["confirm","reopen"],"description":"confirm 確認完成／reopen 退回重做（note 必填）"},"note":{"type":"string","maxLength":2000},"on_behalf_of":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"說這句話的人（照聊天裡的名字，例如 王小姐、Mika）"},"role":{"type":"string","enum":["agency","client","admin"],"description":"agency＝Agency 同事、client＝客戶、admin＝平台管理員"}},"required":["name","role"],"description":"代誰登記（必填）"},"origin":{"type":"object","properties":{"platform":{"type":"string","minLength":1,"maxLength":40,"description":"在哪個平台聽到的：feishu／dingtalk／telegram／discord／cli／other（寫 飛書、釘釘 也可以）"},"gateway":{"description":"哪個 gateway 收到的，例如 main@host-1","type":"string","maxLength":200},"channel":{"description":"群組／頻道名稱，例如 #審稿群（知道就一定帶）","type":"string","maxLength":200},"thread":{"description":"討論串","type":"string","maxLength":200},"requester":{"description":"誰提出的（聊天裡的名字）","type":"string","maxLength":80},"message_ref":{"description":"那則訊息的 id 或連結；同一則重送不會記兩次","type":"string","maxLength":200}},"required":["platform"],"description":"從哪裡聽到的（platform 必填，知道頻道就帶 channel）"},"effective_at":{"description":"這件事實際發生的時間（例如客戶 10/2 通過＝2026-10-02T15:00:00+08:00，或貼文帳號市場的當地時間 \"2026-10-02 15:00\"）；不給＝現在；不可是未來、不可超過 60 天前","type":"string","minLength":1,"maxLength":40}},"required":["action","on_behalf_of","origin"]},"CronJobsInput":{"type":"object","properties":{"jobs":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"job_id":{"type":"string","minLength":1,"maxLength":200,"description":"gateway 裡這個排程的 id（同一個 id 重送會更新同一筆）"},"name":{"type":"string","minLength":1,"maxLength":200,"description":"排程名稱，例如「每日日報」"},"schedule":{"description":"cron 表示式（\"0 9 * * 1-5\"）、@daily 或 \"every 30m\"","type":"string","maxLength":200},"timezone":{"description":"排程的時區，預設 Asia/Taipei","type":"string","minLength":1,"maxLength":64},"gateway":{"description":"哪個 gateway 在跑，例如 main@host-1","type":"string","maxLength":80},"enabled":{"description":"停用的排程送 false（預設 true）","type":"boolean"},"description":{"description":"這個排程在做什麼（一兩句，不含帳密或內部連結）","type":"string","maxLength":2000}},"required":["job_id","name"]},"description":"目前所有排程；沒送到的不會被刪"}},"required":["jobs"]},"CronRunsInput":{"type":"object","properties":{"runs":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"job_id":{"type":"string","minLength":1,"maxLength":200,"description":"report_cron_jobs 用過的排程 id"},"run_id":{"description":"這次執行的 id；不給就用 job_id＋開始時間。同一次執行重送不會變兩筆","type":"string","minLength":1,"maxLength":200},"started_at":{"type":"string","minLength":1,"maxLength":40,"description":"開始時間：帶時區的 ISO（\"2026-10-03T09:00:00+08:00\"），或排程時區的當地時間 \"2026-10-03 09:00:05\""},"finished_at":{"description":"結束時間（執行中就不給），格式同 started_at","type":"string","maxLength":40},"status":{"type":"string","enum":["success","failed","skipped","running","unknown"],"description":"success／failed／skipped／running／unknown"},"summary":{"description":"一兩句：做了什麼、為什麼失敗","type":"string","maxLength":2000},"log":{"description":"修剪過的執行紀錄（保留最後與錯誤的部分，存檔上限 2 萬字）。不可含帳密、token、驗證碼","type":"string","maxLength":100000}},"required":["job_id","started_at","status"]}}},"required":["runs"]},"WikiProposeInput":{"type":"object","properties":{"category":{"type":"string","enum":["worldview","character","voice","format","audience","strategy","playbook","lesson","glossary","other"],"description":"worldview 世界觀／character 角色／voice 口氣／format 格式／audience 受眾／strategy 策略／playbook 做法／lesson 教訓／glossary 名詞／other"},"title":{"type":"string","minLength":1,"maxLength":80,"description":"一個主題一個標題（同標題＝同一條）"},"summary":{"type":"string","minLength":1,"maxLength":200,"description":"一句話：什麼時候需要看這條"},"body":{"type":"string","minLength":1,"maxLength":6000,"description":"煉過的內容（markdown、條列、短）：寫作時要照做的東西，不是原文"},"project":{"description":"專案名稱；省略＝整個租戶（各專案的條目都會列出，也包含不分專案的）","type":"string","maxLength":200},"tags":{"description":"標籤","maxItems":12,"type":"array","items":{"type":"string","minLength":1,"maxLength":30}},"sources":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["vault","notion","post","review","agent","person","other"]},"ref":{"type":"string","minLength":1,"maxLength":500,"description":"路徑、頁面 id、貼文 id 或連結"},"title":{"type":"string","maxLength":200},"note":{"type":"string","maxLength":500}},"required":["kind","ref"]},"description":"從哪裡煉出來的（至少一個）"},"revises":{"description":"要修改的定案條目 id；同標題的定案條目會自動當成修改","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"note":{"description":"改了什麼、為什麼（留在條目紀錄裡）","type":"string","maxLength":1000}},"required":["category","title","summary","body","sources"]},"WikiSyncReportInput":{"type":"object","properties":{"status":{"type":"string","enum":["ok","partial","failed"],"description":"ok 全部完成／partial 做了一部分／failed 沒做成（cursor 不會前進）"},"summary":{"description":"一兩句：新增幾條、改了哪些、略過什麼（不寫帳密、內部網址）","type":"string","maxLength":1000},"cursor":{"description":"下次從哪裡接著讀，例如最後讀到的修改時間 ISO","type":"string","maxLength":500},"counts":{"description":"讀了幾份、新增、修改、沒變、略過各幾條","type":"object","properties":{"read":{"type":"integer","minimum":0,"maximum":9007199254740991},"created":{"type":"integer","minimum":0,"maximum":9007199254740991},"revised":{"type":"integer","minimum":0,"maximum":9007199254740991},"unchanged":{"type":"integer","minimum":0,"maximum":9007199254740991},"skipped":{"type":"integer","minimum":0,"maximum":9007199254740991}}},"started_at":{"description":"開始時間：帶時區的 ISO，或台北當地時間","type":"string","minLength":1,"maxLength":40}},"required":["status"]},"StaffPostMove":{"type":"object","properties":{"action":{"type":"string","enum":["submit","approve","request_changes","reject","request_rewrite","cancel_rewrite","schedule","reschedule","unschedule"]},"comment":{"description":"意見（退回、要求修改、要求重寫時必填）","type":"string","maxLength":2000},"scheduled_for":{"description":"schedule／reschedule 用：發出時間（ISO，帶時區）","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})$"}},"required":["action"]},"DecideNote":{"type":"object","properties":{"note":{"description":"備註；不處理時必填原因","type":"string","maxLength":500}}},"ChooseInput":{"type":"object","properties":{"keys":{"description":"選中的選項 key","maxItems":12,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"other":{"description":"都不是：寫下答案（不能和 keys 一起給）","type":"string","maxLength":500}}},"TaskNoteInput":{"type":"object","properties":{"note":{"type":"string","maxLength":2000}}}},"responses":{"Agent400":{"description":"`invalid_request`：參數格式不對（message 會指出哪個欄位）","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"參數格式不對（message 會指出哪個欄位）","request_id":"req_Xk2…"}}}}},"Agent401":{"description":"`unauthorized`：沒帶金鑰、格式錯、不存在或已撤銷","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"沒帶金鑰、格式錯、不存在或已撤銷","request_id":"req_Xk2…"}}}}},"Agent403":{"description":"`forbidden`：金鑰的角色沒有這個範圍，或不是你負責的帳號／稿","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"金鑰的角色沒有這個範圍，或不是你負責的帳號／稿","request_id":"req_Xk2…"}}}}},"Agent404":{"description":"`not_found`：找不到（包含不屬於你的）","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"找不到（包含不屬於你的）","request_id":"req_Xk2…"}}}}},"Agent409":{"description":"`ambiguous_code`：舊編號在多個平台重複，請加 platform；`idempotency_in_progress`：同一個 Idempotency-Key 的第一個請求還在處理","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ambiguous_code","message":"舊編號在多個平台重複，請加 platform","request_id":"req_Xk2…"}}}}},"Agent413":{"description":"`payload_too_large`：內容或圖片太大","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payload_too_large","message":"內容或圖片太大","request_id":"req_Xk2…"}}}}},"Agent422":{"description":"`rejected`：規則不允許（message 是原因）；`idempotency_mismatch`：同一個 Idempotency-Key 用在不同內容","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rejected","message":"規則不允許（message 是原因）","request_id":"req_Xk2…"}}}}},"Agent429":{"description":"`rate_limited`：超過每把金鑰每分鐘的上限，看 Retry-After","headers":{"X-Request-Id":{"schema":{"type":"string"}},"Retry-After":{"description":"幾秒後再試","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"超過每把金鑰每分鐘的上限，看 Retry-After","request_id":"req_Xk2…"}}}}},"Agent500":{"description":"`internal`：伺服器錯誤，可用同一個 Idempotency-Key 重試","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal","message":"伺服器錯誤，可用同一個 Idempotency-Key 重試","request_id":"req_Xk2…"}}}}},"User400":{"description":"`invalid_request`：參數格式不對（message 會指出哪個欄位）","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"參數格式不對（message 會指出哪個欄位）","request_id":"req_Xk2…"}}}}},"User401":{"description":"`unauthorized`：沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員","request_id":"req_Xk2…"}}}}},"User403":{"description":"`forbidden`：你的角色不能做這件事","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"你的角色不能做這件事","request_id":"req_Xk2…"}}}}},"User404":{"description":"`not_found`：找不到，或你看不到（不會說是哪一種）","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"找不到，或你看不到（不會說是哪一種）","request_id":"req_Xk2…"}}}}},"User413":{"description":"`payload_too_large`：請求內容太大","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payload_too_large","message":"請求內容太大","request_id":"req_Xk2…"}}}}},"User422":{"description":"`rejected`：規則不允許（message 是原因）","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rejected","message":"規則不允許（message 是原因）","request_id":"req_Xk2…"}}}}},"User429":{"description":"`rate_limited`：太快了，看 Retry-After 秒數再試","headers":{"X-Request-Id":{"schema":{"type":"string"}},"Retry-After":{"description":"幾秒後再試","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"太快了，看 Retry-After 秒數再試","request_id":"req_Xk2…"}}}}},"User500":{"description":"`internal`：伺服器錯誤","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal","message":"伺服器錯誤","request_id":"req_Xk2…"}}}}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"1–200 個可見 ASCII 字元。同一個 Agent 24 小時內：同內容重送回第一次的結果（標頭 Idempotent-Replayed: true），不同內容 422 idempotency_mismatch，第一次還在處理 409。只有成功（2xx）才佔用這個鍵。建議值：<run_id>-<編號>-<序號>。","schema":{"type":"string","minLength":1,"maxLength":200}}},"securitySchemes":{"agentKey":{"type":"http","scheme":"bearer","description":"Agent 金鑰：Authorization: Bearer tnz_<8 碼>_<43 碼>"},"userKey":{"type":"http","scheme":"bearer","description":"個人金鑰：Authorization: Bearer tnu_<8 碼>_<43 碼>"}}}}