API v2

API v2 是一套結構化的 REST API，用於管理代理程式並建立自訂聊天體驗。它新增了代理程式管理、串流聊天、對話紀錄、訊息意見回饋、聯絡人、潛在客戶、來源、設定與訓練端點。

使用 API 需要 Hobby 方案以上，且帳單狀態為有效。

基礎 URL

https://your-domain.com/api/v2

身分驗證

除了健康檢查端點外，請以你工作區的 API 金鑰作為 Bearer 權杖傳送：

Authorization: Bearer YOUR_API_KEY

在 設定 > API 金鑰 中建立與撤銷 API 金鑰。

回應格式

大多數成功回應會回傳資源物件，或以 data 封裝：

{
  "data": []
}

清單端點包含游標分頁：

{
  "data": [],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 0
  }
}

錯誤會使用結構化的 error 物件：

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body"
  }
}

每個 v2 回應都包含 x-request-id 標頭。聯絡支援團隊回報 API 請求問題時，請附上此值。

對話範圍

唯讀對話端點預設使用 source=api_v2。設定 source=widget 可回傳小工具與 Playground 對話；Playground 記錄會以 widget 來源儲存。設定 source=all 可回傳 API v2、小工具與 Playground 對話。結果永遠僅限於已驗證帳戶所擁有的代理程式。無效的 source 值，或帶有一個以上的 source 查詢參數，會回傳 400 VALIDATION_INVALID_BODY。對話延續、重試、意見回饋、訊息列表與依使用者查詢，僅適用於 API v2 對話。

健康檢查

GET /api/v2/health

健康檢查端點不需要身分驗證。

成功：200 OK

{
  "status": "ok",
  "timestamp": 1784332800
}

timestamp 為目前的 Unix 時間戳記（秒）。

聊天

POST /api/v2/agents/{agentId}/chat

請求：

{
  "message": "What plans do you offer?",
  "conversationId": "optional-existing-conversation-id",
  "userId": "optional-user-id",
  "stream": true
}

串流回應使用 Server-Sent Events。串流內容包含 message-start、text-start、text-delta、text-end、message-metadata、finish 與 [DONE] 等事件。當串流或完成掛鉤（completion hook）失敗時，會發出 error 事件，其 error.code 設為 CHAT_STREAMING_ERROR；這個僅用於 SSE 的協定代碼獨立於結構化的 REST 錯誤目錄。message-metadata 在訊息成功持久化時，會包含助理訊息 ID，並附上對話 ID、使用者 ID、完成原因（finish reason）與用量資訊。當沒有助理訊息被持久化時，其 messageId 為 null。當回覆因用戶端動作而暫停時，串流也會發出帶有 { "id", "name", "arguments" } 的 tool-call 事件；請將結果提交至 tool-result 端點 以繼續對話——該請求的回應會以串流方式傳回後續內容。

非串流回應會回傳：

{
  "data": {
    "id": "123",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "..." }],
    "pendingToolCall": null,
    "metadata": {
      "userMessageId": "122",
      "conversationId": "abc123",
      "userId": "user_123",
      "finishReason": "stop",
      "usage": { "credits": 1 }
    }
  }
}

非串流回應中的 data.id 與 metadata.userMessageId 是以字串序列化的數字訊息 ID；若對應的訊息未被持久化，則為 null。metadata.userId 為傳入或已儲存的使用者 ID，若無則為 null。pendingToolCall 為 null，除非回覆在用戶端工具呼叫處暫停；此時它會包含 { "id", "name", "arguments" }，供工具結果端點使用。

端點摘要

意見回饋

使用意見回饋功能，將 API v2 助理訊息標記為 positive、negative 或 null。請求結構、回應內容與錯誤行為，請見對話、訊息與意見回饋。

分頁

請將游標視為 API 回傳的不透明權杖。在下一次請求時原封不動地帶上 pagination.cursor 的值；請勿自行建構或解析它。

聯絡人另外接受 search。潛在客戶接受包含邊界的 createdAfter 與 createdBefore ISO 8601 日期時間篩選條件。來源接受 sourceType，可為 web_crawl、file_upload、text_snippet 或 qna_entry。

游標格式屬於內部實作細節。用戶端必須將每個游標都視為不透明權杖，原封不動地重複使用，不得自行建構或解析。

常見錯誤

完整的 27 個已宣告代碼、HTTP 狀態碼、觸發條件與保留代碼，請見完整的 API v2 錯誤目錄。

參考文件

• 錯誤目錄
• 代理程式與設定
• 對話、訊息、重試與意見回饋
• 來源與訓練
• 聯絡人與潛在客戶
• Instagram 頻道

後續步驟

• 建立 API 金鑰
• 設定身分驗證
• 檢視 API v2 錯誤
• 管理代理程式與設定
• 操作對話
• 管理來源與訓練
• 管理聯絡人與潛在客戶
• 管理 Instagram 頻道