File metadata management

Add additional, arbitrary data associated with uploaded files. For example, you could store user IDs, order IDs, or tags.

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.

1
{
2
  "userId": "1",
3
  "type": "avatar"
4
}

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

Examples

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

$
curl -L 'https://upload.uploadcare.com/base/' \
>
     -F "UPLOADCARE_PUB_KEY=$YOUR_PUBLIC_KEY" \
>
     -F "file=@user-avatar.jpeg" \
>
     -F "metadata[userId]=1" \
>
     -F "metadata[type]=avatar"

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

$
curl -L -X PUT 'https://api.uploadcare.com/files/$UUID/metadata/userId/' \
>
     -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"'

Get $YOUR_PUBLIC_KEY and $YOUR_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

• File Uploader
• jQuery File Uploader
• JavaScript
• PHP
• Python & Django
• Ruby
• Rails
• Swift