Cloudinary Logo Docs Documentation
  • Get Started
    • Programmable Media
      • Developer get started guide
      • Service overview
      • Try it! Explorers and demos
      • Using Cloudinary Postman collections
      • How are transformations counted?
      • Glossary
      • Release notes
    • Digital Asset Management
      • DAM get started guide
      • Release notes
    • Video tutorial library
      • Programmatic asset management
      • Transformations and optimizations
      • Digital Asset Management (DAM)
      • Administration
      • Platform integrations
  • Guides
    • Media upload
      • Overview
      • Uploading assets
      • Transformations on upload
      • Analysis on upload
      • Upload presets
      • Upload API reference
    • Image transformations
      • Image transformations overview
      • Resizing and cropping
      • Placing layers on images
      • Effects and enhancements
      • Face-detection based transformations
      • Animated images
      • Transformations on 3D models
      • Conditional transformations
      • User-defined variables and arithmetic transformations
      • Custom functions
      • Image collage generation
    • Video transformations
      • Video transformations overview
      • Resizing and cropping
      • Trimming and concatenating
      • Placing layers on videos
      • Effects and enhancements
      • Adaptive bitrate streaming
      • Converting videos to animated images
      • Audio transformations
      • Conditional transformations
      • User-defined variables and arithmetic transformations
      • Live streaming
      • Video slideshow generation
      • Video generation
    • Media delivery
      • Media optimization
      • Responsive images
      • Deliver remote media files
      • Social media profile pictures
      • Paged and layered media
      • Media access methods
      • Sprite generation
      • Advanced URL delivery options
    • Asset administration
      • Overview
      • Managing assets
      • Backups and version management
      • Account usage data
      • Webhook notifications
      • Signatures
    • Widgets and players
      • Upload Widget
      • Media Library Widget
      • Media Editor
      • Product Gallery
      • Video Player
    • Add-ons
      • Advanced Facial Attributes Detection
      • Amazon Rekognition AI Moderation
      • Amazon Rekognition Video Moderation
      • Amazon Rekognition Auto Tagging
      • Amazon Rekognition Celebrity Detection
      • Aspose Document Conversion
      • Cloudinary AI Background Removal
      • Cloudinary AI Content Analysis
      • Cloudinary Duplicate Image Detection
      • Google AI Video Moderation
      • Google AI Video Transcription
      • Google Auto Tagging
      • Google Automatic Video Tagging
      • Google Translation
      • Imagga Auto Tagging
      • Imagga Crop and Scale
      • JPEGmini Image Optimization
      • Perception Point Malware Detection
      • Microsoft Azure Video Indexer
      • Neural Artwork Style Transfer
      • OCR Text Detection and Extraction
      • Pixelz - Remove the Background
      • URL2PNG Website Screenshots
      • VIESUS™ Automatic Image Enhancement
      • WebPurify Image Moderation
    • Digital Asset Management
      • DAM overview
      • DAM user guide
      • DAM administrator guide
    • Media Optimizer
      • Overview
      • Quick starts
      • Configuration
      • Dashboard
      • Reports
      • Transformations
    • Platform integrations
      • Adobe Creative Cloud Connector
      • Akeneo PIM Integration
      • Chrome Media Library Extension
      • Magento Extension
      • Salesforce Commerce Cloud Cartridges
      • Salesforce Marketing Cloud App
      • SAP Commerce Extension
      • Shopify App
      • WordPress Plugin
      • Zapier Integration
      • Partner-built integrations
      • How to build your own integration
    • Pre-releases and labs
      • MediaFlows (Private Beta)
      • AR/3D Viewer and 3D Model Configurator
      • Media Inspector browser extension
  • References
    • Transformation URL API
    • Upload API
    • Admin API
    • Search API
    • Structured metadata
      • Metadata API
      • Conditional metadata rules API
    • Provisioning API
    • Cloudinary CLI
    • Postman collections
    • Upload Widget API
    • Video Player API
    • Product Gallery API
    • Media Editor API
    • Media Optimizer
      • Media Optimizer API
      • Transformation reference
  • SDKs
    • Backend SDKs
      • Ruby/Rails SDK
      • PHP SDK
      • Python SDK
      • Node.js SDK
      • Java SDK
      • .NET SDK
      • Go SDK
      • Dart SDK
      • PHP SDK (Legacy)
    • Frontend SDKs
      • JavaScript SDK
      • Angular SDK
      • React SDK
      • Vue.js SDK
      • jQuery SDK
      • JavaScript SDK (Legacy)
      • Angular SDK (Legacy)
      • React SDK (Legacy)
      • Vue.js SDK (Legacy)
    • Mobile SDKs
      • iOS SDK
      • Android SDK
      • Flutter SDK
      • Kotlin SDK
    • Community-developed libraries
      • Gatsby
      • Gridsome
      • Laravel
      • Netlify
      • Next.js
      • NuxtJS
      • Storefront UI
BlogTrainingSupportPricingCommunityMediaJamsPodcastsDemosRoadmapCookbookAdditional Resources
  • Blog
  • Training
  • Support
  • Pricing
  • Community
  • MediaJams
  • Podcasts
  • Demos
  • Roadmap
  • Cookbook
  • Additional Resources
Login
sign up for free
  • Get Started
    • Programmable Media
      • Developer get started guide
      • Service overview
      • Try it! Explorers and demos
      • Using Cloudinary Postman collections
      • How are transformations counted?
      • Glossary
      • Release notes
    • Digital Asset Management
      • DAM get started guide
      • Release notes
    • Video tutorial library
      • Programmatic asset management
        • Upload programmatically
        • Create upload presets
        • Auto-tag assets
        • Diagnosing error codes
        • Upload assets in a React app
        • Deliver images with the Next.js Image component
        • Generate upload signature
        • Postman collections introduction
        • Find your credentials
        • Configure the Node.js SDK
        • Get started with the CLI
        • Scripting with the CLI
        • Get creative with the CLI
        • Upload with the CLI
        • Upload Widget
        • Product Gallery
        • Product Gallery accessibility
      • Transformations and optimizations
        • Transformation basics
        • Optimization tips
        • Gravity-based crops for images
        • Convert videos to animated images
        • Text overlay transformations
        • Complex transformations
        • Named transformations
        • Advanced image components
        • Zoompan effect
        • Social media image cards in Next.js
      • Digital Asset Management (DAM)
        • Folder sharing
        • Collection management
        • Collection sharing
        • Transformation presets
        • Media Library upload
        • Video management intro
        • Advanced Search
      • Administration
        • Enable automatic backups
        • Restore asset versions
        • Restore deleted assets
      • Platform integrations
        • Adobe CC Connector overview
        • SAP Commerce Extension overview
        • SFCC site cartridge intro
        • SFCC site cartridge installation
        • SFCC site cartridge modes
        • SFCC site cartridge videos
        • SFCC Page Designer cartridge
        • SFMC app - image block
        • SFMC app - video to GIF block
        • Shopify app
  • Guides
    • Media upload
      • Overview
      • Uploading assets
      • Transformations on upload
      • Analysis on upload
      • Upload presets
      • Upload API reference
    • Image transformations
      • Image transformations overview
      • Resizing and cropping
      • Placing layers on images
      • Effects and enhancements
      • Face-detection based transformations
      • Animated images
      • Transformations on 3D models
      • Conditional transformations
      • User-defined variables and arithmetic transformations
      • Custom functions
      • Image collage generation
    • Video transformations
      • Video transformations overview
      • Resizing and cropping
      • Trimming and concatenating
      • Placing layers on videos
      • Effects and enhancements
      • Adaptive bitrate streaming
      • Converting videos to animated images
      • Audio transformations
      • Conditional transformations
      • User-defined variables and arithmetic transformations
      • Live streaming
        • Live streaming WebRTC (Beta)
        • Live streaming RTMP
        • Simulated live streaming
      • Video slideshow generation
      • Video generation
    • Media delivery
      • Media optimization
        • Optimize images
        • Optimize videos
        • Optimize audio files
      • Responsive images
        • Using HTML and dynamic image transformations
        • Using JavaScript frontend frameworks
        • Using the cloudinary-core JS library
        • Using client hints
      • Deliver remote media files
      • Social media profile pictures
      • Paged and layered media
      • Media access methods
      • Sprite generation
      • Advanced URL delivery options
    • Asset administration
      • Overview
      • Managing assets
      • Backups and version management
      • Account usage data
      • Webhook notifications
      • Signatures
    • Widgets and players
      • Upload Widget
      • Media Library Widget
      • Media Editor
      • Product Gallery
      • Video Player
        • Video Player features
        • Installation and setup
        • How to embed the Video Player
        • Video Player customization
        • Playlists and recommendations
        • HLS and MPEG-DASH
        • Events and analytics
        • Video ads and monetization
        • Shoppable Video
        • Interactive Video (Beta)
        • Video Player API reference
    • Add-ons
      • Advanced Facial Attributes Detection
      • Amazon Rekognition AI Moderation
      • Amazon Rekognition Video Moderation
      • Amazon Rekognition Auto Tagging
      • Amazon Rekognition Celebrity Detection
      • Aspose Document Conversion
      • Cloudinary AI Background Removal
      • Cloudinary AI Content Analysis
      • Cloudinary Duplicate Image Detection
      • Google AI Video Moderation
      • Google AI Video Transcription
      • Google Auto Tagging
      • Google Automatic Video Tagging
      • Google Translation
      • Imagga Auto Tagging
      • Imagga Crop and Scale
      • JPEGmini Image Optimization
      • Perception Point Malware Detection
      • Microsoft Azure Video Indexer
      • Neural Artwork Style Transfer
      • OCR Text Detection and Extraction
      • Pixelz - Remove the Background
      • URL2PNG Website Screenshots
      • VIESUS™ Automatic Image Enhancement
      • WebPurify Image Moderation
    • Digital Asset Management
      • DAM overview
      • DAM user guide
        • Uploading and storing assets
        • Folders and collections
        • Media asset search
          • Global Search
          • Advanced Search
          • Query Builder
          • Visual Search (Beta)
        • Managing individual media assets
      • DAM administrator guide
        • User and group management
          • SAML provisioning
        • Settings and preferences
          • Dynamic folders
        • Upload presets
        • Structured metadata
        • Asset management
        • Usage data
        • Dynamic templating
    • Media Optimizer
      • Overview
      • Quick starts
        • Walkthrough
        • Deliver from a web address
        • Deliver from an AWS S3 bucket
        • Deliver from a Google Storage bucket
        • Deliver using an HTTP proxy
      • Configuration
      • Dashboard
      • Reports
      • Transformations
    • Platform integrations
      • Adobe Creative Cloud Connector
      • Akeneo PIM Integration
      • Chrome Media Library Extension
      • Magento Extension
        • Magento product catalog API
      • Salesforce Commerce Cloud Cartridges
        • Page Designer Cartridge
          • Custom integration
        • Site Cartridge
          • Operational overview
          • Site Cartridge for SiteGenesis
          • Site Cartridge for SFRA
          • Site Cartridge FAQ
      • Salesforce Marketing Cloud App
      • SAP Commerce Extension
      • Shopify App
        • User guide
      • WordPress Plugin
        • Developer guide
      • Zapier Integration
      • Partner-built integrations
        • Agility Custom Field
        • Actindo Connection
        • Builder.io App Extension
        • Chioro Operation
        • Comestri Channel
        • Conscia Connector
        • Contentful App
        • Contentstack Custom Field Extension
        • Creative Force Asset Delivery
        • GraphCMS UI Extension
        • Kontent.ai Custom Element
        • Magnolia DAM Connector
        • Movidmo Upload Connector
        • OpenText TeamSite Connector
        • Sanity Plugin
        • Sitefinity DAM System Integration
        • Smint.io Data Source Connector
        • Stackbit Integration
        • Storyblok App Integration
        • Syndigo Advanced DAM App
        • Uniform Integration
        • Vue Storefront Component
      • How to build your own integration
    • Pre-releases and labs
      • MediaFlows (Private Beta)
        • Oveview
        • Getting started
        • Build your first flow
        • Block reference
      • AR/3D Viewer and 3D Model Configurator
        • Oveview
        • Customizations
        • 3D Model Configurator
      • Media Inspector browser extension
  • References
    • Transformation URL API
    • Upload API
    • Admin API
    • Search API
    • Structured metadata
      • Metadata API
      • Conditional metadata rules API
    • Provisioning API
    • Cloudinary CLI
    • Postman collections
    • Upload Widget API
    • Video Player API
    • Product Gallery API
    • Media Editor API
    • Media Optimizer
      • Media Optimizer API
      • Transformation reference
  • SDKs
    • Backend SDKs
      • Ruby/Rails SDK
        • Ruby/Rails introduction
        • Ruby/Rails quick start
        • Ruby/Rails image and video upload
        • Ruby/Rails image transformations
        • Ruby/Rails video transformations
        • Ruby/Rails asset administration
        • CarrierWave integration
        • Attachinary integration
        • Active Storage integration
      • PHP SDK
        • PHP introduction
        • PHP quick start
        • PHP image and video upload
        • PHP image transformations
        • PHP video transformations
        • PHP asset administration
        • PHP SDK reference
      • Python SDK
        • Python introduction
        • Python quick start
        • Python image and video upload
        • Python image transformations
        • Python video transformations
        • Python asset administration
      • Node.js SDK
        • Node.js introduction
        • Node.js quick start
        • Node.js image and video upload
        • Node.js image transformations
        • Node.js video transformations
        • Node.js asset administration
      • Java SDK
        • Java introduction
        • Java quick start
        • Java image and video upload
        • Java image transformations
        • Java video transformations
        • Java asset administration
      • .NET SDK
        • .NET introduction
        • .NET quick start
        • .NET image and video upload
        • .NET image transformations
        • .NET video transformations
        • .NET asset administration
      • Go SDK
        • Go introduction
        • Go quick start
        • Go image and video upload
        • Go media transformations
        • Go asset administration
        • Go SDK Reference
      • Dart SDK
        • Dart introduction
        • Dart quick start
        • Dart image and video upload
        • Dart media transformations
      • PHP SDK (Legacy)
        • PHP introduction
        • PHP image and video upload
        • PHP image transformations
        • PHP video transformations
        • PHP asset administration
        • PHP migration guide
    • Frontend SDKs
      • JavaScript SDK
        • JavaScript introduction
        • JavaScript quick start
        • JavaScript image and video upload
        • JavaScript image transformations
        • JavaScript video transformations
        • JavaScript SDK reference
        • Transformation Builder reference
      • Angular SDK
        • Angular introduction
        • Angular quick start
        • Angular image and video upload
        • Angular image transformations
        • Angular video transformations
        • Angular SDK reference
        • Transformation Builder reference
      • React SDK
        • React introduction
        • React quick start
        • React image and video upload
        • React image transformations
        • React video transformations
        • React SDK reference
        • Transformation Builder reference
      • Vue.js SDK
        • Vue.js introduction
        • Vue.js quick start
        • Vue.js image and video upload
        • Vue.js image transformations
        • Vue.js video transformations
        • Transformation Builder reference
      • jQuery SDK
        • jQuery introduction
        • jQuery image and video upload
        • jQuery image transformations
        • jQuery video transformations
      • JavaScript SDK (Legacy)
        • JavaScript introduction
        • JavaScript image and video upload
        • JavaScript image transformations
        • JavaScript video transformations
        • JavaScript migration guide
      • Angular SDK (Legacy)
        • Angular introduction
        • Angular image and video upload
        • Angular image transformations
        • Angular video transformations
        • Angular migration guide
      • React SDK (Legacy)
        • React introduction
        • React image and video upload
        • React image transformations
        • React video transformations
        • React migration guide
      • Vue.js SDK (Legacy)
        • Vue.js introduction
        • Vue.js image and video upload
        • Vue.js image transformations
        • Vue.js video transformations
        • Vue.js migration guide
    • Mobile SDKs
      • iOS SDK
        • iOS introduction
        • iOS image and video upload
        • iOS image transformations
        • iOS video transformations
      • Android SDK
        • Android introduction
        • Android image and video upload
        • Android image transformations
        • Android video transformations
      • Flutter SDK
        • Flutter introduction
        • Flutter quick start
        • Flutter image and video upload
        • Flutter media transformations
      • Kotlin SDK
        • Kotlin media transformations
    • Community-developed libraries
      • Gatsby
      • Gridsome
      • Laravel
      • Netlify
      • Next.js
      • NuxtJS
      • Storefront UI
Login
sign up for free
  • References
  • Structured metadata

Metadata API reference

Last updated: Jan-29-2023

Overview

Cloudinary structured metadata allows you to define typed fields for media assets, populate them with values programmatically or via the Media Library, and perform searches on them. You can also add validation rules, set default values, and define fields as mandatory.

A metadata field is a custom, typed field (key) for storing user defined data (value) with a media asset.

Note
Cloudinary product environments are limited to a maximum of 100 structured metadata fields each. After reaching the maximum, you must disable one or more existing fields in order to add a new one.

This page explains the Metadata methods for creating and managing structured metadata fields, as well as the Metadata field structure and how to structure field validation and list (datasource) values.

Tip
It's also possible to create and manage structured metadata fields in the Manage Structured Metadata page of the Cloudinary console. For details, see Structured metadata management in the Digital Asset Management Guide.

Note
You can set up dependencies and hierarchical relationships between structured metadata fields and field options using the Conditional metadata rules API.

On this page:

  • Overview
  • Quick example
  • Metadata methods
  • Metadata field structure

Quick example

Add a new mandatory metadata set (multi-select) field with an external_id of 'color_id', labeled 'Colors', and with 4 available colors: red, green, blue and yellow, where red and green are the default values:

RubyPHPPythonNode.jsJava.NETGocURLAll
Ruby (cloudinary 1.x):
Copy to clipboard
Cloudinary::Api.add_metadata_field({          
  :"external_id" => "color_id",
  :"label" => "Colors",
  :"type" => "set" ,
  :"mandatory" => "true",
  :"default_value" => ["color1","color2"],
  :"datasource" => {
    :"values" => [
      {:"external_id" => "color1", :"value" => "red"},
      {:"external_id" => "color2", :"value" => "green"},
      {:"external_id" => "color3", :"value" => "blue"},
      {:"external_id" => "color4", :"value" => "yellow"}
    ]
  }
})
PHP (cloudinary_php 2.x):
Copy to clipboard
$api->addMetadataField(new SetMetadataField(
  [
    "external_id" => "color_id",
    "label" => "Colors",
    "type" => "set",
    "mandatory" => "true",
    "default_value" => ["color1", "color2"],
    "datasource" => [
      "values" => [
        ["external_id" => "color1", "value" => "red"],
        ["external_id" => "color2", "value" => "green"],
        ["external_id" => "color3", "value" => "blue"],
        ["external_id" => "color4", "value" => "yellow"],
      ]
    ]
  ]
));
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
$api->add_metadata_field(
  array(
    "external_id" => "color_id",
    "label" => "Colors",
    "type" => "set",
    "mandatory" => "true",
    "default_value" => ["color1", "color2"],
    "datasource" => array(
      "values" => array(
        array("external_id" => "color1", "value" => "red"),
        array("external_id" => "color2", "value" => "green"),
        array("external_id" => "color3", "value" => "blue"),
        array("external_id" => "color4", "value" => "yellow"),
      )
    )
  )
);
Python (cloudinary 1.x):
Copy to clipboard
cloudinary.api.add_metadata_field({          
  "external_id": "color_id",
  "label": "Colors",
  "type": "set" ,
  "mandatory": True,
  "default_value": ["color1","color2"],
  "datasource": {
    "values": [
      {"external_id": "color1", "value": "red"},
      {"external_id": "color2", "value": "green"},
      {"external_id": "color3", "value": "blue"},
      {"external_id": "color4", "value": "yellow"}
    ]
  }
})
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.v2.api
.add_metadata_field({          
  "external_id": "color_id",
  "label": "Colors",
  "type": "set" ,
  "mandatory": "true",
  "default_value": ["color1","color2"],
  "datasource": {
    "values": [
      {"external_id": "color1", "value": "red"},
      {"external_id": "color2", "value": "green"},
      {"external_id": "color3", "value": "blue"},
      {"external_id": "color4", "value": "yellow"}
    ]
  }
})
.then(result=>console.log(result));
Java (cloudinary 1.x):
Copy to clipboard
SetMetadataField setField = new SetMetadataField();
setField.setExternalId("color_id");
setField.setLabel("Colors");
setField.setMandatory(true);
setField.setDefaultValue(Arrays.asList("color1", "color2"));
setField.setDataSource(new MetadataDataSource(Arrays.asList(
  new Entry("color1", "red"),
  new Entry("color2", "green"),
  new Entry("color3", "blue"),
  new Entry("color4", "yellow")
)));
api.addMetadataField(setField);
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
var metadataFieldCreateParams = new SetMetadataFieldCreateParams("color_id"){
  Label = "Colors",
  Mandatory = true,
  DefaultValue = new List<string>{"color1" ,"color2"},
  DataSource = new MetadataDataSourceParams(new List<EntryParams>{
    new EntryParams("color1", "red"),
    new EntryParams("color2", "green"),
    new EntryParams("color3", "blue"),
    new EntryParams("color4", "yellow")})
};
cloudinary.AddMetadataField(metadataFieldCreateParams);
Go (cloudinary-go 1.x):
Copy to clipboard
resp, err := cld.Admin.AddMetadataField(ctx, metadata.Field{
    Type:         metadata.SetFieldType,
    ExternalID:   "color_id",
    Label:        "Colors",
    Mandatory:    true,
    DefaultValue: []string{"color1", "color2"},
    DataSource: metadata.DataSource{
        Values: []metadata.DataSourceValue{
            {
                ExternalID: "color1",
                Value:      "red",
                State:      "active",
            },
            {
                ExternalID: "color2",
                Value:      "green",
                State:      "active",
            },
            {
                ExternalID: "color3",
                Value:      "blue",
                State:      "active",
            },
            {
                ExternalID: "color4",
                Value:      "yellow",
                State:      "active",
            },
        },
    }})
curl:
Copy to clipboard
curl \
  -H "Content-Type: application/json" \
  -d '{          
    "external_id": "color_id",
    "label": "Colors",
    "type": "set" ,
    "mandatory": "true",
    "default_value": ["color1","color2"],
    "datasource": {
      "values": [
        {"external_id": "color1", "value": "red"},
        {"external_id": "color2", "value": "green"},
        {"external_id": "color3", "value": "blue"},
        {"external_id": "color4", "value": "yellow"}
      ]
    }
  }' \  
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/metadata_fields
cli:
Copy to clipboard
cld admin add_metadata_field `{"external_id": "color_id", "label": "Colors", "type": "set", "mandatory": "true", "default_value": ["color1","color2"], "datasource": {"values": [{"external_id": "color1", "value": "red"}, {"external_id": "color2", "value": "green"}, {"external_id": "color3", "value": "blue"}, {"external_id": "color4", "value": "yellow"}]}}`

Note
If running the CLI command on Windows, you need to escape the double quotes within the curly braces using either \ or ", for example, \"text\" or ""text"".

Metadata methods

Run in Postman Learn more about running Postman collections

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

Note
These methods are part of the rate-limited Admin API, and share the same usage limits. See that documentation for more information on authentication, pagination and error handling.

Method Description
GET/metadata_fields Lists all metadata field definitions.
GET/metadata_fields/:external_id Returns a single metadata field definition by external ID.
POST/metadata_fields Creates a new metadata field definition.
POST/metadata_fields/:external_id/datasource_restore Restores entries in a metadata field datasource.
PUT/metadata_fields/:external_id Updates a metadata field definition by external ID.
PUT/metadata_fields/:external_id/datasource Updates a metadata field datasource by external ID.
DELETE/metadata_fields/:external_id Deletes a metadata field by external ID.
DELETE/metadata_fields/:external_id/datasource Deletes entries in a metadata field datasource for a specified metadata field definition.

Get metadata fields

Returns a list of all metadata field definitions as an array of JSON objects.

See also: Metadata field structure

Syntax

GET /metadata_fields

RubyPHPPythonNode.jsJava.NETGoCLIAll
Ruby (cloudinary 1.x):
Copy to clipboard
Cloudinary::Api.list_metadata_fields(options = {})
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
$api->list_metadata_fields($options = array());
Python (cloudinary 1.x):
Copy to clipboard
cloudinary.api.list_metadata_fields(**options)
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.v2.api.list_metadata_fields(options).then(callback);
Java (cloudinary 1.x):
Copy to clipboard
api.listMetadataFields();
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
cloudinary.ListMetadataFields();
Go (cloudinary-go 1.x):
Copy to clipboard
resp, err := cld.Admin.ListMetadataFields(ctx)
cli:
Copy to clipboard
cld admin list_metadata_fields

Sample response

Copy to clipboard
{
  "metadata_fields": 
  [
    {
      "type": "date",
      "external_id": "available_date",
      "label": "Available date",
      "mandatory": false,
      "default_value": "2015-01-01",
      "validation": null,
      "default_disabled": false,
      "restrictions": {
        "readonly_ui": false
      }
    },
    {
      "type": "integer",
      "external_id": "in_stock",
      "label": "In stock",
      "mandatory": false,
      "default_value": 42,
      "validation": null,
      "default_disabled": false,
      "restrictions": {
        "readonly_ui": false
      }
    }
  ]
}

Get a metadata field by external ID

Returns a single metadata field definition.

See also: Metadata field structure

Syntax

GET /metadata_fields/:external_id

RubyPHPPythonNode.jsJava.NETGoCLIAll
Ruby (cloudinary 1.x):
Copy to clipboard
Cloudinary::Api.metadata_field_by_field_id(external_id, options = {})
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
$api->metadata_field_by_field_id($external_id, $options = array());
Python (cloudinary 1.x):
Copy to clipboard
cloudinary.api.metadata_field_by_field_id(external_id, **options)
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.v2.api.metadata_field_by_field_id(external_id, options).then(callback);
Java (cloudinary 1.x):
Copy to clipboard
api.metadataFieldByFieldId(String externalId);
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
cloudinary.GetMetadataField(string externalId);
Go (cloudinary-go 1.x):
Copy to clipboard
resp, err := cld.Admin.MetadataFieldByFieldID(ctx, admin.MetadataFieldByFieldIDParams{})
cli:
Copy to clipboard
cld admin metadata_field_by_field_id (external_id)

Required parameters

Parameter Type Description
external_id String The ID of the metadata field (included in the endpoint URL when using the REST API).

Examples

Return the information for the metadata field with the ID of 'in_stock':

RubyPHPPythonNode.jsJava.NETGocURLAll
Ruby (cloudinary 1.x):
Copy to clipboard
Cloudinary::Api.metadata_field_by_field_id("in_stock")
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
$api->metadata_field_by_field_id("in_stock");
Python (cloudinary 1.x):
Copy to clipboard
cloudinary.api.metadata_field_by_field_id("in_stock")
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.v2.api
.metadata_field_by_field_id('in_stock')
.then(result=>console.log(result));
Java (cloudinary 1.x):
Copy to clipboard
api.metadataFieldByFieldId("in_stock");
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
cloudinary.GetMetadataField("in_stock");
Go (cloudinary-go 1.x):
Copy to clipboard
resp, err := cld.Admin.MetadataFieldByFieldID(ctx, admin.MetadataFieldByFieldIDParams{
    FieldExternalID: "in_stock"})
curl:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/metadata_fields/in_stock
cli:
Copy to clipboard
cld admin metadata_field_by_field_id "in_stock"

Sample response

Copy to clipboard
{
    "type": "integer",
    "external_id": "in_stock",
    "label": "In stock",
    "mandatory": false,
    "default_value": 100,
    "validation": null,
    "default_disabled": false,
    "restrictions": {
      "readonly_ui": false
    }
}

Create a metadata field

Creates a new metadata field definition. Expects a single JSON object which defines the field, according to the structure for the required field type.

See also: Metadata field structure

Note
Cloudinary product environments are limited to a maximum of 100 structured metadata fields each. After reaching the maximum, you must disable one or more existing fields in order to add a new one.

Syntax

POST /metadata_fields

RubyPHPPythonNode.jsJava.NETGoCLIAll
Ruby (cloudinary 1.x):
Copy to clipboard
Cloudinary::Api.add_metadata_field(field, options = {})
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
$api->add_metadata_field($field, $options = array());
Python (cloudinary 1.x):
Copy to clipboard
cloudinary.api.add_metadata_field(field, **options)
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.v2.api.add_metadata_field(field, options).then(callback);
Java (cloudinary 1.x):
Copy to clipboard
api.addMetadataField(MetadataField field);
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
cloudinary.AddMetadataField(MetadataFieldCreateParams field);
Go (cloudinary-go 1.x):
Copy to clipboard
resp, err := cld.Admin.AddMetadataField(ctx, metadata.Field{})
cli:
Copy to clipboard
cld admin add_metadata_field $field $options

Required parameters

Parameter Type Description
field Object The metadata field to add. For details see Metadata field structure.

Examples

Add a new mandatory metadata set (multi-select) field with an external_id of 'color_id', labeled 'Colors', and with 4 available colors: red, green, blue and yellow, where red and green are the default values:

RubyPHPPythonNode.jsJava.NETGocURLAll
Ruby (cloudinary 1.x):
Copy to clipboard
Cloudinary::Api.add_metadata_field({          
  :"external_id" => "color_id",
  :"label" => "Colors",
  :"type" => "set" ,
  :"mandatory" => "true",
  :"default_value" => ["color1","color2"],
  :"datasource" => {
    :"values" => [
      {:"external_id" => "color1", :"value" => "red"},
      {:"external_id" => "color2", :"value" => "green"},
      {:"external_id" => "color3", :"value" => "blue"},
      {:"external_id" => "color4", :"value" => "yellow"}
    ]
  }
})
PHP (cloudinary_php 2.x):
Copy to clipboard
$api->addMetadataField(new SetMetadataField(
  [
    "external_id" => "color_id",
    "label" => "Colors",
    "type" => "set",
    "mandatory" => "true",
    "default_value" => ["color1", "color2"],
    "datasource" => [
      "values" => [
        ["external_id" => "color1", "value" => "red"],
        ["external_id" => "color2", "value" => "green"],
        ["external_id" => "color3", "value" => "blue"],
        ["external_id" => "color4", "value" => "yellow"],
      ]
    ]
  ]
));
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
$api->add_metadata_field(
  array(
    "external_id" => "color_id",
    "label" => "Colors",
    "type" => "set",
    "mandatory" => "true",
    "default_value" => ["color1", "color2"],
    "datasource" => array(
      "values" => array(
        array("external_id" => "color1", "value" => "red"),
        array("external_id" => "color2", "value" => "green"),
        array("external_id" => "color3", "value" => "blue"),
        array("external_id" => "color4", "value" => "yellow"),
      )
    )
  )
);
Python (cloudinary 1.x):
Copy to clipboard
cloudinary.api.add_metadata_field({          
  "external_id": "color_id",
  "label": "Colors",
  "type": "set" ,
  "mandatory": True,
  "default_value": ["color1","color2"],
  "datasource": {
    "values": [
      {"external_id": "color1", "value": "red"},
      {"external_id": "color2", "value": "green"},
      {"external_id": "color3", "value": "blue"},
      {"external_id": "color4", "value": "yellow"}
    ]
  }
})
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.v2.api
.add_metadata_field({          
  "external_id": "color_id",
  "label": "Colors",
  "type": "set" ,
  "mandatory": "true",
  "default_value": ["color1","color2"],
  "datasource": {
    "values": [
      {"external_id": "color1", "value": "red"},
      {"external_id": "color2", "value": "green"},
      {"external_id": "color3", "value": "blue"},
      {"external_id": "color4", "value": "yellow"}
    ]
  }
})
.then(result=>console.log(result));
Java (cloudinary 1.x):
Copy to clipboard
SetMetadataField setField = new SetMetadataField();
setField.setExternalId("color_id");
setField.setLabel("Colors");
setField.setMandatory(true);
setField.setDefaultValue(Arrays.asList("color1", "color2"));
setField.setDataSource(new MetadataDataSource(Arrays.asList(
  new Entry("color1", "red"),
  new Entry("color2", "green"),
  new Entry("color3", "blue"),
  new Entry("color4", "yellow")
)));
api.addMetadataField(setField);
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
var metadataFieldCreateParams = new SetMetadataFieldCreateParams("color_id"){
  Label = "Colors",
  Mandatory = true,
  DefaultValue = new List<string>{"color1" ,"color2"},
  DataSource = new MetadataDataSourceParams(new List<EntryParams>{
    new EntryParams("color1", "red"),
    new EntryParams("color2", "green"),
    new EntryParams("color3", "blue"),
    new EntryParams("color4", "yellow")})
};
cloudinary.AddMetadataField(metadataFieldCreateParams);
Go (cloudinary-go 1.x):
Copy to clipboard
resp, err := cld.Admin.AddMetadataField(ctx, metadata.Field{
    Type:         metadata.SetFieldType,
    ExternalID:   "color_id",
    Label:        "Colors",
    Mandatory:    true,
    DefaultValue: []string{"color1", "color2"},
    DataSource: metadata.DataSource{
        Values: []metadata.DataSourceValue{
            {
                ExternalID: "color1",
                Value:      "red",
                State:      "active",
            },
            {
                ExternalID: "color2",
                Value:      "green",
                State:      "active",
            },
            {
                ExternalID: "color3",
                Value:      "blue",
                State:      "active",
            },
            {
                ExternalID: "color4",
                Value:      "yellow",
                State:      "active",
            },
        },
    }})
curl:
Copy to clipboard
curl \
  -H "Content-Type: application/json" \
  -d '{          
    "external_id": "color_id",
    "label": "Colors",
    "type": "set" ,
    "mandatory": "true",
    "default_value": ["color1","color2"],
    "datasource": {
      "values": [
        {"external_id": "color1", "value": "red"},
        {"external_id": "color2", "value": "green"},
        {"external_id": "color3", "value": "blue"},
        {"external_id": "color4", "value": "yellow"}
      ]
    }
  }' \  
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/metadata_fields
cli:
Copy to clipboard
cld admin add_metadata_field `{"external_id": "color_id", "label": "Colors", "type": "set", "mandatory": "true", "default_value": ["color1","color2"], "datasource": {"values": [{"external_id": "color1", "value": "red"}, {"external_id": "color2", "value": "green"}, {"external_id": "color3", "value": "blue"}, {"external_id": "color4", "value": "yellow"}]}}`

Note
If running the CLI command on Windows, you need to escape the double quotes within the curly braces using either \ or ", for example, \"text\" or ""text"".

Sample response

Copy to clipboard
{
    "type": "set", 
    "external_id": "color_id", 
    "label": "Colors", 
    "mandatory": true, 
    "default_value": ["color1", "color2"], 
    "validation": null,
    "default_disabled": false,
    "restrictions": {
      "readonly_ui": false
    }, 
    "datasource": {
      "values": [
      {
        "external_id": "color1", 
        "value": "red", 
        "state": "active"
      }, 
      {
        "external_id": "color2", 
        "value": "green", 
        "state": "active"
      }, 
      {
        "external_id": "color3", 
        "value": "blue", 
        "state": "active"
      }, 
      {
        "external_id": "color4", 
        "value": "yellow", 
        "state": "active"
      }]
    }
}

Restore entries in a metadata field datasource

Restores (unblocks) any previously deleted datasource entries for a specified metadata field definition. Sets the state of the entries to active.

See also: Metadata field structure

Syntax

POST /metadata_fields/:external_id/datasource_restore

RubyPHPPythonNode.jsJava.NETGoCLIAll
Ruby (cloudinary 1.x):
Copy to clipboard
Cloudinary::Api.restore_metadata_field_datasource(external_id, external_ids, options = {})
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
$api->restore_metadata_field_datasource($external_id, $external_ids, $options = array());
Python (cloudinary 1.x):
Copy to clipboard
cloudinary.api.restore_metadata_field_datasource(external_id, external_ids, **options)
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.v2.api.restore_metadata_field_datasource(external_id, external_ids, options).then(callback);
Java (cloudinary 1.x):
Copy to clipboard
api.restoreDatasourceEntries(String externalId, List<String> externalIds);
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
cloudinary.RestoreMetadataDataSourceEntries(string externalId, List<string> externalIds)
Go (cloudinary-go 1.x):
Copy to clipboard
resp, err := cld.Admin.RestoreDatasourceEntries(ctx, admin.RestoreDatasourceEntriesParams{})
cli:
Copy to clipboard
cld admin restore_metadata_field_datasource (external_id, external_ids)

Required parameters

Parameter Type Description
external_id String The ID of the metadata field (included in the endpoint URL when using the REST API).
external_ids String[] An array of IDs of datasource entries to restore (unblock).

Examples

Restore (unblock) the datasource entry with external_id 'color1' from the metadata field with external_id 'color_id':

RubyPHPPythonNode.jsJava.NETGocURLAll
Ruby (cloudinary 1.x):
Copy to clipboard
Cloudinary::Api.restore_metadata_field_datasource("color_id", ["color1"])
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
$api->restore_metadata_field_datasource("color_id", array("color1"));
Python (cloudinary 1.x):
Copy to clipboard
cloudinary.api.restore_metadata_field_datasource("color_id", ["color1"])
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.v2.api
.restore_metadata_field_datasource('color_id', ["color1"])
.then(result=>console.log(result));
Java (cloudinary 1.x):
Copy to clipboard
api.restoreDatasourceEntries("color_id", Arrays.asList("color1"));
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
cloudinary.RestoreMetadataDataSourceEntries("color_id", new List<string>{"color1"});
Go (cloudinary-go 1.x):
Copy to clipboard
resp, err := cld.Admin.RestoreDatasourceEntries(ctx, admin.RestoreDatasourceEntriesParams{
                FieldExternalID: "color_id", 
                EntriesExternalIDs: []string{"color_1"}})
curl:
Copy to clipboard
curl \
  -d "external_ids[]=color1" \
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/metadata_fields/color_id/datasource_restore
cli:
Copy to clipboard
cld admin restore_metadata_field_datasource "color_id" ["color1"]

Sample response

Copy to clipboard
{ 
    "values": [{
      "external_id": "color1", 
      "value": "red"}, 
    { 
      "external_id": "color2",  
      "value": "green"}, 
    {
      "external_id": "color3", 
      "value": "blue"}, 
    {
      "external_id": "color4", 
      "value": "yellow"}]
}

Update a metadata field by external ID

Updates a metadata field definition (partially, no need to pass the entire object) passed as JSON data.

See also: Metadata field structure

Syntax

PUT /metadata_fields/:external_id

RubyPHPPythonNode.jsJava.NETGoCLIAll
Ruby (cloudinary 1.x):
Copy to clipboard
Cloudinary::Api.update_metadata_field(external_id, field, options = {})
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
$api->update_metadata_field($external_id, $field, $options = array());
Python (cloudinary 1.x):
Copy to clipboard
cloudinary.api.update_metadata_field(external_id, field, **options)
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.v2.api.update_metadata_field(external_id, field, options).then(callback);
Java (cloudinary 1.x):
Copy to clipboard
api.updateMetadataField(String externalId, MetadataField field);
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
cloudinary.UpdateMetadataField(string externalId, MetadataFieldUpdateParams field)
Go (cloudinary-go 1.x):
Copy to clipboard
resp, err := cld.Admin.UpdateMetadataField(ctx, admin.UpdateMetadataFieldParams{})
cli:
Copy to clipboard
cld admin update_metadata_field (external_id, field)

Required parameters

Parameter Type Description
external_id String The ID of the metadata field (included in the endpoint URL when using the REST API).
field Object The metadata field to update. For details see Metadata field structure.

Examples

Update the metadata field with the ID of 'in_stock':

RubyPHPPythonNode.jsJava.NETGocURLAll
Ruby (cloudinary 1.x):
Copy to clipboard
Cloudinary::Api.update_metadata_field("in_stock", {
  :"label" => "Now in stock",
  :"mandatory" => true  })
PHP (cloudinary_php 2.x):
Copy to clipboard
$api->updateMetadataField("in_stock", [
  [ "label" => "Now in stock",
    "mandatory" => true]
]);
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
$api->update_metadata_field("in_stock", 
  [ "label" => "Now in stock",
    "mandatory" => true  ]
);
Python (cloudinary 1.x):
Copy to clipboard
cloudinary.api.update_metadata_field("in_stock", {
  "label": "Now in stock",
  "mandatory": True })
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.v2.api
.update_metadata_field('in_stock', {
  "label": "Now in stock",
  "mandatory": true  })
.then(result=>console.log(result));
Java (cloudinary 1.x):
Copy to clipboard
SetMetadataField setField = new SetMetadataField();
setField.setLabel("Now in stock");
setField.setMandatory(true);
api.updateMetadataField("in_stock", setField);
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
var MetadataFieldUpdateParams = new StringMetadataFieldUpdateParams(){
  Label = "Now in stock",
  Mandatory = true  };
cloudinary.UpdateMetadataField("in_stock", MetadataFieldUpdateParams);
Go (cloudinary-go 1.x):
Copy to clipboard
resp, err := cld.Admin.UpdateMetadataField(ctx, admin.UpdateMetadataFieldParams{
    FieldExternalID: "in_stock",
    Field: metadata.Field{
        Label:     "Now in stock",
        Mandatory: true}})
curl:
Copy to clipboard
curl \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Now in stock",
    "mandatory": true
  }' \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/metadata_fields/in_stock
cli:
Copy to clipboard
cld admin update_metadata_field 'in_stock' '{"label": "Now in stock", "mandatory": true}'

Note
If running the CLI command on Windows, you need to escape the double quotes within the curly braces using either \ or ", for example, \"text\" or ""text"".

Sample response

Copy to clipboard
{
  "type": "integer",
  "external_id": "in_stock",
  "label": "Now in stock",
  "mandatory": true,
  "default_value": 100,
  "validation": null,
  "default_disabled": false,
  "restrictions": {
    "readonly_ui": false
  }
}

Update a metadata field datasource

Updates the datasource of a supported field type (currently only enum and set), passed as JSON data. The update is partial: datasource entries with an existing external_id will be updated and entries with new external_id's (or without external_id's) will be appended.

See also: Metadata field structure

Syntax

PUT /metadata_fields/:external_id/datasource

RubyPHPPythonNode.jsJava.NETGoCLIAll
Ruby (cloudinary 1.x):
Copy to clipboard
Cloudinary::Api.update_metadata_field_datasource(external_id, entries, options = {})
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
$api->update_metadata_field_datasource($external_id, $entries, $options = array());
Python (cloudinary 1.x):
Copy to clipboard
cloudinary.api.update_metadata_field_datasource(external_id, entries, **options)
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.v2.api.update_metadata_field_datasource(external_id, entries, options).then(callback);
Java (cloudinary 1.x):
Copy to clipboard
api.updateMetadataFieldDatasource(String externalId, List<MetadataDataSource.Entry> entries);
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
cloudinary.UpdateMetadataDataSourceEntries(string externalId, MetadataDataSourceParams entries)
Go (cloudinary-go 1.x):
Copy to clipboard
resp, err := cld.Admin.UpdateMetadataFieldDataSource(ctx, admin.UpdateMetadataFieldDataSourceParams{})
cli:
Copy to clipboard
cld admin update_metadata_field_datasource (external_id, entries)

Required parameters

Parameter Type Description
external_id String The ID of the metadata field (included in the endpoint URL when using the REST API).
entries Object The datasource enties to update. For details see Datasource values.

Examples

Update the datasource for the metadata field with the ID of ''color_id':

RubyPHPPythonNode.jsJava.NETGocURLAll
Ruby (cloudinary 1.x):
Copy to clipboard
Cloudinary::Api.update_metadata_field_datasource("color_id", {  
  :"values" => [{  
    :"external_id" => "color1",
    :"value" => "orange"
  },
  {  
    :"external_id" => "color2",
    :"value" => "black"
  }]
})
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
$api->update_metadata_field_datasource("color_id", 
  array( 
    "values" => array(
      array("external_id" => "color1", "value" => "orange"),
      array("external_id" => "color2", "value" => "black")
    )
  )
);
Python (cloudinary 1.x):
Copy to clipboard
cloudinary.api.update_metadata_field_datasource("color_id", [  
  {  
    "external_id":"color1",
    "value":"orange"
  },
  {  
    "external_id":"color2",
    "value":"black"
  }]
)
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.v2
.api.update_metadata_field_datasource('color_id', {  
  "values":[{  
    "external_id":"color1",
    "value":"orange"
  },
  {  
    "external_id":"color2",
    "value":"black"
  }]
})
.then(result=>console.log(result));
Java (cloudinary 1.x):
Copy to clipboard
api.updateMetadataFieldDatasource("color_id", 
  new MetadataDataSource(Arrays.asList(
    new Entry("color1", "orange"),
    new Entry("color2", "black")))
);
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
var metadataDataSourceParams = new MetadataDataSourceParams(){  
  Values = [{  
    ExternalId = "color1",
    Value = "orange"
  },
  {  
    ExternalId = "color2",
    Value = "black"
  }]
};
cloudinary.UpdateMetadataDataSourceEntries("color_id", metadataDataSourceParams);
Go (cloudinary-go 1.x):
Copy to clipboard
resp, err := cld.Admin.UpdateMetadataFieldDataSource(ctx, admin.UpdateMetadataFieldDataSourceParams{
        FieldExternalID: "color_id",
        DataSource: metadata.DataSource{
            Values: []metadata.DataSourceValue{
                {
                    ExternalID: "color1",
                    Value:      "orange",
                    State:      "active",
                },
                {
                    ExternalID: "color2",
                    Value:      "black",
                    State:      "active",
                }}}})
curl:
Copy to clipboard
curl \
  -H "Content-Type: application/json" \
  -d '{  
    "values":[{  
      "external_id":"color1",
      "value":"orange"
    },
    {  
      "external_id":"color2",
      "value":"black"
    }]
  }' \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/metadata_fields/color_id/datasource
cli:
Copy to clipboard
cld admin update_metadata_field_datasource 'color_id' '[{"external_id":"color1", "value":"orange"}, {"external_id":"color2", "value":"black"}]'

Note
If running the CLI command on Windows, you need to escape the double quotes within the curly braces using either \ or ", for example, \"text\" or ""text"".

Sample response

Copy to clipboard
{ 
    "values": [{
      "external_id": "color1", 
      "value": "orange"}, 
    { 
      "external_id": "color2",  
      "value": "black"}, 
    {
      "external_id": "color3", 
      "value": "blue"}, 
    {
      "external_id": "color4", 
      "value": "yellow"}]
}

Delete a metadata field by external ID

Deletes a metadata field definition. The field should no longer be considered a valid candidate for all other endpoints (it will not show up in the list of fields, etc).

Note
external_ids can be reused after fields are deleted, but if the fields had many assignments, the process can take a few minutes and the external_id will be reserved until the asynchronous deletion is complete.

See also: Metadata field structure

Syntax

DELETE /metadata_fields/:external_id

RubyPHPPythonNode.jsJava.NETGoCLIAll
Ruby (cloudinary 1.x):
Copy to clipboard
Cloudinary::Api.delete_metadata_field(external_id, options = {})
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
$api->delete_metadata_field($external_id, $options = array());
Python (cloudinary 1.x):
Copy to clipboard
cloudinary.api.delete_metadata_field(external_id, **options)
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.v2.api.delete_metadata_field(external_id, options).then(callback);
Java (cloudinary 1.x):
Copy to clipboard
api.deleteMetadataField(String externalId);
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
cloudinary.DeleteMetadataField(string externalId)
Go (cloudinary-go 1.x):
Copy to clipboard
resp, err := cld.Admin.DeleteMetadataField(ctx, admin.DeleteMetadataFieldParams{})
cli:
Copy to clipboard
cld admin delete_metadata_field (external_id)

Required parameters

Parameter Type Description
external_id String The ID of the metadata field (included in the endpoint URL when using the REST API).

Examples

Delete the metadata field with the ID of 'in_stock':

RubyPHPPythonNode.jsJava.NETGocURLAll
Ruby (cloudinary 1.x):
Copy to clipboard
Cloudinary::Api.delete_metadata_field("in_stock")
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
$api->delete_metadata_field("in_stock");
Python (cloudinary 1.x):
Copy to clipboard
cloudinary.api.delete_metadata_field("in_stock")
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.v2.api
.delete_metadata_field('in_stock')
.then(result=>console.log(result));
Java (cloudinary 1.x):
Copy to clipboard
api.deleteMetadataField("in_stock");
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
cloudinary.DeleteMetadataField("in_stock");
Go (cloudinary-go 1.x):
Copy to clipboard
resp, err := cld.Admin.DeleteMetadataField(ctx, admin.DeleteMetadataFieldParams{
        FieldExternalID: "in_stock"})
curl:
Copy to clipboard
curl 
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/metadata_fields/in_stock
cli:
Copy to clipboard
cld admin delete_metadata_field "in_stock"

Sample response

Copy to clipboard
{ 
   "message": "ok"
}

Delete entries in a metadata field datasource

Deletes (blocks) the datasource entries for a specified metadata field definition. Sets the state of the entries to inactive. This is a soft delete, so the entries still exist under the hood but are marked as having an inactive state. The entries can be activated again with the restore datasource entries method.

Note
As inactive entries are not deleted, they still show up in responses with their state property set to inactive.

See also: Metadata field structure

Syntax

DELETE /metadata_fields/:external_id/datasource

RubyPHPPythonNode.jsJava.NETGoCLIAll
Ruby (cloudinary 1.x):
Copy to clipboard
Cloudinary::Api.delete_datasource_entries(external_id, external_ids, options = {})
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
$api->delete_datasource_entries($external_id, $external_ids, $options = array());
Python (cloudinary 1.x):
Copy to clipboard
cloudinary.api.delete_datasource_entries(external_id, external_ids, **options)
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.v2.api.delete_datasource_entries(external_id, external_ids, options).then(callback);
Java (cloudinary 1.x):
Copy to clipboard
api.deleteDatasourceEntries(String externalId, List<String> externalIds);
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
cloudinary.DeleteMetadataDataSourceEntries(string externalId, List<string> externalIds)
Go (cloudinary-go 1.x):
Copy to clipboard
resp, err := cld.Admin.DeleteDataSourceEntries(ctx, admin.DeleteDataSourceEntriesParams{})
cli:
Copy to clipboard
cld admin delete_datasource_entries (external_id, external_ids)

Required parameters

Parameter Type Description
external_id String The ID of the metadata field (included in the endpoint URL when using the REST API).
external_ids String[] An array of IDs of datasource entries to delete.

Examples

Delete (block) the datasource entry with external_id 'color4' from the metadata field with external_id 'color_id':

RubyPHPPythonNode.jsJava.NETGocURLAll
Ruby (cloudinary 1.x):
Copy to clipboard
Cloudinary::Api.delete_datasource_entries("color_id", ["color4"])
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
$api->delete_datasource_entries("color_id", ["color4"]);
Python (cloudinary 1.x):
Copy to clipboard
cloudinary.api.delete_datasource_entries("color_id", ["color4"])
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.v2.api
.delete_datasource_entries('color_id', ["color4"])
.then(result=>console.log(result));
Java (cloudinary 1.x):
Copy to clipboard
api.deleteDatasourceEntries("color_id", Arrays.asList("color4"));
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
cloudinary.DeleteMetadataDataSourceEntries("color_id", new List<string>{"color4"});
Go (cloudinary-go 1.x):
Copy to clipboard
resp, err := cld.Admin.DeleteDataSourceEntries(ctx, admin.DeleteDataSourceEntriesParams{
        FieldExternalID: "color_id", 
        EntriesExternalIDs: []string{"color4"}})
curl:
Copy to clipboard
curl \
  -d "external_ids[]=color1" \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/metadata_fields/color_id/datasource
cli:
Copy to clipboard
cld admin delete_datasource_entries "color_id" ["color4"]

Sample response

Copy to clipboard
{
    "values": [{
      "external_id": "color1", 
      "value": "red"}, 
    {
      "external_id": "color2", 
      "value": "green"}, 
    {
      "external_id": "color3", 
      "value": "blue"}]
}

Metadata field structure

Copy to clipboard
{
  "external_id": <string>,
  "type": <field_type_enum>,
  "label": <string>,
  "mandatory": <boolean>,
  "restrictions": <restrictions_object>,
  "default_value": <field_type_value>,
  "validation": <validation_object>,
  "datasource": <datasource_object>  //enum and set types
}
Parameter Required Description
external_id No A unique immutable identification string for the metadata field. Default: auto-generated by Cloudinary (although it's recommended to specify a descriptive name). Max character length: 255.
type Yes The type of value that can be assigned to the metadata field, possible types are limited to:
* string - a single string value
* integer - a single integer value
* date - a custom date in the following format: {yyyy-mm-dd}
* enum - a single value referenced by an external_id from a given list, predefined with the datasource parameter
* set - multiple values referenced by external_ids from a given list, predefined with the datasource parameter
label Yes The label of the metadata field for display purposes.
mandatory No Whether a value must be given for this field, either when an asset is first uploaded, or when it is updated. Default: false
restrictions No Any restrictions to apply. Currently can set the readonly_ui boolean parameter to mark this metadata field as read only in the UI (only relevant if mandatory is false). Default: {"readonly_ui": false}
default_value Yes (if mandatory is true) The default value for the field (a set can have multiple default values defined by an array). Default: null
validation No Any validation rules to apply when values are entered (or updated) for this field. See Validating data for more details. Default: null
datasource Yes (for the enum and set type) The predefined list of values, referenced by external_ids, available for this field. See Datasource values for more details.

Validating data

The validation parameter defines a validation object with the logic to apply when a value is entered for the field, via the metadata, upload, explicit or update resource methods, or via the Media Library. The boolean validations also allow for combinations of more than one rule. The following validations are supported:

  • greater_than
  • less_than
  • strlen
  • and

greater_than validation

Relevant for integer and date types:

Copy to clipboard
{
    "type": "greater_than",
    "value": <value_by_type>,
    "equals": <boolean>
}
Property Type Description
value String The value for validation.
equals Boolean Whether to check if greater than or equals. Default: false

For example:

Copy to clipboard
"validation":{ 
    "type": "greater_than",
    "value": "2018-10-15",
    "equals": true
}

less_than validation

Relevant for integer and date types:

Copy to clipboard
{
    "type": "less_than",
    "value": <value_by_type>,
    "equals": <boolean>
}
Property Type Description
value String The value for validation.
equals Boolean Whether to check if less than or equals. Default: false

For example:

Copy to clipboard
"validation":{ 
    "type": "less_than",
    "value": 50,
    "equals": true
}

strlen validation

Relevant only for string types:

Copy to clipboard
{
    "type": "strlen",
    "min": <positive integer>,
    "max": <positive integer>
}
Property Type Description
min Integer The minimum string length. Default: 0
max Integer The maximum string length. Default: 1024

Note
Either min or max must be given, supplying both is optional.

For example:

Copy to clipboard
"validation":{ 
    "type": "strlen",
    "min": 5,
    "max": 20
}

and validation

Relevant for all field types. Allows you to include more than one validation rule to be evaluated:

Copy to clipboard
{
    "type": "and",
    "rules": [ <validation_object>, <validation_object>, … ]
}
Property Type Description
validation_object Object One of the other validations above: greater_than, less_than or strlen

For example:

Copy to clipboard
"validation":{
    "type":  "and"
    "rules": [{ 
        "type": "greater_than",
        "value": 10,
        "equals": true
    },
    { 
        "type": "less_than",
        "value": 50,
        "equals": true
    }]
}

Datasource values

The datasource parameter is relevant for fields where the selected values must come from a predefined list of values (enum or set type fields). The parameter contains the values property, which defines the values for the enum or set list. Up to 3000 values can be defined for a list.

Copy to clipboard
{
    "values": [ <datasource_entry>, <datasource_entry>, … ]
}

Each datasource_entry defines a single possible value for the field:

Copy to clipboard
{
    "external_id": <string>,
    "value": <string>,
    "state": "active" | "inactive"
}
Property Type Description
external_id String (optional) A unique immutable identification string for the datasource entry, (required if the value is referenced by the default_value field). Default: auto-generated by Cloudinary
value String (mandatory) The value for this datasource.
state String (read only) Only given as part of a response - ignored on requests. It is immutable unless changed via DELETE of a datasource entry.

For example:

Copy to clipboard
"datasource": {
    "values": [{
        "external_id": "color1", 
        "value": "red"
    },
    {   
        "external_id": "color2", 
        "value": "green"
    },
    {
        "external_id": "color3", 
        "value": "blue"
    },
    {
        "external_id": "color4", 
        "value": "yellow"
    }]
}

✔️ 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:

  • Search API reference
  • Conditional metadata rules API reference
Cloudinary Logo - White
Products
  • Programmable Media
  • DAM
  • Demos
  • Pricing
  • Roadmap
  • FAQ
Solutions
    • Why Cloudinary
    • Video API
    • E-commerce
    • Retail
    • Media & Entertainment
    • Travel & Hospitality
    • Non-Profits
    • Our Customers
    • Resource Library
    Developers
    • Getting Started
    • Documentation
    • SDKs
    • Add-ons
    • Podcasts
    • Cookbook
    Company
    • About Us
    • Customers
    • Partners
    • Events
    • Careers
    • Newsroom
    • Blog
    • Brand Assets
    • Trust
    Contact Us
    • Technical Support
    • Contact Sales
    • Education & Training
    • Institute of Quality & Control
    • GDPR
    • SOC
    • Forbes Best Startup Employers 2020
    • MarTech Breakthrough Awards
    • Best Places to Work SVBJ 2018
    • 2020 The World's Best Cloud Companies
    • Terms of Use
    • Privacy Policy
    • DMCA Notice

    © 2023 Cloudinary. All rights reserved.