Update document metadata

Update metadata values for specified documents. Documents are identified by document ID and metadata fields by field name. Updates are merged incrementally: provided fields are updated, omitted fields remain unchanged, and an empty string clears that field's value. You can update up to 50 documents per request.

Request Method

PUT

Endpoint

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

Authentication

For authentication details, see API Overview.

Request

Request Example

curl -X PUT 'https://api-${endpoint}.gptbots.ai/v1/bot/doc/metadata/update' \ -H 'Authorization: Bearer ${API Key}' \ -H 'Content-Type: application/json' \ -d '{ "documents": [ { "doc_id": "doc_001", "metadata": { "category": "Technical", "priority": "P1" } }, { "doc_id": "doc_002", "metadata": { "category": "Product", "priority": "" } } ] }'

                      
                      curl -X PUT 'https://api-${endpoint}.gptbots.ai/v1/bot/doc/metadata/update' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "documents": [
        {
            "doc_id": "doc_001",
            "metadata": { "category": "Technical", "priority": "P1" }
        },
        {
            "doc_id": "doc_002",
            "metadata": { "category": "Product", "priority": "" }
        }
    ]
}'

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
documents	Array<Object>	Yes	A list of documents to update, up to 50 at a time.
doc_id	String	Yes	Document ID.
metadata	Object	No	"Field name → value". An empty string clears the field value, and omitted fields remain unchanged. Each field name must be defined within the document's applicable scope.

Note: A LIST field accepts only values defined in its options; otherwise, the document item fails with field 'x' contains value not in options. In the same request, the same metadata key under the same doc_id is updated only from its first occurrence; each later document item containing that duplicate key fails with duplicate metadata key 'x' for doc_id 'y'; only the first value is applied. The doc_id must belong to the Agent associated with the current API Key; otherwise, the item fails with doc not found.

Response

Response Example

{ "success_count": 1, "failure_count": 2, "results": [ { "doc_id": "doc_001", "success": true }, { "doc_id": "doc_002", "success": false, "error_message": "field 'priority2' is not defined" }, { "doc_id": "doc_003", "success": false, "error_message": "doc not found" } ] }

                      
                      {
    "success_count": 1,
    "failure_count": 2,
    "results": [
        {
            "doc_id": "doc_001",
            "success": true
        },
        {
            "doc_id": "doc_002",
            "success": false,
            "error_message": "field 'priority2' is not defined"
        },
        {
            "doc_id": "doc_003",
            "success": false,
            "error_message": "doc not found"
        }
    ]
}

This code block in the floating window

Success Response

Field	Type	Description
success_count	Integer	Number of documents successfully updated.
failure_count	Integer	Number of documents that failed to update.
results	Array<Object>	Document-by-document results.
doc_id	String	Document ID.
success	Boolean	Whether the update is successful.
error_message	String	Failure reason, such as `doc not found` (document does not exist or does not belong to the current Agent), `field 'x' is not defined` (field name is not defined), `field 'x' contains value not in options` (LIST value is not an allowed option), or `duplicate metadata key 'x' for doc_id 'y'; only the first value is applied` (duplicate field in the request; the first value is applied).

Error Response

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