Image & Video APIs
Menu

Contextual metadata

Last updated: Aug-31-2025

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.

Adding context while uploading

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:

Tip
You can open the asset in your Media Library and check the Metadata tab in the Preview pane to confirm that the upload applied the contextual metadata as expected. For more information, see Managing assets on the Media Library for developers page.

The context method

The 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 caption=New and product=shirt to the images with the public IDs of shirt1 and shirt2:

Monitoring context changes using a notification URL

You can use Cloudinary notifications to 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.

To capture these changes, add a Notification URL triggered by the 'Resource context changed' Notification Type in the Webhook Notifications page of your Console Settings. The notification sent will specify resource_context_changed as the notification_type, and include 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.

AltStyle によって変換されたページ (->オリジナル) /

✔️ Feedback sent!

✖️
How helpful was this doc page?

Thanks for submitting your rating. We got it!
We'd love to hear more. Tell us what you liked and how we can make this page even better:

*

Cloudinary is committed to protecting your information security. For details, see our privacy policy.

For additional assistance, open a support request.

Error

Unfortunately there's been an error sending your feedback.

Rate this page: