Metadata API reference

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 account clouds 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:

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

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):

$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)):

$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):

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):

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"}
    ]
  }
});

Java (cloudinary 1.x):

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):

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):

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:

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:

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 account.

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

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.list_metadata_fields(options = {})

PHP (cloudinary_php 1.x (legacy)):

$api->list_metadata_fields($options = array());

Python (cloudinary 1.x):

cloudinary.api.list_metadata_fields(**options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.list_metadata_fields(options, callback);

Java (cloudinary 1.x):

api.listMetadataFields();

.NET (CloudinaryDotNet 1.x):

cloudinary.ListMetadataFields();

Go (cloudinary-go 1.x):

resp, err := cld.Admin.ListMetadataFields(ctx)

cli:

cld admin list_metadata_fields

Sample response

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

Get a metadata field by external ID

Returns a single metadata field definition.

See also: Metadata field structure

Syntax

GET /metadata_fields/:external_id

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.metadata_field_by_field_id(external_id, options = {})

PHP (cloudinary_php 1.x (legacy)):

$api->metadata_field_by_field_id($external_id, $options = array());

Python (cloudinary 1.x):

cloudinary.api.metadata_field_by_field_id(external_id, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.metadata_field_by_field_id(external_id, options, callback);

Java (cloudinary 1.x):

api.metadataFieldByFieldId(String externalId);

.NET (CloudinaryDotNet 1.x):

cloudinary.GetMetadataField(string externalId);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.MetadataFieldByFieldID(ctx, admin.MetadataFieldByFieldIDParams{})

cli:

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':

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

Cloudinary::Api.metadata_field_by_field_id("in_stock")

PHP (cloudinary_php 1.x (legacy)):

$api->metadata_field_by_field_id("in_stock");

Python (cloudinary 1.x):

cloudinary.api.metadata_field_by_field_id("in_stock")

Node.js (cloudinary 1.x):

cloudinary.v2.api.metadata_field_by_field_id('in_stock');

Java (cloudinary 1.x):

api.metadataFieldByFieldId("in_stock");

.NET (CloudinaryDotNet 1.x):

cloudinary.GetMetadataField("in_stock");

Go (cloudinary-go 1.x):

resp, err := cld.Admin.MetadataFieldByFieldID(ctx, admin.MetadataFieldByFieldIDParams{
    FieldExternalID: "in_stock"})

curl:

curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/metadata_fields/in_stock

cli:

cld admin metadata_field_by_field_id "in_stock"

Sample response

{
    "type": "integer",
    "external_id": "in_stock",
    "label": "In stock",
    "mandatory": false,
    "default_value": 100,
    "validation": null
}

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 account clouds 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

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.add_metadata_field(field, options = {})

PHP (cloudinary_php 1.x (legacy)):

$api->add_metadata_field($field, $options = array());

Python (cloudinary 1.x):

cloudinary.api.add_metadata_field(field, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.add_metadata_field(field, options, callback);

Java (cloudinary 1.x):

api.addMetadataField(MetadataField field);

.NET (CloudinaryDotNet 1.x):

cloudinary.AddMetadataField(MetadataFieldCreateParams field);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.AddMetadataField(ctx, metadata.Field{})

cli:

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

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

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):

$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)):

$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):

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):

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"}
    ]
  }
});

Java (cloudinary 1.x):

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):

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):

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:

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:

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

{
    "type": "set", 
    "external_id": "color_id", 
    "label": "Colors", 
    "mandatory": true, 
    "default_value": ["color1", "color2"], 
    "validation": null, 
    "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

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.restore_metadata_field_datasource(external_id, external_ids, options = {})

PHP (cloudinary_php 1.x (legacy)):

$api->restore_metadata_field_datasource($external_id, $external_ids, $options = array());

Python (cloudinary 1.x):

cloudinary.api.restore_metadata_field_datasource(external_id, external_ids, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.restore_metadata_field_datasource(external_id, external_ids, options, callback);

Java (cloudinary 1.x):

api.restoreDatasourceEntries(String externalId, List<String> externalIds);

.NET (CloudinaryDotNet 1.x):

cloudinary.RestoreMetadataDataSourceEntries(string externalId, List<string> externalIds)

Go (cloudinary-go 1.x):

resp, err := cld.Admin.RestoreDatasourceEntries(ctx, admin.RestoreDatasourceEntriesParams{})

cli:

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':

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

Cloudinary::Api.restore_metadata_field_datasource("color_id", ["color1"])

PHP (cloudinary_php 1.x (legacy)):

$api->restore_metadata_field_datasource("color_id", array("color1"));

Python (cloudinary 1.x):

cloudinary.api.restore_metadata_field_datasource("color_id", ["color1"])

Node.js (cloudinary 1.x):

cloudinary.v2.api.restore_metadata_field_datasource('color_id', ["color1"]);

Java (cloudinary 1.x):

api.restoreDatasourceEntries("color_id", Arrays.asList("color1"));

.NET (CloudinaryDotNet 1.x):

cloudinary.RestoreMetadataDataSourceEntries("color_id", new List<string>{"color1"});

Go (cloudinary-go 1.x):

resp, err := cld.Admin.RestoreDatasourceEntries(ctx, admin.RestoreDatasourceEntriesParams{
                FieldExternalID: "color_id", 
                EntriesExternalIDs: []string{"color_1"}})

curl:

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:

cld admin restore_metadata_field_datasource "color_id" ["color1"]

Sample response

{ 
    "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

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.update_metadata_field(external_id, field, options = {})

PHP (cloudinary_php 1.x (legacy)):

$api->update_metadata_field($external_id, $field, $options = array());

Python (cloudinary 1.x):

cloudinary.api.update_metadata_field(external_id, field, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.update_metadata_field(external_id, field, options, callback);

Java (cloudinary 1.x):

api.updateMetadataField(String externalId, MetadataField field);

.NET (CloudinaryDotNet 1.x):

cloudinary.UpdateMetadataField(string externalId, MetadataFieldUpdateParams field)

Go (cloudinary-go 1.x):

resp, err := cld.Admin.UpdateMetadataField(ctx, admin.UpdateMetadataFieldParams{})

cli:

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':

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

Cloudinary::Api.update_metadata_field("in_stock", {
  :"label" => "Now in stock",
  :"mandatory" => true  })

PHP (cloudinary_php 2.x):

$api->updateMetadataField("in_stock", [
  [ "label" => "Now in stock",
    "mandatory" => true]
]);

PHP (cloudinary_php 1.x (legacy)):

$api->update_metadata_field("in_stock", 
  [ "label" => "Now in stock",
    "mandatory" => true  ]
);

Python (cloudinary 1.x):

cloudinary.api.update_metadata_field("in_stock", {
  "label": "Now in stock",
  "mandatory": true  })

Node.js (cloudinary 1.x):

cloudinary.v2.api.update_metadata_field('in_stock', {
  "label": "Now in stock",
  "mandatory": true  });

Java (cloudinary 1.x):

SetMetadataField setField = new SetMetadataField();
setField.setLabel("Now in stock");
setField.setMandatory(true);
api.updateMetadataField("in_stock", setField);

.NET (CloudinaryDotNet 1.x):

var MetadataFieldUpdateParams = new StringMetadataFieldUpdateParams(){
  Label = "Now in stock",
  Mandatory = true  };
cloudinary.UpdateMetadataField("in_stock", MetadataFieldUpdateParams);

Go (cloudinary-go 1.x):

resp, err := cld.Admin.UpdateMetadataField(ctx, admin.UpdateMetadataFieldParams{
    FieldExternalID: "in_stock",
    Field: metadata.Field{
        Label:     "Now in stock",
        Mandatory: true}})

curl:

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:

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

{
  "type": "integer",
  "external_id": "in_stock",
  "label": "Now in stock",
  "mandatory": true,
  "default_value": 100,
  "validation": null
}

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

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.update_metadata_field_datasource(external_id, entries, options = {})

PHP (cloudinary_php 1.x (legacy)):

$api->update_metadata_field_datasource($external_id, $entries, $options = array());

Python (cloudinary 1.x):

cloudinary.api.update_metadata_field_datasource(external_id, entries, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.update_metadata_field_datasource(external_id, entries, options, callback);

Java (cloudinary 1.x):

api.updateMetadataFieldDatasource(String externalId, List<MetadataDataSource.Entry> entries);

.NET (CloudinaryDotNet 1.x):

cloudinary.UpdateMetadataDataSourceEntries(string externalId, MetadataDataSourceParams entries)

Go (cloudinary-go 1.x):

resp, err := cld.Admin.UpdateMetadataFieldDataSource(ctx, admin.UpdateMetadataFieldDataSourceParams{})

cli:

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':

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

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)):

$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):

cloudinary.api.update_metadata_field_datasource("color_id", [  
  {  
    "external_id":"color1",
    "value":"orange"
  },
  {  
    "external_id":"color2",
    "value":"black"
  }]
)

Node.js (cloudinary 1.x):

cloudinary.v2.api.update_metadata_field_datasource('color_id', {  
  "values":[{  
    "external_id":"color1",
    "value":"orange"
  },
  {  
    "external_id":"color2",
    "value":"black"
  }]
});

Java (cloudinary 1.x):

api.updateMetadataFieldDatasource("color_id", 
  new MetadataDataSource(Arrays.asList(
    new Entry("color1", "orange"),
    new Entry("color2", "black")))
);

.NET (CloudinaryDotNet 1.x):

var metadataDataSourceParams = new MetadataDataSourceParams(){  
  Values = [{  
    ExternalId = "color1",
    Value = "orange"
  },
  {  
    ExternalId = "color2",
    Value = "black"
  }]
};
cloudinary.UpdateMetadataDataSourceEntries("color_id", metadataDataSourceParams);

Go (cloudinary-go 1.x):

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:

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:

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

{ 
    "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

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.delete_metadata_field(external_id, options = {})

PHP (cloudinary_php 1.x (legacy)):

$api->delete_metadata_field($external_id, $options = array());

Python (cloudinary 1.x):

cloudinary.api.delete_metadata_field(external_id, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.delete_metadata_field(external_id, options, callback);

Java (cloudinary 1.x):

api.deleteMetadataField(String externalId);

.NET (CloudinaryDotNet 1.x):

cloudinary.DeleteMetadataField(string externalId)

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteMetadataField(ctx, admin.DeleteMetadataFieldParams{})

cli:

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':

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

Cloudinary::Api.delete_metadata_field("in_stock")

PHP (cloudinary_php 1.x (legacy)):

$api->delete_metadata_field("in_stock");

Python (cloudinary 1.x):

cloudinary.api.delete_metadata_field("in_stock")

Node.js (cloudinary 1.x):

cloudinary.v2.api.delete_metadata_field('in_stock');

Java (cloudinary 1.x):

api.deleteMetadataField("in_stock");

.NET (CloudinaryDotNet 1.x):

cloudinary.DeleteMetadataField("in_stock");

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteMetadataField(ctx, admin.DeleteMetadataFieldParams{
        FieldExternalID: "in_stock"})

curl:

curl 
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/metadata_fields/in_stock

cli:

cld admin delete_metadata_field "in_stock"

Sample response

{ 
   "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

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

Cloudinary::Api.delete_datasource_entries(external_id, external_ids, options = {})

PHP (cloudinary_php 1.x (legacy)):

$api->delete_datasource_entries($external_id, $external_ids, $options = array());

Python (cloudinary 1.x):

cloudinary.api.delete_datasource_entries(external_id, external_ids, **options)

Node.js (cloudinary 1.x):

cloudinary.v2.api.delete_datasource_entries(external_id, external_ids, options, callback);

Java (cloudinary 1.x):

api.deleteDatasourceEntries(String externalId, List<String> externalIds);

.NET (CloudinaryDotNet 1.x):

cloudinary.DeleteMetadataDataSourceEntries(string externalId, List<string> externalIds)

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteDataSourceEntries(ctx, admin.DeleteDataSourceEntriesParams{})

cli:

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 'color1' from the metadata field with external_id 'color_id':

Ruby PHP Python Node.js Java .NET Go cURL All

Ruby (cloudinary 1.x):

Cloudinary::Api.delete_datasource_entries("color_id", ["color4"])

PHP (cloudinary_php 1.x (legacy)):

$api->delete_datasource_entries("color_id", ["color4"]);

Python (cloudinary 1.x):

cloudinary.api.delete_datasource_entries("color_id", ["color4"])

Node.js (cloudinary 1.x):

cloudinary.v2.api.delete_datasource_entries('color_id', ["color4"]);

Java (cloudinary 1.x):

api.deleteDatasourceEntries("color_id", Arrays.asList("color4"));

.NET (CloudinaryDotNet 1.x):

cloudinary.DeleteMetadataDataSourceEntries("color_id", new List<string>{"color4"});

Go (cloudinary-go 1.x):

resp, err := cld.Admin.DeleteDataSourceEntries(ctx, admin.DeleteDataSourceEntriesParams{
        FieldExternalID: "color_id", 
        EntriesExternalIDs: []string{"color4"}})

curl:

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:

cld admin delete_datasource_entries "color_id" ["color4"]

Sample response

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

Metadata field structure

{
    "external_id": <string>,
    "type": <field_type_enum>,
    "label": <string>,
    "mandatory": <boolean>,
    "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_id`s 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`
`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_id`s, 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:

{
    "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:

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

less_than validation

Relevant for integer and date types:

{
    "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:

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

strlen validation

Relevant only for string types:

{
    "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:

"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:

{
    "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:

"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.

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

Each datasource_entry defines a single possible value for the field:

{
    "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:

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

✔️ Feedback sent!

✖️

Error

Unfortunately there's been an error sending your feedback.

Rate this page: