Image & Video APIs
Menu

Conditional metadata rules

Last updated: Aug-31-2025

Important
This feature is available only to Cloudinary customers on an Enterprise plan.

Overview

Conditional metadata rules allow you to set up dependencies and hierarchical relationships between structured metadata fields and field options. This allows you to:

  • Enable/disable (show/hide) another metadata field based on the value selected for a metadata field.
  • Activate options displayed for a particular metadata field based on the value specified in another field.
  • Set the default metadata value in a particular field based on the value specified in another field.

Some popular use cases for conditional metadata include:

  • High-level file type selection, for example: setting metadata fields on different types of content such as image, video and document.
  • Support segmenting into categories, for example: product imagery vs lifestyle photography.
  • Document asset usage rights, for example: stock imagery.
  • Support large organizations with multiple metadata schemas.

For example, one of the metadata fields can include various category values for photos on a company intranet site, such as 'Employee', 'Conference', and 'Culture'. You could set up rules based on these values as follows:

  1. Selecting 'Employee' in the Category metadata field enables (displays) the Team metadata field with values such as 'R&D', 'Product' or 'HR'.
  2. Selecting 'R&D' for the Team metadata field enables the Role metadata field with values such as 'QA', 'Devops' or 'Backend'.
  3. Selecting 'QA' for the Role metadata field enables the Name metadata field with the members of the QA team: 'John Smith' or 'Jane Kelly'. If Devops had been selected for the Role metadata field, then the Name field would be enabled with members of the Devops team: 'Paul Green' or 'Mary Rose'.

Metadata rules endpoint

The Metadata rules API endpoint is accessed using HTTPS. By default, the API endpoint uses the following format:

https://api.cloudinary.com/v1_1/:cloud_name/metadata_rules

For example, to list all Metadata rules in the 'demo' product environment:

The API uses Basic Authentication over secure HTTP. Your Cloudinary API Key and API Secret (which can be found on the API Keys page of your Cloudinary Console Settings) are used for the authentication.

You can experiment with returning a list of the metadata rules in your own Cloudinary product environment by replacing the API_KEY, API_SECRET, and CLOUD_NAME in the cURL command below:

For most actions, request parameters are passed as JSON objects. The response is in a JSON snippet and includes information about the action that was performed.

Metadata rules methods

The Metadata rules methods enable you to manage the metadata rules available for your product environment.

The table below provides a quick summary of the methods available for the Admin API metadata_rules endpoint. See the Admin API documentation for detailed information on the following Metadata rules methods, as well as detailed information on the Metadata rule structure.

Method Description
GET/metadata_rules Returns an index of all metadata rules.
POST/metadata_rules Creates a new metadata rule definition.
PUT/metadata_rules/:external_id Updates an existing metadata rule definition.
DELETE/metadata_rules/:external_id Deletes a metadata rule by external ID.

Metadata rule structure

Each metadata rule connects a specified metadata field with a condition to evaluate on a metadata payload (based on other fields' values), and then with a result to apply to the specified metadata field in the case that the condition is met.

Metadata rule = Metadata field + condition + result

Condition structure

The condition that must be met in order to activate the result. Each of the conditions must include the metadata_field_id (external_id of a metadata field) to evaluate, and the specific criteria to evaluate.

Note
For details on all the parameters, see the Condition structure reference.

For example:

Result structure

The result options are applied to the metadata field when the condition is met. The syntax is specified as follows:

Note
For details on all the parameters, see the Result structure reference.

For example:

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: