> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://uploadcare.com/docs/_mcp/server.

# File metadata management

> Add additional custom data associated with the uploaded file.

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.

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

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

## Examples

Using the [File metadata Upload API](https://uploadcare.com/docs/api/upload/upload/base-upload), you can set the metadata
for uploaded files and read the metadata from already uploaded ones. Direct
upload request example:

```bash
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](https://uploadcare.com/docs/api/rest/file-metadata/file-metadata)
(get, update, and delete keys). File metadata is also passed via
[webhooks](/docs/webhooks/#webhook-notifications). REST API request example:

```bash
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](https://app.uploadcare.com/projects/-/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](/docs/file-uploader/options/#metadata)
* [jQuery File Uploader](/docs/uploads/file-uploader-options/#option-metadata)
* [JavaScript](/docs/integrations/javascript/)
* [PHP](/docs/integrations/php/)
* [Python & Django](/docs/integrations/python/)
* [Ruby](/docs/integrations/ruby/)
* [Rails](/docs/integrations/rails/)
* [Swift](/docs/integrations/swift/)