Create metadata fields

Create metadata fields in batches. Omit knowledge_base_id to create global fields that apply to all documents under the Agent, or provide it to create fields for that knowledge base only. Both name and display_label must be unique.

Batch rules:
You can create up to 50 fields per request. If the request exceeds this limit, the entire batch is rejected.
Duplicates within the request: only the first item is retained; subsequent duplicates are marked as failed.
Conflicts with existing fields: conflicting items fail while the remaining items are created normally.

Request Method

POST

Endpoint

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

Authentication

For authentication details, see API Overview.

Request

Request Example

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": "Category", "type": "LIST", "options": ["Technical", "Product"], "description": "Document category", "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": "Category",
            "type": "LIST",
            "options": ["Technical", "Product"],
            "description": "Document category",
            "ai_search_filter": true
        }
    ]
}'

This code block in the floating window

Request Headers

Field	Type	Description
Authorization	Bearer ${API Key}	Authenticate with `Authorization: Bearer ${API Key}`. Obtain the API Key from the API Keys page.
Content-Type	application/json	Data type, set to `application/json`.

Request Parameters

Field	Type	Required	Description
knowledge_base_id	String	No	Omit for global fields that apply to all documents under the Agent; provide it for fields that apply only to this knowledge base. The knowledge base must belong to the Agent associated with the current API Key; otherwise, the request fails with `knowledge_base_id not found`.
fields	Array<Object>	Yes	A list of fields to create, up to 50 at a time.
name	String	Yes	Internal field identifier. Format `^[a-z][a-z0-9_]{0,31}$` (starts with a lowercase letter, 1-32 characters), unique.
display_label	String	Yes	Field display name, up to 64 characters, unique.
type	String	Yes	Field type: STRING / NUMBER / DATETIME / LIST (case sensitive).
options	Array<String>	No	Enumeration options. Required and non-empty when `type` is `LIST`.
description	String	No	Field description, up to 50 characters.
ai_search_filter	Boolean	No	Whether to use as AI Search filter field.

Response

Response Example

{ "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"
        }
    ]
}

This code block in the floating window

Success Response

Field	Type	Description
success_count	Integer	Number of successfully created fields.
failure_count	Integer	Number of fields that failed to be created.
results	Array<Object>	Field-by-field results, returned in request order.
name	String	Field name.
success	Boolean	Whether it was created successfully.
id	String	System-generated field ID (returned on success, used when editing/deleting).
error_message	String	Reason for failure: name or display_label already exists (name or display_label conflicts with existing fields) / duplicate name in request (duplicate within the request) / field limit exceeded (exceeds the upper limit of the total number of fields).

Error Response

Field	Type	Description
code	Integer	Error code.
message	String	Error details.