Metadata

Introduction

Metadata is an attribute on File and Media objects that lets you store your own key-value pairs.

For example, you might store the uploader's user_id or username on a file to help you identify who uploaded it.

These values are returned in the file or media response.

{
  "id": "file_abcdefgh1234",
  "object": "file",
  // ... other props
  "metadata": {
    "user_id": "abcd-1234-efgh-5678",
    "username": "@totallyrealperson",
  }
}

Usage

Keys

  • You can add upto 32 keys per object
  • Metadata keys can be up to 32 characters
  • Metadata keys must contain only letters, numbers and underscores
  • Keys must use UTF-8 encoding

Values

  • Metadata values must be 2048 characters or fewer
  • Metadata values must be strings. If you need to use values in your application, you will need to parse them e.g. const episodeNumber = parseInt(metadata.episode)
  • Values must use UTF-8 encoding

Be careful when checking boolean values. Because metadata values are strings, you will need to check for "true" or "false" instead of true or false.

Add Metadata

To add a new key, include it in the metadata object in the request body of a POST or PATCH request.

Update Metadata

To update a key, include it – and the new value – in the metadata object of a PATCH request.

Delete Metadata

To delete a key, include it in the metadata object of a PATCH request with an empty string "" value.

Note that passing null or undefined will not delete the key because the API will interpret these as the string "null" or "undefined".

To delete all metadata, pass an empty object {} with the metadata prop of a PATCH request.

API Reference

Check out the API Reference for information on adding or updating metadata.

API Reference

Intelligence

Previous Page

Storage

Next Page

On this page