Admin API reference

The Admin API is a rate-limited API that provides full control of all uploaded media assets (resources), fetched social profile pictures, generated transformations and more.

API Overview

The Admin API is accessed using HTTPS to endpoints. By default, the API endpoint uses the following format:

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

For example, to list all video assets in the 'demo' account:

Copy to clipboard
GET https://api.cloudinary.com/v1_1/demo/resources/video

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

You can experiment with returning a list of the images on your own Cloudinary account by replacing the API_KEY, API_SECRET, and CLOUD_NAME in the cURL command below:

Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/resources/image

For most actions, request parameters are appended to the URL. In a few cases, they are passed as JSON objects. The response is in a JSON snippet. The response includes information about the action that was performed as well as data about the relevant assets.

The following sections provide additional details on working with the Admin API:

Using SDKs with the Admin API

Our server-side SDK libraries provide a wrapper for the Admin API, enabling you to use your native programming language of choice. When using an SDK, request building and authentication are handled automatically, and the JSON response is parsed and returned.

For example, you can use the following SDK command to return a listing of all image (the default resource_type) assets:

Ruby:
Copy to clipboard
Cloudinary::Api.resources
PHP:
Copy to clipboard
$api->resources();
Python:
Copy to clipboard
cloudinary.api.resources()
Node.js:
Copy to clipboard
cloudinary.v2.api.resources(
function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.resources(ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.ListResources();
CLI:
Copy to clipboard
cld admin resources

Using the CLI to access the Admin API

You can use the Cloudinary CLI (Command Line Interface) to interact with the admin API. This can provide an easy way to add automation to your workflows and manage your assets without the need for a formal coding environment or having to access your management console.

You can find instructions for setting up and using the CLI in the CLI reference.

Error handling

The Admin API returns the status of requests using HTTP status codes:

200: OK | Success.
400: Bad request.
401: Authorization required.
403: Not allowed.
404: Not found.
409: Already exists.
420: Rate limited.

The SDKs report errors by raising applicative exceptions. Additionally, an informative JSON message is returned. For example:

Copy to clipboard
{ "error": { "message": "Resource not found - 5traNge_nam3" } }

Usage limits

You can use the Admin API quite extensively, but it is a rate limited API. The specific limits depend on the plan your account is registered to. If you require more flexible limits, don’t hesitate to contact us.

Note
This limit refers only to Admin API requests, and not to requests that use the Upload API, which is not rate-limited. In some cases, you may be able to use certain methods of the Upload API to achieve some administration goals. For example, you can modify or remove tags for one or multiple resources using the tags method. You can modify many attributes of an individual resource using the explicit method, and you can return most details about a single (original) resource in response to any upload or explicit method call.

For each Admin API call, standard HTTP headers are returned with details on your current usage statistics, including your per-hour limit, remaining number of actions and the time the hourly count will be reset.

The header might look something like this:

Copy to clipboard
X-FeatureRateLimit-Limit: 500
X-FeatureRateLimit-Remaining: 499
X-FeatureRateLimit-Reset: Wed, 03 Oct 2012 08:00:00 GMT

You can use the SDKs to retrieve this data as follows:

Ruby:
Copy to clipboard
result = Cloudinary::Api.resources
result.rate_limit_allowed
=> 500
$ result.rate_limit_remaining
=> 499
$ result.rate_limit_reset_at
=> 2019-10-03 10:00:00 +0200
PHP:
Copy to clipboard
$result = $api->resources();
var_dump($result->rate_limit_allowed);
php > int(500)
var_dump($result->rate_limit_allowed);
php > int(500)
var_dump($result->rate_limit_remaining);
php > int(499)
var_dump($result->rate_limit_reset_at);
php > int(1570089600)
Python:
Copy to clipboard
result = cloudinary.api.resources()
result.rate_limit_allowed
>>>500
result.rate_limit_remaining
>>>499
result.rate_limit_reset_at
>>>(2019, 10, 3, 08, 0, 0, 0, 1, -1)
Node.js:
Copy to clipboard
cloudinary.v2.api.resources(
function(error, result) {
  console.log(result.rate_limit_allowed,
              result.rate_limit_remaining,
              result.rate_limit_reset_at);
});

> 500 499 Sun, 03 Oct 2019 08:00:00 GMT
Java:
Copy to clipboard
ApiResponse result = api.resources(ObjectUtils.emptyMap());
System.out.println(result.apiRateLimit().getLimit());
=> 500
System.out.println(result.apiRateLimit().getRemaining());
=> 499
System.out.println(result.apiRateLimit().getReset());
=> 2019-10-03 10:00:00 +0200
.Net:
Copy to clipboard
var result = cloudinary.ListResources();
result.Limit
// returns 500
result.Remaining
// returns 499
result.Reset
//returns  2019-10-03 10:00:00 +0200

Tip
You can also retrive rate limits details as well as transformation, bandwidth, and storage limits, and a variety of additional account usage data with the GET /usage method.

Pagination

The GET methods of the API return a limited set of results, ordered by the creation time of the relevant entities. You can control the number of results returned in a single request by specifying the max_results parameter. The default is 10 for most methods. There is also a maximum number of results you can request for a single API call (either 100 or 500 as documented for each of the relevant methods). DELETE methods also operate in chunks.

When a GET request has more results to return than max_results or when a DELETE request has more than 1000 entities to delete, the next_cursor value is returned as part of the response. You can then specify this cursor value as the next_cursor parameter of the following GET or DELETE request. For example, this enables you to iterate through the full list of uploaded resources, transformations, or tags in your Cloudinary account or to delete an entire set of entities that matches your deletion request.

Alternative data centers and endpoints (Premium feature)

By default, Cloudinary accounts use US-based data centers. In these cases, the endpoint format is as shown at the beginning of this Overview.

If the majority of your users are located in Europe or Asia, Cloudinary can set up your account to use our Europe (EU) or Asia Pacific (AP) data center. In that case, your endpoints will take the form:

https://api-eu.cloudinary.com/v1_1/:cloud_name/:action

OR

https://api-ap.cloudinary.com/v1_1/:cloud_name/:action

Note
This is a premium feature that is supported only for our Custom plans and must be arranged when the account is created. Contact support for more information.


Resources

Enables you to manage all the resources (assets) stored in your account.

Method Description
GET/resources/:resource_type(/:type) Get resources
GET/resources/:resource_type/tags/:tag Get resources by tag
GET/resources/:resource_type/context/ Get resources by context
GET/resources/:resource_type/moderations/:moderation_kind/:status Get resources in moderation queues
GET/resources/:resource_type/:type/:public_id Get the details of a single resource
GET/resources/search Search for resources
POST/resources/:resource_type/:type/:public_id Update details of an existing resource
POST/resources/:resource_type/:type/restore Restore resources
POST/resources/:resource_type/upload/update_access_mode Update access mode
DELETE/resources/:resource_type/:type Delete resources
DELETE/resources/:resource_type/tags/:tag Delete resources by tags
DELETE/derived_resources Delete derived resources

Get resources

Lists resources (assets) uploaded to your account.

Syntax

GET /resources(/:resource_type)(/:type)

Ruby:
Copy to clipboard
Cloudinary::Api.resources(options = {})
PHP:
Copy to clipboard
$api->resources($options = array());
Python:
Copy to clipboard
cloudinary.api.resources(**options)
Node.js:
Copy to clipboard
cloudinary.v2.api.resources(options, callback);
Java:
Copy to clipboard
api.resources(Map options);
.Net:
Copy to clipboard
cloudinary.ListResources(ListResourceParams params);
CLI:
Copy to clipboard
cld admin resources

Optional parameters

Parameter Type Description
resource_type String The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw, video.
type String The delivery type, relevant as a parameter only when using the SDKs (the type is included in the endpoint URL when using the REST API). Possible values: upload, private, authenticated, facebook, twitter, gravatar, youtube, hulu, vimeo, animoto, worldstarhiphop, dailymotion. Default: all.
prefix String Find all assets with a public ID that starts with the given prefix. The assets are sorted by public ID in the response.
public_ids String[] An array of public IDs. Get assets with the given public IDs (up to 100).

Note: Not supported for SDKs. Instead use the resources_by_ids SDK method.

max_results Integers Maximum number of assets to return (up to 500). Default: 10.
next_cursor String When a request has more results to return than max_results, the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of a following request.
start_at String Get assets that were created since the given timestamp. Supported unless prefix or public_ids were specified.
direction String/Integer Control the order of returned assets, according to the created_at date. Note: if a prefix is specified, this parameter is ignored and the results are sorted by public ID. Possible values: desc or -1 (default), asc or 1.
tags Boolean Whether to include the list of tag names assigned to each asset. Default: false.
context Boolean Whether to include key-value pairs of context associated with each asset. Default: false.
moderation Boolean Whether to include the image moderation status of each asset. Default: false.
metadata Boolean Whether to include the metadata fields and values set for each asset. Default: false.

Examples

Get all images:

Ruby:
Copy to clipboard
Cloudinary::Api.resources
PHP:
Copy to clipboard
$api->resources();
Python:
Copy to clipboard
cloudinary.api.resources()
Node.js:
Copy to clipboard
cloudinary.v2.api.resources(
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.resources(ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.ListResources();
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image
CLI:
Copy to clipboard
cld admin resources

Get uploaded images, up to a maximum of 30 results:

Ruby:
Copy to clipboard
Cloudinary::Api.resources(
  :type => :upload,
  :max_results => 30)
PHP:
Copy to clipboard
$api->resources(
  array("type" => "upload", "max_results" => 30));
Python:
Copy to clipboard
cloudinary.api.resources(type = "upload", max_results = 30)
Node.js:
Copy to clipboard
cloudinary.v2.api.resources(
  { type: 'upload', max_results: 30 }, 
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.resources(
  ObjectUtils.asMap("type", "upload", "max_results", 30));
.Net:
Copy to clipboard
var listResourcesParams = new ListResourcesParams(){
  Type = "upload",
  MaxResults = 30};
var listResourcesResult = cloudinary.ListResources(listResourcesParams);
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload
CLI:
Copy to clipboard
cld admin resources type=upload

Get all uploaded images with a given prefix:

Ruby:
Copy to clipboard
Cloudinary::Api.resources(
:type => :upload, 
:prefix => "sample")
PHP:
Copy to clipboard
$api->resources(
array(
  "type" => "upload", 
  "prefix" => "sample"));
Python:
Copy to clipboard
cloudinary.api.resources(
type = "upload", 
prefix = "sample")
Node.js:
Copy to clipboard
cloudinary.v2.api.resources(
{ type: 'upload', 
  prefix: 'sample' }, 
function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.resources(
ObjectUtils.asMap(
  "type", "upload", 
  "prefix", "sample"));
.Net:
Copy to clipboard
var listResourcesByPrefixParams = new listResourcesByPrefixParams(){
  Type = "upload",
  Prefix = "sample"};
var listResourcesResult = cloudinary.ListResources(listResourcesByPrefixParams);
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload?prefix=sample
CLI:
Copy to clipboard
cld admin resources type=upload prefix=sample

Get Facebook images:

Ruby:
Copy to clipboard
Cloudinary::Api.resources(:type => :facebook)
PHP:
Copy to clipboard
$api->resources(
array("type" => "facebook"));
Python:
Copy to clipboard
cloudinary.api.resources(type = "facebook"))
Node.js:
Copy to clipboard
cloudinary.v2.api.resources(
  { type: 'facebook' }, 
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.resources(
  ObjectUtils.asMap("type", "facebook"));
.Net:
Copy to clipboard
var listResourcesParams = new ListResourcesParams(){
  Type = "facebook"};
var listResourcesResult = cloudinary.ListResources(listResourcesParams);
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/facebook
CLI:
Copy to clipboard
cld admin resources type=facebook

Get raw uploaded files:

Ruby:
Copy to clipboard
Cloudinary::Api.resources(
  :resource_type => :raw)
PHP:
Copy to clipboard
$api->resources(
  array("resource_type" => "raw"));
Python:
Copy to clipboard
cloudinary.api.resources(resource_type = "raw")
Node.js:
Copy to clipboard
cloudinary.v2.api.resources(
  { resource_type: 'raw' }, 
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.resources(
  ObjectUtils.asMap("resource_type", "raw"));
.Net:
Copy to clipboard
var listResourcesParams = new ListResourcesParams(){
  ResourceType = "raw"};
var listResourcesResult = cloudinary.ListResources(listResourcesParams);
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/raw
CLI:
Copy to clipboard
cld admin resources resource_type=raw

Get all uploaded images with the given IDs:

Ruby:
Copy to clipboard
resources_by_ids
Cloudinary::Api.resources_by_ids(["user_photo_1", "user_photo_2"])
PHP:
Copy to clipboard
$api->resources_by_ids(array("user_photo_1", "user_photo_2"));
Python:
Copy to clipboard
cloudinary.api.resources_by_ids(["user_photo_1", "user_photo_2"])
Node.js:
Copy to clipboard
cloudinary.v2.api.resources_by_ids(["user_photo_1", "user_photo_2"],
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.resources_by_ids(Arrays.asList("user_photo_1", "user_photo_2"),
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
var publicIds = new List<string>(){"user_photo_1", "user_photo_2" };
cloudinary.ListResourceByPublicIds(publicIds);
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload?public_ids[]=user_photo_1&public_ids[]=user_photo_2
CLI:
Copy to clipboard
cld admin resources_by_ids user_photo_1,user_photo2

Sample response

Copy to clipboard
{
  "resources": [
    {
      "asset_id": "b1ce1d159bc3696e5a74d8b8aefbe707",
      "public_id": "face_center",
      "format": "jpg",
      "version": 1333013579,
      "resource_type": "image",
      "type": "upload",
      "created_at": "2012-03-29T09:32:59Z",
      "bytes": 128891,
      "width": 283,
      "height": 424,
      "backup": true,
      "access_mode": "public",
      "url": "http://res.cloudinary.com/demo/image/upload/v1333013579/face_center.jpg",
      "secure_url": "https://.../image/upload/v1333013579/face_center.jpg"
    },
    {
      "asset_id": "835d1cf89bd7c1b84dc4f53d35bc235f",
      "public_id": "12208495",
      "format": "jpg",
      "resource_type": "image",
      "type": "facebook",
      "created_at": "2012-10-06T17:18:52Z",
      "bytes": 0,
      "access_mode": "public",
      "url": "http://res.cloudinary.com/demo/image/facebook/12208495.jpg",
      "secure_url": "https://.../image/facebook/12208495.jpg"
    },
  ]
}

Get resources by tag

Lists resources (assets) with a specified tag. This method does not return deleted assets even if they have been backed up.

Syntax

GET /resources/:resource_type/tags/:tag

Ruby:
Copy to clipboard
Cloudinary::Api.resources_by_tag(tag, options = {})
PHP:
Copy to clipboard
$api->resources_by_tag($tag, $options = array());
Python:
Copy to clipboard
cloudinary.api.resources_by_tag(tag, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.resources_by_tag(tag, options, callback);
Java:
Copy to clipboard
api.resourcesByTag(String tag, Map options);
.Net:
Copy to clipboard
cloudinary.ListResourcesByTag(ListResourcesByTagParams params);
CLI:
Copy to clipboard
cld admin resources_by_tag (tag)

Required parameters

Parameter Type Description
tag String The assets to return that have this tag.

Optional parameters

Parameter Type Description
resource_type String The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw, video.
max_results Integer Maximum number of assets to return (maximum=500). Default: 10.
next_cursor String When a request has more results to return than max_results, the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of the following request.
direction String/Integer Control the order of returned assets, according to the created_at date. Note: if a prefix is specified, this parameter is ignored and the results are sorted by public ID. Possible values: desc or -1 (default), asc or 1.
tags Boolean Whether to include the list of tag names assigned to each asset. Default: false.
context Boolean Whether to include key-value pairs of context associated with each asset. Default: false.
moderations Boolean Whether to include image moderation status of each asset. Default: false.
metadata Boolean Whether to include the metadata fields and values set for each asset. Default: false.

Examples

Get all images by tag:

Ruby:
Copy to clipboard
Cloudinary::Api.resources_by_tag('mytag')
PHP:
Copy to clipboard
$api->resources_by_tag("mytag");
Python:
Copy to clipboard
cloudinary.api.resources_by_tag("mytag")
Node.js:
Copy to clipboard
cloudinary.v2.api.resources_by_tag("mytag", 
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.resourcesByTag("mytag", ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.ListResourcesByTag("mytag");
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/tags/mytag
CLI:
Copy to clipboard
cld admin resources_by_tag mytag

Get all raw files by tag:

Ruby:
Copy to clipboard
Cloudinary::Api.resources_by_tag('mytag',
  :resource_type => :raw)
PHP:
Copy to clipboard
$api->resources_by_tag("mytag",
  array("resource_type" => "raw"));
Python:
Copy to clipboard
cloudinary.api.resources_by_tag("mytag",
resource_type = "raw")
Node.js:
Copy to clipboard
cloudinary.v2.api.resources_by_tag("mytag", 
  { resource_type: 'raw'},
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.resourcesByTag("mytag", 
  ObjectUtils.asMap("resource_type", "raw"));
.Net:
Copy to clipboard
var listResourcesParams = new ListResourcesByTagParams(){
  Tag = "mytag",
  ResourceType = "raw"};
var listResourcesResult = cloudinary.ListResources(ListResourcesByTagParams);
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/raw/tags/mytag
CLI:
Copy to clipboard
cld admin resources_by_tag mytag resource_type=raw

Get resources by context

Retrieves resources (assets) with a specified context key. This method does not return deleted assets even if they have been backed up.

Syntax

GET /resources/:resource_type/context/

Ruby:
Copy to clipboard
Cloudinary::Api.resources_by_context(key, options = {})
PHP:
Copy to clipboard
$api->resources_by_context($key, $options = array());
Python:
Copy to clipboard
cloudinary.api.resources_by_context(key, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.resources_by_context(key, options, callback);
Java:
Copy to clipboard
api.resourcesByContext(String key, Map options);
.Net:
Copy to clipboard
Not supported by this SDK
CLI:
Copy to clipboard
cld admin resources_by_context $key $options

Required parameters

Parameter Type Description
key String Only assets with this context key are returned.

Optional parameters

Parameter Type Description
resource_type String The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw, video.
value String Only assets with this value for the context key are returned. If this parameter is not provided, all assets with the given context key are returned, regardless of the actual value of the key.
max_results Integer Maximum number of assets to return (maximum=500). Default: 10.
next_cursor String When a request has more results to return than max_results, the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of the following request.
direction String/Integer Control the order of returned assets, according to the created_at date. Note: if a prefix is specified, this parameter is ignored and the results are sorted by public ID. Possible values: desc or -1 (default), asc or 1.
tags Boolean Whether to include the list of tag names assigned to each asset. Default: false.
context Boolean Whether to include key-value pairs of context associated with each asset. Default: false.
moderations Boolean Whether to include image moderation status of each asset. Default: false.
metadata Boolean Whether to include the metadata fields and values set for each asset. Default: false.

Examples

Get images by context key:

Ruby:
Copy to clipboard
Cloudinary::Api.resources_by_context('mycontextkey')
PHP:
Copy to clipboard
$api->resources_by_context("mycontextkey");
Python:
Copy to clipboard
cloudinary.api.resources_by_context("mycontextkey")
Node.js:
Copy to clipboard
cloudinary.v2.api.resources_by_context("mycontextkey", 
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.resourcesByContext("mycontextkey", ObjectUtils.emptyMap());
.Net:
Copy to clipboard
Not supported by this SDK
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/context?key=mycontextkey
CLI:
Copy to clipboard
cld admin resources_by_context "mycontextkey"

Get video files by context key=value:

Ruby:
Copy to clipboard
Cloudinary::Api.resources_by_context('mycontextkey', 'mycontextvalue',
  :resource_type => :video)
PHP:
Copy to clipboard
$api->resources_by_context("mycontextkey", "mycontextvalue"
  array("resource_type" => "video"));
Python:
Copy to clipboard
cloudinary.api.resources_by_context("mycontextkey", "mycontextvalue"
  resource_type = "video")
Node.js:
Copy to clipboard
cloudinary.v2.api.resources_by_context("mycontextkey", "mycontextvalue", 
  { resource_type: 'video'}, 
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.resourcesByContext("mycontextkey", "mycontextvalue", 
  ObjectUtils.asMap("resource_type", "video"));
.Net:
Copy to clipboard
Not supported by this SDK
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/video/context?key=mycontextkey&value=mycontextvalue
CLI:
Copy to clipboard
cld admin resources_by_context "mycontextkey" value="mycontextvalue" resource_type="video"

Get resources in moderation queues

Retrieves resources (assets) with a particular status from a specified moderation queue.

Syntax

GET /resources/:resource_type/moderations/:moderation_kind/:status

Ruby:
Copy to clipboard
Cloudinary::Api.resources_by_moderation(moderation_kind, status, options = {})
PHP:
Copy to clipboard
$api->resources_by_moderation($moderation_kind, $status, $options = array());
Python:
Copy to clipboard
cloudinary.api.resources_by_moderation(moderation_kind, status, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.resources_by_moderation(moderation_kind, status, options, callback);
Java:
Copy to clipboard
cloudinary.api().resourcesByModeration(String moderation_kind, String status, Map options);
.Net:
Copy to clipboard
cloudinary.ListResourcesByModerationStatus(ModerationStatus Params);
CLI:
Copy to clipboard
cld admin resources_by_moderation (moderation_kind, status)

Required parameters

Parameter Type Description
moderation_kind String The type of moderation queue to list. Possible values: manual, webpurify, aws_rek, metascan.
status String The moderation status of assets to retrieve. Possible values: pending, approved, rejected.

Optional parameters

Parameter Type Description
resource_type String The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw, video.
max_results Integer Maximum number of assets to return (maximum=500). Default: 10.
next_cursor String When a request has more results to return than max_results, the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of the following request.
direction String/Integer Control the order of returned assets, according to the created_at date. Note: if a prefix is specified, this parameter is ignored and the results are sorted by public ID. Possible values: desc or -1 (default), asc or 1.
tags Boolean Whether to include the list of tag names assigned to each asset. Default: false.
context Boolean Whether to include key-value pairs of context associated with each asset. Default: false.
moderations Boolean Whether to include image moderation status of each asset. Default: false.
metadata Boolean Whether to include the metadata fields and values set for each asset. Default: false.

Examples

Get images pending manual moderation:

Ruby:
Copy to clipboard
Cloudinary::Api.resources_by_moderation("manual", "pending")
PHP:
Copy to clipboard
$api->resources_by_moderation("manual", "pending");
Python:
Copy to clipboard
cloudinary.api.resources_by_moderation("manual", "pending")
Node.js:
Copy to clipboard
cloudinary.v2.api.resources_by_moderation('manual', 'pending',
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
cloudinary.api().resourcesByModeration("manual", "pending",
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.ListResourcesByModerationStatus("manual", "pending");
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/moderations/manual/pending
CLI:
Copy to clipboard
cld admin resources_by_moderation manual pending

Get images automatically approved by the WebPurify add-on:

Ruby:
Copy to clipboard
Cloudinary::Api.resources_by_moderation("webpurify", "approved")
PHP:
Copy to clipboard
$api->resources_by_moderation("webpurify", "approved");
Python:
Copy to clipboard
cloudinary.api.resources_by_moderation("webpurify", "approved")
Node.js:
Copy to clipboard
cloudinary.v2.api.resources_by_moderation('webpurify', 'approved',
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
cloudinary.api().resourcesByModeration("webpurify", "approved",
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.ListResourcesByModerationStatus("webpurify", "approved");
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/moderations/webpurify/approved
CLI:
Copy to clipboard
cld admin resources_by_moderation webpurify approved

Sample response

Copy to clipboard
{
   "resources":
    [{
      "asset_id": "e590ea35ca6f56ee383e0437e43e1c54",
      "public_id": "q7vcvrfjm9mj4bfp3qc8",
      "format": "jpg",
      "version": 1570976812,
      "resource_type": "image",
      "type": "upload",
      "created_at": "2014-03-02T21:06:43Z",
      "bytes": 120253,
      "width": 864,
      "height": 576,
      "backup": true,
      "access_mode": "public",
      "url":
       "http://res.cloudinary.com/demo/image/upload/v1570976812/q7vcvrfjm9mj4bfp3qc8.jpg",
      "secure_url":
       "https://res.cloudinary.com/demo/image/upload/v1570976812/q7vcvrfjm9mj4bfp3qc8.jpg"
     },
     {
      "asset_id": "53270b5120ab81ede6f570a203677652",
      "public_id": "zp4fgdbabhlwwa7bxu84",
      "format": "jpg",
      "version": 1570977154,
      "resource_type": "image",
      "type": "upload",
      "created_at": "2014-03-02T21:06:39Z",
      "bytes": 120253,
      "width": 864,
      "height": 576,
      "backup": true,
      "access_mode": "public",
      "url":
       "http://res.cloudinary.com/demo/image/upload/v1570977154/zp4fgdbabhlwwa7bxu84.jpg",
      "secure_url":
       "https://res.cloudinary.com/demo/image/upload/v1570977154/zp4fgdbabhlwwa7bxu84.jpg"
     }
   ]
}

Get the details of a single resource

Return details of the requested resource (asset) as well as all its derived assets.

GET /resources/:resource_type/:type/:public_id

Syntax

Ruby:
Copy to clipboard
Cloudinary::Api.resource(public_id, options = {})
PHP:
Copy to clipboard
$api->resource($public_id, $options = array());
Python:
Copy to clipboard
cloudinary.api.resource(public_id, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.resource(public_id, options, callback);
Java:
Copy to clipboard
api.resource(String public_id, Map options);
.Net:
Copy to clipboard
cloudinary.GetResource(ResourceParams params);
CLI:
Copy to clipboard
cld admin resource (public_id)

Required parameters

Parameter Type Description
public_id String The public ID of the asset.

Optional parameters

Parameter Type Description
resource_type String The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API).

Note: use video for all video and audio assets, such as .mp3.

Possible values: image (default), raw, video.

type String The delivery type, relevant as a parameter only when using the SDKs (the type is included in the endpoint URL when using the REST API).

Possible values: upload, private, authenticated, facebook, twitter, gravatar, youtube, hulu, vimeo, animoto, worldstarhiphop, dailymotion. Default: all.

colors Boolean Whether to include color information: predominant colors and histogram of 32 leading colors. Default: false.
image_metadata Boolean Whether to include IPTC, XMP, and detailed Exif metadata.
Default: false.

Returned metadata by type:

- Images: PixelsPerUnitX, PixelsPerUnitY, PixelUnits, Colorspace, and DPI.

- Audio and video: audio_codec, audio_bit_rate, audio_frequency, audio_profile ,channels, channel_layout.

- Video: pix_format, codec, level, profile, video_duration, video_bit_rate, dar.

Note: Using this parameter also returns the asset's ETag value for all asset types, including raw.

exif Boolean Deprecated. Use image_metadata instead. Default: false.
faces Boolean Whether to include a list of coordinates of detected faces. Default: false.
quality_analysis Boolean Whether to return quality analysis scores for the image. Default: false.
accessibility_analysis Boolean Whether to return accessibility analysis scores for the image. Default: false.
pages Boolean Whether to report the number of pages in multi-page documents (e.g., PDF). Default: false.
phash Boolean Whether to include the perceptual hash (pHash) of the uploaded photo for image similarity detection. Default: false.
coordinates Boolean Whether to include previously specified custom cropping coordinates and faces coordinates. Default: false.
versions Boolean Whether to include details of all the backed up versions of the asset. Default: false.
max_results Integer Maximum number of derived assets to return (maximum=500). Default: 10.
derived_next_cursor String If there are more derived images than max_results, the derived_next_cursor value is returned as part of the response. You can then specify this value as the derived_next_cursor parameter of the following request.

Examples

Uploaded image details:

Ruby:
Copy to clipboard
Cloudinary::Api.resource('sample')
PHP:
Copy to clipboard
$api->resource("sample");
Python:
Copy to clipboard
cloudinary.api.resource("sample")
Node.js:
Copy to clipboard
cloudinary.v2.api.resource('sample',
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.resource("sample", ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.GetResource("sample");
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/sample
CLI:
Copy to clipboard
cld admin resource sample

Faces, colors, image metadata and versions details:

Ruby:
Copy to clipboard
Cloudinary::Api.resource('sample',
  :faces => true, 
  :colors => true, 
  :image_metadata => true,
  :versions => true)
PHP:
Copy to clipboard
$api->resource("sample",
  array(
    "faces" => TRUE, 
    "colors" => TRUE, 
    "image_metadata" => TRUE,
    "versions" => TRUE));
Python:
Copy to clipboard
cloudinary.api.resource("sample",
  faces = True, 
  colors = True, 
  image_metadata = True,
  versions = True)
Node.js:
Copy to clipboard
cloudinary.v2.api.resource('sample', 
  { faces: true, 
    colors: true, 
    image_metadata: true,
    versions: true },
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.resource("sample", 
  ObjectUtils.asMap(
    "faces", true,
    "colors", true, 
    "image_metadata", true,
    "versions", true));
.Net:
Copy to clipboard
var getResource = new GetResourceParams("sample"){
  Faces = true,

Colors = ImageMetadata = Versions = true };
var info = cloudinary.GetResource(getResource);
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/sample?faces=1&colors=1&image_metadata=1&versions=1
CLI:
Copy to clipboard
cld admin resource sample faces=true colors=true image_metadata=true versions=true

Facebook picture details:

Ruby:
Copy to clipboard
Cloudinary::Api.resource('4', 
  :type => :facebook)
PHP:
Copy to clipboard
$api->resource("4", 
  array("type" => "facebook"));
Python:
Copy to clipboard
cloudinary.api.resource("4", 
  type = "facebook")
Node.js:
Copy to clipboard
cloudinary.v2.api.resource('4', 
  { type: 'facebook' },
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.resource("4", 
  ObjectUtils.asMap("type", "facebook"));
.Net:
Copy to clipboard
var getResource = new GetResourceParams("4"){
Type = "facebook" };
var info = cloudinary.GetResource(getResource);
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/facebook/4
CLI:
Copy to clipboard
cld admin resource "4" type=facebook

Uploaded raw file details:

Ruby:
Copy to clipboard
Cloudinary::Api.resource('rwkaliebnufp3bxyrvyo.txt',
  :resource_type => :raw)
PHP:
Copy to clipboard
$api->resource("rwkaliebnufp3bxyrvyo.txt",
  array("resource_type" => "raw"));
Python:
Copy to clipboard
cloudinary.api.resource("rwkaliebnufp3bxyrvyo.txt",
  resource_type = "raw")
Node.js:
Copy to clipboard
cloudinary.v2.api.resource('rwkaliebnufp3bxyrvyo.txt', 
  { resource_type: 'raw'},
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.resource("rwkaliebnufp3bxyrvyo.txt",
  ObjectUtils.asMap("resource_type", "raw"));
.Net:
Copy to clipboard
var getResource = new GetResourceParams("rwkaliebnufp3bxyrvyo.txt"){
ResourceType = "raw" };
var info = cloudinary.GetResource(getResource);
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/raw/upload/rwkaliebnufp3bxyrvyo.txt
CLI:
Copy to clipboard
cld admin resource rwkaliebnufp3bxyrvyo.txt resource_type=raw

Sample response

This sample response is from the request including faces, colors, image metadata and versions:

Copy to clipboard
{
    "asset_id": "d86882d7788f5d1d702cb63418f082a6",
    "public_id": "sample",
    "format": "jpg",
    "version": 1312461204,
    "resource_type": "image",
    "type": "upload",
    "created_at": "2011-08-04T12:33:24Z",
    "bytes": 120253,
    "width": 864,
    "height": 576,
    "access_mode": "public",
    "url": "http://res.cloudinary.com/demo/image/upload/v1312461204/sample.jpg",
    "secure_url": "https://.../image/upload/v1312461204/sample.jpg",
    "tags": [
      "flower",
      "plant",
      "naturet"
    ],
    "context": {
      "custom": {
        "alt": "sample flower",
        "caption": "beautiful flower"
      }
    },
    "next_cursor": "041a39fc10971b9eabd4993470f6bfaf",
    "derived": [
      {
        "transformation": "c_fill,w_100,h_100",
        "format": "jpg",
        "bytes": 7112,
        "id": "8267a869b62a93a59248f35d7f124c1f",
        "url": "http://.../demo/image/upload/c_fill,w_100,h_100/v1312461204/sample.jpg",
        "secure_url": "https://.../image/upload/c_fill,w_100,h_100/v1312461204/sample.jpg"
      },
      {
        "transformation": "w_230,h_168,c_fit",
        "format": "jpg",
        "bytes": 19173,
        "id": "383e22a57167445552a3cdc16f0a0c85",
        "url": "http://.../demo/image/upload/w_230,h_168,c_fit/v1312461204/sample.jpg",
        "secure_url": "https://.../image/upload/w_230,h_168,c_fit/v1312461204/sample.jpg"
      }
    ],

    "faces": [[98,74,61,83], [140,130,52,71]],

    "colors": [["#162E02",6.7], ["#385B0C",6.3], ["#F3285C",5.0], ["#B3CB6E",5.0], ["#688F1C",4.4], ["#324D07",4.4], ["#8EAA34",4.3], ["#4F6D0D",4.2], ["#789446",4.1], ["#DF1327",3.9], ["#A10B12",3.7], ["#273804",3.4], ["#0D1802",3.4], ["#D5E191",3.2], ["#646E20",3.1], ["#94AF4D",2.9], ["#FB54A9",2.8], ["#48570B",2.7], ["#ACC655",2.7], ["#FCA2D9",2.7], ["#63110A",2.6], ["#E9B327",2.2], ["#6D644D",2.1], ["#6D8D12",2.0], ["#8F9F27",1.9], ["#C3573E",1.8], ["#CFD76E",1.6], ["#A0B058",1.6], ["#FCD0E9",1.6], ["#728F2D",1.4], ["#F958A1",1.4], ["#D1B694",1.0]],

    "predominant": {
      "google": [
        [
          "yellow",
          52.9
        ],
        [
          "pink",
          13.5
        ],
        [
          "red",
          12.0
        ],
        [
          "black",
          10.1
        ],
        [
          "green",
          6.3
        ]
      ]
    },

    "versions": [
        {
            "version_id": "d214063097a43d1d1293db61a397f60f",
            "version": "1312461204",
            "format": "jpg",
            "size": 109669,
            "time": "2011-08-04T12:33:24+00:00",
            "restorable": false
        }
    ]
}

Search for resources

Search allows you fine control on filtering and retrieving information on all the resources (assets) in your account with the help of query expressions in a Lucene-like query language.

For detailed information on the search method and building expressions, see the Search API documentation.

Note
Request parameters cannot be appended to the endpoint URL as in the other Admin API methods. Search API parameters are passed as JSON data.

Syntax

GET /resources/search

Ruby:
Copy to clipboard
result = Cloudinary::Search.execute
PHP:
Copy to clipboard
result = \Cloudinary\search->execute();
Python:
Copy to clipboard
result = cloudinary.Search().expression().execute()
Node.js:
Copy to clipboard
cloudinary.v2.search.execute().then(result=>console.log(result));
Java:
Copy to clipboard
result = cloudinary.search().execute();
.Net:
Copy to clipboard
SearchResult result = cloudinary.Search().Execute();
CLI:
Copy to clipboard
cld search

Optional parameters

Parameter Type Description
expression String The (Lucene-like) string expression specifying the search query. If this parameter is not provided then all resources are listed (up to max_results). For details, see the expressions section in the Search API documentation..
sort_by String[] An array of string values representing a key value pair, where the key is the field to sort by and the value is the direction. Valid sort directions are asc or desc. If this parameter is not provided then the results are sorted by descending creation date. You can specify more than one sort_by parameter; results will be sorted according to the order of the fields provided.
max_results Integer Maximum number of assets to return (maximum=500). Default: 10.
next_cursor String When a request has more results to return than max_results, the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of the following request.
with_field String The name of an additional asset attribute to include for each asset in the response. You can specify more than one with_field parameter. Possible value: context, tags, and for Tier 2 also image_metadata, and image_analysis.
aggregate String (Tier 2 only) The name of a field (attribute) for which an aggregation count should be calculated and returned in the response. You can specify more than one aggregate parameter. Supported values: resource_type, type, pixels (only the image assets in the response are aggregated), duration (only the video assets in the response are aggregated), format, and bytes. For aggregation fields without discrete values, the results are divided into categories. For example:
- bytes are divided into small (<500 kb), medium (500 kb - 5 mb), large (5 mb - 100 mb), and huge (>100 mb).
- Video duration is divided into short (< 3 minutes), medium (3-12 min), and long (> 12 min).

Examples

Find assets containing 'cat' in any field (attribute), include context metadata and tags in the details of each resource, and limit the returned results to 10 resources:

Ruby:
Copy to clipboard
result = Cloudinary::Search
  .expression('cat')
  .with_field('context')
  .with_field('tags')
  .max_results(10)
  .execute
PHP:
Copy to clipboard
result = \Cloudinary\search
  ->expression('cat')
  ->with_field('context')
  ->with_field('tags')
  ->max_results(10)
  ->execute();
Python:
Copy to clipboard
result = cloudinary.Search()\
  .expression('cat')\
  .with_field('context')\
  .with_field('tags')\
  .max_results('10')\
  .execute()
Node.js:
Copy to clipboard
cloudinary.v2.search
  .expression('cat')
  .with_field('context')
  .with_field('tags')
  .max_results(10)
  .execute().then(result=>console.log(result));
Java:
Copy to clipboard
result = cloudinary.search()
  .expression("cat")
  .withField("context")
  .withField("tags")
  .maxResults(10)
  .execute();
.Net:
Copy to clipboard
SearchResult result = cloudinary.Search()
  .Expression("cat")
  .WithField("context")
  .WithField("tags")
  .MaxResults(10)
  .Execute();
cURL:
Copy to clipboard
curl \
  -H "Content-Type: application/json" \
  -d '{
        "expression": "cat",
        "with_field": ["context", "tags"],
        "max_results": 10
      }' \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/search
CLI:
Copy to clipboard
cld search cat -f context -f tags -n 10

Find assets containing 'cat' in any field but not 'kitten' in the tags field, sort the results by public_id in descending order, and calculate an aggregation count based on the values of the format field:

Ruby:
Copy to clipboard
result = Cloudinary::Search
  .expression('cat AND -tags:kitten')
  .sort_by('public_id','desc')
  .aggregate('format')
  .execute
PHP:
Copy to clipboard
result = \Cloudinary\search()
  ->expression('cat AND -tags:kitten')
  ->sort_by('public_id','desc')
  ->aggregate('format')
  ->execute();
Python:
Copy to clipboard
result = cloudinary.Search()
  .expression('cat AND -tags:kitten')
  .sort_by('public_id','desc')
  .aggregate('format')
  .execute()
Node.js:
Copy to clipboard
cloudinary.v2.search
  .expression('cat AND -tags:kitten')
  .sort_by('public_id','desc')
  .aggregate('format')
  .execute().then(result=>console.log(result));
Java:
Copy to clipboard
result = cloudinary.search()
  .expression("cat AND -tags:kitten")
  .sortBy("public_id","desc")
  .aggregate("format")
  .execute();
.Net:
Copy to clipboard
SearchResult result = cloudinary.Search()
  .Expression("cat AND -tags:kitten")
  .SortBy("public_id","desc")
  .Aggregate("format")
  .Execute();
cURL:
Copy to clipboard
curl \
  -H "Content-Type: application/json" \
  -d '{
        "expression": "cat AND -tags:kitten",
        "sort_by": [{"public_id": "desc"}],
        "aggregate": ["format"]
      }' \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/search
CLI:
Copy to clipboard
cld search "cat AND -tags:kitten" -s public_id desc -a format

Sample response

Copy to clipboard
{
    "total_count": 32,
    "time": 30,
    "aggregations": {
      "format": {
        "png": 4,
        "jpg": 21,
        "mp4": 3,
        "doc": 4
      }
    },
    "next_cursor": "b16b8bd80426df43a107f26b0348",
    "resources": [
    {
      "public_id": "sample",
      "folder": "",
      "filename": "sample",
      "format": "png",
      "version": 1492606756,
      "resource_type": "image",
      "type": "upload",
      "created_at": "2017-04-03T09:56:49+00:00",
      "uploaded_at": "2017-04-19T12:59:16+00:00",
      "bytes": 3381,
      "backup_bytes": 16905,
      "width": 241,
      "height": 51,
      "aspect_ratio": 4.7254901960784315,
      "pixels": 12291,
      "context": {},
      "image_analysis": { 
        "face_count": 0,
        "faces": [],
        "grayscale": true,
        "illustration_score": 1,
        "transparent": false,
        "colors": {
          "gray": 96.7
        }
      },
      "url": "http://res.cloudinary.com/demo/image/upload/v1492606756/sample.png",
      "secure_url": "https://res.cloudinary.com/demo/image/upload/v1492606756/sample.png",
      "status": "active",
      "access_mode": "public"
    },
    {
      "public_id": "dog",
       
       
    }
    
}

Update details of an existing resource

Update one or more of the attributes associated with a specified resource (asset). Note that you can also update many attributes of an existing asset using the explicit method, which is not rate limited.

Syntax

POST /resources/:resource_type/:type/:public_id

Ruby:
Copy to clipboard
Cloudinary::Api.update(public_id, options = {})
PHP:
Copy to clipboard
$api->update($public_id, $options = array());
Python:
Copy to clipboard
cloudinary.api.update(public_id, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.update(public_id, options, callback);
Java:
Copy to clipboard
cloudinary.api().update(String public_id, Map options);
.Net:
Copy to clipboard
cloudinary.Update(UpdateParams params);
CLI:
Copy to clipboard
cld admin update (public_id)

Required parameters

Parameter Type Description
public_id String The public ID of the asset to update.

Optional parameters

Parameter Type Description
resource_type String The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw, video.
type String The delivery type, relevant as a parameter only when using the SDKs (the type is included in the endpoint URL when using the REST API). Possible values: upload, private, authenticated, facebook, twitter, gravatar, youtube, hulu, vimeo, animoto, worldstarhiphop, dailymotion. Default: all.
tags String A comma-separated list of tag names to assign to the uploaded asset for later group reference.
context String A map (using the SDKs) or pipe-separated list (for REST API calls) of key-value pairs of general textual context metadata to attach to an uploaded asset. The context values of uploaded files are available for fetching using the Admin API. For example: `alt=My image
metadata String A map (supported for Java SDK only) or pipe-separated list (for REST API calls) of custom metadata fields (by external_id) and the values to assign to each of them. The =, " and ❘ characters can be supported as values when escaped with a prepended backslash (\).
For example: in_stock_id=50❘color_id=[\"green\",\"red\"].
face_coordinates String List of coordinates of faces contained in an uploaded image. The given coordinates are used for cropping uploaded images using the face or faces gravity mode. The specified coordinates override the automatically detected faces. Each face is specified by the X & Y coordinates of the top left corner and the width & height of the face. The coordinates are comma separated while faces are concatenated with a pipe (`
custom_coordinates String Coordinates of an interesting region contained in an uploaded image. The given coordinates are used for cropping uploaded images using the custom gravity mode. The region is specified by the X & Y coordinates of the top left corner and the width & height of the region. For example: 85,120,220,310.
quality_override Integer Sets a quality value for this asset that will override any automatic quality transformations (q_auto) for this specific asset.
moderation_status String Manually set image moderation status or override previously automatically moderated images by approving or rejecting. Possible values: approved, rejected.
auto_tagging Decimal Whether to assign tags to an image according to detected scene categories with confidence score higher than the given value. See the Google Automatic Video Tagging, Google Auto Tagging, Imagga Auto Tagging, Amazon Rekognition Auto Tagging, and Amazon Rekognition Celebrity Detection add-ons for more details. Range: 0.0 to 1.0
detection String Set to adv_face or aws_rek_face to extract an extensive list of face attributes from an image using the Advanced Facial Attribute Detection or Amazon Rekognition Celebrity Detection add-ons.

Relevant for images only.

ocr String Set to adv_ocr to extract all text elements in an image as well as the bounding box coordinates of each detected element using the OCR text detection and extraction add-on.
Relevant for images only.
raw_convert String Asynchronously generates a related file based on the uploaded file.

  • Set to aspose to automatically create a PDF or other image format from a raw Office document using the Aspose Document Conversion add-on.
  • Set to google_speech to instruct the Google AI Video Transcription add-on to generate an automatic transcript raw file from an uploaded video.
  • Set to extract_text to extract all the text from a PDF file and store it in a raw file. The public ID of the generated raw file will be in the format: [pdf_public_id].extract_text.json.
See also: Converting raw files.
categorization String A comma-separated list of the categorization add-ons to run on the asset. Set to google_tagging, google_video_tagging, imagga_tagging and/or aws_rek_tagging to automatically classify the scenes of the uploaded asset. See the Google Automatic Video Tagging, Google Auto Tagging, Imagga Auto Tagging and Amazon Rekognition Auto Tagging add-ons for more details.
background_removal String Automatically remove the background of an image using an add-on. Relevant for images only.
access_control access_types[] An array of access_types for the asset. The asset is accessible as long as one of the access types is valid. Possible values for each access type:

  • token - requires either Token-based authentication or Cookie-based authentication for accessing the resource. For example: access_type: 'token'
  • anonymous - allows public access to the resource. The anonymous access type should also include start and end dates (in ISO 8601 format) defining when the resource is publically available. For example: access_type: 'anonymous', start: '2017-12-15T12:00Z', end: '2018-01-20T12:00Z'

Examples

Update tags and moderation status of an uploaded image:

Ruby:
Copy to clipboard
Cloudinary::Api.update("image1",
  :tags => "important",
  :moderation_status => "approved")
PHP:
Copy to clipboard
$api->update("image1",
  array(
    "tags" => "important", 
    "moderation_status" => "approved"));
Python:
Copy to clipboard
cloudinary.api.update("image1",
  tags = "important",
  moderation_status = "approved")
Node.js:
Copy to clipboard
cloudinary.v2.api.update("image1", 
  { tags: "important", 
    moderation_status: "approved"},
    function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
cloudinary.api().update("image1",
  ObjectUtils.asMap(
    "tags", "important",
    "moderation_status", "approved"));
.Net:
Copy to clipboard
var updateParams = new UpdateParams("image1"){
  Tags = "important",
  ModerationStatus = "approved"};
var updateResult = cloudinary.Update(updateParams);
cURL:
Copy to clipboard
curl \
 -d "tags=important&moderation_status=approved" \
 -X POST \
 https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/image1
CLI:
Copy to clipboard
cld admin update image1 tags="important" moderation_status="approved"

Restore resources

Restores one or more resources (assets) from backup.

Syntax

POST /resources/:resource_type/:type/restore

Ruby:
Copy to clipboard
Cloudinary::Api.restore(public_ids = {}, options = {})
PHP:
Copy to clipboard
$api->restore($public_ids = array(), $options = array());
Python:
Copy to clipboard
cloudinary.api.restore(**public_ids, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.restore(public_ids, options, callback);
Java:
Copy to clipboard
api.restore(Map public_ids, Map options);
.Net:
Copy to clipboard
cloudinary.Restore(RestoreParams params);
CLI:
Copy to clipboard
cld admin restore (public_ids)

Required parameters

Parameter Type Description
public_ids String[] The public IDs of (deleted or existing) backed up assets to restore. By default, the latest backed up version of the asset is restored. If the versions parameter is specified, the corresponding version of each public ID is restored.

Optional parameters

Parameter Type Description
resource_type String The asset type of the requested assets. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw, video.
type String The delivery type of the requested assets, relevant as a parameter only when using the SDKs (the type is included in the endpoint URL when using the REST API). Possible values: upload, private, authenticated, Default: image.
versions String[] The version of each of the assets to restore. Specify the version_id for each public ID. Use the resource method to list details of backed up versions of an asset.

Examples

Restore deleted resources by public_ids 'image1' and 'image2':

Ruby:
Copy to clipboard
Cloudinary::Api.restore(["image1", "image2"])
PHP:
Copy to clipboard
$api->restore(array("image1", "image2"));
Python:
Copy to clipboard
cloudinary.api.restore(["image1", "image2"])
Node.js:
Copy to clipboard
cloudinary.v2.api.restore(["image1", "image2"],
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
cloudinary.api().restore(Arrays.asList("image1", "image2"),
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
var publicIds = new List<string>(){"image1", "image2"};
cloudinary.Restore(publicIds);
cURL:
Copy to clipboard
curl \
 -d "public_ids[]=image1&public_ids[]=image2" \
 -X POST \
 https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/restore
CLI:
Copy to clipboard
cld admin restore "image1","image2"

Restore specific versions of deleted resources by public_ids 'image1' and 'image2':

Ruby:
Copy to clipboard
Cloudinary::Api.restore(["image1", "image2"], versions => ["c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f"])
PHP:
Copy to clipboard
$api->restore(array("image1", "image2"), "versions" => array("c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f"));
Python:
Copy to clipboard
cloudinary.api.restore(["image1", "image2"], versions = ["c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f"])
Node.js:
Copy to clipboard
cloudinary.v2.api.restore(["image1", "image2"], versions: ["c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f"],
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
cloudinary.api().restore(Arrays.asList("image1", "image2"), ObjectUtils.asMap("versions", Arrays.asList("c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f")),
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
var publicIds = new List<string>(){"image1", "image2"};
var versionIds = new List<string>(){"c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f" };
var restoreParams = new RestoreParams(){
  PublicIds = publicIds,
  Versions = versionIds};
cloudinary.Restore(restoreParams);
cURL:
Copy to clipboard
curl \
 -d "public_ids[]=image1&public_ids[]=image2&versions[]=c3fe4be5921eb89acd9af738c892f654&versions[]=d214063097a43d1d1293db61a397f60f" \
 -X POST \
 https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/restore
CLI:
Copy to clipboard
cld admin restore "image1","image2" versions="c3fe4be5921eb89acd9af738c892f654","d214063097a43d1d1293db61a397f60f"

Sample response

The details of the restored resources (note that when specific versions are restored, they are given new version IDs):

Copy to clipboard
{
  "image1": 
  {
    "asset_id": "9ec64ab330767f4c1e939e2b4fcbaeac",
    "public_id": "image1", 
    "version": 1574260348, 
    "version_id": "8a7d06c83656a2a2d1d559f2ea5661f7",
    "signature": "b7f24977706edff33686e053e5a57a1684ff260b", 
    "width": 5472, 
    "height": 3648, 
    "format": "jpg", 
    "resource_type": "image", 
    "created_at": "2019-11-20T14:32:28Z", 
    "tags": [], 
    "bytes": 3477251, 
    "type": "upload", 
    "placeholder": false,
    "access_mode": "public"
  }
  "image2": 
  {
    "asset_id": "835d1cf89bd7c1b84dc4f53d35bc235f",
    "public_id": "image2", 
    "version": 1574261348, 
    "version_id": "80541d2d17a4485b84a7d264b3e778d0",
    "signature": "1aa2b977b02adffa268ae05a22aa57a1682fa202", 
    "width": 5234, 
    "height": 3234, 
    "format": "jpg", 
    "resource_type": "image", 
    "created_at": "2019-10-20T12:34:18Z", 
    "tags": [], 
    "bytes": 2427151, 
    "type": "upload", 
    "placeholder": false,
    "access_mode": "public"
  }
}

Update access mode

Update the access_mode of resources (assets) by public_id(s), by tag, or by prefix. When access_mode = 'authenticated', uploaded resources of type 'upload' behave as if they are of type 'authenticated'. The resource can later be made public by changing its access_mode to 'public', without having to update any image delivery URLs. In the case where public images are reverted to authenticated by changing their access_mode to 'authenticated', all the existing original and derived versions of the images are also invalidated on the CDN.

Note
You can only update the access_mode of an asset that was already assigned an access_mode when uploaded. For more details, see: Upload method and Access mode.

Syntax

POST /resources/:resource_type/upload/update_access_mode

Ruby:
Copy to clipboard
Cloudinary::Api.update_resources_access_mode(access_mode, options = {})
PHP:
Copy to clipboard
$api->update_resources_access_mode($access_mode, $options = array());
Python:
Copy to clipboard
cloudinary.api.update_resources_access_mode(access_mode, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.update_resources_access_mode(access_mode, options, callback);
Java:
Copy to clipboard
api.updateResourcesAccessMode(String access_mode, Map options);
.Net:
Copy to clipboard
cloudinary.UpdateResourceAccessMode(RestoreParams params);
CLI:
Copy to clipboard
Not supported by the CLI

Required parameters

Parameter Type Description
access_mode String The new access mode to be set. Possible values: public, authenticated.
One of the following:
- public_ids String[] Update all assets with the given public IDs (array of up to 100 public_ids).
- prefix String Update all assets where the public ID starts with the given prefix (up to a maximum of 100 matching original assets).
- tag String Update all assets with the given tag (up to a maximum of 100 matching original assets).

Optional parameters

Parameter Type Description
resource_type String The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw, video.

Examples

Update the access mode of uploaded images by public IDs:

Ruby:
Copy to clipboard
Cloudinary::Api.update_resources_access_mode_by_ids('public', 
  ['image1', 'image2'])
PHP:
Copy to clipboard
$api->update_resources_access_mode_by_ids("public", 
  array("image1", "image2"));
Python:
Copy to clipboard
cloudinary.api.update_resources_access_mode_by_ids("public", 
  ["image1", "image2"])
Node.js:
Copy to clipboard
cloudinary.v2.api.update_resources_access_mode_by_ids("public", 
  ['image1', 'image2'],
  function(error, result){console.log(result);});
Java:
Copy to clipboard
api.updateResourcesAccessModeByIds("public", 
  Arrays.asList("image1", "image2"), null);
.Net:
Copy to clipboard
var updateResourceAccessModeParams = new UpdateResourceAccessModeParams(){
  AccessMode = "public",
  PublicIds = new List<string>(){"image1", "image2"}};
cloudinary.UpdateResourceAccessModeByIds(updateResourceAccessModeParams);
cURL:
Copy to clipboard
curl \
  -d "access_mode=public&public_ids[]=image1&public_ids[]=image2" \
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/update_access_mode
CLI:
Copy to clipboard
Not supported by the CLI

Update the access mode of uploaded videos by prefix:

Ruby:
Copy to clipboard
Cloudinary::Api.update_resources_access_mode_by_prefix('public', "to-publish", 
  :resource_type => :video)
PHP:
Copy to clipboard
$api->update_resources_access_mode_by_prefix("public", "to-publish", 
  array("resource_type" => "video"));
Python:
Copy to clipboard
cloudinary.api.update_resources_access_mode_by_prefix("public", "to-publish", 
  resource_type = "video")
Node.js:
Copy to clipboard
cloudinary.v2.api.update_resources_access_mode_by_prefix("public", "to-publish",
  { resource_type: 'video'}, 
  function(error, result){console.log(result);});
Java:
Copy to clipboard
api.updateResourcesAccessModeByPrefix("public", "to-publish", 
  ObjectUtils.asMap("resource_type", "video"));
.Net:
Copy to clipboard
var updateResourceAccessModeParams = new UpdateResourceAccessModeParams(){
  AccessMode = "public",
  ResourceType = "video"};
cloudinary.UpdateResourceAccessModeByPrefix("to-publish", updateResourceAccessModeParams);
cURL:
Copy to clipboard
curl \
  -d "access_mode=public&prefix=to-publish" \
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/video/upload/update_access_mode
CLI:
Copy to clipboard
Not supported by the CLI

Update the access mode of uploaded images by tag:

Ruby:
Copy to clipboard
Cloudinary::Api.update_resources_access_mode_by_tag('public', '20170216')
PHP:
Copy to clipboard
$api->update_resources_access_mode_by_tag("public", "20170216");
Python:
Copy to clipboard
cloudinary.api.update_resources_access_mode_by_tag("public", "20170216")
Node.js:
Copy to clipboard
cloudinary.v2.api.update_resources_access_mode_by_tag('public', "20170216", 
  function(error, result){console.log(result);});
Java:
Copy to clipboard
api.updateResourcesAccessModeByTag("public", "20170216", null);
.Net:
Copy to clipboard
var updateResourceAccessModeParams = new UpdateResourceAccessModeParams(){
  AccessMode = "public"};
cloudinary.UpdateResourceAccessModeByTag("20170216", updateResourceAccessModeParams);
cURL:
Copy to clipboard
curl \
  -d "access_mode=public&tag=20170216" \
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/update_access_mode
CLI:
Copy to clipboard
Not supported by the CLI

Sample response

Copy to clipboard
{
    "updated": {
      "image1": "updated",
      "image2": "updated"
    },
    "failed": {
    },
}

Delete resources

Deletes resources (assets) uploaded to your account

Syntax

DELETE /resources/:resource_type/:type

Ruby:
Copy to clipboard
Cloudinary::Api.delete_resources(public_ids = {}, options = {})
PHP:
Copy to clipboard
$api->delete_resources($public_ids = array(), $options = array());
Python:
Copy to clipboard
cloudinary.api.delete_resources(**public_ids, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_resources(public_ids, options, callback);
Java:
Copy to clipboard
api.deleteResources(Map public_ids, Map options);
.Net:
Copy to clipboard
cloudinary.DeleteResources(DelResParams params);
CLI:
Copy to clipboard
cld admin delete_resources (public_ids)

Required parameters

One of the following:

Parameter Type Description
public_ids String[] Delete all assets with the given public IDs (array of up to 100 public_ids).
prefix String Delete all assets, including derived assets, where the public ID starts with the given prefix (up to a maximum of 1000 original resources).
all Boolean Delete all assets (of the relevant resource_type and type), including derived assets (up to a maximum of 1000 original resources).

Optional parameters

Parameter Type Description
resource_type String The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw, video.
type String The delivery type, relevant as a parameter only when using the SDKs (the type is included in the endpoint URL when using the REST API). Possible values: upload, private, fetch,authenticated, facebook, twitter, gravatar, youtube, hulu, vimeo, animoto, worldstarhiphop, dailymotion. Default: all.
keep_original Boolean Whether to delete only the derived resources. Default: false.
invalidate Boolean Whether to also invalidate the copies of the resource on the CDN. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. There are also a number of other important considerations to keep in mind when invalidating files. Note that by default this parameter is not enabled: if you need this parameter enabled, please open a support request. Default: false.
next_cursor String When a deletion request has more than 1000 resources to delete, the response includes the partial boolean parameter set to true, as well as a next_cursor value. You can then specify this returned next_cursor value as a parameter of the following deletion request.
transformations String Only the derived resources matching this hash of transformation parameters will be deleted.

Examples

Delete uploaded images by public IDs:

Ruby:
Copy to clipboard
Cloudinary::Api.delete_resources(['image1', 'image2'])
PHP:
Copy to clipboard
$api->delete_resources(array("image1", "image2"));
Python:
Copy to clipboard
cloudinary.api.delete_resources(["image1", "image2"])
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_resources(['image1', 'image2'],
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.deleteResources(Arrays.asList("image1", "image2"),
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
var delResParams = new DelResParams(){
  PublicIds = new List<string>{"image1", "image2"}};
cloudinary.DeleteResources(delResParams);
cURL:
Copy to clipboard
curl \
  -d "public_ids[]=image1&public_ids[]=image2" \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload
CLI:
Copy to clipboard
cld admin delete_resources "image1","image2"

Delete Facebook pictures by public IDs:

Ruby:
Copy to clipboard
Cloudinary::Api.delete_resources(['4'], 
  :type => :facebook)
PHP:
Copy to clipboard
$api->delete_resources(array("4"), 
  array("type" => "facebook"));
Python:
Copy to clipboard
cloudinary.api.delete_resources(["4"], 
  type = "facebook")
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_resources(['4'], 
  { type: 'facebook' },
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.deleteResources(Arrays.asList("4"),
  ObjectUtils.asMap("type", "facebook"));
.Net:
Copy to clipboard
var delResParams = new DelResParams(){
  PublicIds = new List<string>{"4"},
  Type = "facebook"};
cloudinary.DeleteResources(delResParams);
cURL:
Copy to clipboard
curl \
  -d "public_ids=4" \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/facebook
CLI:
Copy to clipboard
cld admin delete_resources "4" type="facebook"

Delete uploaded images by prefix:

Ruby:
Copy to clipboard
Cloudinary::Api.delete_resources_by_prefix('sunday')
PHP:
Copy to clipboard
$api->delete_resources_by_prefix("sunday");
Python:
Copy to clipboard
cloudinary.api.delete_resources_by_prefix("sunday")
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_resources_by_prefix('sunday', 
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.deleteResourcesByPrefix("sunday", 
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.DeleteResourcesByPrefix("sunday");
cURL:
Copy to clipboard
curl \
  -d "prefix=sunday" \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload
CLI:
Copy to clipboard
cld admin delete_resources_by_prefix "sunday"

Delete derived images only:

Ruby:
Copy to clipboard
Cloudinary::Api.delete_resources(['image1', 'image2'],
  :keep_original => true)
PHP:
Copy to clipboard
$api->delete_resources(array("image1", "image2"),
  array("keep_original" => TRUE));
Python:
Copy to clipboard
cloudinary.api.delete_resources(["image1", "image2"],
  keep_original = True)
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_resources(['image1', 'image2'], 
  { keep_original: true},
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.deleteResources(Arrays.asList("image1", "image2"),
<OBJECT></OBJECT>bjectUtils.asMap("keep_original", true));
.Net:
Copy to clipboard
var delResParams = new DelResParams(){
PublicIds = new List<string>{"image1", "image2"},
  KeepOriginal = true};
cloudinary.DeleteResources(delResParams);
cURL:
Copy to clipboard
curl \
  -d "public_ids[]=image1&public_ids[]=image2&keep_original=1" \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload
CLI:
Copy to clipboard
cld admin delete_resources "image1","image2" keep_original=true

Delete all Facebook pictures:

Ruby:
Copy to clipboard
Cloudinary::Api.delete_all_resources(
  :type => :facebook)
PHP:
Copy to clipboard
$api->delete_all_resources(
  array("type" => "facebook"));
Python:
Copy to clipboard
cloudinary.api.delete_all_resources(
  type = "facebook")
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_all_resources(
  {type: 'facebook'}, 
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.deleteAllResources(
  ObjectUtils.asMap("type", "facebook"));
.Net:
Copy to clipboard
var delResParams = new DelResParams(){
  Type = "facebook",
  All = true};
cloudinary.DeleteResources(delResParams);
cURL:
Copy to clipboard
curl \
  -d "all=true" \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/facebook
CLI:
Copy to clipboard
cld admin delete_all_resources type="facebook"

Sample response

Copy to clipboard
{
    "deleted": {
        "image1": "deleted",
        "image2": "deleted"
    },
    "partial": false
}

Delete resources by tags

Deletes resources (assets) with a specified tag.

Syntax

DELETE /resources/:resource_type/tags/:tag

Ruby:
Copy to clipboard
Cloudinary::Api.delete_resources_by_tag(tag, options = {})
PHP:
Copy to clipboard
$api->delete_resources_by_tag($tag, $options = array());
Python:
Copy to clipboard
cloudinary.api.delete_resources_by_tag(tag, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_resources_by_tag(tag, options, callback);
Java:
Copy to clipboard
api.deleteResourcesByTag(String tag, Map options);
.Net:
Copy to clipboard
cloudinary.DeleteResourcesByTag(TagParams params);
CLI:
Copy to clipboard
cld admin delete_resources_by_tag (tag)

Required parameters

Parameter Type Description
tag String Delete all assets (and their derivatives) with the given tag name (up to a maximum of 1000 original assets).

Optional parameters

Parameter Type Description
resource_type String The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw, video.
keep_original Boolean Whether to delete only the derived resources. Default: false.
invalidate Boolean Whether to also invalidate the copies of the resource on the CDN. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. There are also a number of other important considerations to keep in mind when invalidating files. Note that by default this parameter is not enabled: if you need this parameter enabled, please open a support request. Default: false.
next_cursor String When a deletion request has more than 1000 resources to delete, the response includes the partial boolean parameter set to true, as well as a next_cursor value. You can then specify this returned next_cursor value as a parameter of the following deletion request.
transformations String Only the derived resources matching this hash of transformation parameters will be deleted.

Examples

Delete images by tag name:

Ruby:
Copy to clipboard
Cloudinary::Api.delete_resources_by_tag('mytag')
PHP:
Copy to clipboard
$api->delete_resources_by_tag("mytag");
Python:
Copy to clipboard
cloudinary.api.delete_resources_by_tag("mytag")
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_resources_by_tag('mytag',
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.deleteResourcesByTag("mytag", ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.DeleteResourcesByTag("mytag");
cURL:
Copy to clipboard
curl \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/tags/mytag
CLI:
Copy to clipboard
cld admin delete_resources_by_tag mytag

Sample response

Copy to clipboard
{
    "deleted": {
        "image1": "deleted",
        "image2": "deleted"
    },
    "partial": false
}

Delete derived resources

Deletes derived resources (assets) from your account.

Syntax

DELETE /derived_resources

Ruby:
Copy to clipboard
Cloudinary::Api.delete_derived_resources(derived_resource_ids = {}, options = {})
PHP:
Copy to clipboard
$api->delete_derived_resources($derived_resource_ids = array(), $options = array());
Python:
Copy to clipboard
cloudinary.api.delete_derived_resources(**derived_resource_ids, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_derived_resources(derived_resource_ids, options, callback);
Java:
Copy to clipboard
api.deleteDerivedResources(Iterable<String> derivedResourceIds, Map options)
.Net:
Copy to clipboard
cloudinary.DeleteDerivedResources(List<string> DerivedResourceIds);
CLI:
Copy to clipboard
cld admin delete_derived_resources (derived_resource_ids)

Required parameters

One of the following:

Parameter Type Description
derived_resource_ids String[] Delete all assets with the given derived_resource_ids IDs (array of up to 100 IDs). The derived resource IDs are returned when calling the Details of a single resource method.

Optional parameters

Parameter Type Description
invalidate Boolean Whether to also invalidate the copies of the resource on the CDN. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. There are also a number of other important considerations to keep in mind when invalidating files. Note that by default this parameter is not enabled: if you need this parameter enabled, please open a support request. Default: false.

Examples

Delete assets by derived resource IDs (8267a869b62a93a59248f35d7f124c1f and 383e22a57167445552a3cdc16f0a0c85):

Ruby:
Copy to clipboard
Cloudinary::Api.derived_resource_ids(['8267a869b62a93a59248f35d7f124c1f', '383e22a57167445552a3cdc16f0a0c85'])
PHP:
Copy to clipboard
$api->derived_resource_ids(array("8267a869b62a93a59248f35d7f124c1f", "383e22a57167445552a3cdc16f0a0c85"));
Python:
Copy to clipboard
cloudinary.api.derived_resource_ids(["8267a869b62a93a59248f35d7f124c1f", "383e22a57167445552a3cdc16f0a0c85"])
Node.js:
Copy to clipboard
cloudinary.v2.api.derived_resource_ids(['8267a869b62a93a59248f35d7f124c1f', '383e22a57167445552a3cdc16f0a0c85'],
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.deleteDerivedResources(Arrays.asList("8267a869b62a93a59248f35d7f124c1f", "383e22a57167445552a3cdc16f0a0c85"),
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.DeleteDerivedResources(new List<string>{"8267a869b62a93a59248f35d7f124c1f", "383e22a57167445552a3cdc16f0a0c85");
cURL:
Copy to clipboard
curl \
  -d "derived_resource_ids[]=8267a869b62a93a59248f35d7f124c1f&derived_resource_ids[]=383e22a57167445552a3cdc16f0a0c85" \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/derived_resources
CLI:
Copy to clipboard
cld admin delete_derived_resources "8267a869b62a93a59248f35d7f124c1f","383e22a57167445552a3cdc16f0a0c85"

Transformations

Enables you to manage stored transformations. See the Image transformations and video transformations documentation for more information.

Method Description
GET /transformations Get all transformations
GET /transformations/:transformation Get details of a transformation
POST/transformations/:name Create a named transformation
PUT/transformations/:transformation Update a transformation
DELETE/transformations/:transformation Delete a transformation

Get Transformations

List all transformations.

Syntax

GET /transformations

Ruby:
Copy to clipboard
Cloudinary::Api.transformations(options = {})
PHP:
Copy to clipboard
$api->transformations($options = array());
Python:
Copy to clipboard
cloudinary.api.transformations(**options)
Node.js:
Copy to clipboard
cloudinary.v2.api.transformations(options, callback);
Java:
Copy to clipboard
api.transformations(Map options);
.Net:
Copy to clipboard
cloudinary.ListTransformations(TransformParams params);
CLI:
Copy to clipboard
cld admin transformations

Optional parameters

Parameter Type Description
max_results Integer Maximum number of transformations to return (up to 500). Default: 10.
next_cursor String When a request has more results to return than max_results, the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of a following request.
named Boolean Whether to return only named (true) or unnamed (false) transformations. If this parameter is not included, both named and unnamed transformations will be returned.

Examples

List all transformations:

Ruby:
Copy to clipboard
Cloudinary::Api.transformations
PHP:
Copy to clipboard
$api->transformations();
Python:
Copy to clipboard
cloudinary.api.transformations()
Node.js:
Copy to clipboard
cloudinary.v2.api.transformations(function(error, result){console.log(result);});
Java:
Copy to clipboard
api.transformations(ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.ListTransformations();
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations
CLI:
Copy to clipboard
cld admin transformations

Sample response

The response contains an array of transformations. If the number of transformations exceeds the max_results value, the next_cursor parameter is also returned. You can specify this value as the next_cursor parameter of the following listing request.

Copy to clipboard
{
    "transformations": [
    {
        "name": "t_Aspen_LUT",
        "allowed_for_strict": true,
        "used": false,
        "named": true
    },
    {
        "name": "w_110,h_100,c_fill",
        "allowed_for_strict": false,
        "used": false,
        "named": false
    },
    {
        "name": "c_thumb,g_face,h_100,w_80",
        "allowed_for_strict": false,
        "used": true,
        "named": false
    },
    {
        "name": "c_fill,h_75,w_75/jpg",
        "allowed_for_strict": false,
        "used": true,
        "named": false
    }
    ],
    "next_cursor": "8edbc61040178db60b0973ca9494bf3a"
}

Get Transformation details

Get details of a single transformation. Supply either the name of the transformation or the transformation parameters.

Syntax

GET /transformations/:transformation

Ruby:
Copy to clipboard
Cloudinary::Api.transformation(transformation, options = {})
PHP:
Copy to clipboard
$api->transformation($transformation, $options = array());
Python:
Copy to clipboard
cloudinary.api.transformation(transformation, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.transformation(transformation,
options, callback);
Java:
Copy to clipboard
api.transformations(String transformation, Map options);
.Net:
Copy to clipboard
cloudinary.GetTransform(TransformParams params);
CLI:
Copy to clipboard
cld admin transformation

Required parameters

Parameter Type Description
transformation String The name of the transformation or the transformation parameters.

Optional parameters

Parameter Type Description
max_results Integer Maximum number of derived resources to return (up to 500). Default: 10.
next_cursor String When a request has more results to return than max_results, the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of a following request.

Examples

Get transformation by name:

Ruby:
Copy to clipboard
Cloudinary::Api.transformation('w_150,h_100,c_fill')
PHP:
Copy to clipboard
$api->transformation("w_150,h_100,c_fill");
Python:
Copy to clipboard
cloudinary.api.transformation("w_150,h_100,c_fill")
Node.js:
Copy to clipboard
cloudinary.v2.api.transformation('w_150,h_100,c_fill',
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.transformations("w_150,h_100,c_fill", ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.GetTransform("w_150,h_100,c_fill");
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations/w_150,h_100,c_fill
CLI:
Copy to clipboard
cld admin transformation "w_150,h_100,c_fill"

Get transformation by parameters:

Ruby:
Copy to clipboard
Cloudinary::Api.transformation(:width => 150, :height => 100,
  :crop => :fill)
PHP:
Copy to clipboard
$api->transformation(array("width" => 150, "height" => 100,
  "crop" => "fill"));
Python:
Copy to clipboard
cloudinary.api.transformation(dict(width = 150, height = 100, crop = "fill"))
Node.js:
Copy to clipboard
cloudinary.v2.api.transformation({width: 150, height: 100, crop: 'fill'},
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.transformation(new Transformation().width(150).height(100).
  crop("fill").generate(), ObjectUtils.emptyMap());
.Net:
Copy to clipboard
Not supported by this SDK
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations/c_fill,h_100,w_150
CLI:
Copy to clipboard
cld admin transformation '{"width": 500, "height": 100, "crop": "fill"}'

Sample response

Copy to clipboard
{
  "name": "w_150,h_100,c_fill",
  "allowed_for_strict": false,
  "used": true,
  "named": false,
  "info": [
    {
      "width": 150,
      "height": 100,
      "crop": "fill"
    }
  ],
  "derived": [
    {
      "public_id": "sample",
      "resource_type": "image",
      "type": "upload",
      "format": "jpg",
      "url":
        "http://.../demo/image/upload/w_150,h_100,c_fill/v1341141057/sample.jpg",
      "secure_url":
        "https://.../demo/image/upload/w_150,h_100,c_fill/v1341141057/sample.jpg",
      "bytes": 10202,
      "id": "2adf1841874c7b2326d1f90cbedbc914"
    }
  ]
}

Create a named transformation

Create a new named transformation.

Syntax

POST /transformations/:name

Ruby:
Copy to clipboard
Cloudinary::Api.create_transformation(name, transformation)
PHP:
Copy to clipboard
$api->create_transformation($name, transformation);
Python:
Copy to clipboard
cloudinary.api.create_transformation(name, transformation)
Node.js:
Copy to clipboard
cloudinary.v2.api.create_transformation(name,
transformation, callback);
Java:
Copy to clipboard
api.createTransformations(String name, String transformation));
.Net:
Copy to clipboard
cloudinary.CreateTransform(createTransformParams params);
CLI:
Copy to clipboard
cld admin create_transformation (name, transformation)

Required parameters

Parameter Type Description
name String The name of the transformation.
transformation String The transformation parameters.

Examples

Create named transformation by string:

Ruby:
Copy to clipboard
Cloudinary::Api.create_transformation('small_fill',
  'w_150,h_100,c_fill')
PHP:
Copy to clipboard
$api->create_transformation("small_fill", "w_150,h_100,c_fill");
Python:
Copy to clipboard
cloudinary.api.create_transformation("small_fill",
  "w_150,h_100,c_fill")
Node.js:
Copy to clipboard
cloudinary.v2.api.create_transformation('small_fill',
  'w_150,h_100,c_fill',
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.createTransformation("small_fill", "w_150,h_100,c_fill",
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
var createTransformParams = new CreateTransformParams(){
  Name = "small_fill",
  Transformation = new Transformation().Width(150).Height(100).Crop("fill")};
cloudinary.CreateTransform(createTransformParams);
cURL:
Copy to clipboard
curl \
  -d 'transformation=w_150,h_100,c_fill' \
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations/small_fill
CLI:
Copy to clipboard
cld admin create_transformation "small_fill" "w_150,h_100,c_fill"

Create named transformation by parameters:

Ruby:
Copy to clipboard
Cloudinary::Api.create_transformation('small_fill2',
  {:width => 150, :height => 100, :crop => :fill})
PHP:
Copy to clipboard
$api->create_transformation("small_fill2",
  array("width" => 150, "height" => 100, "crop" => "fill"));
Python:
Copy to clipboard
cloudinary.api.create_transformation("small_fill2",
  dict(width = 150, height = 100, crop = "fill"))
Node.js:
Copy to clipboard
cloudinary.v2.api.create_transformation('small_fill2',
  { width: 150, height: 100, crop: 'fill' },
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.createTransformation("small_fill2",
  new Transformation().width(150).height(100).crop("fill").generate(),
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
var createTransformParams = new CreateTransformParams(){
  Name = "small_fill2",
  Transformation = new Transformation().Width(150).Height(100).Crop("fill")};
cloudinary.CreateTransform(createTransformParams);
cURL:
Copy to clipboard
curl \
  -d 'transformation=w_150,h_100,c_fill' \
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations/small_fill
CLI:
Copy to clipboard
cld admin create_transformation "small_fill2" '{"width": 150, "height": 100, "crop": "fill"}'

Sample response

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

Update transformation

Update a single transformation. Supply either the name of the transformation or the transformation parameters.

Syntax

PUT /transformations/:transformation

Ruby:
Copy to clipboard
Cloudinary::Api.update_transformation(transformation, options = {})
PHP:
Copy to clipboard
$api->update_transformation($transformation, $options = array());
Python:
Copy to clipboard
cloudinary.api.update_transformation(transformation, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.update_transformation(transformation,
options, callback);
Java:
Copy to clipboard
api.updateTransformations(String transformation, Map options));
.Net:
Copy to clipboard
cloudinary.UpdateTransform(updateTransformParams params);
CLI:
Copy to clipboard
cld admin update_transformation (transformation)

Required parameters

Parameter Type Description
transformation String The name of the transformation or the transformation parameters.

Optional parameters

Parameter Type Description
allowed_for_strict Boolean Whether allow this transformation when Strict Transformations are enabled. Default: false.
unsafe_update String Allows updating an existing named transformation without updating all associated derived images (the new settings of the named transformation only take effect from now on).

Examples

Allow transformation by name:

Ruby:
Copy to clipboard
Cloudinary::Api.update_transformation('w_150,h_100,c_fill',
  :allowed_for_strict => true)
PHP:
Copy to clipboard
$api->update_transformation("w_150,h_100,c_fill",
  array("allowed_for_strict" => 1));
Python:
Copy to clipboard
cloudinary.api.update_transformation("w_150,h_100,c_fill",
  allowed_for_strict = True)
Node.js:
Copy to clipboard
cloudinary.v2.api.update_transformation('w_150,h_100,c_fill',
  { allowed_for_strict: true },
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.updateTransformation("w_150,h_100,c_fill",
  ObjectUtils.asMap("allowed_for_strict", true);
.Net:
Copy to clipboard
var updateTransformParams = new UpdateTransformParams(){
  Transformation = "w_150,h_100,c_fill",
  Strict = true};
cloudinary.UpdateTransform(updateTransformParams);
cURL:
Copy to clipboard
curl \
  -d 'allowed_for_strict=true' \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations/w_150,h_100,c_fill
CLI:
Copy to clipboard
cld admin update_transformation "w_150,h_100,c_fill" allowed_for_strict=true

Disallow transformation by parameters:

Ruby:
Copy to clipboard
Cloudinary::Api.update_transformation(
  { :width => 150, :height => 100, :crop => :fill},
  { :allowed_for_strict => false })
PHP:
Copy to clipboard
$api->update_transformation(
  array("width" => 150, "height" => 100,"crop" => "fill"),
  array("allowed_for_strict" => 0));
Python:
Copy to clipboard
cloudinary.api.update_transformation(
  dict(width = 150, height = 100, crop = "fill"), 
  dict(allowed_for_strict = False))
Node.js:
Copy to clipboard
cloudinary.v2.api.update_transformation(
  { width: 150, height: 100, crop: 'fill' },
  { allowed_for_strict: false },
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.updateTransformation(
  new Transformation().width(150).height(100).crop("fill").generate(), 
  ObjectUtils.asMap("allowed_for_strict", false);
.Net:
Copy to clipboard
var updateTransformParams = new UpdateTransformParams(){
  Transformation = "w_150,h_100,c_fill",
  Strict = false};
cloudinary.UpdateTransform(updateTransformParams);
cURL:
Copy to clipboard
curl \
  -d 'allowed_for_strict=false' \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations/c_fill,h_100,w_150
CLI:
Copy to clipboard
cld admin update_transformation '{"width": 150, "height": 100, "crop": "fill"}' allowed_for_strict=true

Update a named transformation:

Ruby:
Copy to clipboard
Cloudinary::Api.update_transformation('my_named',
  :unsafe_update => { :crop => :scale, :width =>103 })
PHP:
Copy to clipboard
:
$api->update_transformation("my_named",
  array("crop" => "scale", "width" => 103));
Python:
Copy to clipboard
cloudinary.api.update_transformation("my_named",
  dict(crop = "scale", width = 103))
Node.js:
Copy to clipboard
cloudinary.v2.api.update_transformation("my_named",
  {crop: 'scale', width: 103},
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.updateTransformation("my_named",
  ObjectUtils.asMap("unsafe_update",
  new Transformation().crop("scale").width(103).generate());
.Net:
Copy to clipboard
var updateTransformParams = new UpdateTransformParams(){
  Transformation = "my_named",
  UnsafeTransform = new Transformation().Crop("scale").Width(103)};
cloudinary.UpdateTransform(updateTransformParams);
cURL:
Copy to clipboard
curl \
  -d 'unsafe_update=c_scale,w_103' \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations/my_named
CLI:
Copy to clipboard
cld admin update_transformation my_named unsafe_update='{"crop": "scale", "width": 103}'

Sample response

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

Delete transformation

Delete a single transformation. Supply either the name of the transformation or the transformation parameters.

Note
Deleting a transformation also deletes all the derived images based on this transformation (up to 1000). The method returns an error if there are more than 1000 derived images based on this transformation.

Syntax

DELETE /transformations/:transformation

Ruby:
Copy to clipboard
Cloudinary::Api.delete_transformation(transformation)
PHP:
Copy to clipboard
$api->delete_transformation($transformation);
Python:
Copy to clipboard
cloudinary.api.delete_transformation(transformation)
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_transformation(transformation, callback});
Java:
Copy to clipboard
api.deleteTransformations(String transformation);
.Net:
Copy to clipboard
cloudinary.DeleteTransform(transformation);
CLI:
Copy to clipboard
cld admin delete_transformation (transformation)

Required parameters

Parameter Type Description
transformation String The name of the transformation or the transformation parameters.

Examples

Delete transformation by name:

Ruby:
Copy to clipboard
Cloudinary::Api.delete_transformation('w_150,h_100,c_fill')
PHP:
Copy to clipboard
$api->delete_transformation("w_150,h_100,c_fill");
Python:
Copy to clipboard
cloudinary.api.delete_transformation("w_150,h_100,c_fill")
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_transformation('w_150,h_100,c_fill',
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.deleteTransformation("w_150,h_100,c_fill",
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.DeleteTransform("w_150,h_100,c_fill");
cURL:
Copy to clipboard
curl  \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations/w_150,h_100,c_fill
CLI:
Copy to clipboard
cld admin delete_transformation "w_150,h_100,c_fill"

Delete transformation by parameters:

Ruby:
Copy to clipboard
Cloudinary::Api.delete_transformation(:width => 150, :height => 100,
  :crop => :fill)
PHP:
Copy to clipboard
$api->delete_transformation(array("width" => 150, "height" => 100,
  "crop" => "fill"));
Python:
Copy to clipboard
cloudinary.api.delete_transformation(dict(width = 150, height = 100,
  crop = "fill"))
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_transformation(
  {width: 150, height: 100, crop: 'fill'},
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.deleteTransformation(new Transformation().width(150).height(100).
  crop("fill").generate(), ObjectUtils.emptyMap());
.Net:
Copy to clipboard
Not supported by this SDK
cURL:
Copy to clipboard
curl \
  -X DELETE \  
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/transformations/c_fill,h_100,w_150
CLI:
Copy to clipboard
cld admin delete_transformation '{"width": 150, "height": 100, "crop": "fill"}'

Sample response

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

Upload mappings

Dynamically fetches images from existing online locations and uploads the files to your account.

See the Auto upload remote images documentation for more information.

Method Description
GET/upload_mappings Get upload mappings
GET/upload_mappings/:folder Get the details of a single upload mapping
POST/upload_mappings Create an upload mapping
PUT/upload_mappings Update an upload mapping
DELETE/upload_mappings/:folder Delete an upload mapping

Get upload mappings

List all upload mappings by folder and includes its mapped template (URL).

Syntax

GET /upload_mappings

Ruby:
Copy to clipboard
Cloudinary::Api.upload_mappings(options = {})
PHP:
Copy to clipboard
$api->upload_mappings($options = array());
Python:
Copy to clipboard
cloudinary.api.upload_mappings(**options)
Node.js:
Copy to clipboard
cloudinary.v2.api.upload_mappings(options, callback);
Java:
Copy to clipboard
api.uploadMappings(Map options);
.Net:
Copy to clipboard
cloudinary.UploadMappings(uploadMappingParams params);
CLI:
Copy to clipboard
cld admin upload_mappings

Optional parameters

Parameter Type Description
max_results Integers Maximum number of assets to return (up to 500). Default: 10.
next_cursor String When a request has more results to return than max_results, the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of a following request.

Examples

List all upload mappings

Ruby:
Copy to clipboard
Cloudinary::Api.upload_mappings
PHP:
Copy to clipboard
$api->upload_mappings();
Python:
Copy to clipboard
cloudinary.api.upload_mappings()
Node.js:
Copy to clipboard
cloudinary.v2.api.upload_mappings(function(error, result){console.log(result);});
Java:
Copy to clipboard
api.uploadMappings(ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.UploadMappings();
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_mappings
CLI:
Copy to clipboard
cld admin upload_mappings

Sample response

Copy to clipboard
{
    "mappings": [
      {
        "folder": "wiki", 
        "template": "https://u.wiki.example.com/wiki-images/"
      },
      {
        "folder": "exam", 
        "template": "https://images.example.com/product_assets/images/"
      }, 
    ]
}

Get the details of a single upload mapping

Retrieve the mapped template (URL) of a given upload mapping folder.

Syntax

GET /upload_mappings/:folder

Ruby:
Copy to clipboard
Cloudinary::Api.upload_mapping(folder)
PHP:
Copy to clipboard
$api->upload_mapping($folder);
Python:
Copy to clipboard
cloudinary.api.upload_mapping(folder)
Node.js:
Copy to clipboard
cloudinary.v2.api.upload_mapping(folder, callback);
Java:
Copy to clipboard
api.uploadMapping(String folder));
.Net:
Copy to clipboard
cloudinary.UploadMapping(uploadMappingParams params);
CLI:
Copy to clipboard
cld admin upload_mapping (folder)

Required parameters

Parameter Type Description
folder String The name of the folder to map.

Examples

Upload mapping details by folder the 'wiki' folder:

Ruby:
Copy to clipboard
Cloudinary::Api.upload_mapping('wiki')
PHP:
Copy to clipboard
$api->upload_mapping("wiki");
Python:
Copy to clipboard
cloudinary.api.upload_mapping("wiki")
Node.js:
Copy to clipboard
cloudinary.v2.api.upload_mapping('wiki',
  function(error, result){console.log(result);});
Java:
Copy to clipboard
api.uploadMapping("wiki",
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.UploadMapping("wiki");
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_mappings/wiki
CLI:
Copy to clipboard
cld admin upload_mapping "wiki"

Sample response

Copy to clipboard
{
    "folder": "wiki", 
    "template": "https://u.wiki.example.com/wiki-images/"
}

Create an upload mapping

Create a new upload mapping folder and its template (URL).

Syntax

POST /upload_mappings

Ruby:
Copy to clipboard
Cloudinary::Api.create_upload_mapping(folder, options = {})
PHP:
Copy to clipboard
$api->create_upload_mapping(folder, $options = array());
Python:
Copy to clipboard
cloudinary.api.create_upload_mapping(folder, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.create_upload_mapping(folder, options, callback);
Java:
Copy to clipboard
api.createUploadMapping(String folder, Map options));
.Net:
Copy to clipboard
cloudinary.CreateUploadMapping(uploadMappingParams params);
CLI:
Copy to clipboard
cld admin create_upload_mapping (folder)

Required parameters

Parameter Type Description
folder String The name of the folder to map.
template String The URL to be mapped to the folder, as part of options.

Examples

Create upload mapping from 'https://www.example.com/images/' to a folder called 'my_map':

Ruby:
Copy to clipboard
Cloudinary::Api.create_upload_mapping("my_map",
  :template => "https://www.example.com/images/")
PHP:
Copy to clipboard
$api->create_upload_mapping("my_map",
  array("template" => "https://www.example.com/images/"));
Python:
Copy to clipboard
cloudinary.api.create_upload_mapping("my_map",
  template = "https://www.example.com/images/")
Node.js:
Copy to clipboard
cloudinary.v2.api.create_upload_mapping('my_map',
  { template: "https://www.example.com/images/" },
  function(error, result){console.log(result);});
Java:
Copy to clipboard
api.createUploadMapping("my_map",
  ObjectUtils.asMap("template", "https://www.example.com/images/"));
.Net:
Copy to clipboard
cloudinary.CreateUploadMapping("my_map", "https://www.example.com/images/");
cURL:
Copy to clipboard
curl \
 -d "folder=my_map&template=https://www.example.com/images/" \
 -X POST \
 https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_mappings
CLI:
Copy to clipboard
cld admin create_upload_mapping "my_map" template="https://www.example.com/images/"

Sample response

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

Update an upload mapping

Update an existing upload mapping folder with a new template (URL).

Syntax

PUT /upload_mappings

Ruby:
Copy to clipboard
Cloudinary::Api.update_upload_mapping(folder, options = {})
PHP:
Copy to clipboard
$api->update_upload_mapping(folder, $options = array());
Python:
Copy to clipboard
cloudinary.api.update_upload_mapping(folder, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.update_upload_mapping(folder, options, callback);
Java:
Copy to clipboard
api.updateUploadMapping(String folder, Map options));
.Net:
Copy to clipboard
cloudinary.UpdateUploadMapping(uploadMappingParams params);
CLI:
Copy to clipboard
cld admin update_upload_mapping (folder)

Required parameters

Parameter Type Description
folder String The name of the folder to map.
template String The URL to be mapped to the folder, as part of options.

Examples

Update an upload mapping to the 'wiki' folder with the https://u.wiki.com/images/ URL:

Ruby:
Copy to clipboard
Cloudinary::Api.update_upload_mapping("wiki",
  :template => "https://u.wiki.com/images/")
PHP:
Copy to clipboard
$api->update_upload_mapping("wiki",
  array("template" => "https://u.wiki.com/images/"));
Python:
Copy to clipboard
cloudinary.api.update_upload_mapping("wiki",
  template = "https://u.wiki.com/images/")
Node.js:
Copy to clipboard
cloudinary.v2.api.update_upload_mapping('wiki',
  { template: "https://u.wiki.com/images/" },
  function(error, result){console.log(result);});
Java:
Copy to clipboard
api.updateUploadMapping("wiki",
  ObjectUtils.asMap("template", "https://u.wiki.com/images/"), ObjectUtils.emptyMap());
.Net:
Copy to clipboard
var uploadMappingParams = new UploadMappingParams(){
  Folder = "wiki",
  Template = "https://u.wiki.com/images/";
cloudinary.UploadMapping(uploadMappingParams);
cURL:
Copy to clipboard
curl \
  -d "folder=wiki&template=https://u.wiki.com/images/" \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_mappings
CLI:
Copy to clipboard
cld admin update_upload_mapping "wiki" template="https://u.wiki.com/images/"

Sample response

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

Delete an upload mapping

Delete an upload mapping by folder name.

Syntax

DELETE /upload_mappings/:folder

Ruby:
Copy to clipboard
Cloudinary::Api.delete_upload_mapping(folder)
PHP:
Copy to clipboard
$api->delete_upload_mapping(folder);
Python:
Copy to clipboard
cloudinary.api.delete_upload_mapping(folder)
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_upload_mapping(folder, callback);
Java:
Copy to clipboard
api.deleteUploadMapping(String folder));
.Net:
Copy to clipboard
cloudinary.DeleteUploadMapping(uploadMappingParams params);
CLI:
Copy to clipboard
cld admin delete_upload_mapping (folder)

Required parameters

Parameter Type Description
folder String The name of the folder to map.

Examples

Delete an upload mapping to the 'wiki' folder:

Ruby:
Copy to clipboard
Cloudinary::Api.delete_upload_mapping('wiki')
PHP:
Copy to clipboard
$api->delete_upload_mapping("wiki");
Python:
Copy to clipboard
cloudinary.api.delete_upload_mapping("wiki")
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_upload_mapping('wiki',
  function(error, result){console.log(result);});
Java:
Copy to clipboard
api.deleteUploadMapping("wiki",
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.DeleteUploadMapping("wiki");
cURL:
Copy to clipboard
curl \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_mappings/wiki
CLI:
Copy to clipboard
cld admin delete_upload_mapping "wiki"

Sample response

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

Upload presets

Enables you to centrally define image upload options instead of specifying them in each upload call.

See the upload preset documentation for more information.

Methods Description
GET /upload_presets Get upload presets
GET /upload_presets/:name Get the details of a single upload preset
POST/upload_presets Create an upload preset
PUT/upload_presets/:name Update an upload preset
DELETE/upload_presets/:name Delete an upload preset

Get upload presets

Lists the upload presets defined for your account.

Syntax

GET /upload_presets

Ruby:
Copy to clipboard
Cloudinary::Api.upload_presets(options = {})
PHP:
Copy to clipboard
$api->upload_presets($options = array());
Python:
Copy to clipboard
cloudinary.api.upload_presets(**options)
Node.js:
Copy to clipboard
cloudinary.v2.api.upload_presets(options, callback);
Java:
Copy to clipboard
api.uploadPresets(Map options);
.Net:
Copy to clipboard
cloudinary.ListUploadPresets(uploadPresetParams params);
CLI:
Copy to clipboard
cld admin upload_presets

Optional parameters

Parameter Type Description
max_results Integers Maximum number of assets to return (up to 500). Default: 10.
next_cursor String When a request has more results to return than max_results, the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of a following request.

Examples

List all upload presets:

Ruby:
Copy to clipboard
Cloudinary::Api.upload_presets
PHP:
Copy to clipboard
$api->upload_presets();
Python:
Copy to clipboard
cloudinary.api.upload_presets()
Node.js:
Copy to clipboard
cloudinary.v2.api.upload_presets(function(error, result){console.log(result);});
Java:
Copy to clipboard
api.uploadPresets(ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.ListUploadPresets();
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_presets
CLI:
Copy to clipboard
cld admin upload_presets

Sample response

Copy to clipboard
{
    "presets": [
      {
        "name": "pd1e4lst",
        "unsigned": true,
        "settings": 
          {
            "transformation": "c_crop,g_custom/ar_1,c_pad,w_1.0"
          }
      }, 
      {
        "name": "remote_media",
        "unsigned": false,
        "settings": 
          {
            "tags": "test"
            "allowed_formats": "jpg,png",
            "eager": "c_fill,g_face,h_150,w_200"
          }
      }, 
    ]
}

Get the details of a single upload preset

Retrieves the details of an upload preset.

Syntax

GET /upload_presets/:name

Ruby:
Copy to clipboard
Cloudinary::Api.upload_preset(name, options = {})
PHP:
Copy to clipboard
$api->upload_preset($name, $options = array());
Python:
Copy to clipboard
cloudinary.api.upload_preset(name, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.upload_preset(name, options, callback);
Java:
Copy to clipboard
api.uploadPreset(String name, Map options);
.Net:
Copy to clipboard
cloudinary.GetUploadPreset(uploadPresetParams params);
CLI:
Copy to clipboard
cld admin upload_preset (name)

Required parameters

Parameter Type Description
name String The name of the upload preset.

Examples

Upload preset details for the 'remote_media' preset:

Ruby:
Copy to clipboard
Cloudinary::Api.upload_preset('remote_media')
PHP:
Copy to clipboard
$api->upload_preset("remote_media");
Python:
Copy to clipboard
cloudinary.api.upload_preset("remote_media")
Node.js:
Copy to clipboard
cloudinary.v2.api.upload_preset('remote_media',
  function(error, result){console.log(result);});
Java:
Copy to clipboard
api.uploadPreset("remote_media",
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.GetUploadPreset("remote_media");
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_presets/remote_media
CLI:
Copy to clipboard
cld admin upload_preset "remote_media"

Sample response

Copy to clipboard
{
    "name": "remote_media",
    "unsigned": false,
    "settings": 
      {
        "tags": "test",
        "allowed_formats": "jpg,png",
        "eager": "c_fill,g_face,h_150,w_200"
      }
}

Create an upload preset

Create a new upload preset.

Syntax

POST /upload_presets

Ruby:
Copy to clipboard
Cloudinary::Api.create_upload_preset(options = {})
PHP:
Copy to clipboard
$api->create_upload_preset($options = array());
Python:
Copy to clipboard
cloudinary.api.create_upload_preset(**options)
Node.js:
Copy to clipboard
cloudinary.v2.api.create_upload_preset(options, callback);
Java:
Copy to clipboard
api.createUploadPreset(Map options);
.Net:
Copy to clipboard
cloudinary.CreateUploadPreset(uploadPresetParams params);
CLI:
Copy to clipboard
cld admin create_upload_preset

Optional parameters

Parameter Type Description
name String The name to assign to the new upload preset. If not specified, a random name is generated. If the name is of an existing preset, it will be overwritten.
unsigned Boolean Whether this upload preset allows unsigned uploading to Cloudinary. Default: false.
disallow_public_id Boolean Whether this upload preset disables assigning a public_id in the upload call. Default: false.
live Boolean Whether to enable "live broadcast", so that the upload preset can be used for live streaming.
{Upload parameters} The upload parameters to apply to assets uploaded with this preset.

Examples

Create a new upload preset called 'my_preset', that allows unsigned uploading, adds the tag 'remote' to uploaded images, and only allows the uploading of JPG and PNG image formats:

Ruby:
Copy to clipboard
Cloudinary::Api.create_upload_preset(
  :name => "my_preset",
  :unsigned => true, 
  :tags => "remote", 
  :allowed_formats => "jpg,png")
PHP:
Copy to clipboard
$api->create_upload_preset(
  array(
    "name" => "my_preset", 
    "unsigned" => true, 
    "tags" => "remote", 
    "allowed_formats" => "jpg,png"));
Python:
Copy to clipboard
cloudinary.api.create_upload_preset(
  name = "my_preset",
  unsigned = True, 
  tags = "remote", 
  allowed_formats = "jpg,png")
Node.js:
Copy to clipboard
cloudinary.v2.api.create_upload_preset(
  { name: "my_preset", 
    unsigned: true, 
    tags: "remote", 
    allowed_formats: "jpg,png" },
  function(error, result){console.log(result);});
Java:
Copy to clipboard
api.createUploadPreset(
  ObjectUtils.asMap(
    "name", "my_preset",
    "unsigned", true, 
    "tags" => "remote", 
    "allowed_formats" => "jpg,png"));
.Net:
Copy to clipboard
var uploadPresetParams = new UploadPresetParams(){
  Name = "my_preset",
  Unsigned = true,
  Tags = "remote",
  AllowedFormats = "jpg,png"};
cloudinary.CreateUploadPreset(uploadPresetParams);
cURL:
Copy to clipboard
curl \
  -d "name=my_preset&unsigned=true&tags=remote&allowed_formats=jpg,png" \
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_presets
CLI:
Copy to clipboard
cld admin create_upload_preset name="my_preset" unsigned="true" tags="remote" allowed_formats="jpg,png"

Sample response

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

Update an upload preset

Update an existing upload preset.

Syntax

PUT /upload_presets/:name

Ruby:
Copy to clipboard
Cloudinary::Api.update_upload_preset(name, options = {})
PHP:
Copy to clipboard
$api->update_upload_preset($name, $options = array());
Python:
Copy to clipboard
cloudinary.api.update_upload_preset(name, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.update_upload_preset(name, options, callback);
Java:
Copy to clipboard
api.updateUploadPreset(String name, Map options);
.Net:
Copy to clipboard
cloudinary.UpdateUploadPreset(uploadPresetParams params);
CLI:
Copy to clipboard
cld admin update_upload_preset (name)

Optional parameters

Parameter Type Description
name String The name of the upload preset.
unsigned Boolean Whether this upload preset allows unsigned uploading to Cloudinary. Default: false.
disallow_public_id Boolean Whether this upload preset disables assigning a public_id in the upload call. Default: false.
live Boolean Whether to enable "live broadcast", so that the upload preset can be used for live streaming.
{Upload parameters} The upload parameters to apply to assets uploaded with this preset.

Examples

Update an upload preset called 'wiki', to allow unsigned uploading, add the tag 'remote' to uploaded images, and only allow the uploading of JPG and PNG image formats:

Ruby:
Copy to clipboard
Cloudinary::Api.update_upload_preset("wiki",
  :unsigned => true, 
  :tags => "remote", 
  :allowed_formats => "jpg,png")
PHP:
Copy to clipboard
$api->update_upload_preset("wiki",
  array(
    "unsigned" => true, 
    "tags" => "remote", 
    "allowed_formats" => "jpg,png"));
Python:
Copy to clipboard
cloudinary.api.update_upload_preset("wiki",
  unsigned = True, 
  tags = "remote", 
  allowed_formats = "jpg,png")
Node.js:
Copy to clipboard
cloudinary.v2.api.update_upload_preset('wiki',
  { unsigned: true,
    tags: "remote", 
    allowed_formats: "jpg,png"},
  function(error, result){console.log(result);});
Java:
Copy to clipboard
api.updateUploadPreset("wiki",
  ObjectUtils.asMap(
    "unsigned", true, 
    "tags" => "remote", 
    "allowed_formats" => "jpg,png"));
.Net:
Copy to clipboard
var uploadPresetParams = new UploadPresetParams(){
  Name = "wiki",
  Unsigned = true,
  Tags = "remote",
  AllowedFormats = "jpg,png"};
cloudinary.UpdateUploadPreset(uploadPresetParams);
cURL:
Copy to clipboard
curl \
  -d "unsigned=true&tags=remote&allowed_formats=jpg,png" \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_presets/wiki
CLI:
Copy to clipboard
cld admin update_upload_preset "wiki" unsigned="true" tags="remote" allowed_formats="jpg,png"

Sample response

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

Delete an upload preset

Delete an existing upload preset.

Syntax

DELETE /upload_presets/:name

Ruby:
Copy to clipboard
Cloudinary::Api.delete_upload_preset(name)
PHP:
Copy to clipboard
$api->delete_upload_preset($name);
Python:
Copy to clipboard
cloudinary.api.delete_upload_preset(name)
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_upload_preset(name, callback);
Java:
Copy to clipboard
api.deleteUploadPreset(String name));
.Net:
Copy to clipboard
cloudinary.DeleteUploadPreset(String name);
CLI:
Copy to clipboard
cld admin delete_upload_preset (name)

Required parameters

Parameter Type Description
name String The name of the upload preset.

Examples

Delete an upload preset called 'remote_media':

Ruby:
Copy to clipboard
Cloudinary::Api.delete_upload_preset('remote_media')
PHP:
Copy to clipboard
$api->delete_upload_preset("remote_media");
Python:
Copy to clipboard
cloudinary.api.delete_upload_preset("remote_media")
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_upload_preset('remote_media',
  function(error, result){console.log(result);});
Java:
Copy to clipboard
api.deleteUploadPreset("remote_media",
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.DeleteUploadPreset("remote_media");
cURL:
Copy to clipboard
curl \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_presets/remote_media
CLI:
Copy to clipboard
cld admin delete_upload_preset "remote_media"

Sample response

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

Metadata

Enables you to manage the metadata fields available for your account.

For information on the overall structure of a metadata field as well as how to work with field validation and list (datasource) values, see the Metadata API reference documentation.

Method Description
GET/metadata_fields Get metadata fields
GET/metadata_fields/:external_id Get a metadata field by external id
POST/metadata_fields Create a metadata field
POST/metadata_fields/:external_id/datasource_restore Restore entries in a metadata field datasource
PUT/metadata_fields/:external_id Update a metadata field by external id
PUT/metadata_fields/:external_id/datasource Update a metadata field datasource
DELETE/metadata_fields/:external_id Delete a metadata field by external id
DELETE/metadata_fields/:external_id/datasource Delete entries in a metadata field datasource

Get metadata fields

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

Syntax

GET /metadata_fields

Ruby:
Copy to clipboard
Cloudinary::Api.list_metadata_fields(options = {})
PHP:
Copy to clipboard
$api->list_metadata_fields($options = array());
Python:
Copy to clipboard
cloudinary.api.list_metadata_fields(**options)
Node.js:
Copy to clipboard
cloudinary.v2.api.list_metadata_fields(options, callback);
Java:
Copy to clipboard
api.listMetadataFields();
.Net:
Copy to clipboard
cloudinary.ListMetadataFields();
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
      },
      {
        "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.

Syntax

GET /metadata_fields/:external_id

Ruby:
Copy to clipboard
Cloudinary::Api.metadata_field_by_field_id(external_id, options = {})
PHP:
Copy to clipboard
$api->metadata_field_by_field_id($external_id, $options = array());
Python:
Copy to clipboard
cloudinary.api.metadata_field_by_field_id(external_id, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.metadata_field_by_field_id(external_id, options, callback);
Java:
Copy to clipboard
api.metadataFieldByFieldId(String externalId);
.Net:
Copy to clipboard
cloudinary.GetMetadataField(string externalId);
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':

Ruby:
Copy to clipboard
Cloudinary::Api.metadata_field_by_field_id("in_stock")
PHP:
Copy to clipboard
$api->metadata_field_by_field_id("in_stock");
Python:
Copy to clipboard
cloudinary.api.metadata_field_by_field_id("in_stock")
Node.js:
Copy to clipboard
cloudinary.v2.api.metadata_field_by_field_id('in_stock');
Java:
Copy to clipboard
api.metadataFieldByFieldId("in_stock");
.Net:
Copy to clipboard
cloudinary.GetMetadataField("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
}

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 Generic structure of a metadata field for details.

Syntax

POST /metadata_fields

Ruby:
Copy to clipboard
Cloudinary::Api.add_metadata_field(field, options = {})
PHP:
Copy to clipboard
$api->add_metadata_field($field, $options = array());
Python:
Copy to clipboard
cloudinary.api.add_metadata_field(field, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.add_metadata_field(field, options, callback);
Java:
Copy to clipboard
api.addMetadataField(MetadataField field);
.Net:
Copy to clipboard
cloudinary.AddMetadataField(MetadataFieldCreateParams field);
CLI:
Copy to clipboard
cld admin add_metadata_field (field)

Required parameters

Parameter Type Description
field Object The metadata field to add. For details see Generic structure of a metadata field.

Examples

Add a new metadata field:

Ruby:
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:
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:
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:
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"}
    ]
  }
});
Java:
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:
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);
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"}]}}`

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.

Syntax

POST /metadata_fields/:external_id/datasource_restore

Ruby:
Copy to clipboard
Cloudinary::Api.restore_metadata_field_datasource(external_id, external_ids, options = {})
PHP:
Copy to clipboard
$api->restore_metadata_field_datasource($external_id, $external_ids, $options = array());
Python:
Copy to clipboard
cloudinary.api.restore_metadata_field_datasource(external_id, external_ids, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.restore_metadata_field_datasource(external_id, external_ids, options, callback);
Java:
Copy to clipboard
api.restoreDatasourceEntries(String externalId, List<String> externalIds);
.Net:
Copy to clipboard
cloudinary.RestoreMetadataDataSourceEntries(string externalId, List<string> externalIds)
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':

Ruby:
Copy to clipboard
Cloudinary::Api.restore_metadata_field_datasource("color_id", ["color1"])
PHP:
Copy to clipboard
$api->restore_metadata_field_datasource("color_id", array("color1"));
Python:
Copy to clipboard
cloudinary.api.restore_metadata_field_datasource("color_id", ["color1"])
Node.js:
Copy to clipboard
cloudinary.v2.api.restore_metadata_field_datasource('color_id', ["color1"]);
Java:
Copy to clipboard
api.restoreDatasourceEntries("color_id", Arrays.asList("color1"));
.Net:
Copy to clipboard
cloudinary.RestoreMetadataDataSourceEntries("color_id", new List<string>{"color1"});
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"]

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 Generic structure of a metadata field for details.

Syntax

PUT /metadata_fields/:external_id

Ruby:
Copy to clipboard
Cloudinary::Api.update_metadata_field(external_id, field, options = {})
PHP:
Copy to clipboard
$api->update_metadata_field($external_id, $field, $options = array());
Python:
Copy to clipboard
cloudinary.api.update_metadata_field(external_id, field, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.update_metadata_field(external_id, field, options, callback);
Java:
Copy to clipboard
api.updateMetadataField(String externalId, MetadataField field);
.Net:
Copy to clipboard
cloudinary.UpdateMetadataField(string externalId, MetadataFieldUpdateParams field)
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 Generic structure of a metadata field.

Examples

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

Ruby:
Copy to clipboard
Cloudinary::Api.update_metadata_field("in_stock", {
  :"label" => "Now in stock",
  :"mandatory" => true  })
PHP:
Copy to clipboard
$api->update_metadata_field("in_stock", 
  array(
    "label" => "Now in stock",
    "mandatory" => true  ));
Python:
Copy to clipboard
cloudinary.api.update_metadata_field("in_stock", {
  "label": "Now in stock",
  "mandatory": true  })
Node.js:
Copy to clipboard
cloudinary.v2.api.update_metadata_field('in_stock', {
  "label": "Now in stock",
  "mandatory": true  });
Java:
Copy to clipboard
SetMetadataField setField = new SetMetadataField();
setField.setLabel("Now in stock");
setField.setMandatory(true);
api.updateMetadataField("in_stock", setField);
.Net:
Copy to clipboard
var MetadataFieldUpdateParams = new StringMetadataFieldUpdateParams(){
  Label = "Now in stock",
  Mandatory = true  };
cloudinary.UpdateMetadataField("in_stock", MetadataFieldUpdateParams);
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}'

Sample response

Copy to clipboard
{
    "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.

Syntax

PUT /metadata_fields/:external_id/datasource

Ruby:
Copy to clipboard
Cloudinary::Api.update_metadata_field_datasource(external_id, entries, options = {})
PHP:
Copy to clipboard
$api->update_metadata_field_datasource($external_id, $entries, $options = array());
Python:
Copy to clipboard
cloudinary.api.update_metadata_field_datasource(external_id, entries, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.update_metadata_field_datasource(external_id, entries, options, callback);
Java:
Copy to clipboard
api.updateMetadataFieldDatasource(String externalId, List<MetadataDataSource.Entry> entries);
.Net:
Copy to clipboard
cloudinary.UpdateMetadataDataSourceEntries(string externalId, MetadataDataSourceParams entries)
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':

Ruby:
Copy to clipboard
Cloudinary::Api.update_metadata_field_datasource("color_id", {  
  :"values" => [{  
    :"external_id" => "color1",
    :"value" => "orange"
  },
  {  
    :"external_id" => "color2",
    :"value" => "black"
  }]
})
PHP:
Copy to clipboard
{  
    "external_id":"color2",
    "value":"black"
  }]
})
Python:
Copy to clipboard
cloudinary.api.update_metadata_field_datasource("color_id", [  
  "values":[{  
    "external_id":"color1",
    "value":"orange"
  },
Node.js:
Copy to clipboard
cloudinary.v2.api.update_metadata_field_datasource('color_id', {  
  "values":[{  
    "external_id":"color1",
    "value":"orange"
  },
  {  
    "external_id":"color2",
    "value":"black"
  }]
});
Java:
Copy to clipboard
api.updateMetadataFieldDatasource("color_id", 
  new MetadataDataSource(Arrays.asList(
    new Entry("color1", "orange"),
    new Entry("color2", "black")))
);
.Net:
Copy to clipboard
var metadataDataSourceParams = new MetadataDataSourceParams(){  
  Values = [{  
    ExternalId = "color1",
    Value = "orange"
  },
  {  
    ExternalId = "color2",
    Value = "black"
  }]
};
cloudinary.UpdateMetadataDataSourceEntries("color_id", metadataDataSourceParams);
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' '{"values":[{"external_id":"color1", "value":"orange"}, {"external_id":"color2", "value":"black"}]}'

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

Syntax

DELETE /metadata_fields/:external_id

Ruby:
Copy to clipboard
Cloudinary::Api.delete_metadata_field(external_id, options = {})
PHP:
Copy to clipboard
$api->delete_metadata_field($external_id, $options = array());
Python:
Copy to clipboard
cloudinary.api.delete_metadata_field(external_id, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_metadata_field(external_id, options, callback);
Java:
Copy to clipboard
api.deleteMetadataField(String externalId);
.Net:
Copy to clipboard
cloudinary.DeleteMetadataField(string externalId)
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':

Ruby:
Copy to clipboard
Cloudinary::Api.delete_metadata_field("in_stock")
PHP:
Copy to clipboard
$api->delete_metadata_field("in_stock");
Python:
Copy to clipboard
cloudinary.api.delete_metadata_field("in_stock")
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_metadata_field('in_stock');
Java:
Copy to clipboard
api.deleteMetadataField("in_stock");
.Net:
Copy to clipboard
cloudinary.DeleteMetadataField("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"

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, the entries still exist under the hood and can be activated again with the restore datasource entries method.

Syntax

DELETE /metadata_fields/:external_id/datasource

Ruby:
Copy to clipboard
Cloudinary::Api.delete_datasource_entries(external_id, external_ids, options = {})
PHP:
Copy to clipboard
$api->delete_datasource_entries($external_id, $external_ids, $options = array());
Python:
Copy to clipboard
cloudinary.api.delete_datasource_entries(external_id, external_ids, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_datasource_entries(external_id, external_ids, options, callback);
Java:
Copy to clipboard
api.deleteDatasourceEntries(String externalId, List<String> externalIds);
.Net:
Copy to clipboard
cloudinary.DeleteMetadataDataSourceEntries(string externalId, List<string> externalIds)
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 'color1' from the metadata field with external_id 'color_id':

Ruby:
Copy to clipboard
Cloudinary::Api.delete_datasource_entries("color_id", ["color1"])
PHP:
Copy to clipboard
$api->delete_datasource_entries("color_id", ["color1"]);
Python:
Copy to clipboard
cloudinary.api.delete_datasource_entries("color_id", ["color1"])
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_datasource_entries('color_id', ["color1"]);
Java:
Copy to clipboard
api.deleteDatasourceEntries("color_id", Arrays.asList("color1"));
.Net:
Copy to clipboard
cloudinary.DeleteMetadataDataSourceEntries("color_id", new List<string>{"color1"});
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" ["color1"]

Folders

Enables you to manage folders for your account.

Methods Description
GET/folders Get root folders
GET/folders/:root_folder Get subfolders
POST/folders/:folder Create a folder
DELETE/folders/:folder Delete a folder

Get root folders

Lists all the root folders. Limited to 2000 results.

Syntax

GET /folders

Ruby:
Copy to clipboard
Cloudinary::Api.root_folders
PHP:
Copy to clipboard
$api->root_folders();
Python:
Copy to clipboard
cloudinary.api.root_folders()
Node.js:
Copy to clipboard
cloudinary.v2.api.root_folders(callback);
Java:
Copy to clipboard
api.rootFolders(ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.RootFolders();
CLI:
Copy to clipboard
cld admin root_folders

Sample response

The response contains an array of all the root folders.

Copy to clipboard
{
    "folders": [
      {
        "name": "cloud",
        "path": "cloud"
      }, 
      {
        "name": "brooks",
        "path": "brooks"
      }   
    ]
}

Get subfolders

Lists the name and path of all the subfolders of a given folder. Limited to 2000 results.

Syntax

GET /folders/:folder

Ruby:
Copy to clipboard
Cloudinary::Api.subfolders(folder, options = {})
PHP:
Copy to clipboard
$api->subfolders($folder, $options = array());
Python:
Copy to clipboard
cloudinary.api.subfolders(folder, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.sub_folders(folder, options, callback);
Java:
Copy to clipboard
api.subfolders(String folder, Map options);
.Net:
Copy to clipboard
cloudinary.SubFolders(folderParams params);
CLI:
Copy to clipboard
cld admin subfolders (folder)

Required parameters

Parameter Type Description
folder String The full path of the folder to return subfolders of.

Optional parameters

Parameter Type Description
max_results Integers Maximum number of results to return (up to 500). Default: 10.
next_cursor String When a request has more results to return than max_results, the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of a following request.

Examples

List all subfolders of a given folder 'product/shoe':

Ruby:
Copy to clipboard
Cloudinary::Api.subfolders("product/shoe")
PHP:
Copy to clipboard
$api->subfolders("product/shoe");
Python:
Copy to clipboard
cloudinary.api.subfolders("product/shoe")
Node.js:
Copy to clipboard
cloudinary.v2.api.sub_folders("product/shoe", function(error, result){console.log(result);});
Java:
Copy to clipboard
api.subfolders("product/shoe", ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.SubFolders("product/shoe");
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/folders/product/shoe
CLI:
Copy to clipboard
cld admin subfolders "product/shoe"

Sample response

The response contains an array of all the subfolders of the given folder.

Copy to clipboard
{
    "folders": [
      {
        "name": "red",
        "path": "product/shoe/red"
      }, 
      {
        "name": "white",
        "path": "product/shoe/white"
      }   
    ]
 }

Create folder

Create a new empty folder.

Syntax

POST /folders/:folder

Ruby:
Copy to clipboard
Cloudinary::Api.create_folder(folder)
PHP:
Copy to clipboard
$api->create_folder($folder);
Python:
Copy to clipboard
cloudinary.api.create_folder(folder)
Node.js:
Copy to clipboard
cloudinary.v2.api.create_folder(folder, callback);
Java:
Copy to clipboard
api.createFolder(String folder, Map options);
.Net:
Copy to clipboard
cloudinary.CreateFolder(folder);
CLI:
Copy to clipboard
cld admin create_folder $folder

Required parameters

Parameter Type Description
folder String The full path of the new folder to create.

Examples

Create a new folder called 'test' as a subfolder of the root folder 'product' ('product/test'):

Ruby:
Copy to clipboard
Cloudinary::Api.create_folder("product/test")
PHP:
Copy to clipboard
$api->create_folder("product/test");
Python:
Copy to clipboard
cloudinary.api.create_folder("product/test")
Node.js:
Copy to clipboard
cloudinary.v2.api.create_folder("product/test", function(error, result){console.log(result);});
Java:
Copy to clipboard
api.createFolder("product/test", ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.CreateFolder("product/test");
cURL:
Copy to clipboard
curl \
  -X POST
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/folders/product/test
CLI:
Copy to clipboard
cld admin create_folder "product/test"

Sample response

Copy to clipboard
{
    "success": true,
    "path": "product/test",
    "name": "test"
}

Delete folder

Deletes an empty folder.

Note
Use the Delete resources method to delete the assets within a folder.

Syntax

DELETE /folders/:folder

Ruby:
Copy to clipboard
Cloudinary::Api.delete_folder(folder)
PHP:
Copy to clipboard
$api->delete_folder($folder);
Python:
Copy to clipboard
cloudinary.api.delete_folder(folder)
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_folder(folder, callback);
Java:
Copy to clipboard
api.deleteFolder(String folder, Map options);
.Net:
Copy to clipboard
cloudinary.DeleteFolder(folder);
CLI:
Copy to clipboard
cld admin delete_folder (folder)

Required parameters

Parameter Type Description
folder String The full path of the empty folder to delete.

Examples

Delete a folder called 'test' which is a subfolder of the root folder 'product' ('product/test'):

Ruby:
Copy to clipboard
Cloudinary::Api.delete_folder("product/test")
PHP:
Copy to clipboard
$api->delete_folder("product/test");
Python:
Copy to clipboard
cloudinary.api.delete_folder("product/test")
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_folder("product/test", function(error, result){console.log(result);});
Java:
Copy to clipboard
api.deleteFolder("product/test", ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.DeleteFolder("product/test");
cURL:
Copy to clipboard
curl \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/folders/product/test
CLI:
Copy to clipboard
cld admin delete_folder "product/test"

Sample response

Copy to clipboard
{
    "deleted": [
        "product/test"
    ]
}

Adaptive streaming profiles

Enables you to list, get details of, create, modify, or delete built-in and custom adaptive streaming profiles, which can be used to deliver your video using HLS and MPEG-DASH adaptive bitrate streaming.

Methods Description
GET/streaming_profiles Get adaptive streaming profiles
GET/streaming_profiles/:name Get details of a streaming profile
POST/streaming_profiles Create a streaming profile
PUT/streaming_profiles/:name Update an existing streaming profile
DELETE/streaming_profiles/:name Delete or revert the specified streaming profile

Get adaptive streaming profiles

List streaming profiles, including built-in and custom profiles.

Syntax

GET /streaming_profiles

Ruby:
Copy to clipboard
Cloudinary::Api.list_streaming_profiles
PHP:
Copy to clipboard
$api->list_streaming_profiles();
Python:
Copy to clipboard
cloudinary.api.list_streaming_profiles()
Node.js:
Copy to clipboard
cloudinary.v2.api.list_streaming_profiles(callback);
Java:
Copy to clipboard
api.listStreamingProfiles();
.Net:
Copy to clipboard
Not supported by this SDK
CLI:
Copy to clipboard
cld admin list_streaming_profiles

Sample response

The response contains an array of all the defined streaming profiles.

Copy to clipboard
{
  "data": [
    {
      "name": "4k",
      "display_name": "4K (2160p)",
      "predefined": true
    },
    {
      "name": "full_hd",
      "display_name": "Full HD (1080p)",
      "predefined": true
    },
    {
      "name": "hd",
      "display_name": "HD (720p)",
      "predefined": true
    },
    {
      "name": "sd",
      "display_name": "SD (480p)",
      "predefined": true
    },
    {
      "name": "full_hd_wifi",
      "display_name": "Full HD WiFi (1080p)",
      "predefined": true
    },
    {
      "name": "full_hd_lean",
      "display_name": "Full HD Lean (1080p)",
      "predefined": true
    },
    {
      "name": "hd_lean",
      "display_name": "HD Lean (720p)",
      "predefined": true
    },
    {
      "name": "custom_square",
      "display_name": "Custom square resolution",
      "predefined": false
    }
  ]
}

Get details of a single streaming profile

Retrieve the details of a single streaming profile by name.

Syntax

GET /streaming_profiles/:name

Ruby:
Copy to clipboard
Cloudinary::Api.get_streaming_profile(name)
PHP:
Copy to clipboard
$api->get_streaming_profile($name);
Python:
Copy to clipboard
cloudinary.api.get_streaming_profile(name)
Node.js:
Copy to clipboard
cloudinary.v2.api.get_streaming_profile(name, callback);
Java:
Copy to clipboard
api.getStreamingProfile(String name);
.Net:
Copy to clipboard
Not supported by this SDK
CLI:
Copy to clipboard
cld admin get_streaming_profile (name)

Required parameters

Parameter Type Description
name String The name of the streaming profile to get the details of.

Examples

Get the details of a specified streaming file:

Ruby:
Copy to clipboard
Cloudinary::Api.get_streaming_profile('custom_square')
PHP:
Copy to clipboard
$api->get_streaming_profile("custom_square");
Python:
Copy to clipboard
cloudinary.api.get_streaming_profile("custom_square")
Node.js:
Copy to clipboard
cloudinary.v2.api.get_streaming_profile('custom_square', function(error, result){console.log(result);});
Java:
Copy to clipboard
api.getStreamingProfile("custom_square");
.Net:
Copy to clipboard
Not supported by this SDK
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/streaming_profiles/custom_square
CLI:
Copy to clipboard
cld admin get_streaming_profile "custom_square"

Sample response

The response contains details for a single streaming profile.

Copy to clipboard
{
 "data": {
   "name": "custom_square",
   "display_name": "Custom square resolution",
   "predefined": false,
   "representations": [
     {
       "transformation": {
         "width": 1200, "height": 1200, "bit_rate": "5m", "video_codec": "h264:main:3.1"
       }
     },
     {
       "transformation": {
         "width": 900, "height": 900, "bit_rate": "3500k", "video_codec": "h264:main:3.1"
       }
     },
     {
       "transformation": {
         "width": 600, "height": 600, "bit_rate": "1500k", "video_codec": "h264:baseline:3.0"
       }
     }
   ]
 }
}

Create a streaming profile

Create a new, custom streaming profile.

Syntax

POST /streaming_profiles

Ruby:
Copy to clipboard
Cloudinary::Api.create_streaming_profile(name, options = {})
PHP:
Copy to clipboard
$api->create_streaming_profile($name, $options = array());
Python:
Copy to clipboard
cloudinary.api.create_streaming_profile(name, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.create_streaming_profile(name, options, callback);
Java:
Copy to clipboard
:
api.createStreamingProfile(String name, Map options);
.Net:
Copy to clipboard
Not supported by this SDK
CLI:
Copy to clipboard
cld admin create_streaming_profile (name)

Required parameters

Parameter Type Description
name String The identification name to assign to the new streaming profile. The name is case-insensitive and can contain alphanumeric characters, underscores (_) and hyphens (-).
representations JSON string An array of structures that defines a custom streaming profile.
transformation String or Hash Specifies the transformation parameters for the representation. All video transformation parameters except video_sampling are supported. Common transformation parameters for representations include: width, height (or aspect_ratio), bit_rate, video_codec, audio_codec, sample_rate (or fps), etc.

Optional parameters

Parameter Type Description
display_name String A descriptive name for the profile.

Examples

Create a streaming profile with 3 representations:

Ruby:
Copy to clipboard
Cloudinary::Api.create_streaming_profile("custom_square",
  :display_name => "Custom square resolution",
  :representations =>
    [{:transformation => {:crop => "limit", :width => "1200", :height => "1200", :bit_rate => "5m"}},
     {:transformation => {:crop => "limit", :width => "900", :height => "900", :bit_rate => "3500k"}}
     {:transformation => {:crop => "limit", :width => "600", :height => "600", :bit_rate => "1500k"}}])
PHP:
Copy to clipboard
$api->create_streaming_profile("custom_square", 
  array(
    "display_name" => "Custom square resolution",
    "representations" => array(
      array("crop" => "limit", "width" => 1200, "height" => 1200, "bit_rate" => "5m"),
      array("crop" => "limit", "width" => 900, "height" => 900, "bit_rate" => "3500k"),
      array("crop" => "limit", "width" => 600, "height" => 600, "bit_rate" => "1500k"))));
Python:
Copy to clipboard
cloudinary.api.create_streaming_profile("custom_square",
  display_name="Custom square resolution",
  representations=[
    {"transformation": {"crop": "limit", "width": 1200, "height": 1200, "bit_rate": "5m"}},
    {"transformation": {"crop": "limit", "width": 900, "height": 900, "bit_rate": "3500k"}},
    {"transformation": {"crop": "limit", "width": 600, "height": 600, "bit_rate": "1500k"}}])
Node.js:
Copy to clipboard
cloudinary.v2.api.create_streaming_profile('custom_square',
  { display_name: "Custom square resolution",
    representations: [
    { transformation:{crop: "limit", width: 1200, height: 1200, bit_rate: "5m" }},
    { transformation:{crop: "limit", width: 900, height: 900, bit_rate: "3500k" }},
    { transformation:{crop: "limit", width: 600, height: 600, bit_rate: "1500k" }}] },
  function(error, result){console.log(result);});
Java:
Copy to clipboard
:
api.createStreamingProfile("custom_square", "Custom square resolution",
  Arrays.asList(
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(1200).height(1200).bitRate("5m")),
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(900).height(900).bitRate("3500k")),
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(600).height(600).bitRate("1500k"))));
.Net:
Copy to clipboard
Not supported by this SDK
cURL:
Copy to clipboard
curl \
  -d 'name=custom_square&display_name=Custom%20square%20resolution&representations=\[\{%22transformation%22:%22c_limit,w_1200,h_1200,br_5m%22\},\{%22transformation%22:%22c_limit,w_900,h_900,br_3500k%22\},\{%22transformation%22:%22c_limit,w_600,h_600,br_1500k%22\}\]'
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/streaming_profiles
CLI:
Copy to clipboard
cld admin create_streaming_profile "custom_square" display_name="Custom square resolution" representations='[{"transformation": {"crop": "limit","width": 1200, "height": 1200, "bit_rate": "5m"}},{"transformation": {"crop": "limit", "width": 900, "height": 900, "bit_rate": "3500k"}},{"transformation": {"crop": "limit", "width": 600, "height": 600, "bit_rate": "1500k"}}]'

Sample response

The response contains details for the streaming profile that was created.

Copy to clipboard
{
 "data": {
   "name": "custom_square",
   "display_name": "Custom square resolution",
   "predefined": false,
   "representations": [
     {
       "transformation": {
         "width": 1200, "height": 1200, "bit_rate": "5m", "video_codec": "h264:main:3.1"
       }
     },
     {
       "transformation": {
         "width": 900, "height": 900, "bit_rate": "3500k", "video_codec": "h264:main:3.1"
       }
     },
     {
       "transformation": {
         "width": 600, "height": 600, "bit_rate": "1500k", "video_codec": "h264:baseline:3.0"
       }
     }
   ]
 }
}

Create a streaming profile with 6 representations and a combination of codecs:

Ruby:
Copy to clipboard
Cloudinary::Api.create_streaming_profile("custom_square_combo",
  :display_name => "Custom square resolution with combination of codecs",
  :representations =>
    [{:transformation => {:crop => "limit", :width => "1200", :height => "1200", :video_codec => "h265", :bit_rate => "5m"}},
     {:transformation => {:crop => "limit", :width => "900", :height => "900", :video_codec => "h265", :bit_rate => "3500k"}},
     {:transformation => {:crop => "limit", :width => "600", :height => "600", :video_codec => "h265", :bit_rate => "1500k"}},
     {:transformation => {:crop => "limit", :width => "1200", :height => "1200", :video_codec => "vp9", :bit_rate => "5m"}},
     {:transformation => {:crop => "limit", :width => "900", :height => "900", :video_codec => "vp9", :bit_rate => "3500k"}}
     {:transformation => {:crop => "limit", :width => "600", :height => "600", :video_codec => "vp9", :bit_rate => "1500k"}}])
PHP:
Copy to clipboard
$api->create_streaming_profile("custom_square_combo", 
  array(
    "display_name" => "Custom square resolution with combination of codecs",
    "representations" => array(
      array("crop" => "limit", "width" => 1200, "height" => 1200, "video_codec" => "h265", "bit_rate" => "5m"),
      array("crop" => "limit", "width" => 900, "height" => 900, "video_codec" => "h265", "bit_rate" => "3500k"),
      array("crop" => "limit", "width" => 600, "height" => 600, "video_codec" => "h265", "bit_rate" => "1500k"),
      array("crop" => "limit", "width" => 1200, "height" => 1200, "video_codec" => "vp9", "bit_rate" => "5m"),
      array("crop" => "limit", "width" => 900, "height" => 900, "video_codec" => "vp9", "bit_rate" => "3500k"),
      array("crop" => "limit", "width" => 600, "height" => 600, "video_codec" => "vp9", "bit_rate" => "1500k"))));
Python:
Copy to clipboard
cloudinary.api.create_streaming_profile("custom_square_combo",
  display_name="Custom square resolution with combination of codecs",
  representations=[
    {"transformation": {"crop": "limit", "width": 1200, "height": 1200, "video_codec": "h265", "bit_rate": "5m"}},
    {"transformation": {"crop": "limit", "width": 900, "height": 900, "video_codec": "h265", "bit_rate": "3500k"}},
    {"transformation": {"crop": "limit", "width": 600, "height": 600, "video_codec": "h265", "bit_rate": "1500k"}},
    {"transformation": {"crop": "limit", "width": 1200, "height": 1200, "video_codec": "vp9", "bit_rate": "5m"}},
    {"transformation": {"crop": "limit", "width": 900, "height": 900, "video_codec": "vp9", "bit_rate": "3500k"}},
    {"transformation": {"crop": "limit", "width": 600, "height": 600, "video_codec": "vp9", "bit_rate": "1500k"}}])
Node.js:
Copy to clipboard
cloudinary.v2.api.create_streaming_profile('custom_square_combo',
  { display_name: "Custom square resolution with combination of codecs",
    representations: [
    { transformation:{crop: "limit", width: 1200, height: 1200, video_codec: "h265", bit_rate: "5m" }},
    { transformation:{crop: "limit", width: 900, height: 900, video_codec: "h265", bit_rate: "3500k" }},
    { transformation:{crop: "limit", width: 600, height: 600, video_codec: "h265", bit_rate: "1500k" }},
    { transformation:{crop: "limit", width: 1200, height: 1200, video_codec: "vp9", bit_rate: "5m" }},
    { transformation:{crop: "limit", width: 900, height: 900, video_codec: "vp9", bit_rate: "3500k" }},
    { transformation:{crop: "limit", width: 600, height: 600, video_codec: "vp9", bit_rate: "1500k" }}] },
  function(error, result){console.log(result);});
Java:
Copy to clipboard
:
api.createStreamingProfile("custom_square_combo", "Custom square resolution with combination of codecs",
  Arrays.asList(
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(1200).height(1200).videoCodec("h265").bitRate("5m")),
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(900).height(900).videoCodec("h265").bitRate("3500k")),
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(600).height(600).videoCodec("h265").bitRate("1500k")),
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(1200).height(1200).videoCodec("vp9").bitRate("5m")),
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(900).height(900).videoCodec("vp9").bitRate("3500k")),
    ObjectUtils.asMap("transformation", new 
      Transformation().crop("limit").width(600).height(600).videoCodec("vp9").bitRate("1500k"))));
.Net:
Copy to clipboard
Not supported by this SDK
cURL:
Copy to clipboard
curl \
  -d 'name=custom_square_combo&display_name=Custom%20square%20resolution%20with%20combination%20of%20codecs&representations=\[\{%22transformation%22:%22c_limit,w_1200,h_1200,vc_h264,br_5m%22\},\{%22transformation%22:%22c_limit,w_900,h_900,vc_h264,br_3500k%22\},\{%22transformation%22:%22c_limit,w_600,h_600,vc_h264,br_1500k%22\},\{%22transformation%22:%22c_limit,w_1200,h_1200,vc_vp9,br_5m%22\},\{%22transformation%22:%22c_limit,w_900,h_900,vc_vp9,br_3500k%22\},\{%22transformation%22:%22c_limit,w_600,h_600,vc_vp9,br_1500k%22\}\]'
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/streaming_profiles
CLI:
Copy to clipboard
cld admin create_streaming_profile "custom_square_combo" display_name="Custom square resolution with combination of codecs" representations='[{"transformation": {"crop": "limit", "width": 1200, "height": 1200, "video_codec": "h265", "bit_rate": "5m"}},{"transformation": {"crop": "limit", "width": 900, "height": 900, "video_codec": "h265", "bit_rate": "3500k"}},{"transformation": {"crop": "limit", "width": 600, "height": 600, "video_codec": "h265", "bit_rate": "1500k"}},{"transformation": {"crop": "limit", "width": 1200, "height": 1200, "video_codec": "vp9", "bit_rate": "5m"}},{"transformation": {"crop": "limit", "width": 900, "height": 900, "video_codec": "vp9", "bit_rate": "3500k"}},{"transformation": {"crop": "limit", "width": 600, "height": 600, "video_codec": "vp9", "bit_rate": "1500k"}}]'

Sample response

The response contains details for the streaming profile that was created.

Copy to clipboard
{
  "data":{
    "name":"custom_square_combo",
    "display_name":"Custom square resolution with combination of codecs",
    "predefined":false,
    "representations":[
      {
        "transformation":[
          {
            "width":1200,
            "height":1200,
            "video_codec":"h265",
            "bit_rate":"5m",
            "crop":"limit"
          }
        ]
      },
      {
        "transformation":[
          {
            "width":900,
            "height":900,
            "video_codec":"h265",
            "bit_rate":"3500k",
            "crop":"limit"
          }
        ]
      },
      {
        "transformation":[
          {
            "width":600,
            "height":600,
            "video_codec":"h265",
            "bit_rate":"1500k",
            "crop":"limit"
          }
        ]
      },
      {
        "transformation":[
          {
            "width":1200,
            "height":1200,
            "video_codec":"vp9",
            "bit_rate":"5m",
            "crop":"limit"
          }
        ]
      },
      {
        "transformation":[
          {
            "width":900,
            "height":900,
            "video_codec":"vp9",
            "bit_rate":"3500k",
            "crop":"limit"
          }
        ]
      },
      {
        "transformation":[
          {
            "width":600,
            "height":600,
            "video_codec":"vp9",
            "bit_rate":"1500k",
            "crop":"limit"
          }
        ]
      }
    ]
  }
}

Update an existing streaming profile

Update the specified existing streaming profile. You can update both custom and built-in profiles. The specified list of representations replaces the previous list.

Syntax

PUT /streaming_profiles

Ruby:
Copy to clipboard
Cloudinary::Api.update_streaming_profile(name, options = {})
PHP:
Copy to clipboard
$api->update_streaming_profile($name, $options = array());
Python:
Copy to clipboard
cloudinary.api.update_streaming_profile(name, **options)
Node.js:
Copy to clipboard
cloudinary.v2.api.update_streaming_profile(name,up options, callback);
Java:
Copy to clipboard
:
api.updateStreamingProfile(String name, Map options);
.Net:
Copy to clipboard
Not supported by this SDK
CLI:
Copy to clipboard
cld admin update_streaming_profile (name)

Required parameters

Parameter Type Description
name String The identification name to assign to the new streaming profile. The name is case-insensitive and can contain alphanumeric characters, underscores (_) and hyphens (-).
representations JSON string An array of structures that defines a custom streaming profile.
transformation String or Hash Specifies the transformation parameters for the representation. All video transformation parameters except video_sampling are supported. Common transformation parameters for representations include: width, height (or aspect_ratio), bit_rate, video_codec, audio_codec, sample_rate (or fps), etc.

Optional parameters

Parameter Type Description
display_name String A descriptive name for the profile.

Examples

Add a fourth (fallback) representation to an existing custom streaming profile:

Ruby:
Copy to clipboard
Cloudinary::Api.update_streaming_profile("custom_square",  
:representations => 
  [{:transformation => {:crop => "limit", :width => "1200", :height => "1200", :bit_rate => "5m"}},
   {:transformation => {:crop => "limit", :width => "900", :height => "900", :bit_rate => "3500k"}},
   {:transformation => {:crop => "limit", :width => "600", :height => "600", :bit_rate => "1500k"}},
   {:transformation => {:crop => "limit", :width => "320", :height => "320", :bit_rate => "192k"}}])
PHP:
Copy to clipboard
$api->update_streaming_profile("custom_square", 
  array(
    "representations" => array(
      array("transformation" => array("crop" => "limit", "width" => 1200, "height" => 1200, "bit_rate" => "5m")),
      array("transformation" => array("crop" => "limit", "width" => 900, "height" => 900, "bit_rate" => "3500k")),
      array("transformation" => array("crop" => "limit", "width" => 600, "height" => 600, "bit_rate" => "1500k")),
      array("transformation" => array("crop" => "limit", "width" => 320, "height" => 320, "bit_rate" => "192k")))));
Python:
Copy to clipboard
cloudinary.api.create_streaming_profile("custom_square",
  representations=[
    {"transformation": {"crop": "limit", "width": 1200, "height": 1200, "bit_rate": "5m"}},
    {"transformation": {"crop": "limit", "width": 900, "height": 900, "bit_rate": "3500k"}},
    {"transformation": {"crop": "limit", "width": 600, "height": 600, "bit_rate": "1500k"}},
    {"transformation": {"crop": "limit", "width": 320, "height": 320, "bit_rate": "192k"}}])
Node.js:
Copy to clipboard
cloudinary.v2.api.update_streaming_profile('custom_square',
  { representations: [
    { transformation: {crop: "limit", width: 1200, height: 1200, bit_rate: "5m" }},
    { transformation: {crop: "limit", width: 900, height: 900, bit_rate: "3500k" }},
    { transformation: {crop: "limit", width: 600, height: 600, bit_rate: "1500k" }},
    { transformation: {crop: "limit", width: 320, height: 320, bit_rate: "192k" }}]},
  function(error, result){console.log(result);});
Java:
Copy to clipboard
:

api.updateStreamingProfile("custom_square", null,
  Arrays.asList(
    new Transformation().crop("limit").width(1200).height(1200).bit_rate("5m"),
    new Transformation().crop("limit").width(900).height(900).bit_rate("3500k"),
    new Transformation().crop("limit").width(600).height(600).bit_rate("1500k"),
    new Transformation().crop("limit").width(320).height(320).bit_rate("192k")));
.Net:
Copy to clipboard
Not supported by this SDK
cURL:
Copy to clipboard
curl \
  -d 'representations=\[\{%22transformation%22:%22c_limit,w_1200,h_1200,br_5m%22\},\{%22transformation%22:%22c_limit,w_900,h_900,br_3500k%22\},\{%22transformation%22:%22c_limit,w_600,h_600,br_1500k%22\},\{%22transformation%22:%22c_limit,w_320,h_320,br_192k%22\}\]' \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/streaming_profiles/custom_square
CLI:
Copy to clipboard
cld admin update_streaming_profile "custom_square" representations='[{"transformation": {"crop": "limit", "width": 1200, "height": 1200, "bit_rate": "5m"}},{"transformation": {"crop": "limit", "width": 900, "height": 900, "bit_rate": "3500k"}},{"transformation": {"crop": "limit", "width": 600, "height": 600, "bit_rate": "1500k"}},{"transformation": {"crop": "limit", "width": 320, "height": 320, "bit_rate": "192k"}}]'

Sample response

The response contains details for the streaming profile that was updated.

Copy to clipboard
{
  "message": "updated",
  "data": {
    "name": "custom_square",
    "display_name": "Custom square resolution",
    "predefined": false,
    "representations": [
      {
        "transformation": {
          "width": 1200, "height": 1200, "bit_rate": "5m", "video_codec": "h264:main:3.1"
        }
      },
      {
        "transformation": {
          "width": 900, "height": 900, "bit_rate": "3500k", "video_codec": "h264:main:3.1"
        }
      },
      {
        "transformation": {
          "width": 600, "height": 600, "bit_rate": "1500k", "video_codec": "h264:baseline:3.0"
        }
      }
      {
        "transformation": {
          "width": 320, "height": 320, "bit_rate": "192k", "video_codec": "h264:baseline:3.0"
        }
      }                
    ]
  }
}

Delete or revert the specified streaming profile

For custom streaming profiles, delete the specified profile.

For built-in streaming profiles, if the built-in profile was modified, revert the profile to the original settings.

For built-in streaming profiles that have not been modified, the Delete method returns an error.

Syntax

DELETE /streaming_profiles/:name

Ruby:
Copy to clipboard
Cloudinary::Api.delete_streaming_profile(name)
PHP:
Copy to clipboard
$api->delete_streaming_profile($name);
Python:
Copy to clipboard
cloudinary.api.delete_streaming_profile(name)
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_streaming_profile(name, callback);
Java:
Copy to clipboard
api.deleteStreamingProfile(String name);
.Net:
Copy to clipboard
Not supported by this SDK
CLI:
Copy to clipboard
cld admin delete_streaming_profile (name)

Required parameters

Parameter Type Description
name String The name of the streaming profile to delete or revert.

Examples

Delete the custom_square streaming file:

Ruby:
Copy to clipboard
Cloudinary::Api.delete_streaming_profile('custom_square')
PHP:
Copy to clipboard
$api->delete_streaming_profile("custom_square");
Python:
Copy to clipboard
cloudinary.api.delete_streaming_profile("custom_square")
Node.js:
Copy to clipboard
cloudinary.v2.api.delete_streaming_profile('custom_square', 
  function(error, result){console.log(result);});
Java:
Copy to clipboard
api.deleteStreamingProfile("custom_square");
.Net:
Copy to clipboard
Not supported by this SDK
cURL:
Copy to clipboard
curl \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/streaming_profiles/custom_square
CLI:
Copy to clipboard
cld admin delete_streaming_profile "custom_square"

Sample response

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

Tags

Enables you to retrieve a list of all the tags currently used for a specified resource_type.

Methods Description
GET /tags Get tags

Get tags

Syntax

GET /tags/:resource_type

Ruby:
Copy to clipboard
Cloudinary::Api.tags
PHP:
Copy to clipboard
$api->tags();
Python:
Copy to clipboard
cloudinary.api.tags()
Node.js:
Copy to clipboard
cloudinary.v2.api.tags(callback);
Java:
Copy to clipboard
api.tags(ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.ListTags();
CLI:
Copy to clipboard
cld admin tags

Optional parameters

Parameter Type Description
resource_type String The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Possible values: image (default), raw, video.
prefix String Find all tags that start with the given prefix.
max_results Integers Maximum number of assets to return (up to 500). Default: 10.
next_cursor String When a request has more results to return than max_results, the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of a following request.

Examples

List tags for all images

Ruby:
Copy to clipboard
Cloudinary::Api.tags
PHP:
Copy to clipboard
$api->tags();
Python:
Copy to clipboard
cloudinary.api.tags()
Node.js:
Copy to clipboard
cloudinary.v2.api.tags(
  function(error, result){console.log(result);});
Java:
Copy to clipboard
api.tags(ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.ListTags();
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/tags/image
CLI:
Copy to clipboard
cld admin tags

List tags that start with 'pro' for all images:

Ruby:
Copy to clipboard
Cloudinary::Api.tags(:prefix => "pro")
PHP:
Copy to clipboard
$api->tags(array("prefix" => "pro"));
Python:
Copy to clipboard
cloudinary.api.tags(prefix = "pro")
Node.js:
Copy to clipboard
cloudinary.v2.api.tags({prefix: 'pro'}, 
  function(error, result){console.log(result);});
Java:
Copy to clipboard
api.tags(ObjectUtils.asMap("prefix", "pro"));
.Net:
Copy to clipboard
cloudinary.ListTagsByPrefix("pro");
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/tags/image?prefix=pro
CLI:
Copy to clipboard
cld admin tags prefix="pro"

Sample response

Copy to clipboard
{
  "tags": [
    "arrow_animation",
    "logo"
  ]
}

Usage

Enables you to get a report on the status of your Cloudinary account usage details, including storage, credits, bandwidth, requests, number of resources, and add-on usage. Note that numbers are updated periodically.

Methods Description
GET /usage Get account usage details

Get account usage details

Syntax

GET /usage

Ruby:
Copy to clipboard
Cloudinary::Api.usage
PHP:
Copy to clipboard
$api->usage();
Python:
Copy to clipboard
cloudinary.api.usage()
Node.js:
Copy to clipboard
cloudinary.v2.api.usage(callback);
Java:
Copy to clipboard
api.usage(ObjectUtils.emptyMap());
.Net:
Copy to clipboard
cloudinary.GetUsage();
CLI:
Copy to clipboard
cld admin usage

Optional parameters

Parameter Type Description
date String The date for the usage report. Must be within the last 3 months and given in the format: dd-mm-yyyy. Default: the current date

Examples

Return a usage report for the 10th of November, 2019 (10-11-2019):

Ruby:
Copy to clipboard
Cloudinary::Api.usage(:date => "10-11-2019")
PHP:
Copy to clipboard
$api->usage(array("date" => "10-11-2019"));
Python:
Copy to clipboard
cloudinary.api.usage(date = "10-11-2019")
Node.js:
Copy to clipboard
cloudinary.v2.api.usage({date: '10-11-2019'}, 
  function(error, result){console.log(result);});
Java:
Copy to clipboard
api.usage(ObjectUtils.asMap("date", "10-11-2019"));
.Net:
Copy to clipboard
cloudinary.GetUsage("10-11-2019");
cURL:
Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/usage/10-11-2019
CLI:
Copy to clipboard
cld admin usage date="10-11-2019"

Sample response

The response contains an object with detailed usage information.

Copy to clipboard
{
  "plan": "Basic",
  "last_updated": "2019-11-10",
  "transformations": {"usage": 1218018, "credits_usage": 1.22}, 
  "objects": {"usage": 1217216}, 
  "bandwidth": {"usage": 268903064875, "credits_usage": 0.24}, 
  "storage": {"usage": 10298444599, "credits_usage": 0.01}, 
  "credits": {"usage": 1.47}, 
  "requests": 877212,
  "resources": 1239,
  "derived_resources": 10091,
  "url2png": {"usage": 15, "limit": 50},
  "webpurify": {"usage": 28, "limit": 50},
  "aspose": {"usage": 40, "limit": 50},
  "style_transfer": {"usage": 76, "limit": 5000},
  "azure_video_indexer": {"usage": 2340, "limit": 5000}, 
  "object_detection": {"usage": 340, "limit": 500},
  "media_limits": { 
    "image_max_size_bytes": 157286400, 
    "video_max_size_bytes": 3145728000, 
    "raw_max_size_bytes": 2097152000, 
    "image_max_px": 100000000, 
    "asset_max_total_px": 300000000 
  }
}

Ping

Enables you to test the reachability of the Cloudinary API with the ping method.

Methods Description
GET/ping Ping Cloudinary servers

Ping Cloudinary servers

Syntax

GET /ping

Ruby:
Copy to clipboard
Cloudinary::Api.ping
PHP:
Copy to clipboard
$api->ping();
Python:
Copy to clipboard
cloudinary.api.ping()
Node.js:
Copy to clipboard
cloudinary.v2.api.ping(callback);
Java:
Copy to clipboard
api.ping(ObjectUtils.emptyMap());
.Net:
Copy to clipboard
Not supported by this SDK
CLI:
Copy to clipboard
cld admin ping

Sample response

The response contains the current status of the Cloudinary servers.

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

✔️ Feedback sent!

Rate this page: