Update Document Metadata in Batch
Update metadata values for multiple documents in a single request.
1 min read
post/datasets/{dataset_id}/documents/metadata
Request example
curl --request POST \
--url https://api.dify.ai/v1/datasets/{dataset_id}/documents/metadata \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"operation_data": [
{
"document_id": "<string>",
"metadata_list": [
{
"id": "<string>",
"name": "<string>",
"value": null
}
],
"partial_update": false
}
]
}'import requests
url = "https://api.dify.ai/v1/datasets/{dataset_id}/documents/metadata"
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
}
payload = {
"operation_data": [
{
"document_id": "<string>",
"metadata_list": [
{
"id": "<string>",
"name": "<string>",
"value": None
}
],
"partial_update": False
}
]
}
response = requests.request("POST", url, headers=headers, json=payload)
print(response.text)const response = await fetch('https://api.dify.ai/v1/datasets/{dataset_id}/documents/metadata', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"operation_data": [
{
"document_id": "<string>",
"metadata_list": [
{
"id": "<string>",
"name": "<string>",
"value": null
}
],
"partial_update": false
}
]
})
});
const data = await response.json();
console.log(data);<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/metadata',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => '{
"operation_data": [
{
"document_id": "<string>",
"metadata_list": [
{
"id": "<string>",
"name": "<string>",
"value": null
}
],
"partial_update": false
}
]
}',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer <token>',
'Content-Type: application/json',
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
url := "https://api.dify.ai/v1/datasets/{dataset_id}/documents/metadata"
payload := strings.NewReader("{\n \"operation_data\": [\n {\n \"document_id\": \"<string>\",\n \"metadata_list\": [\n {\n \"id\": \"<string>\",\n \"name\": \"<string>\",\n \"value\": null\n }\n ],\n \"partial_update\": false\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.dify.ai/v1/datasets/{dataset_id}/documents/metadata"))
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString("{\n \"operation_data\": [\n {\n \"document_id\": \"<string>\",\n \"metadata_list\": [\n {\n \"id\": \"<string>\",\n \"name\": \"<string>\",\n \"value\": null\n }\n ],\n \"partial_update\": false\n }\n ]\n}"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'uri'
require 'net/http'
url = URI('https://api.dify.ai/v1/datasets/{dataset_id}/documents/metadata')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'
request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = '{
"operation_data": [
{
"document_id": "<string>",
"metadata_list": [
{
"id": "<string>",
"name": "<string>",
"value": null
}
],
"partial_update": false
}
]
}'
response = http.request(request)
puts response.read_bodyResponse
{
"result": "success"
}{
"code": "invalid_param",
"message": "Another document metadata operation is running, please wait a moment.",
"status": 400
}{
"code": "forbidden",
"message": "Dataset api access is not enabled.",
"status": 403
}{
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription.",
"status": 403
}{
"code": "forbidden",
"message": "The API key is not authorized to access this knowledge base.",
"status": 403
}{
"code": "not_found",
"message": "Dataset not found.",
"status": 404
}{
"code": "not_found",
"message": "Document not found.",
"status": 404
}{
"code": "not_found",
"message": "Metadata not found.",
"status": 404
}post/datasets/{dataset_id}/documents/metadata
Authorization
Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).
Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).
Path parameters
Knowledge base ID, from List Knowledge Bases. For a scoped key, copy the ID from the Dify URL.
Body
application/jsonDocument metadata update operations, one entry per document.
Show child attributesHide child attributes
ID of the document to update. See List Documents.
Metadata fields to set on the document.
Show child attributesHide child attributes
Metadata field ID. See List Metadata Fields.
Metadata field name.
Metadata value. Can be a string, number, or
null.Whether to partially update metadata, keeping existing values for unspecified fields.
Default: false
Responses
application/json
Document metadata updated successfully.
Operation result.