Metadata

File metadata is additional, arbitrary data associated with uploaded files. For example, you could store a unique file identifier from your system.

Metadata is key-value data. You can specify up to 50 keys, with key names up to 64 characters long and values up to 512 characters long.

{
  "userId": "1",
  "type": "avatar"
}json

Note: don't store any sensitive information (bank account numbers, card details, etc.) as metadata.

Examples

Using the Upload API, you can set the metadata for uploaded files and read the metadata from already uploaded ones. Direct upload request example:

curl -F "UPLOADCARE_PUB_KEY=YOUR_PUBLIC_KEY" \
     -F "-avatar.jpeg" \
     -F "metadata[userId]=1" \
     -F "metadata[type]=avatar" \
     "https://upload.uploadcare.com/base/"bash

You can modify the metadata through the REST API (get, update, and delete keys). File metadata is also passed via webhooks. REST API request example:

curl -X PUT \
     -H "Content-Type: application/json" \
     -H "Accept: application/vnd.uploadcare-v0.7+json" \
     -H "Authorization: Uploadcare.Simple YOUR_PUBLIC_KEY:YOUR_SECRET_KEY" \
     -d '"2"' \
     "https://api.uploadcare.com/files/:uuid/metadata/userId/"bash

(Take your public and secret key from API keys).

Limitations

File metadata is provided by the end-users uploading the files and can contain symbols unsafe in, for example, HTML context. Please escape the metadata before use according to the rules of the target runtime context (HTML browser, SQL query parameter, etc.). List of allowed characters for the key:

  • Latin letters in lower or upper case (a-z,A-Z)
  • digits (0-9)
  • underscore _
  • a hyphen -
  • dot .
  • colon :

If there are keys in the metadata with characters not included in this list, then they will be ignored.

Integrations