创建元数据字段

批量创建元数据字段。不传 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	错误详情。