API v2 代理程式與設定

建立並管理代理程式，接著讀取或更新其 AI、設計、安全性、通知與訓練設定。

使用以下端點管理代理程式及其設定。本頁的每個端點都需要 Authorization: Bearer YOUR_API_KEY。當代理程式不存在，或不屬於此 API 金鑰所屬的帳戶時，代理程式範圍的路由會回傳 404 AGENT_NOT_FOUND。

成功的清單回應會以 data 與 pagination 封裝。代理程式明細與設定回應則是不含 data 封裝的裸物件。共用的驗證與驗證錯誤，請見錯誤目錄。

代理程式物件

欄位	類型	備註
`id`	string	代理程式 ID。
`name`	string	代理程式名稱。
`url`	string 或 null	關聯的網站 URL。
`createdAt`	integer 或 null	Unix 時間戳記（秒）。
`settings`	object	已儲存的代理程式設定。

{
  "id": "955f28f1-8515-40bb-802c-f3f730bf0343",
  "name": "Support Agent",
  "url": "https://example.com",
  "createdAt": 1784332800,
  "settings": {
    "ai": {
      "model": "openai/gpt-5.6-luna",
      "instructionsPreset": "ai-chatbot",
      "instructionsPrompt": "Be helpful, accurate, and conversational."
    },
    "title": "AI Assistant",
    "branding": {
      "appearance": "Light",
      "bubbleColor": "#e9e9e7",
      "primaryColor": "#0a0a0a",
      "primaryColorHeader": false
    },
    "position": "bottom-right",
    "conversation": {
      "defaultPrompts": {
        "enabled": false,
        "prompts": [],
        "keepShowing": false
      },
      "initialMessages": ["Hey! What can I help with?"],
      "messagePlaceholder": "Ask our chatbot a question...",
      "showInitialMessageBubble": true
    },
    "features": {
      "attachments": true
    },
    "notification": {
      "dailyConversations": true,
      "dailyEmails": true,
      "quotaAlerts": true
    }
  }
}

列出代理程式

路徑：/api/v2/agents

GET /api/v2/agents

身分驗證：Bearer API 金鑰。

查詢參數	是否必填	限制
`limit`	否	1 到 100 之間的整數，預設為 20。
`cursor`	否	前一頁回傳的不透明游標。請原封不動地重複使用。

成功：200 OK

curl 'https://your-domain.com/api/v2/agents?limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "id": "955f28f1-8515-40bb-802c-f3f730bf0343",
      "name": "Support Agent",
      "url": "https://example.com/",
      "createdAt": 1784332800,
      "settings": {}
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

無效的 limit 或 cursor 會回傳 400 VALIDATION_INVALID_BODY。

建立代理程式

POST /api/v2/agents

身分驗證：Bearer API 金鑰。

主體欄位	是否必填	類型與限制
`name`	是	字串，經過修剪，1 到 255 個字元。
`url`	否	有效的 URL 字串、空字串或 `null`。空字串、`null` 與省略此欄位，都會儲存為 `null`。

curl -X POST 'https://your-domain.com/api/v2/agents' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Support Agent","url":"https://example.com"}'

成功：201 Created，回傳裸的代理程式物件。

無效的主體會回傳 400 VALIDATION_INVALID_BODY。超出工作區的代理程式數量上限會回傳 403 QUOTA_CHATBOT_LIMIT。

取得代理程式

路徑：/api/v2/agents/{agentId}

GET /api/v2/agents/{agentId}

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

成功：200 OK，回傳裸的代理程式物件。

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343' \
  -H 'Authorization: Bearer YOUR_API_KEY'

更新代理程式

PATCH /api/v2/agents/{agentId}

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

至少須提供一個欄位。

主體欄位	是否必填	類型與限制
`name`	否	字串，經過修剪，1 到 255 個字元。
`url`	否	有效的 URL 字串、空字串或 `null`。空字串與 `null` 會清除此 URL。

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Customer Support"}'

成功：200 OK，回傳更新後的裸代理程式物件。無效或空的主體會回傳 400 VALIDATION_INVALID_BODY。

刪除代理程式

DELETE /api/v2/agents/{agentId}

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

curl -X DELETE 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343' \
  -H 'Authorization: Bearer YOUR_API_KEY'

成功：200 OK

{
  "deleted": true
}

AI 設定結構

路徑：/api/v2/agents/{agentId}/settings/ai

更新 AI 設定至少須提供一個欄位。

主體欄位	是否必填	類型與限制
`model`	否	可為 `openai/gpt-5.6-sol`、`openai/gpt-5.6-terra`、`openai/gpt-5.6-luna`、`anthropic/claude-opus-5`、`anthropic/claude-sonnet-5`、`anthropic/claude-haiku-4-5`、`google/gemini-3.7-flash` 或 `google/gemini-3.1-pro-preview` 其中之一。
`instructionsPreset`	否	可為 `custom`、`ai-chatbot`、`customer-support`、`sales-agent`、`language-tutor`、`coding-expert` 或 `life-coach` 其中之一。
`instructionsPrompt`	否	字串。

為了向下相容，model 也接受已淘汰的識別碼 openai/gpt-5.5、openai/gpt-5.4、openai/gpt-5.4-mini、openai/gpt-5.4-nano、anthropic/claude-opus-4.7、anthropic/claude-opus-4-6、anthropic/claude-sonnet-4-6、google/gemini-3-flash-preview 與 google/gemini-3.6-flash。既有代理程式可能仍儲存（GET 也可能仍回傳）這些值，因此 GET→PATCH 的往返操作永遠能通過驗證——但這些值已不再出現於儀表板的模型選單中，新的整合應使用上方目前的模型清單。

取得 AI 設定

GET /api/v2/agents/{agentId}/settings/ai

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

成功：200 OK。AI 設定物件以裸物件回傳；未設定的 AI 設定會產生 {}。

{
  "model": "openai/gpt-5.6-luna",
  "instructionsPreset": "customer-support",
  "instructionsPrompt": "Answer using the support documentation."
}

更新 AI 設定

PATCH /api/v2/agents/{agentId}/settings/ai

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/ai' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model":"openai/gpt-5.6-luna","instructionsPreset":"customer-support"}'

成功：200 OK，回傳更新後的裸 AI 設定物件。不可用的模型會回傳 403 CHAT_MODEL_NOT_ALLOWED；無效或空的主體會回傳 400 VALIDATION_INVALID_BODY。

設計設定結構

路徑：/api/v2/agents/{agentId}/settings/design

更新設計設定至少須提供一個欄位。

主體欄位	是否必填	類型與限制
`title`	否	字串。
`language`	否	支援的小工具語系字串，或 `null`。像 `en-US`、`pt-BR`、`zh-Hant` 這類地區別名，會正規化為對應的標準小工具語系（`en`、`pt`、`zh-tw`）；不支援的字串會被拒絕，而 `null` 會清除覆寫值，恢復自動語系偵測。
`appearance`	否	`Light` 或 `Dark`。
`primaryColor`	否	字串。
`bubbleColor`	否	字串。
`primaryColorHeader`	否	布林值。
`position`	否	`bottom-left` 或 `bottom-right`。
`showInitialMessageBubble`	否	布林值。
`initialMessages`	否	最多 5 個字串組成的陣列，每個字串經過修剪且最多 140 個字元；或以換行分隔的字串，最多 5 行非空白且經過修剪的內容，每行最多 140 個字元。
`messagePlaceholder`	否	經過修剪的字串，最多 100 個字元。
`bubbleIconUrl`	否	有效的 URL 或 `null`。
`profilePictureUrl`	否	有效的 URL 或 `null`。
`hideBranding`	否	布林值。只有在工作區方案允許移除品牌標識時，才會儲存為 `true`。
`keepShowing`	否	布林值，控制預設提示是否維持顯示。
`prompts`	否	最多 4 個字串組成的陣列，每個字串經過修剪且最多 80 個字元。空白提示會被移除。

取得設計設定

GET /api/v2/agents/{agentId}/settings/design

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

成功：200 OK。回應為裸物件，包含目前的 title、language、position、branding 與 conversation 群組。未設定的選填欄位會被省略。

{
  "title": "AI Assistant",
  "language": "en",
  "position": "bottom-right",
  "branding": {
    "appearance": "Light",
    "bubbleColor": "#e9e9e7",
    "primaryColor": "#0a0a0a",
    "primaryColorHeader": false
  },
  "conversation": {
    "defaultPrompts": {
      "enabled": false,
      "prompts": [],
      "keepShowing": false
    },
    "initialMessages": ["Hey! What can I help with?"],
    "messagePlaceholder": "Ask our chatbot a question...",
    "showInitialMessageBubble": true
  }
}

更新設計設定

PATCH /api/v2/agents/{agentId}/settings/design

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/design' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Support","language":"en-US","appearance":"Dark","prompts":["Track my order"]}'

成功：200 OK。與設計設定的 GET 回應不同，PATCH 會以裸物件回傳完整的設定物件。當有設定值時，它可包含以下頂層欄位與群組：title、language、position、branding、ai、conversation、security、guardrails、notification、training、channels 與 identityVerification。語系別名會以標準形式回傳並儲存。無效或空的主體會回傳 400 VALIDATION_INVALID_BODY。

安全性設定結構

路徑：/api/v2/agents/{agentId}/settings/security

更新安全性設定至少須提供一個頂層欄位。

主體欄位	是否必填	類型與限制
`isPrivate`	否	布林值。
`rateLimit`	否	物件。提供時，以下三個巢狀欄位皆為必填。
`rateLimit.maxMessages`	與 `rateLimit` 一併提供	1 到 100 之間的數字。
`rateLimit.windowSeconds`	與 `rateLimit` 一併提供	10 到 3,600 之間的數字。
`rateLimit.limitMessage`	與 `rateLimit` 一併提供	1 到 500 個字元的字串。
`allowedDomains`	否	物件，須包含必填的 `enabled` 布林值與必填的 `domains` 陣列。
`allowedDomains.domains[]`	與 `allowedDomains` 一併提供	非空的 CSP 風格網域運算式，例如 `https://example.com`、`https://*.example.com`、`example.com`，或帶有選填連接埠／路徑的值。當 `enabled` 為 `true` 時，此陣列至少須包含一個網域。

取得安全性設定

GET /api/v2/agents/{agentId}/settings/security

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

成功：200 OK。安全性物件以裸物件回傳；未設定的安全性設定會產生 {}。

{
  "isPrivate": false,
  "rateLimit": {
    "maxMessages": 20,
    "windowSeconds": 240,
    "limitMessage": "Too many messages in a row"
  },
  "allowedDomains": {
    "enabled": true,
    "domains": ["https://example.com"]
  }
}

更新安全性設定

PATCH /api/v2/agents/{agentId}/settings/security

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/security' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"allowedDomains":{"enabled":true,"domains":["https://example.com"]}}'

成功：200 OK，回傳更新後的裸安全性設定物件。無效或空的主體會回傳 400 VALIDATION_INVALID_BODY。

通知設定結構

路徑：/api/v2/agents/{agentId}/settings/notifications

至少須提供一個欄位。

主體欄位	是否必填	類型與限制
`dailyConversations`	否	布林值。
`dailyEmails`	否	布林值。
`quotaAlerts`	否	布林值。

省略 dailyConversations 時視為 false（停用）；省略 dailyEmails 與 quotaAlerts 時視為 true（已啟用）。GET 回應僅回傳已明確設定的欄位。

取得通知設定

GET /api/v2/agents/{agentId}/settings/notifications

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

成功：200 OK。通知物件以裸物件回傳；未設定的通知設定會產生 {}。

{
  "dailyConversations": true,
  "dailyEmails": true,
  "quotaAlerts": true
}

更新通知設定

PATCH /api/v2/agents/{agentId}/settings/notifications

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/notifications' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"dailyConversations":false}'

成功：200 OK，回傳更新後的裸通知設定物件。無效或空的主體會回傳 400 VALIDATION_INVALID_BODY。

訓練設定結構

路徑：/api/v2/agents/{agentId}/settings/training

主體欄位	是否必填	類型與限制
`autoRetrainEnabled`	是	布林值。

取得訓練設定

GET /api/v2/agents/{agentId}/settings/training

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

成功：200 OK。訓練設定物件以裸物件回傳；未設定的訓練設定會產生 {}。

{
  "autoRetrainEnabled": true
}

更新訓練設定

PATCH /api/v2/agents/{agentId}/settings/training

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/training' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"autoRetrainEnabled":true}'

成功：200 OK，回傳更新後的裸訓練設定物件。在沒有方案存取權限的情況下啟用自動重新訓練，會回傳 403 SUBSCRIPTION_API_RESTRICTED_PLAN；無效的主體會回傳 400 VALIDATION_INVALID_BODY。

API v2 代理程式與設定

建立並管理代理程式，接著讀取或更新其 AI、設計、安全性、通知與訓練設定。

代理程式物件

列出代理程式

建立代理程式

取得代理程式

更新代理程式

刪除代理程式

AI 設定結構

取得 AI 設定

更新 AI 設定

設計設定結構

取得設計設定

更新設計設定

安全性設定結構

取得安全性設定

更新安全性設定

通知設定結構

取得通知設定

更新通知設定

訓練設定結構

取得訓練設定

更新訓練設定

參考文件