API v2 來源與訓練

列出並建立代理程式來源、將檔案直接上傳到儲存空間、刪除文件、查看訓練狀態，並啟動已索引網頁來源的重新訓練。

使用以下端點管理文字、問答（Q&A）、URL 與檔案來源，並重新訓練已索引的網頁來源。本頁的每個端點都需要 Authorization: Bearer YOUR_API_KEY，以及對 {agentId} 的存取權限。

共用的驗證、驗證、配額與資源錯誤，請見錯誤目錄。

來源物件

欄位	類型	備註
`id`	string	文件 ID。
`title`	string	來源標題。
`sourceType`	string	已儲存的來源類型，包括 `web_crawl`、`file_upload`、`text_snippet` 或 `qna_entry`。
`createdAt`	integer 或 null	Unix 時間戳記（秒）。
`lastCrawledAt`	integer 或 null	Unix 時間戳記（秒）。
`sourceMetadata`	任意 JSON 值	已儲存的來源中繼資料。

列出來源

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

GET /api/v2/agents/{agentId}/sources

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

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

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources?sourceType=text_snippet&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

成功：200 OK

{
  "data": [
    {
      "id": "41b4c1d3-887d-46a5-95ae-c761922c6bc7",
      "title": "Refund policy",
      "sourceType": "text_snippet",
      "createdAt": 1784332800,
      "lastCrawledAt": null,
      "sourceMetadata": null
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

無效的 limit、cursor 或來源類型都會回傳 400 VALIDATION_INVALID_BODY。

新增文字來源

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

POST /api/v2/agents/{agentId}/sources/text

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

主體欄位	是否必填	類型與限制
`title`	是	修剪前為 1 到 200 個字元的字串；接受的值會經過修剪。
`content`	是	非空字串，不超過 262,144 個 UTF-8 位元組（256 KB），且不能全為空白字元。

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/text' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Refund policy","content":"Refunds are available within 30 days."}'

成功：201 Created

{
  "documentId": "41b4c1d3-887d-46a5-95ae-c761922c6bc7"
}

無效的輸入，或非儲存空間相關的處理失敗，會回傳 400 VALIDATION_INVALID_BODY。處理過程中的儲存空間上限失敗會回傳 403 QUOTA_STORAGE_LIMIT。

新增問答（Q&A）來源

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

POST /api/v2/agents/{agentId}/sources/qna

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

主體欄位	是否必填	類型與限制
`title`	是	修剪前為 1 到 200 個字元的字串；接受的值會經過修剪。
`questions`	是	最多 10 個字串組成的陣列，每個字串最多 500 個字元。至少須有一個項目包含非空白字元。
`answer`	是	非空字串，不超過 262,144 個 UTF-8 位元組（256 KB），且不能全為空白字元。

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/qna' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Shipping time","questions":["How long does shipping take?","When will my order arrive?"],"answer":"Standard shipping takes 3–5 business days."}'

成功：201 Created

{
  "documentId": "531a3fbe-40c2-4d22-a524-1f4a70f509f1"
}

無效的輸入，或非儲存空間相關的處理失敗，會回傳 400 VALIDATION_INVALID_BODY。處理過程中的儲存空間上限失敗會回傳 403 QUOTA_STORAGE_LIMIT。

新增或重新訓練 URL 來源

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

POST /api/v2/agents/{agentId}/sources/url

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

主體欄位	是否必填	類型與限制
`url`	是	帶有網域的非空 HTTP 或 HTTPS URL。缺少通訊協定時會正規化為 `https://`。迴路位址、私有位址、連結本地位址、唯一本地位址、保留 IP 範圍、localhost 變體、內部 TLD 與單一標籤主機名稱都會被拒絕。

提交一個該代理程式已索引的 URL，會建立一項重新訓練工作。新的 URL 會先檢查儲存空間容量。影片 URL 還需要具備影片轉錄的方案存取權限。

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/url' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://docs.example.com/getting-started"}'

成功：202 Accepted

{
  "jobId": "c3c61f67-70fe-42da-a843-24112ded8aeb",
  "isRetrain": false
}

無效的輸入會回傳 400 VALIDATION_INVALID_BODY。缺少影片轉錄存取權限會回傳 403 SUBSCRIPTION_API_RESTRICTED_PLAN；儲存空間或佇列配額失敗會回傳 403 QUOTA_STORAGE_LIMIT；非配額原因造成的工作建立失敗會回傳 500 INTERNAL_SERVER_ERROR。

以簽署上傳網址新增檔案來源

檔案來源採用兩步驟的 API 流程，讓檔案位元組直接從你的用戶端傳送到私有儲存空間，而不經過 API 路由。每個檔案最大為 50 MB，單一請求最多可包含 20 個檔案。支援的副檔名為 .pdf、.txt、.md、.docx、.xlsx 與 .pptx。

1. 建立簽署上傳網址

路徑：/api/v2/agents/{agentId}/sources/file/upload-url

POST /api/v2/agents/{agentId}/sources/file/upload-url

傳送原始檔案名稱：

{
  "files": [
    { "fileName": "product-guide.pdf" },
    { "fileName": "faq.md" }
  ]
}

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/file/upload-url' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"files":[{"fileName":"product-guide.pdf"},{"fileName":"faq.md"}]}'

成功：200 OK

{
  "files": [
    {
      "fileName": "product-guide.pdf",
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/V1StGXR8_Z5jdHi6-product-guide.pdf",
      "uploadUrl": "https://storage.example.com/storage/v1/object/upload/sign/training_files/chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/V1StGXR8_Z5jdHi6-product-guide.pdf?token=SIGNED_TOKEN",
      "token": "SIGNED_TOKEN"
    },
    {
      "fileName": "faq.md",
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/N5jFt4Z9kSC3vHqA-faq.md",
      "uploadUrl": "https://storage.example.com/storage/v1/object/upload/sign/training_files/chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/N5jFt4Z9kSC3vHqA-faq.md?token=SIGNED_TOKEN",
      "token": "SIGNED_TOKEN"
    }
  ]
}

2. 上傳檔案位元組

以 PUT 方式，將每個檔案直接上傳到其 uploadUrl：

await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': file.type },
  body: file,
});

若使用 Supabase JavaScript 用戶端，請帶入步驟 1 取得的對應路徑與權杖：

await supabase.storage
  .from('training_files')
  .uploadToSignedUrl(storagePath, token, file);

請勿自行變更或建構儲存路徑。註冊時只會接受步驟 1 為此代理程式回傳的路徑。

3. 註冊已上傳的檔案

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

POST /api/v2/agents/{agentId}/sources/file

每次直接上傳完成後，請連同其原始檔案名稱一起註冊回傳的路徑：

{
  "files": [
    {
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/V1StGXR8_Z5jdHi6-product-guide.pdf",
      "fileName": "product-guide.pdf"
    },
    {
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/N5jFt4Z9kSC3vHqA-faq.md",
      "fileName": "faq.md"
    }
  ]
}

成功：202 Accepted

{
  "jobId": 321,
  "fileCount": 2
}

在開始處理工作前，註冊程序會驗證每個物件存在、非空、不超過 50 MB，且屬於所請求的代理程式。無效或缺少的上傳項目會回傳 400 VALIDATION_INVALID_BODY；儲存空間配額拒絕會回傳 403 QUOTA_STORAGE_LIMIT；儲存空間或佇列失敗會回傳 500 INTERNAL_SERVER_ERROR。

刪除來源

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

DELETE /api/v2/agents/{agentId}/sources/{documentId}

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

{documentId} 必須是由來源建立或列表回應所回傳的 UUID。

curl -X DELETE 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/41b4c1d3-887d-46a5-95ae-c761922c6bc7' \
  -H 'Authorization: Bearer YOUR_API_KEY'

成功：200 OK

{
  "deleted": true
}

無效的 UUID 會回傳 400 VALIDATION_INVALID_BODY。有效但不屬於該代理程式任何文件的 UUID，會回傳 404 RESOURCE_DOCUMENT_NOT_FOUND。

取得訓練狀態

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

GET /api/v2/agents/{agentId}/train

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

成功：200 OK，回傳裸的狀態物件。

欄位	類型	備註
`status`	string	存在待處理／執行中的工作時為 `training`；否則若存在最後訓練時間戳記則為 `trained`；否則為 `idle`。
`documentCount`	integer	該代理程式的來源文件數量。
`lastTrainedAt`	integer 或 null	Unix 時間戳記（秒）。
`activeJob`	object 或 null	最近一筆待處理／執行中的工作。
`activeJob.id`	string	工作 ID。
`activeJob.status`	string	已儲存的工作狀態。
`activeJob.tasksCount`	integer	任務總數。
`activeJob.tasksCompletedCount`	integer	已完成的任務數。
`activeJob.createdAt`	integer 或 null	Unix 時間戳記（秒）。

{
  "status": "training",
  "documentCount": 12,
  "lastTrainedAt": 1784246400,
  "activeJob": {
    "id": "c3c61f67-70fe-42da-a843-24112ded8aeb",
    "status": "running",
    "tasksCount": 8,
    "tasksCompletedCount": 3,
    "createdAt": 1784332800
  }
}

啟動網頁來源重新訓練

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

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。此端點不需要請求主體。

此端點會重新訓練已索引的網頁 URL，不包含文字、問答（Q&A）或已上傳的檔案來源。

當至少存在一個已索引的 URL 時，成功回應為 202 Accepted：

{
  "jobId": "c3c61f67-70fe-42da-a843-24112ded8aeb",
  "count": 8,
  "message": "Retraining started for 8 URLs"
}

當沒有已索引的 URL 時，成功回應為 200 OK，且不會建立任何工作：

{
  "jobId": null,
  "count": 0,
  "message": "No web sources to retrain"
}

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

API v2 來源與訓練

列出並建立代理程式來源、將檔案直接上傳到儲存空間、刪除文件、查看訓練狀態，並啟動已索引網頁來源的重新訓練。

來源物件

列出來源

新增文字來源

新增問答（Q&A）來源

新增或重新訓練 URL 來源

以簽署上傳網址新增檔案來源

1. 建立簽署上傳網址

2. 上傳檔案位元組

3. 註冊已上傳的檔案

刪除來源

取得訓練狀態

啟動網頁來源重新訓練

參考文件