Skip to main content
For the complete documentation index for agents and LLMs, see llms.txt.

Add Metadata to Files with the REST API

Attach metadata to your files when you upload them with the REST API, or add and update the metadata of files that are already uploaded.

About This Task​

If you upload files through the API, pass the metadata for each file in a separate dictionary formatted like this: meta={"key1":"value1", "key2":"value2"}. For each file you upload, provide a corresponding metadata dictionary. The order matters: the first dictionary you pass is linked to the first file, the second dictionary to the second file, and so on.

For the allowed metadata format, value types, and limits, see Add Metadata to Your Files.

Prerequisites​

You need an API key. For details, see Generate API Keys.

Add Metadata When You Upload a File​

Use this code to add metadata to a file when you upload it with the REST API. The meta form field holds the metadata for your file:

curl --request POST \
     --url 'https://api.cloud.deepset.ai/api/v1/workspaces/<YOUR_WORKSPACE>/files?write_mode=OVERWRITE' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <YOUR_API_KEY>' \
     --header 'content-type: multipart/form-data' \
     --form file=@<YOUR_FILE.PDF> \
     --form 'meta={"year":"2009", "type":"financial report"}'

Make sure you update the following parameters:

  • In the URL, update <YOUR_WORKSPACE> to your Haystack Platform workspace name.
  • In the authorization header, replace <YOUR_API_KEY> with your Haystack Platform API key.
  • In the form section:
    • Replace <YOUR_FILE.PDF> with the path to your file.
    • Update the metadata.

Update the Metadata of an Uploaded File​

To add or update the metadata of a file that's already uploaded, use the Update File Meta endpoint. You need the ID of the file whose metadata you want to change. You can check it with the List Files endpoint. The --data option holds the metadata:

curl --request PATCH \
     --url https://api.cloud.deepset.ai/api/v1/workspaces/<YOUR_WORKSPACE>/files/<FILE_ID>/meta \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <YOUR_API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
     "year": "2009",
     "type": "financial report"
}
'

To update the metadata of many files at once, use the Update File Meta Bulk endpoint.