參考資料

REST API

從你自己的程式碼建立、排程和發布貼文、上傳媒體和讀取成效。API 遵守和 SPREVA 本身相同的規則和驗證。

你的第一個請求

1
在 SPREVA 的開發人員中，於 API 金鑰建立一組 API 金鑰。這個範例只需要「唯讀」金鑰；發布則需要具備「發布」存取權的金鑰。

列出你的社群帳號：

終端機

curl https://dev-app.spreva.ai/api/v1/social-accounts \
  -H "Authorization: Bearer spreva_sk_..."

讀取回覆。結果會放在 data 中，為某個帳號建立貼文時，要把該帳號的 id 當作 connectionId 傳送。範例已經縮短：實際的物件有更多欄位。

JSON

{
  "data": [
    {
      "id": "e81b3f52-0000-4000-8000-000000000005",
      "provider": "instagram",
      "displayName": "Acme Studio",
      "username": "acme",
      "status": "ACTIVE",
      "needsReconnect": false
    }
  ]
}

基本資訊

所有端點都在這個位址下。以 JSON 傳送，並以 Authorization: Bearer 加上金鑰的形式提供金鑰。

網址

https://dev-app.spreva.ai/api/v1

一組金鑰屬於一個工作空間，而且只能看到那個工作空間。
上限：在一個工作空間中，每個人每分鐘 120 個請求，由他建立的所有金鑰共用。超過之後，回覆會是 429，訊息中會說明需要等待幾秒。
錯誤會以請求的 Accept-Language 標頭所指定的語言回傳；錯誤的 code 永遠不變。
從已登入 SPREVA 的瀏覽器呼叫時，請傳送包含工作空間 ID 的 x-workspace-id，而不是金鑰。

金鑰和權限

金鑰會代表建立它的人執行動作，而且絕不能超出那個人的角色所允許的範圍。金鑰由擁有者和管理員在包含 API 存取權的方案中建立，完整的金鑰只會顯示一次。每組金鑰都有建立時所授予的權限：

posts:read: 查看貼文、貼文狀態、結果和佇列
media:read: 查看媒體庫
accounts:read: 查看已連結的社群帳號
analytics:read: 查看數據分析
posts:write: 建立、編輯、排程、發布和刪除貼文，以及管理佇列
media:write: 上傳、重新命名和刪除媒體
webhooks:write: 查看和新增 Webhook 端點
ai:write: 使用 AI。文案和主題標籤還需要 posts:write；替代文字和圖片還需要 media:write

唯讀提供四項讀取權限。發布另外加上 posts:write、media:write 和 ai:write，足以用於自動化流程或 AI 代理程式。403 表示金鑰缺少該權限，或建立者的角色已不再允許。

金鑰和代理程式都絕對無法核准貼文：在需要核准的工作空間中，只有人能在 SPREVA 中核准。

錯誤

每個錯誤的結構都相同。依 code 判斷處理方式，並顯示 message。

JSON

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key needs the posts:write scope for posts:create"
  }
}

400: INVALID_REQUEST, INVALID_JSON, WORKSPACE_REQUIRED
本文或查詢參數與端點不符。details 會列出每個錯誤的欄位。沒有 x-workspace-id 的瀏覽器呼叫會收到 WORKSPACE_REQUIRED。
401: UNAUTHENTICATED
金鑰缺少、輸入錯誤、已撤銷或已過期。請傳送「Authorization: Bearer <key>」。
402: ENTITLEMENT_EXCEEDED, AI_LIMIT_REACHED
工作空間沒有生效中的方案、AI 點數已用完，或方案不包含這項功能。擁有者可以在「設定」>「帳單」中選擇方案或購買點數。
403: FORBIDDEN
金鑰沒有這個請求所需的權限，或你的角色不允許。請建立存取權更多的金鑰。
404: NOT_FOUND
這個工作空間中沒有這個物件。金鑰只能看到建立它的工作空間。
409: CONCURRENT_MODIFICATION, INVALID_STATE_TRANSITION, CONFLICT, AI_NOT_CONFIGURED, REVIEW_REQUIRED
你讀取貼文後它已有變更、它的狀態不允許這個動作（例如發布已發布的貼文）、你要刪除的檔案仍被貼文使用，或這個安裝版本尚未設定 AI。請重新取得後再試一次。REVIEW_REQUIRED 不同：工作空間要求貼文發布前先經過核准，所以請用 POST /posts/{id}/review 送出審核，而不是重試。
422: VALIDATION_FAILED, PROVIDER_VALIDATION_FAILED, AI_REFUSED
內容不符合要發布的帳號，或 AI 請求遭到拒絕。GET /providers 會列出每個社群平台的規則。
429: RATE_LIMITED, AI_BUSY
你在這個工作空間中一分鐘內的請求超過 120 個，或同時有太多 AI 請求。RATE_LIMITED 的訊息會說明需要等待幾秒；AI_BUSY 則稍候片刻即可。
500: INTERNAL
處理請求時，SPREVA 或社群平台發生錯誤。稍後再試一次。
503: AI_UNAVAILABLE
AI 供應商目前無法使用。稍後再試一次。

端點

路徑是相對於基礎網址的路徑。OpenAPI 文件描述了每個本文和參數，你也可以用它產生用戶端：

網址

https://dev-app.spreva.ai/api/openapi.json

社群帳號和社群平台

get /social-accounts已連結的社群帳號。
get /providers每個社群平台的規則：格式、版位和上限。

貼文

get /posts貼文，可依狀態、日期、帳號、社群平台或行銷活動篩選。
post /posts為一個或多個帳號建立草稿貼文。
get /posts/{id}一則貼文，包含它的帳號、驗證結果和媒體。
patch /posts/{id}變更貼文。傳送你讀取的 version；如果之後有變更，回覆會是 409。
delete /posts/{id}刪除貼文。
post /posts/{id}/publish立即發布。回覆是 202：追蹤貼文或 Webhook 以取得結果。
post /posts/{id}/schedule排程在指定時間，並附上時區。
post /posts/{id}/queue加入佇列的下一個空時段。
post /posts/{id}/review附上時間或佇列送出審核；核准後就會發布。
post /posts/{id}/retry重試發布失敗的帳號。

媒體

get /media媒體庫，可搜尋和篩選。
post /media/uploads開始上傳：回覆會說明要把檔案傳送到哪裡。
post /media/uploads/{id}/complete完成上傳。接著會檢查和處理檔案。
get /media/{id}一個檔案，包含它的狀態和已知的資訊。
delete /media/{id}刪除檔案。仍被貼文使用的檔案會回覆 409。
put /media/{id}/alt-text儲存或清除檔案的替代文字。
post /media/{id}/alt-text/suggestion用 AI 建議替代文字，但不儲存。

數據分析

get /analytics一段期間的成效。
get /analytics/export以 CSV 檔案提供相同的成效。

佇列

get /queues發布佇列。
post /queues建立含每週時段的佇列。
patch /queues/{id}變更佇列。
delete /queues/{id}刪除佇列。

Webhook

get /webhooksWebhook 端點。
post /webhooks新增端點。回覆會附上它的密鑰，只有這一次。

get /aiAI 是否可用、剩餘的點數，以及每個動作的費用。
post /ai/captions建議改寫文案、翻譯或主題標籤，但不儲存。
post /ai/images生成圖片。持續查詢 GET /media/{id}，直到圖片完成。