tennnzoAgent 與 API

API 參考

個人 API 參考

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

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

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

使用方法：個人 API 使用方法、MCP 連線。

身分

金鑰是誰、在哪個組織、什麼角色。

get/api/user/v1/me

我是誰#

角色 客戶、Agency、平台管理員MCP whoami

金鑰主人、組織、角色與可見的專案。個人金鑰在組織層級運作，不綁工作區。

可用角色：客戶、Agency、平台管理員。

回應

200身分與組織。

  • 401unauthorized：沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員
  • 429rate_limited：太快了，看 Retry-After 秒數再試
  • 500internal：伺服器錯誤

審稿

審稿佇列、單篇、審稿動作。

get/api/user/v1/review

審稿佇列#

角色 客戶、Agency、平台管理員MCP review_queue

等審的貼文。客戶只有「待客戶審」（client_review）；Agency 與管理員看全部階段。每篇的 images（圖片與影片，kind 區分）帶 15 分鐘有效的簽名連結；影片連結支援 Range。

可用角色：客戶、Agency、平台管理員。

參數

欄位型別說明
stagestring · 查詢只看某個階段（客戶只有 client_review）可用值：draft、internal_review、client_review、approved、scheduled
limitinteger · 查詢1–100

回應

200posts 陣列；每篇的 images[] 有 id、caption、kind、mime_type、duration_ms、thumb_url、url。

json 範例
{
  "posts": [
    {
      "id": "e6baef30-…",
      "images": [
        {
          "id": "…",
          "caption": null,
          "thumb_url": "https://api.tennnzo.com/api/user/v1/media/…?k=…&size=thumb&exp=…&sig=…",
          "url": "https://…"
        }
      ]
    }
  ]
}
  • 400invalid_request：參數格式不對（message 會指出哪個欄位）
  • 401unauthorized：沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員
  • 429rate_limited：太快了，看 Retry-After 秒數再試
  • 500internal：伺服器錯誤
get/api/user/v1/posts/{id}

看一篇#

角色 客戶、Agency、平台管理員MCP get_post

單篇貼文與相關脈絡（含簽名圖片連結）。看不到的貼文一律 404。

可用角色：客戶、Agency、平台管理員。

參數

欄位型別說明
id必填string (uuid) · 路徑貼文 id（審稿佇列給的）

回應

200貼文內容；images[] 同審稿佇列。

  • 401unauthorized：沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員
  • 404not_found：找不到，或你看不到（不會說是哪一種）
  • 429rate_limited：太快了，看 Retry-After 秒數再試
  • 500internal：伺服器錯誤
post/api/user/v1/posts/{id}/transition

審稿／排程#

角色 客戶、Agency、平台管理員MCP review_post

規則和 dashboard 的按鈕一樣。客戶：approve、request_changes、reject、request_rewrite（後三者要 comment），只能在「待客戶審」、專案開著客戶審稿、你有審稿權時。Agency／管理員另有 submit、cancel_rewrite、schedule／reschedule（要未來的 scheduled_for）、unschedule。

可用角色：客戶、Agency、平台管理員（客戶要有審稿權）。

參數

欄位型別說明
id必填string (uuid) · 路徑貼文 id

請求本文（JSON）

客戶只能用 approve、request_changes、reject、request_rewrite（不收 scheduled_for）。

欄位型別說明
action必填string可用值：submit、approve、request_changes、reject、request_rewrite、cancel_rewrite、schedule、reschedule、unschedule
commentstring意見（退回、要求修改、要求重寫時必填）最多 2000 字
scheduled_forstringschedule／reschedule 用：發出時間（ISO，帶時區）
json 範例
{
  "action": "request_changes",
  "comment": "開頭太像上一篇，換個角度"
}

回應

200移動後的狀態。

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

已發布與報告

已發布的貼文與報告。

get/api/user/v1/posts/published

已發布的貼文#

角色 客戶、Agency、平台管理員MCP published_posts

已發布的貼文，新的在前；用 before 分頁。

可用角色：客戶、Agency、平台管理員。

參數

欄位型別說明
limitinteger · 查詢1–100
beforestring · 查詢分頁：這個時間之前發布的
persona_idstring · 查詢

回應

200posts 陣列。

  • 400invalid_request：參數格式不對（message 會指出哪個欄位）
  • 401unauthorized：沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員
  • 429rate_limited：太快了，看 Retry-After 秒數再試
  • 500internal：伺服器錯誤
get/api/user/v1/reports

報告清單#

角色 客戶、Agency、平台管理員MCP list_reports

客戶只看得到已發給客戶的報告。

可用角色：客戶、Agency、平台管理員。

參數

欄位型別說明
limitinteger · 查詢1–100

回應

200reports 陣列。

  • 400invalid_request：參數格式不對（message 會指出哪個欄位）
  • 401unauthorized：沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員
  • 429rate_limited：太快了，看 Retry-After 秒數再試
  • 500internal：伺服器錯誤
get/api/user/v1/reports/{id}

讀一份報告#

角色 客戶、Agency、平台管理員MCP get_report

報告內容。

可用角色：客戶、Agency、平台管理員。

參數

欄位型別說明
id必填string (uuid) · 路徑報告 id

回應

200報告。

  • 401unauthorized：沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員
  • 404not_found：找不到，或你看不到（不會說是哪一種）
  • 429rate_limited：太快了，看 Retry-After 秒數再試
  • 500internal：伺服器錯誤

待裁決

Agency 與管理員：看待裁決、裁決、回答選項題。

get/api/user/v1/decisions

待裁決#

角色 Agency、平台管理員MCP list_decisions

預設列未裁決的。

可用角色：Agency、平台管理員。

參數

欄位型別說明
statusstring · 查詢預設 open（未裁決）可用值：open、resolved、dismissed、decided
limitinteger · 查詢1–200

回應

200items 陣列。

  • 400invalid_request：參數格式不對（message 會指出哪個欄位）
  • 401unauthorized：沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員
  • 403forbidden：你的角色不能做這件事
  • 429rate_limited：太快了，看 Retry-After 秒數再試
  • 500internal：伺服器錯誤
post/api/user/v1/decisions/{id}/resolve

裁決：已處理#

角色 Agency、平台管理員MCP decide_issue

把待裁決標成已處理，可附備註。

可用角色：Agency、平台管理員。

參數

欄位型別說明
id必填string (uuid) · 路徑待裁決的 id

請求本文（JSON）

欄位型別說明
notestring備註；不處理時必填原因最多 500 字
json 範例
{
  "note": "已和客戶確認"
}

回應

200裁決後的狀態。

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

裁決：不處理#

角色 Agency、平台管理員MCP decide_issue

標成不處理，note 必填（原因）。

可用角色：Agency、平台管理員。

參數

欄位型別說明
id必填string (uuid) · 路徑待裁決的 id

請求本文（JSON）

欄位型別說明
notestring備註；不處理時必填原因最多 500 字
json 範例
{
  "note": "這張不需要換"
}

回應

200裁決後的狀態。

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

回答選項題#

角色 Agency、平台管理員MCP choose_issue

選選項 keys，或都不是時寫 other（兩者不能一起給）。

可用角色：Agency、平台管理員。

參數

欄位型別說明
id必填string (uuid) · 路徑待裁決的 id

請求本文（JSON）

欄位型別說明
keysstring[]選中的選項 key最多 12 個
otherstring都不是：寫下答案（不能和 keys 一起給）最多 500 字
json 範例
{
  "keys": [
    "tabby"
  ]
}

回應

200裁決後的狀態。

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

Agent 看板

Agency 與管理員：看板卡、交辦、確認、退回重做。

get/api/user/v1/tasks

Agent 看板#

角色 Agency、平台管理員MCP list_tasks

看板卡；預設進行中的三種（待領取、進行中、待確認）。

可用角色：Agency、平台管理員。

參數

欄位型別說明
statusstring · 查詢逗號分隔的狀態：open、in_progress、awaiting_confirmation、done、failed、cancelled
limitinteger · 查詢最多幾張（1–200）1–200

回應

200tasks 陣列。

  • 400invalid_request：參數格式不對（message 會指出哪個欄位）
  • 401unauthorized：沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員
  • 403forbidden：你的角色不能做這件事
  • 429rate_limited：太快了，看 Retry-After 秒數再試
  • 500internal：伺服器錯誤
post/api/user/v1/tasks

交辦新任務#

角色 Agency、平台管理員MCP open_task

開一張卡給 Agent（不指定 agent_id＝誰先領誰做）。target_type 與 target_id 要一起給。

可用角色：Agency、平台管理員。

請求本文（JSON）

欄位型別說明
agent_idstring交給哪個 Agent；不給＝誰先領誰做
kind必填string可用值：write_posts、rewrite_post、change_avatar、change_bio、delete_post、pause_account、resume_account、export_data、other
title必填string1–200 字
detailstring最多 4000 字
target_typestring可用值：slot、persona、post、issue
target_idstring
due_atstring
json 範例
{
  "kind": "change_bio",
  "title": "TW-T014 改 bio",
  "detail": "改成「下班後的咖啡地圖」"
}

回應

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

201新卡回 201，已有同一張回 200。

json 範例
{
  "task": {
    "id": "…"
  },
  "created": true
}
  • 400invalid_request：參數格式不對（message 會指出哪個欄位）
  • 401unauthorized：沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員
  • 403forbidden：你的角色不能做這件事
  • 413payload_too_large：請求內容太大
  • 422rejected：規則不允許（message 是原因）
  • 429rate_limited：太快了，看 Retry-After 秒數再試
  • 500internal：伺服器錯誤
post/api/user/v1/tasks/{id}/confirm

確認完成#

角色 Agency、平台管理員MCP confirm_task

確認 Agent 交回來的卡。

可用角色：Agency、平台管理員。

參數

欄位型別說明
id必填string (uuid) · 路徑卡的 id

請求本文（JSON）

欄位型別說明
notestring最多 2000 字
json 範例
{}

回應

200更新後的卡。

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

退回重做#

角色 Agency、平台管理員MCP reopen_task

退回 Agent 重做，note 必填（哪裡不對）。

可用角色：Agency、平台管理員。

參數

欄位型別說明
id必填string (uuid) · 路徑卡的 id

請求本文（JSON）

欄位型別說明
notestring最多 2000 字
json 範例
{
  "note": "顏色不對，要偏暖"
}

回應

200更新後的卡。

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

今日與成效

Agency 與管理員：今日摘要與成效數字。

get/api/user/v1/today

今日摘要#

角色 Agency、平台管理員MCP today

今天需要處理的事與排程概況。

可用角色：Agency、平台管理員。

回應

200今日摘要。

  • 401unauthorized：沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員
  • 403forbidden：你的角色不能做這件事
  • 429rate_limited：太快了，看 Retry-After 秒數再試
  • 500internal：伺服器錯誤
get/api/user/v1/metrics

成效#

角色 Agency、平台管理員MCP metrics

各帳號的成效數字，可依平台篩選。

可用角色：Agency、平台管理員。

參數

欄位型別說明
platformstring · 查詢可用值：threads、tiktok、x、facebook、instagram、reddit
limitinteger · 查詢1–500

回應

200成效。

  • 400invalid_request：參數格式不對（message 會指出哪個欄位）
  • 401unauthorized：沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員
  • 403forbidden：你的角色不能做這件事
  • 429rate_limited：太快了，看 Retry-After 秒數再試
  • 500internal：伺服器錯誤

金鑰管理

平台管理員：這個組織所有金鑰、撤銷。

get/api/user/v1/admin/keys

金鑰清單#

角色 平台管理員MCP list_keys

這個組織所有成員與 Agent 的金鑰（只有前綴與使用時間，看不到金鑰本身）。

可用角色：平台管理員。

回應

200金鑰清單。

  • 401unauthorized：沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員
  • 403forbidden：你的角色不能做這件事
  • 429rate_limited：太快了，看 Retry-After 秒數再試
  • 500internal：伺服器錯誤
post/api/user/v1/admin/keys/{kind}/{id}/revoke

撤銷金鑰#

角色 平台管理員MCP revoke_key

撤銷任何成員或 Agent 的金鑰。立即生效、不能恢復。

可用角色：平台管理員。

參數

欄位型別說明
kind必填string · 路徑user 成員的個人金鑰／agent Agent 金鑰可用值：user、agent
id必填string (uuid) · 路徑金鑰 id

回應

200撤銷結果。

  • 401unauthorized：沒帶金鑰、金鑰錯誤或已撤銷、Agent 金鑰的工作區已封存、還沒完成首次登入設定、已不是組織成員
  • 403forbidden：你的角色不能做這件事
  • 404not_found：找不到，或你看不到（不會說是哪一種）
  • 422rejected：規則不允許（message 是原因）
  • 429rate_limited：太快了，看 Retry-After 秒數再試
  • 500internal：伺服器錯誤

圖片連結

佇列與單篇回傳的簽名圖片連結。

get/api/user/v1/media/{id}

圖片（簽名連結）#

不用金鑰

審稿佇列與單篇回傳的 thumb_url／url。不用帶金鑰，15 分鐘內有效；金鑰撤銷後也立刻失效。照原樣使用，不要自己組。

參數

欄位型別說明
id必填string (uuid) · 路徑圖片 id
k必填string · 查詢金鑰 id
sizestring · 查詢thumb 縮圖／full 原圖可用值：thumb、full
exp必填integer · 查詢到期時間（Unix 秒）
sig必填string · 查詢簽名

回應

200圖檔本身（image/*）。

  • 400invalid_request：參數格式不對（message 會指出哪個欄位）
  • 404not_found：找不到，或你看不到（不會說是哪一種）
  • 500internal：伺服器錯誤