Last updated: Nov-08-2023
Contextual metadata is a custom key-value pair that you can assign to individual assets either programmatically or in the Cloudinary Console. Once defined, contextual metadata can be referenced in your application, for example to find assets that meet relevant criteria and for generating transformations based on the value of a particular contextual metadata key, using user-defined variables and/or conditional transformations.
You can assign context to assets while uploading them by specifying the
context parameter in the upload method.
For example, uploading the image
boots.jpg and adding the context key
caption set to a value of
New to the image:
context parameter of an uploaded asset contains a pipe-separated list of key-value pairs of contextual metadata (up to 255 characters). The
context method can be used to manage the contextual metadata of an uploaded asset by setting the value of the
command parameter to either
add a new key-value pair, or
remove_all contextual metadata from the asset. The Cloudinary SDKs wrap the REST API
context method and offer two separate methods: one for adding contextual metadata and one for removing all contextual metadata:
For example, adding the contextual metadata key-pairs
product=shirt to the images with the Public IDs of
You can monitor for changes to the contextual metadata on your media assets, including contextual metadata that has been added or removed via API or the Cloudinary Console UI. These changes are sent as webhook notifications to the Notification URL specified in the Upload page of your Console Settings. To capture these changes, monitor for the response parameter:
resource_context_changed. Within it, you'll find information about which resource was changed, the source of the change (UI or API), and whether contextual metadata was added, removed, or updated. For example:
See the documentation on Notifications for more information.