Modify documents metadata through API

[nicologiammaria]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

1. Is this request related to a challenge you're experiencing? Tell me about your story.

I created a custom "uuid" metadata field in my knowledge base, to have personalized filtering based on who is using the chatbot linked to this knowledge base.
I just tested it updating manually the uuid metadata field from the UI and it works fine.
I need now to automate this process to generalize it for all my customer base.
I would like to update the metadata field of each document in the knowledge base with a python script through the knowledge base API, but so far, I did not find a way to make it work.
Is there an endpoint to make it happen? Could you give me some directives?

2. Additional context or comments

No response

[dosubot[bot]]

You can update document metadata (including custom fields like "uuid") in Dify using the API endpoint:

PUT /datasets/<uuid:dataset_id>/documents/<uuid:document_id>/metadata

Your request should include a JSON payload with two fields: doc_type (string) and doc_metadata (dictionary). You must have dataset editor permissions (admin, owner, dataset_operator, or editor role) to use this endpoint. The metadata you send will fully replace the existing metadata for the document, so always include all fields you want to keep, not just the ones you want to change. For bulk updates, you’ll need to loop through your documents and send individual requests for each one—there’s no batch update endpoint yet.

Example Python snippet using requests:

import requests

url = "https://your-dify-instance/api/datasets/{dataset_id}/documents/{document_id}/metadata"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "doc_type": "others",  # or your specific type
    "doc_metadata": {
        "uuid": "your-uuid-value",
        # ...other metadata fields
    }
}

response = requests.put(url, json=payload, headers=headers)
print(response.json())

If you need to update many documents, fetch each document’s current metadata, merge your changes, and send the full metadata in each update request. More details on the endpoint and its behavior are in the API implementation and community discussions.

If you’ve defined your custom metadata fields at the dataset level, this approach will work for your "uuid" field. If you haven’t, make sure to do so first—otherwise, only built-in fields will be updated or shown (discussion).

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[nicologiammaria]

@dosu Is the "datasets/{dataset_id}/documents/{document_id}/metadata" endpoint sill available in dify version 1.9.1 self-hosted?
I can't find any documentation about that and my python request returns a 404 error

[dosubot[bot]]

The endpoint /datasets/{dataset_id}/documents/{document_id}/metadata is not available in Dify version 1.9.1 self-hosted, which is why you’re seeing a 404 error and can’t find documentation for it. This endpoint was introduced in later releases after 1.9.1 see details.

In v1.9.1, document metadata updates are likely handled via a PATCH request to /datasets/{dataset_id}/documents/{document_id} instead. You’ll need to send the updated metadata as part of the payload to that endpoint. If you need help with the exact payload structure for your version, let me know and I can dig into the specifics.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[nicologiammaria]

Apparently in the new v1.9.1 documentation, the endpoint to update metadata is not mentioned.
Still, I was able to use the endpoint mentioned in previous versions API docs, even using dify v1.9.1.
Below the python code, hope it helps:

import requests

dataset_id = "yourdatasetid"
document_id = "yourdocumentid"
uuid_metadata_id = "yourmetadataid"
dns = "yourdns"

url = f"https://{dns}/v1/datasets/{dataset_id}/documents/metadata"

payload = {
    "operation_data": [
        {
            "document_id": document_id, 
            "metadata_list": [
                {
                    "id": uuid_metadata_id,
                    "value": "mynewbeatuifulvalue", 
                    "name": "uuid"
                }
            ]
        }
    ]
}

try:
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()
    print("Metadata updated successfully:", response.json())
except requests.exceptions.RequestException as e:
    print("Error updating metadata:", e)