Agent API 參考文件

Po Once Agent API 讓 AI 代理與腳本能代表單一組織探索已連結帳號、讀取分析數據、搜尋 Threads，並發佈或排程貼文。所有端點皆由 bearer token 限定於該組織範圍。

基礎網址

https://dynamic-lapwing-647.convex.site

以下所有路徑皆相對於此主機。若你的部署不同，請將用戶端指向你自己的 Convex HTTP 部署主機。

驗證

每個請求都使用限定組織範圍的 bearer token 進行驗證。請在網頁應用程式的 組織設定 → Agent Access 中建立金鑰。Token 只會顯示一次。

Authorization: Bearer po_live_org_<secret>

正式金鑰以 po_live_org_ 開頭。
每個請求都限定於從 token 解析出的組織範圍 — 請勿自行傳入任何組織識別資訊。
使用 Agent API 需要該組織擁有有效的 Starter 或 Pro 訂閱方案。

核心流程

一般的發佈流程會串接以下端點：

GET /accounts — 探索發佈目標並複製其 ID。
POST /media/create-upload-url 並以 PUT 上傳檔案（僅在貼文含媒體時需要）。
POST /contents — 建立文案 + 媒體記錄。
POST /posts — 直接發佈或排程。
GET /posts/:id — 輪詢狀態；仍在排程狀態時可用 DELETE /posts/:id 刪除。

端點

GET/api/agent/v1/accounts

列出帳號

列出已連結至當前驗證組織的所有發佈帳號。請務必先呼叫此端點 — 它回傳的 ID 是分析、關鍵字搜尋與發佈的輸入來源。

id / socialProfileId用於個人檔案分析與發佈。
linkedAccountId 用於需要連結帳號的端點，例如 Threads 關鍵字搜尋。

請求

curl -s "https://dynamic-lapwing-647.convex.site/api/agent/v1/accounts" \
  -H "Authorization: Bearer $PO_ONCE_AGENT_API_KEY"

回應200 OK

{
  "accounts": [
    {
      "id": "jh7f4q1x1x9m5k8v6n0h3m2g6s7f1z1g",
      "socialProfileId": "jh7f4q1x1x9m5k8v6n0h3m2g6s7f1z1g",
      "provider": "instagram",
      "displayName": "Brand Account",
      "linkedAccountId": "k17d8v2x1x9m5k8v6n0h3m2g6s7f1z1p",
      "avatarUrl": "https://..."
    }
  ]
}

GET/api/agent/v1/analytics/profiles/:profileId

取得個人檔案分析

取得單一已連結個人檔案的即時、各平台專屬的成效分析。除非使用者明確要求比較，否則一次只查詢一個個人檔案。

路徑參數

profileId

string必填

來自 GET /accounts 的個人檔案 id / socialProfileId。

查詢參數

`days` integer選填	滾動時間窗長度，例如 `28`。僅限 Meta 個人檔案。請勿與 `period`、`since` 或 `until` 併用。
`period` enum選填	`day`、`week`、`days_28`、`custom` 其中之一。僅限 Meta 個人檔案。
`since` integer選填	自訂時間窗起點（epoch）。須與 `until` 一起使用。
`until` integer選填	自訂時間窗終點（epoch）。須與 `since` 一起使用。
`cursor` integer選填	分頁游標。僅限 TikTok 個人檔案。
`maxCount` integer選填	回傳項目的上限數量。僅限 TikTok 個人檔案。

摘要前請先從 meta 確認時間窗。
只比較使用相同時間窗且指標類型相近的個人檔案。
明確指出缺少的指標，而非自行推論。
Facebook：Meta 已於 2025 年 11 月與 2026 年 6 月移除多項粉絲專頁洞察指標，因此回應中不再包含 postImpressions（貼文曝光）、engagedUsers（互動人數）、newFollowers、unfollows 與頁面層級 reactions。請改用 views（內容觀看次數）、reach（不重複觀看人數）與 postEngagements（總互動次數）。詳情請見 meta.deprecations。

請求

curl -s "https://dynamic-lapwing-647.convex.site/api/agent/v1/analytics/profiles/<social_profile_id>?days=28" \
  -H "Authorization: Bearer $PO_ONCE_AGENT_API_KEY"

回應200 OK

{
  "profile": {
    "id": "<social_profile_id>",
    "provider": "facebook",
    "displayName": "Brand Page"
  },
  "analytics": {
    "totals": {
      "followers": 42,
      "views": 44703,
      "profileViews": 679,
      "reach": 34045,
      "postEngagements": 1760
    }
  },
  "meta": {
    "period": "days_28",
    "fetchedAt": 1782978060077,
    "deprecations": [
      "postImpressions, engagedUsers, newFollowers and unfollows are no longer returned: Meta removed page_posts_impressions, page_engaged_users, page_fan_adds and page_fan_removes."
    ]
  }
}

POST/api/agent/v1/keyword-search

Threads 關鍵字搜尋

針對公開貼文執行臨時的 Threads 關鍵字探索。這是唯讀的探索呼叫，並非監測管理端點。

請求主體參數

`linkedAccountId` string必填	來自 GET /accounts 的 Threads `linkedAccountId`。必須屬於當前驗證組織，且須為 Threads 帳號。
`keyword` string必填	要搜尋的關鍵字或片語。
`searchType` enum選填預設: `TOP`	`TOP` 或 `RECENT` 其中之一。

請求

curl -s "https://dynamic-lapwing-647.convex.site/api/agent/v1/keyword-search" \
  -X POST \
  -H "Authorization: Bearer $PO_ONCE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"linkedAccountId":"<threads_linked_account_id>","keyword":"launch tips","searchType":"TOP"}'

回應200 OK

{
  "keyword": "launch tips",
  "results": [
    {
      "id": "123_456",
      "text": "Launch tip: post a short demo first.",
      "username": "creator",
      "timestamp": "2026-04-24T08:00:00+0000",
      "permalink": "https://www.threads.net/@creator/post/...",
      "mediaType": "TEXT_POST",
      "hasReplies": true,
      "isQuotePost": false,
      "isReply": false
    }
  ],
  "totalResults": 1
}

GET/api/agent/v1/keyword-monitors

列出關鍵字監測

列出組織已儲存的 Threads 關鍵字監測，也就是 Po Once 依排程搜尋的關鍵字。此端點為唯讀；監測需在網頁應用程式中建立與編輯。

查詢參數

`active` boolean選填	設為 `true` 時只回傳啟用中的監測；省略或 false 包含全部。
`limit` integer選填預設: `20`	每頁預設 20 筆，最多 100 筆。
`cursor` string選填	前一頁回傳的 `nextCursor`。

回傳的 id 可作為 GET /keyword-matches 的 monitorId。
autoReplyEnabled 目前一律為 false；回覆需由使用者明確發起。範本內容不會回傳。

請求

curl -s "https://dynamic-lapwing-647.convex.site/api/agent/v1/keyword-monitors?active=true" \
  -H "Authorization: Bearer $PO_ONCE_AGENT_API_KEY"

回應200 OK

{
  "monitors": [
    {
      "id": "k57d8v2x1x9m5k8v6n0h3m2g6s7f1z1q",
      "keyword": "launch tips",
      "isActive": true,
      "searchType": "TOP",
      "searchFrequency": "every_hour",
      "linkedAccountId": "k17d8v2x1x9m5k8v6n0h3m2g6s7f1z1p",
      "socialProfileId": "jh7f4q1x1x9m5k8v6n0h3m2g6s7f1z1g",
      "profile": {
        "displayName": "Brand on Threads",
        "provider": "threads"
      },
      "autoReplyEnabled": false,
      "lastSearchedAt": 1783000000000,
      "totalMatches": 42,
      "totalReplies": 0,
      "createdAt": 1782000000000,
      "updatedAt": 1783000000000
    }
  ],
  "nextCursor": null,
  "isDone": true
}

GET/api/agent/v1/keyword-matches

列出關鍵字比對結果

列出關鍵字監測已找到的貼文，由新到舊排序。適用於「監測抓到了什麼」與「還有哪些待回覆」；若需即時查詢，請改用關鍵字搜尋。

查詢參數

`monitorId` string選填	來自 GET /keyword-monitors 的 `id`。必須屬於當前驗證組織。
`status` enum選填	`pending`、`replied`、`failed`、`skipped` 其中之一。
`postAgeHours` integer選填	排除 Threads 貼文發布時間超過此小時數的比對結果。
`limit` integer選填預設: `20`	每頁筆數，最多 `100`。
`cursor` string選填	前一頁回傳的 `nextCursor`。

pending = 已找到但尚未回覆。replied = Po Once 已回覆（replyId、repliedAt）。failed = 回覆失敗（errorMessage）。skipped = 刻意不回覆（skipReason）。
持續使用 nextCursor 取得下一頁，直到 null。時間篩選套用於有限筆數的頁面，因此頁面可能為空但仍有下一頁。

請求

curl -s "https://dynamic-lapwing-647.convex.site/api/agent/v1/keyword-matches?status=pending&limit=20" \
  -H "Authorization: Bearer $PO_ONCE_AGENT_API_KEY"

回應200 OK

{
  "matches": [
    {
      "id": "m97d8v2x1x9m5k8v6n0h3m2g6s7f1z1r",
      "monitorId": "k57d8v2x1x9m5k8v6n0h3m2g6s7f1z1q",
      "keyword": "launch tips",
      "threadsPostId": "123_456",
      "postText": "Launch tip: post a short demo first.",
      "postAuthor": "creator",
      "postAuthorId": "789",
      "postPermalink": "https://www.threads.net/@creator/post/...",
      "postTimestamp": 1783000000000,
      "matchedAt": 1783003600000,
      "status": "pending",
      "replyId": null,
      "repliedAt": null,
      "errorMessage": null,
      "skipReason": null
    }
  ],
  "nextCursor": null,
  "isDone": true
}

POST/api/agent/v1/media/create-upload-url

建立媒體上傳網址

為媒體檔案建立一次性的預簽署上傳目標。以單一 HTTP PUT（附 Content-Length，從磁碟串流）將檔案上傳至回傳的 uploadUrl，接著在建立內容時將回傳的 key 作為 storageKey 引用。Po Once 本身沒有檔案大小上限，僅受目標平台限制。

請求主體參數

`filename` string選填	原始檔名。僅使用副檔名（用於命名儲存物件）。
`contentType` enum選填	`image/jpeg`、`image/png`、`image/webp`、`image/gif`、`video/mp4`、`video/quicktime` 其中之一。
`sizeBytes` integer選填	選填的檔案大小（位元組）。提供時，若上傳將超出工作區儲存空間額度，請求會回傳 `402 STORAGE_LIMIT_EXCEEDED`，讓你在傳輸檔案前就能停止。

請求

curl -s "https://dynamic-lapwing-647.convex.site/api/agent/v1/media/create-upload-url" \
  -X POST \
  -H "Authorization: Bearer $PO_ONCE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"launch.mp4","contentType":"video/mp4","sizeBytes":367001600}'

回應201 Created

{
  "key": "uuid.mp4",
  "uploadUrl": "https://...",
  "method": "PUT"
}

POST/api/agent/v1/contents

建立內容

在所有上傳完成後，建立可重複使用的內容記錄（文案 + 媒體）。回傳的 contentId 之後用於建立貼文。

請求主體參數

`caption` string必填	貼文文案。
`postType` enum必填	`image`、`video`、`text` 其中之一。`text` 不可含媒體項目；`image`/`video` 至少需要一個。
`mediaItems` object[]必填	媒體物件陣列。每個項目須含字串 `storageKey`（來自 create-upload-url 的 `key`）。選填：`width`、`height`、`sizeBytes`、`thumbnailStorageId`、`thumbnailWidth`、`thumbnailHeight`。純文字貼文請傳入 `[]`。儲存空間用量以實際儲存物件的大小計算；`sizeBytes` 僅為相容性保留，不影響計量。
`title` string選填	選填標題（用於 YouTube 等平台）。
`profileHint` string選填	完整且相同的工作區名稱。工作區擁有者啟用名稱提示要求後為必填；若有提供，必須與 API 金鑰所屬工作區相同。
`isAI` boolean選填	標記內容為 AI 生成。

請求

curl -s "https://dynamic-lapwing-647.convex.site/api/agent/v1/contents" \
  -X POST \
  -H "Authorization: Bearer $PO_ONCE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Launch clip","caption":"Shipping this week.","profileHint":"Acme Workspace","postType":"video","mediaItems":[{"storageKey":"agent/org_id/uuid.mp4","sizeBytes":123456}]}'

回應201 Created

{
  "contentId": "jx7f4q1x1x9m5k8v6n0h3m2g6s7f1z1g",
  "nearLimit": false
}

POST/api/agent/v1/posts

建立貼文

將內容記錄發佈到一個或多個個人檔案，可立即發佈（direct）或於未來時間發佈（scheduled）。回傳一個批次及建立的貼文 ID。

請求主體參數

`contentId` string必填	由 POST /contents 回傳的 `contentId`。
`socialProfileIds` string[]必填	要發佈到的個人檔案 ID 陣列（不可為空），來自 GET /accounts。
`mode` enum必填	`scheduled` 或 `direct` 其中之一。
`scheduledTime` integer選填	Epoch 毫秒。當 `mode` 為 `scheduled` 時為必填；`direct` 時預設為當下時間。
`scheduledTimezone` string選填預設: `UTC`	IANA 時區，例如 `America/Los_Angeles`。
`captionOverride` string選填	為此貼文覆寫內容文案。
`titleOverride` string選填	為此貼文覆寫內容標題。
`youtubePrivacyStatus` enum選填	`public`、`unlisted`、`private` 其中之一。
`tiktokPrivacyLevel` enum選填	`PUBLIC_TO_EVERYONE`、`MUTUAL_FOLLOW_FRIENDS`、`FOLLOWER_OF_CREATOR`、`SELF_ONLY` 其中之一。
`tiktok* toggles` boolean選填	`tiktokAllowComment`、`tiktokAllowDuet`、`tiktokAllowStitch`、`tiktokBrandContentToggle`、`tiktokBrandOrganicToggle`、`tiktokDraftMode`。
`instagramUserTags` object[]選填	`{ username, x?, y? }` 的陣列。每個標記的 `username` 為必填。
`instagramCollaborators` string[]選填	要邀請為共同作者的使用者名稱。
`videoThumbnailOffsetMs` number選填	用於挑選影片縮圖的影格位移（毫秒）。
`customThumbnailStorageKey` string選填	自訂縮圖上傳的儲存鍵。
`mediaOrderOverride` string[]選填	以儲存鍵為此貼文重新排序媒體。
`firstComment` string選填	僅限 Facebook／Instagram／Threads。發布後立即以留言或回覆送出。

選填的平台欄位僅在符合目標平台與媒體類型時才會生效。
若要直接發佈，請省略 scheduledTime 與 scheduledTimezone，並設定 mode: "direct"。
亞洲區註冊的 TikTok 帳號目前發布圖片貼文會遇到嚴重延遲（可能超過 12 小時），這是 TikTok 端接收服務的問題；貼文可能先顯示 failed 但稍後仍成功發布。請避免重複提交同一篇圖片貼文 — 重試可能造成重複貼文。影片發布不受影響。

請求

curl -s "https://dynamic-lapwing-647.convex.site/api/agent/v1/posts" \
  -X POST \
  -H "Authorization: Bearer $PO_ONCE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contentId":"<content_id>","socialProfileIds":["<social_profile_id_1>","<social_profile_id_2>"],"mode":"scheduled","scheduledTime":1770000000000,"scheduledTimezone":"America/Los_Angeles"}'

回應201 Created

{
  "batchId": "4e9d52cb-1f1c-4e6b-a927-d22b6f99d0d1",
  "postIds": [
    "j97f4q1x1x9m5k8v6n0h3m2g6s7f1z1g"
  ],
  "nearLimit": false
}

GET/api/agent/v1/posts

列出貼文

列出組織近期的貼文，最新優先，並支援游標分頁。

查詢參數

`limit` integer選填預設: `20`	每頁數量，1–100（超過會限制為 100）。
`cursor` string選填	以 `nextCursor` 回傳的分頁游標。
`status` enum選填	依狀態篩選：`pending`、`scheduled`、`initializing`、`uploading`、`uploaded`、`processing`、`published`、`failed`、`error`。

請求

curl -s "https://dynamic-lapwing-647.convex.site/api/agent/v1/posts?limit=20&status=scheduled" \
  -H "Authorization: Bearer $PO_ONCE_AGENT_API_KEY"

回應200 OK

{
  "posts": [
    {
      "_id": "j97f4q1x1x9m5k8v6n0h3m2g6s7f1z1g",
      "type": "scheduled",
      "status": "scheduled",
      "scheduledTime": 1770000000000
    }
  ],
  "nextCursor": null,
  "isDone": true
}

GET/api/agent/v1/posts/:id

取得單一貼文

取得單一貼文及其完整詳細資訊。

路徑參數

id

string必填

來自列出貼文或建立貼文的貼文 ID。

請求

curl -s "https://dynamic-lapwing-647.convex.site/api/agent/v1/posts/<post_id>" \
  -H "Authorization: Bearer $PO_ONCE_AGENT_API_KEY"

回應200 OK

{
  "_id": "j97f4q1x1x9m5k8v6n0h3m2g6s7f1z1g",
  "type": "scheduled",
  "status": "scheduled",
  "scheduledTime": 1770000000000,
  "content": {
    "caption": "Shipping this week.",
    "postType": "video"
  }
}

DELETE/api/agent/v1/posts/:id

刪除貼文

刪除貼文。僅尚未開始處理的排程貼文可刪除 — 已發佈、直接發佈、失敗及處理中的貼文無法移除。

路徑參數

id

string必填

要刪除的貼文 ID。

唯有當 type === "scheduled" 且 status === "scheduled" 時，貼文才可刪除。

請求

curl -s "https://dynamic-lapwing-647.convex.site/api/agent/v1/posts/<post_id>" \
  -X DELETE \
  -H "Authorization: Bearer $PO_ONCE_AGENT_API_KEY"

回應200 OK

{
  "success": true
}

錯誤處理

錯誤會回傳一個 JSON 結構，內含穩定的 code 以及人類可讀的 message。

{
  "error": {
    "code": "AGENT_POSTS_FAILED",
    "message": "Profile not found: <invalid_social_profile_id>"
  }
}

狀態碼	錯誤代碼	說明
`400`	`AGENT_*_FAILED`	輸入無效 — 缺少必填欄位或格式錯誤。
`401`	`UNAUTHORIZED`	缺少或格式錯誤的 bearer token。
`402`	`SUBSCRIPTION_REQUIRED`	該組織需要有效的 Starter 或 Pro 方案才能使用 Agent API。
`402`	`STORAGE_LIMIT_EXCEEDED`	該組織需要有效的 Starter 或 Pro 方案才能使用 Agent API。
`403`	`FORBIDDEN`	Agent API 金鑰無效／已撤銷，或該資源屬於其他組織。
`404`	`NOT_FOUND`	找不到請求的個人檔案或貼文。
`405`	`METHOD_NOT_ALLOWED`	此路徑不支援該 HTTP 方法。
`500`	`AGENT_*_FAILED`	非預期的伺服器錯誤。