Back to changelog

Metadata per File in One Upload

One upload request can now give each file its own metadata.

Before, custom_metadata on Index File applied to every file in the request. The only way to tag files differently was to send them one request at a time. Now the same request also takes file_metadata, a list with one entry per file, in the order the files are sent.

files:          invoice.pdf           contract.pdf           invoice.pdf
file_metadata:  [{"type": "invoice"}, {"type": "contract"}, {"type": "invoice", "year": 2025}]

How the two fields combine. custom_metadata still applies to every file. Each file's own entry is added on top, and wins where both set the same key. Use {} or null for a file that needs nothing extra.

Paired by position, not by name. The first entry belongs to the first file, the second to the second. Two files in one request can share a filename and still get different metadata.

Search and listings. A file's metadata is stored on the document and on its chunks. A search with filter: {"type": "invoice"} returns only the files tagged invoice.

When the list does not match the files. A list with more or fewer entries than files, a value that is not a list, or an entry that is not an object returns a 400 that says what was expected and what was sent. Nothing is uploaded.

Do I need to change anything?

  • If you do not send file_metadata: no. Requests behave as before.
  • If you upload one file per request only to tag files differently: send up to 20 files in one request with file_metadata. One job replaces twenty.
  • Keep a key's type the same across files. A key can be filtered on with one type only, so do not send "year": 2025 for one file and "year": "2025" for another.
  • Limits: each entry follows the custom_metadata rules. The list as a whole is limited to 64 KB, and so is each file's combined metadata.

Same day: Uploaded Files Keep Their Names, Word Files Return Plain Text