建立元資料欄位

批次建立元資料欄位。不傳 knowledge_base_id 時建立全域欄位（對 Agent 下所有文件生效）；傳入時則僅在該知識庫建立。name 與 display_label 均需唯一。

批次規則：
一次最多建立 50 個，超過 50 整批不處理。
請求內重複：僅保留第一筆，其餘標記為失敗。
與現有欄位衝突：衝突項目標記為失敗，其餘項目正常建立。

請求方式

POST

呼叫位址

https://api-${endpoint}.gptbots.ai/v1/bot/doc/metadata/field/create

呼叫驗證

鑒權方式請參閱 API 總覽。

請求

請求範例

curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/bot/doc/metadata/field/create' \ -H 'Authorization: Bearer ${API Key}' \ -H 'Content-Type: application/json' \ -d '{ "knowledge_base_id": "kb_001", "fields": [ { "name": "category", "display_label": "分類", "type": "LIST", "options": ["技術", "產品"], "description": "文件分類", "ai_search_filter": true } ] }'

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/bot/doc/metadata/field/create' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "knowledge_base_id": "kb_001",
    "fields": [
        {
            "name": "category",
            "display_label": "分類",
            "type": "LIST",
            "options": ["技術", "產品"],
            "description": "文件分類",
            "ai_search_filter": true
        }
    ]
}'

此代碼塊在浮窗中顯示

請求標頭

欄位	類型	描述
Authorization	Bearer ${API Key}	使用 `Authorization: Bearer ${API Key}` 進行驗證。請前往 API 金鑰頁面取得 API Key。
Content-Type	application/json	資料型，設定為 `application/json`。

請求參數

欄位	類型	必填	說明
knowledge_base_id	String	否	不傳時建立全域欄位（Agent 下所有文件）；傳入時僅套用至該知識庫。該知識庫必須屬於目前 API Key 對應的 Agent，否則傳回 `knowledge_base_id not found`。
fields	Array<Object>	是	要建立的欄位列表，一次最多 50 個。
name	String	是	欄位內部識別碼。格式為 `^[a-z][a-z0-9_]{0,31}$`（以小寫字母開頭，長度 1-32），且必須唯一。
display_label	String	是	欄位展示名，最長 64 字元，唯一。
type	String	是	欄位類型：STRING / NUMBER / DATETIME / LIST（大小寫敏感）。
options	Array<String>	否	枚舉選項。 type 為 LIST 時必填且非空白。
description	String	否	欄位說明，最長 50 字元。
ai_search_filter	Boolean	否	是否以 AI Search 篩選欄位。

回應

回應範例

{ "success_count": 1, "failure_count": 2, "results": [ { "name": "category", "success": true, "id": "665f1c8a9b2e4d001a3f0001" }, { "name": "priority", "success": false, "error_message": "name or display_label already exists" }, { "name": "category", "success": false, "error_message": "duplicate name in request" } ] }

                      
                      {
    "success_count": 1,
    "failure_count": 2,
    "results": [
        {
            "name": "category",
            "success": true,
            "id": "665f1c8a9b2e4d001a3f0001"
        },
        {
            "name": "priority",
            "success": false,
            "error_message": "name or display_label already exists"
        },
        {
            "name": "category",
            "success": false,
            "error_message": "duplicate name in request"
        }
    ]
}

此代碼塊在浮窗中顯示

成功回應

欄位	類型	說明
success_count	Integer	建立成功的欄位數。
failure_count	Integer	建立失敗的欄位數。
results	Array<Object>	逐欄位結果，依請求順序回傳。
name	String	欄位名稱。
success	Boolean	是否建立成功。
id	String	系統產生的欄位 ID（成功時返回，編輯/刪除時使用）。
error_message	String	失敗原因：name or display_label already exists（name 或 display_label 與已有欄位衝突） / duplicate name in request（請求內重複） / field limit exceeded（超量上限）。

失敗回應

欄位	類型	描述
code	Integer	錯誤碼。
message	String	錯誤詳情。