Admin API

Overview

The administrative API allows full control of all uploaded raw files and images, fetched social profile pictures, generated transformations and more. The admin API supports the following actions:

Listing all uploaded images and raw files.
Receiving details and metadata for uploaded images, including timestamps, format, dimensions, etc.
Listing the derived images of uploaded images.
Finding all images that share a given tag.
Listing all transformations.
Listing tags.
Receiving transformation details.
Creating named transformations.
Deleting images, raw files, derived images and transformations.
Listing all upload presets.
Deleting, updating and creating upload presets.
Listing all upload mappings.
Deleting, updating and creating upload mappings.
Restoring deleted files from backup.
Listing root folders and subfolders.
Getting usage reports.
Pinging Cloudinary's API.

Protocol and authentication

The API is accessed using HTTPS to endpoints in the following format:

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

For example, image listing of the 'demo' account:

https://api.cloudinary.com/v1_1/demo/resources/images

You can try the following cURL command after setting the correct cloud name, API key and API secret of your account:

curl 'https://API_KEY:API_SECRET@api.cloudinary.com/v1_1/CLOUD_NAME/resources/image'

Authentication is done using Basic Authentication over secure HTTP. Your Cloudinary API Key and API Secret are used for the authentication.

Request parameters are appended to the URL. The response is in a simple JSON snippet. Like any REST API, read-only requests are sent in HTTP GET while write requests are sent in PUT, POST and DELETE.

Pagination

Listing 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 listing. There is a maximum number of results you can request for a single API call (either 100 or 500 for the various methods).

Resource deletion methods also operate in chunks. A single call can delete up to 1000 resources.

When a listing request has more results to return than max_results or when a deletion request has more resources to delete than 1000, 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 listing or deletion request. This way you can browse through the full lists of uploaded resources, transformations and tags of your Cloudinary account or delete the entire set that matches the deletion query.

Error handling

The API returns the status of requests using the HTTP status code:

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

The API wrapping of Cloudinary's client libraries report errors by raising applicative exception.

In addition, a JSON with an informative message is returned. For example:

{ "error": { "message": "Resource not found - strange_name" } }

Usage limits

You can use the Admin API quite extensively. We ask for that you keep your ongoing API requests to 500 per hour (12,000 daily) when using our Free plan. Subscribe to our Basic plan onward to increase the limit to 2,000 calls per hour (48,000 daily). If you require more flexible limits, don’t hesitate to contact us.

Note: This limit refers only to Admin API requests (listing & deleting images and resources), and not to image uploads.

For each 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.

Here is how these headers might look like:

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

Framework integration

Our client libraries provide an easy to use wrapper for this URL-based API, utilizing your native programming language of choice. Request building and authentication are done automatically, and the JSON response is parsed and returned.

Ruby PHP Python Node.js Java Endpoint All

Usage examples

URL:

GET /resources/image

Ruby:

require 'cloudinary'
result = Cloudinary::Api.resources

PHP:

require "cloudinary.php";

require "api.php";

$api = new \Cloudinary\Api();

$result = $api->resources();

Python:

import cloudinary.api

result = cloudinary.api.resources()

Node.js:

var cloudinary = require('cloudinary');

cloudinary.api.resources(function(result) { console.log(result) });

Java:

import com.cloudinary.*;
import com.cloudinary.utils.*;

Map config = ObjectUtils.asMap(
  "cloud_name", "my_cloud_name",
  "api_key", "my_api_key",
  "api_secret", "my_api_secret");

Cloudinary cloudinary = new Cloudinary(config);
Api api = cloudinary.api();

Map result = api.resources(ObjectUtils.emptyMap());

Endpoint:

/resources/image

Ruby PHP Python Node.js Java All

API wrapper source code

Ruby:

https://github.com/cloudinary/cloudinary_gem/blob/master/lib/cloudinary/api.rb

PHP:

https://github.com/cloudinary/cloudinary_php/blob/master/src/Api.php

Python:

https://github.com/cloudinary/pycloudinary/blob/master/cloudinary/api.py

Node.js:

https://github.com/cloudinary/cloudinary_npm/blob/master/lib/api.coffee

Java:

https://github.com/cloudinary/cloudinary_java/blob/master/cloudinary-core/src/main/java/com/cloudinary/Api.java

Ruby PHP Python Node.js Java All

Limit checking

Ruby:

$ result = Cloudinary::Api.resources
$ result.rate_limit_allowed
=> 500
$ result.rate_limit_remaining
=> 499
$ result.rate_limit_reset_at
=> 2012-10-03 10:00:00 +0200

PHP:

php > $result = $api->resources();
php > var_dump($result->rate_limit_allowed);
int(500)
php > var_dump($result->rate_limit_allowed);
int(500)
php > var_dump($result->rate_limit_remaining);
int(499)
php > var_dump($result->rate_limit_reset_at);
int(1349622000)

Python:

>>> result = cloudinary.api.resources()
>>> result.rate_limit_allowed
500
>>>result.rate_limit_remaining
499
>>>result.rate_limit_reset_at
(2012, 10, 7, 15, 0, 0, 0, 1, -1)

Node.js:

> cloudinary.api.resources(
  function(result) {
    console.log(result.rate_limit_allowed,
                result.rate_limit_remaining,
                result.rate_limit_reset_at)
  });
> 500 499 Sun, 07 Oct 2012 15:00:00 GMT

Java:

import com.cloudinary.Api.*;

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());
=> 2012-10-03 10:00:00 +0200

Browse resources

Use the resources methods to: list all uploaded resources, list resources by tag, list resources in moderation queues, list tags or list the details of a single resource.

GET /resources/:resource_type(/:type)

List resources

Parameters:

prefix - Optional. (String). Find all resources with a public ID that starts with the given prefix.
public_ids - Optional. (String, comma-separated list of public IDs). List resources with the given public IDs (up to 100).
max_results - Optional. (Integer, default=10. maximum=500). Max number of resources to return.
next_cursor - Optional. When a listing 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 listing request.
start_at - Optional. (Timestamp string). List resources that were created since the given timestamp. Supported if no prefix or public IDs were specified.
direction - Optional. (String/Integer, "asc" (or 1), "desc" (or -1), default: "desc" by creation date). Control the order of returned resources. When a prefix is specified, this parameter is ignored and the results are sorted by public ID.
tags - Optional (Boolean, default: false). If true, include the list of tag names assigned each resource.
context - Optional (Boolean, default: false). If true, include key-value pairs of context associated with each resource.
moderations - Optional (Boolean, default: false). If true, include image moderation status of each listed resource.

Result sample:

{
  "resources": [
    {
      "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,
      "url": "http://res.cloudinary.com/demo/image/upload/v1333013579/face_center.jpg",
      "secure_url": "https://.../image/upload/v1333013579/face_center.jpg"
    },
    {
      "public_id": "12208495",
      "format": "jpg",
      "resource_type": "image",
      "type": "facebook",
      "created_at": "2012-10-06T17:18:52Z",
      "bytes": 0,
      "url": "http://res.cloudinary.com/demo/image/facebook/4.jpg",
      "secure_url": "https://.../image/facebook/4.jpg"
    },
  ]
}

Ruby PHP Python Node.js Java Endpoint All

List all images

URL:

GET /resources/image

Ruby:

Cloudinary::Api.resources

PHP:

$api->resources();

Python:

cloudinary.api.resources()

Node.js:

cloudinary.api.resources(function(result)  { console.log(result) });

Java:

api.resources(ObjectUtils.emptyMap());

Endpoint:

/resources/image

Ruby PHP Python Node.js Java Endpoint All

List uploaded images:

URL:

GET /resources/image/upload

Ruby:

Cloudinary::Api.resources(:type => :upload)

PHP:

$api->resources(array("type" => "upload"));

Python:

cloudinary.api.resources(type = "upload")

Node.js:

cloudinary.api.resources(function(result){}, { type: 'upload' });

Java:

api.resources(ObjectUtils.asMap("type", "upload"));

Endpoint:

/resources/image/upload

Ruby PHP Python Node.js Java Endpoint All

List all uploaded images with a given prefix

URL:

GET /resources/image/upload/?prefix=sampl

Ruby:

Cloudinary::Api.resources(:type => :upload, :prefix => "sampl")

PHP:

$api->resources(array("type" => "upload", "prefix" => "sampl"));

Python:

cloudinary.api.resources(type = "upload", prefix = "sampl")

Node.js:

cloudinary.api.resources(function(result){},
    { type: 'upload', prefix: 'sampl' });

Java:

api.resources(ObjectUtils.asMap("type", "upload", "prefix", "sampl"));

Endpoint:

/resources/image/upload/?prefix=sampl

Ruby PHP Python Node.js Java Endpoint All

List Facebook images:

URL:

GET /resources/image/facebook

Ruby:

Cloudinary::Api.resources(:type => :facebook)

PHP:

$api->resources(array("type" => "facebook"));

Python:

cloudinary.api.resources(type = "facebook"))

Node.js:

cloudinary.api.resources(function(result){}, { type: 'facebook' });

Java:

api.resources(ObjectUtils.asMap("type", "facebook"));

Endpoint:

/resources/image/facebook

Ruby PHP Python Node.js Java Endpoint All

List raw uploaded files

URL:

GET /resources/raw

Ruby:

Cloudinary::Api.resources(:resource_type => :raw)

PHP:

$api->resources(array("resource_type" => "raw"));

Python:

cloudinary.api.resources(resource_type = "raw")

Node.js:

cloudinary.api.resources(function(result){}, { resource_type: 'raw' });

Java:

api.resources(ObjectUtils.asMap("resource_type", "raw"));

Endpoint:

/resources/raw

Ruby PHP Python Node.js Java Endpoint All

List all uploaded images with the given IDs

URL:

GET /resources/image/upload/?public_ids[]=user_photo_1&public_ids[]=user_photo_2

Ruby:

resources_by_ids
Cloudinary::Api.resources_by_ids(["user_photo_1", "user_photo_2"])

PHP:

$api->resources_by_ids(array("user_photo_1", "user_photo_2"));

Python:

cloudinary.api.resources_by_ids(["user_photo_1", "user_photo_2"])

Node.js:

cloudinary.api.resources_by_ids(["user_photo_1", "user_photo_2"],
  function(result){});

Java:

api.resources_by_ids(Arrays.asList("user_photo_1", "user_photo_2"),
  ObjectUtils.emptyMap());

Endpoint:

/resources/image/upload/?public_ids[]=user_photo_1&public_ids[]=user_photo_2

GET /resources/:resource_type/tags/:tag

List resources by tag

Retrieve a list of resources with a specified tag.

Parameters:

max_results - Optional. (Integer, default=10. maximum=500). Max number of resources to return.
next_cursor - Optional. When a listing 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 listing request.
direction - Optional. (String/Integer, "asc" (or 1), "desc" (or -1), default: "desc" by creation date). Control the order of returned resources.
tags - Optional (Boolean, default: false). If true, include the list of tag names assigned each resource.
context - Optional (Boolean, default: false). If true, include key-value pairs of context associated with each resource.
moderations - Optional (Boolean, default: false). If true, include image moderation status of each listed resource.

Ruby PHP Python Node.js Java Endpoint All

List images by tag

URL:

GET /resources/image/tags/mytag

Ruby:

Cloudinary::Api.resources_by_tag('mytag')

PHP:

$api->resources_by_tag("mytag");

Python:

cloudinary.api.resources_by_tag("mytag")

Node.js:

cloudinary.api.resources_by_tag("mytag", function(result){});

Java:

api.resourcesByTag("mytag", ObjectUtils.emptyMap());

Endpoint:

/resources/image/tags/mytag

Ruby PHP Python Node.js Java Endpoint All

List raw files by tag

URL:

GET /resources/raw/tags/mytag

Ruby:

Cloudinary::Api.resources_by_tag('mytag',
    :resource_type => :raw)

PHP:

$api->resources_by_tag("mytag"),
    array("resource_type" => "raw"));

Python:

cloudinary.api.resources_by_tag("mytag"),
    resource_type = "raw")

Node.js:

cloudinary.api.resources_by_tag("mytag",
    function(result){}, { resource_type: 'raw' });

Java:

api.resourcesByTag("mytag", ObjectUtils.asMap("resource_type", "raw"));

Endpoint:

/resources/raw/tags/mytag

GET /resources/:resource_type/moderations/:moderation_type/:status

List resources in moderation queues

Parameters:

moderation_type - (String: "manual", "webpurify", "metascan"). Type of image moderation queue to list.
status - (String: "pending", "approved", "rejected"). Moderation status of resources.
max_results - Optional. (Integer, default=10. maximum=500). Max number of resources to return.
next_cursor - Optional. When a listing 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 listing request.
direction - Optional. (String/Integer, "asc" (or 1), "desc" (or -1), default: "desc" by creation date). Control the order of returned resources.
tags - Optional (Boolean, default: false). If true, include the list of tag names assigned each resource.
context - Optional (Boolean, default: false). If true, include key-value pairs of context associated with each resource.
moderations - Optional (Boolean, default: false). If true, include image moderation status of each listed resource.

Result sample:

{
 "resources"=>
  [{
    "public_id": "q7vcvrfjm9mj4bfp3qc8",
    "format": "jpg",
    "version": 1393794403,
    "resource_type": "image",
    "type": "upload",
    "created_at": "2014-03-02T21:06:43Z",
    "bytes": 120253,
    "width": 864,
    "height": 576,
    "backup": true,
    "url":
     "http://res.cloudinary.com/demo/image/upload/v1393794403/q7vcvrfjm9mj4bfp3qc8.jpg",
    "secure_url":
     "https://res.cloudinary.com/demo/image/upload/v1393794403/q7vcvrfjm9mj4bfp3qc8.jpg"
   },
   {
    "public_id": "zp4fgdbabhlwwa7bxu84",
    "format": "jpg",
    "version": 1393794399,
    "resource_type": "image",
    "type": "upload",
    "created_at": "2014-03-02T21:06:39Z",
    "bytes": 120253,
    "width": 864,
    "height": 576,
    "backup": true,
    "url":
     "http://res.cloudinary.com/demo/image/upload/v1393794399/zp4fgdbabhlwwa7bxu84.jpg",
    "secure_url":
     "https://res.cloudinary.com/demo/image/upload/v1393794399/zp4fgdbabhlwwa7bxu84.jpg"
   }
 ]
}

Ruby PHP Python Node.js Java Endpoint All

List images pending manual moderation

URL:

GET /resources/image/moderations/manual/pending

Ruby:

Cloudinary::Api.resources_by_moderation("manual", "pending")

PHP:

$api = new \Cloudinary\Api();
$api->resources_by_moderation("manual", "pending");

Python:

cloudinary.api.resources_by_moderation("manual", "pending")

Node.js:

cloudinary.api.resources_by_moderation('manual', 'pending',
  function(result)  { console.log(result) });

Java:

cloudinary.api().resourcesByModeration("manual", "pending",
  ObjectUtils.emptyMap());

Endpoint:

/resources/image/moderations/manual/pending

Ruby PHP Python Node.js Java Endpoint All

List images automatically approved by the WebPurify add-on

URL:

GET /resources/image/moderations/webpurify/approved

Ruby:

Cloudinary::Api.resources_by_moderation("webpurify", "approved")

PHP:

$api = new \Cloudinary\Api();
$api->resources_by_moderation("webpurify", "approved");

Python:

cloudinary.api.resources_by_moderation("webpurify", "approved")

Node.js:

cloudinary.api.resources_by_moderation('webpurify', 'approved',
  function(result)  { console.log(result) });

Java:

cloudinary.api().resourcesByModeration("webpurify", "approved",
  ObjectUtils.emptyMap());

Endpoint:

/resources/image/moderations/webpurify/approved

GET /tags/:resource_type

List tags

Parameters:

prefix - Optional. Find all tags that start with the given prefix.
max_results - Optional. Max number of tags to return. Default=10. Maximum=500.
next_cursor - Optional. When a listing 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 listing request.

Result sample:

{
  "tags": [
    "arrow_animation",
    "logo"
  ]
}

Ruby PHP Python Node.js Java Endpoint All

List tags of images

URL:

GET /tags/image

Ruby:

Cloudinary::Api.tags

PHP:

$api->tags();

Python:

cloudinary.api.tags()

Node.js:

cloudinary.api.tags(function(result){});

Java:

api.tags(ObjectUtils.emptyMap());

Endpoint:

/tags/image

Ruby PHP Python Node.js Java Endpoint All

List all tags with a given prefix

URL:

GET /tags/image/?prefix=myta

Ruby:

Cloudinary::Api.tags(:prefix => "myta")

PHP:

$api->tags(array("prefix" => "myta"));

Python:

cloudinary.api.tags(prefix = "myta")

Node.js:

cloudinary.api.tags(function(result){}, { prefix: 'myta' });

Java:

api.tags(ObjectUtils.asMap("prefix", "myta"));

Endpoint:

/tags/image/?prefix=myta

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

Details of a single resource

Parameters:

colors - Optional (Boolean, default: false). If true, include color information: predominant colors and histogram of 32 leading colors.
image_metadata - Optional (Boolean, default: false). If true, include colorspace, ETag, IPTC, XMP, and detailed Exif metadata of the uploaded photo. Note: retrieves video metadata if the resource is a video file.
exif - Optional (Boolean, default: false). If true, include image metadata (e.g., camera details). Deprecated. Please use image_metadata instead.
faces - Optional (Boolean, default: false). If true, include a list of coordinates of detected faces.
pages - Optional (Boolean, default: false). If true, report the number of pages in multi-page documents (e.g., PDF)
phash - Optional (Boolean, default: false). If true, include the perceptual hash (pHash) of the uploaded photo for image similarity detection.
coordinates - Optional (Boolean, default: false). If true, include previously specified custom cropping coordinates and faces coordinates.
max_results - Optional. Max number of derived images to include. Default=10. Maximum=100.
next_cursor - Optional. When a listing 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 listing request.

Result sample:

{
  "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,
  "url": "http://res.cloudinary.com/demo/image/upload/v1312461204/sample.jpg",
  "secure_url": "https://.../image/upload/v1312461204/sample.jpg",
  "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
      ]
    ]
  },

  "exif": {
    "ApertureValue": "4281/1441",
    "ColorSpace": "1",
    "ComponentsConfiguration": "1, 2, 3, 0",
    "Compression": "6",
    "DateTime": "2010:12:27 11:17:34",
    "DateTimeDigitized": "2010:12:27 11:17:34",
    "DateTimeOriginal": "2010:12:27 11:17:34",
    "ExifImageLength": "1936",
    "ExifImageWidth": "2592",
    "ExifOffset": "204",
    "ExifVersion": "48, 50, 50, 49",
    "ExposureMode": "0",
    "ExposureProgram": "2",
    "ExposureTime": "1/4309",
    "Flash": "24",
    "FlashPixVersion": "48, 49, 48, 48",
    "FNumber": "14/5",
    "FocalLength": "77/20",
    "GPSAltitude": "20723/924",
    "GPSAltitudeRef": "0",
    "GPSImgDirection": "42155/344",
    "GPSImgDirectionRef": "T",
    "GPSInfo": "574",
    "GPSLatitude": "21/1, 768/100, 0/1",
    "GPSLatitudeRef": "N",
    "GPSLongitude": "86/1, 4500/100, 0/1",
    "GPSLongitudeRef": "W",
    "GPSTimeStamp": "17/1, 17/1, 3326/100",
    "ISOSpeedRatings": "80",
    "JPEGInterchangeFormat": "870",
    "JPEGInterchangeFormatLength": "9932",
    "Make": "Apple",
    "MeteringMode": "1",
    "Model": "iPhone 4",
    "Orientation": "6",
    "ResolutionUnit": "2",
    "SceneCaptureType": "0",
    "SensingMethod": "2",
    "Sharpness": "2",
    "ShutterSpeedValue": "4781/396",
    "Software": "4.2.1",
    "SubjectArea": "1295, 967, 699, 696",
    "WhiteBalance": "0",
    "XResolution": "72/1",
    "YCbCrPositioning": "1",
    "YResolution": "72/1"
  },

}

Ruby PHP Python Node.js Java Endpoint All

Uploaded image details

URL:

GET /resources/image/upload/sample

Ruby:

Cloudinary::Api.resource('sample')

PHP:

$api->resource("sample");

Python:

cloudinary.api.resource("sample")

Node.js:

cloudinary.api.resource('sample',
    function(result)  { console.log(result) });

Java:

api.resource("sample", ObjectUtils.emptyMap());

Endpoint:

/resources/image/upload/sample

Ruby PHP Python Node.js Java Endpoint All

Faces, colors and Exif image details

URL:

GET /resources/image/upload/sample?faces=1&colors=1&exif=1

Ruby:

Cloudinary::Api.resource('sample',
  :faces => true, :colors => true, :exif => true)

PHP:

$api->resource("sample",
  array("faces" => TRUE, "colors" => TRUE, "exif" => TRUE));

Python:

cloudinary.api.resource("sample",
  faces = True, colors = True, exif = True)

Node.js:

cloudinary.api.resource('sample',
    function(result)  { console.log(result) },
    { faces: true, colors: true, exif: true });

Java:

api.resource("sample", ObjectUtils.asMap("faces", true,
    "colors", true, "exif", true));

Endpoint:

/resources/image/upload/sample?faces=1&colors=1&exif=1

Ruby PHP Python Node.js Java Endpoint All

Facebook picture details

URL:

GET /resources/image/facebook/4

Ruby:

Cloudinary::Api.resource('4', :type => :facebook)

PHP:

$api->resource("4", array("type" => "facebook"));

Python:

cloudinary.api.resource("4", type = "facebook")

Node.js:

cloudinary.api.resource('4',
    function(result){}, { type: 'facebook' });

Java:

api.resource("4", ObjectUtils.asMap("type", "facebook"));

Endpoint:

/resources/image/facebook/4

Ruby PHP Python Node.js Java Endpoint All

Uploaded raw file details

URL:

GET /resources/raw/upload/rwkaliebnufp3bxyrvyo.txt

Ruby:

Cloudinary::Api.resource('rwkaliebnufp3bxyrvyo.txt',
    :resource_type => :raw)

PHP:

$api->resource("rwkaliebnufp3bxyrvyo.txt",
    array("resource_type" => "raw"));

Python:

cloudinary.api.resource("rwkaliebnufp3bxyrvyo.txt",
    resource_type = "raw")

Node.js:

cloudinary.api.resource('rwkaliebnufp3bxyrvyo.txt',
    function(result){}, { resource_type: 'raw' });

Java:

api.resource("rwkaliebnufp3bxyrvyo.txt",
    ObjectUtils.asMap("resource_type", "raw"));

Endpoint:

/resources/raw/upload/rwkaliebnufp3bxyrvyo.txt

Update resources

Update one or more of the parameters associated with a specified resource.

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

Update details of an existing resource

Parameters:

public_id - The public ID of a single image or a raw file that was uploaded to Cloudinary.
tags - (Optional). A comma-separated list of tag names to assign to the uploaded image for later group reference.
context - (Optional). A pipe separated list of key-value pairs of general textual context metadata to attach to an uploaded resource. The context values of uploaded files are available for fetching using the Admin API. For example: "alt=My image|caption=Profile Photo".
face_coordinates - (Optional). 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 '|'. For example: "10,20,150,130|213,345,82,61".
custom_coordinates - (Optional). 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".
moderation_status - (Optional. String: "approved", "rejected"). Manually set image moderation status or override previously automatically moderated images by approving or rejecting.
auto_tagging (0.0 to 1.0 Decimal number) - (Optional). Whether to assign tags to an image according to detected scene categories with confidence score higher than the given value.
detection - (Optional). Set to 'adv_face' to automatically extract advanced face attributes of photos using the Advanced Facial Attributes Detection add-on.
raw_convert - (Optional). Set to 'aspose' to automatically convert Office documents to PDF files and other image formats using the Aspose Document Conversion add-on.
categorization - (Optional). Set to 'imagga_tagging' to automatically detect scene categories of photos using the Imagga Auto Tagging add-on.
background_removal - (Optional). Set to 'remove_the_background' (or 'pixelz' - the new name of the company) to automatically clear the background of an uploaded photo using the Remove-The-Background Editing add-on.

Ruby PHP Python Node.js Java Endpoint All

Update tags and moderation status of an uploaded image

URL:

POST /resources/image/upload/image1

Ruby:

Cloudinary::Api.update("image1",
  :tags => "important",
  :moderation_status => "approved")

PHP:

$api = new \Cloudinary\Api();
$api->update("image1",
  array("tags" => "important", "moderation_status" => "approved"));

Python:

cloudinary.api.update("image1",
  tags = "important",
  moderation_status = "approved")

Node.js:

cloudinary.api.update("image1",
  function(result) { console.log(result); },
  { tags: "important", moderation_status: "approved" });

Java:

cloudinary.api().update("image1",
  ObjectUtils.asMap("tags", "important",
    "moderation_status", "approved"));

Endpoint:

/resources/image/upload/image1

Delete resources

Use the delete methods to: delete resources by public ID or prefix, delete resources by tag, or delete derived resources.

DELETE /resources/:resource_type/:type

Delete resources by public ID or prefix

Parameters:

public_ids - Delete all resources with the given public IDs (array of up to 100 public_ids).
prefix - Delete all resources including their derivatives, where their public ID starts with the given prefix (up to a maximum of 1000 original resources).
all - Optional (Boolean, default: false). Delete all resources including their derivatives (up to a maximum of 1000 original resources).
keep_original - Optional (Boolean, default: false). If true, delete only the derived resources.
invalidate - Optional (Boolean, default: false). Whether to also invalidate the copies of the resource on the CDN.
Notes:
- By default, the invalidate parameter is not supported for bulk operations such as this one. If you need this option enabled, open a support request.
- It usually takes a few minutes (although it might take up to an hour) 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.
next_cursor - Optional. When a deletion request has more resources to delete than 1000, 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 deletion request.
transformations - Optional. Only the derived resources matching this array of transformation parameters will be deleted.

Result sample:

{
  "deleted": {
    "image1": "deleted",
    "image2": "deleted"
  },
  "partial": false
}

Ruby PHP Python Node.js Java Endpoint All

Delete uploaded images by public IDs

URL:

DELETE /resources/image/upload?public_ids[]=image1&public_ids[]=image2

Ruby:

Cloudinary::Api.delete_resources(['image1', 'image2'])

PHP:

$api->delete_resources(array("image1", "image2"));

Python:

cloudinary.api.delete_resources(["image1", "image2"])

Node.js:

cloudinary.api.delete_resources(['image1', 'image2'],
    function(result){});

Java:

api.deleteResources(Arrays.asList("image1", "image2"),
    ObjectUtils.emptyMap());

Endpoint:

/resources/image/upload?public_ids[]=image1&public_ids[]=image2

Ruby PHP Python Node.js Java Endpoint All

Delete Facebook pictures by public IDs

URL:

DELETE /resources/image/facebook?public_ids=4

Ruby:

Cloudinary::Api.delete_resources(['4'], :type => :facebook)

PHP:

$api->delete_resources(array("4"), array("type" => "facebook"));

Python:

cloudinary.api.delete_resources(["4"], type = "facebook")

Node.js:

cloudinary.api.delete_resources(['4'],
    function(result){}, { type: 'facebook' });

Java:

api.deleteResources(Arrays.asList("4"),
    ObjectUtils.asMap("type", "facebook"));

Endpoint:

/resources/image/facebook?public_ids=4

Ruby PHP Python Node.js Java Endpoint All

Delete uploaded images by prefix

URL:

DELETE /resources/image/upload?prefix=sunday

Ruby:

Cloudinary::Api.delete_resources_by_prefix('sunday')

PHP:

$api->delete_resources_by_prefix("sunday");

Python:

cloudinary.api.delete_resources_by_prefix("sunday")

Node.js:

cloudinary.api.delete_resources_by_prefix('sunday', function(result){});

Java:

api.deleteResourcesByPrefix("sunday", ObjectUtils.emptyMap());

Endpoint:

/resources/image/upload?prefix=sunday

Ruby PHP Python Node.js Java Endpoint All

Delete derived images only

URL:

DELETE /resources/image/upload?public_ids[]=image1&public_ids[]=image2&keep_original=1

Ruby:

Cloudinary::Api.delete_resources(['image1', 'image2'],
  :keep_original => true)

PHP:

$api->delete_resources(array("image1", "image2"),
  array("keep_original" => TRUE));

Python:

cloudinary.api.delete_resources(["image1", "image2"],
  keep_original = True)

Node.js:

cloudinary.api.delete_resources(['image1', 'image2'],
    function(result){}, { keep_original: true });

Java:

api.deleteResources(Arrays.asList("image1", "image2"),
    ObjectUtils.asMap("keep_original", true));

Endpoint:

/resources/image/upload?public_ids[]=image1&public_ids[]=image2&keep_original=1

Ruby PHP Python Node.js Java Endpoint All

Delete all Facebook pictures

URL:

DELETE /resources/image/facebook?all=true

Ruby:

Cloudinary::Api.delete_all_resources(:type => :facebook)

PHP:

$api->delete_all_resources(array("type" => "facebook"));

Python:

cloudinary.api.delete_all_resources(type = "facebook")

Node.js:

cloudinary.api.delete_all_resources(function(result){}, { type: 'facebook' });

Java:

api.deleteAllResources(ObjectUtils.asMap("type", "facebook"));

Endpoint:

/resources/image/facebook?all=true

DELETE /resources/:resource_type/tags/:tag

Delete resources by tags

Parameters:

tag - Delete all resources (and their derivatives) with the given tag name (up to a maximum of 1000 original resources).
keep_original - Optional (Boolean, default: false). If true, delete only the derived images of the matching resources.
invalidate - Optional (Boolean, default: false). Whether to also invalidate the copies of the resource on the CDN.
Notes:
- By default, the invalidate parameter is not supported for bulk operations such as this one. If you need this option enabled, open a support request.
- It usually takes a few minutes (although it might take up to an hour) 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.
transformations - Optional. Only the derived resources matching this array of transformation parameters will be deleted.
next_cursor - Optional. When a deletion request has more resources to delete than 1000, 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 deletion request.

Result sample:

{
  "deleted": {
    "image1": "deleted",
    "image2": "deleted"
  },
  "partial": false
}

Ruby PHP Python Node.js Java Endpoint All

Delete images by tag name

URL:

DELETE /resources/image/tags/mytag

Ruby:

Cloudinary::Api.delete_resources_by_tag('mytag')

PHP:

$api->delete_resources_by_tag("mytag");

Python:

cloudinary.api.delete_resources_by_tag("mytag")

Node.js:

cloudinary.api.delete_resources_by_tag('mytag',
    function(result){});

Java:

api.deleteResourcesByTag("mytag", ObjectUtils.emptyMap());

Endpoint:

/resources/image/tags/mytag

DELETE /derived_resources

Delete derived resources

Parameters:

derived_resource_ids - Delete all derived resources with the given IDs (an array of up to 100 derived_resource_ids). The derived resource IDs are returned when calling the Details of a single resource method.

Result sample:

{
  "deleted": {
    "cb4eaaf650": "deleted",
    "a7b2a2756a": "deleted"
  }
}

Ruby PHP Python Node.js Java Endpoint All

Delete transformed images by IDs

URL:

DELETE /derived_resources?derived_resource_ids[]=cb4eaaf650&derived_resource_ids[]=a7b2a2756a

Ruby:

Cloudinary::Api.delete_derived_resources(['cb4eaaf6503',
    'a7b2a2756ab'])

PHP:

$api->delete_derived_resources(array("cb4eaaf6503", "a7b2a2756ab"));

Python:

cloudinary.api.delete_derived_resources(["cb4eaaf6503", "a7b2a2756ab"])

Node.js:

cloudinary.api.delete_derived_resources(['cb4eaaf6503', 'a7b2a2756ab'],
    function(result){});

Java:

api.deleteDerivedResources(Arrays.asList("cb4eaaf6503", "a7b2a2756ab"),
    ObjectUtils.emptyMap());

Endpoint:

/derived_resources?derived_resource_ids[]=cb4eaaf650&derived_resource_ids[]=a7b2a2756a

Manage transformations

Use the transformations methods to: retrieve a list of all transformations, retrieve the details of a single transformation, delete a transformation, update a transformation or create named transformation.

See the Image transformations and video transformations documentation for more information.

GET /transformations

List transformations

Parameters:

max_results - Optional. Max number of transformations to return. Default=10. Maximum=500.
next_cursor - Optional. When a listing 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 listing request.

Result sample:

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

Ruby PHP Python Node.js Java Endpoint All

List all image transformations

URL:

GET /transformations

Ruby:

Cloudinary::Api.transformations

PHP:

$api->transformations();

Python:

cloudinary.api.transformations()

Node.js:

cloudinary.api.transformations(function(result){console.log(result)});

Java:

api.transformations(ObjectUtils.emptyMap());

Endpoint:

/transformations

GET /transformations/:transformation

Details of a single transformation

Parameters:

max_results - Optional. Max number of derived resources to return. Default=10. Maximum=100.
next_cursor - Optional. When a listing 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 listing request.

Result sample:

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

Ruby PHP Python Node.js Java Endpoint All

Transformation details by name

URL:

GET /transformations/w_150,h_100,c_fill

Ruby:

Cloudinary::Api.transformation('w_150,h_100,c_fill')

PHP:

$api->transformation("w_150,h_100,c_fill");

Python:

cloudinary.api.transformation("w_150,h_100,c_fill")

Node.js:

cloudinary.api.transformation('w_150,h_100,c_fill',
    function(result) { console.log(result) });

Java:

api.transformation("w_150,h_100,c_fill",
    ObjectUtils.emptyMap());

Endpoint:

/transformations/w_150,h_100,c_fill

Ruby PHP Python Node.js Java Endpoint All

Transformation details by parameters

URL:

GET /transformations/c_fill,h_100,w_150

Ruby:

Cloudinary::Api.transformation(:width => 150, :height => 100,
    :crop => :fill)

PHP:

$api->transformation(array("width" => 150, "height" => 100,
    "crop" => "fill"));

Python:

cloudinary.api.transformation(dict(width = 150, height = 100, crop = "fill"))

Node.js:

cloudinary.api.transformation({width: 150, height: 100, crop: 'fill'},
    function(result) { console.log(result) });

Java:

api.transformation(new Transformation().width(150).height(100).
    crop("fill").generate(), ObjectUtils.emptyMap());

Endpoint:

/transformations/c_fill,h_100,w_150

DELETE /transformations/:transformation

Delete transformation

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.

Result sample:

{
 "message": "deleted"
}

Ruby PHP Python Node.js Java Endpoint All

Delete transformation name

URL:

DELETE /transformations/w_150,h_100,c_fill

Ruby:

Cloudinary::Api.delete_transformation('w_150,h_100,c_fill')

PHP:

$api->delete_transformation("w_150,h_100,c_fill");

Python:

cloudinary.api.delete_transformation("w_150,h_100,c_fill")

Node.js:

cloudinary.api.delete_transformation('w_150,h_100,c_fill',
    function(result) { console.log(result) });

Java:

api.deleteTransformation("w_150,h_100,c_fill",
    ObjectUtils.emptyMap());

Endpoint:

/transformations/w_150,h_100,c_fill

Ruby PHP Python Node.js Java Endpoint All

Delete transformation by parameters

URL:

DELETE /transformations/c_fill,h_100,w_150

Ruby:

Cloudinary::Api.delete_transformation(:width => 150, :height => 100,
    :crop => :fill)

PHP:

$api->delete_transformation(array("width" => 150, "height" => 100,
    "crop" => "fill"));

Python:

cloudinary.api.delete_transformation(dict(width = 150, height = 100,
    crop = "fill"))

Node.js:

cloudinary.api.delete_transformation(
    {width: 150, height: 100, crop: 'fill'},
    function(result) { console.log(result) });

Java:

api.deleteTransformation(new Transformation().width(150).height(100).
    crop("fill").generate(), ObjectUtils.emptyMap());

Endpoint:

/transformations/c_fill,h_100,w_150

PUT /transformations/:transformation

Update transformation

Parameters:

allowed_for_strict - Boolean. Whether this transformation is allowed when Strict Transformations are enabled.
unsafe_update - Optional. 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).

Result sample:

{
 "message": "updated"
}

Ruby PHP Python Node.js Java Endpoint All

Allow transformation by name

URL:

PUT /transformations/w_150,h_100,c_fill?allowed_for_strict=true

Ruby:

Cloudinary::Api.update_transformation('w_150,h_100,c_fill',
    :allowed_for_strict => true)

PHP:

$api->update_transformation("w_150,h_100,c_fill",
    array("allowed_for_strict" => 1));

Python:

cloudinary.api.update_transformation("w_150,h_100,c_fill",
    allowed_for_strict = True)

Node.js:

cloudinary.api.update_transformation('w_150,h_100,c_fill',
    { allowed_for_strict: true },
    function(result) { console.log(result) });

Java:

api.updateTransformation("w_150,h_100,c_fill",
    ObjectUtils.asMap("allowed_for_strict", true), ObjectUtils.emptyMap());

Endpoint:

/transformations/w_150,h_100,c_fill?allowed_for_strict=true

Ruby PHP Python Node.js Java Endpoint All

Disallow transformation by parameters

URL:

PUT /transformations/c_fill,h_100,w_150?allowed_for_strict=false

Ruby:

Cloudinary::Api.update_transformation({:width => 150, :height => 100,
    :crop => :fill},
    {:allowed_for_strict => false})

PHP:

$api->update_transformation(
    array("width" => 150, "height" => 100,"crop" => "fill")
    array("allowed_for_strict" => 0));

Python:

cloudinary.api.update_transformation(dict(width = 150, height = 100,
    crop = "fill"), dict( allowed_for_strict = False))

Node.js:

cloudinary.api.update_transformation(
    { width: 150, height: 100, crop: 'fill' },
    { allowed_for_strict: false },
    function(result) { console.log(result) });

Java:

api.updateTransformation(new Transformation().width(150).height(100).
    crop("fill").generate(), ObjectUtils.asMap("allowed_for_strict", false),
    ObjectUtils.emptyMap());

Endpoint:

/transformations/c_fill,h_100,w_150?allowed_for_strict=false

Ruby PHP Python Node.js Java Endpoint All

Update a named transformation

URL:

PUT /transformations/my_named?unsafe_update=c_scale,w_103

Ruby:

Cloudinary::Api.update_transformation('my_named',
     :unsafe_update => { :crop => :scale, :width =>103 })

PHP:

$api->update_transformation("my_named",
    array("crop" => "scale", "width" => 103));

Python:

cloudinary.api.update_transformation("my_named",
    dict(crop = "scale", width = 103))

Node.js:

cloudinary.api.update_transformation("my_named",
    { crop: 'scale', width: 103 },
    function(result) { console.log(result) });

Java:

api.updateTransformation("my_named",
    ObjectUtils.asMap("unsafe_update",
    new Transformation().crop("scale").width(103).generate()),
        ObjectUtils.emptyMap());

Endpoint:

/transformations/my_named?unsafe_update=c_scale,w_103

POST /transformations/:name

Create named transformation

Parameters:

transformation - Strinct representation of transformation parameters.

Result sample:

{
 "message": "created"
}

Ruby PHP Python Node.js Java Endpoint All

Create named transformation by string

URL:

POST /transformations/small_fill?transformation=w_150,h_100,c_fill

Ruby:

Cloudinary::Api.create_transformation('small_fill',
    'w_150,h_100,c_fill')

PHP:

$api->create_transformation("small_fill", "w_150,h_100,c_fill");

Python:

cloudinary.api.create_transformation("small_fill",
    "w_150,h_100,c_fill")

Node.js:

cloudinary.api.create_transformation('small_fill',
    'w_150,h_100,c_fill',
    function(result) { console.log(result) });

Java:

api.createTransformation("small_fill", "w_150,h_100,c_fill",
    ObjectUtils.emptyMap());

Endpoint:

/transformations/small_fill?transformation=w_150,h_100,c_fill

Ruby PHP Python Node.js Java Endpoint All

Create named transformation by parameters

URL:

POST /transformations/small_fill2?transformation=c_fill,h_100,w_150

Ruby:

Cloudinary::Api.create_transformation('small_fill2',
    {:width => 150, :height => 100, :crop => :fill})

PHP:

$api->create_transformation("small_fill2",
    array("width" => 150, "height" => 100,
    "crop" => "fill"));

Python:

cloudinary.api.create_transformation("small_fill2",
    dict(width = 150, height = 100, crop = "fill"))

Node.js:

cloudinary.api.create_transformation('small_fill2',
    { width: 150, height: 100, crop: 'fill' },
    function(result) { console.log(result) });

Java:

api.createTransformation("small_fill2",
    new Transformation().width(150).height(100).crop("fill").generate(),
    ObjectUtils.emptyMap());

Endpoint:

/transformations/small_fill2?transformation=c_fill,h_100,w_150

Restore resources

Restore one or more deleted resources from backup.

POST /resources/:resource_type/:type/restore

Restore a deleted resource

Parameters:

public_ids - The public IDs of backed up resources that were previously deleted.

Result sample:

{
 "message": "restored"
}

Ruby PHP Python Node.js Java Endpoint All

Restore deleted resources by public_ids

URL:

POST /resources/image/upload/restore?public_ids[]=image1&public_ids[]=image2

Ruby:

Cloudinary::Api.restore(["image1", "image2"])

PHP:

$api->restore(array("image1", "image2");

Python:

cloudinary.api.restore(["image1", "image2"])

Node.js:

cloudinary.api.restore(["image1", "image2"],
  function(result) { console.log(result); });

Java:

cloudinary.api().restore(Arrays.asList("image1", "image2"),
  ObjectUtils.emptyMap());

Endpoint:

/resources/image/upload/restore?public_ids[]=image1&public_ids[]=image2

Manage upload mappings

The Upload Mappings feature is used for dynamic image fetching from existing online locations. Use the upload_mappings methods to: retrieve a list of all upload mappings, retrieve the details of a single upload mapping, delete an upload mapping, update an upload mapping or create a new upload mapping.

See the Auto upload remote images documentation for more information.

GET /upload_mappings

List upload mappings

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

Parameters:

max_results - Optional. Max number of upload mappings to return. Default=10. Maximum=500.
next_cursor - Optional. When a listing 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 listing request.

Result sample:

{
  "mappings"=>[
    {
      "folder": "wiki", 
      "template": "https://u.wiki.example.com/wiki-images/"
    },
    {
      "folder"=>"exam", 
      "template": "http://images.example.com/product_assets/images/"
    }, 
  ]
}

Ruby PHP Python Node.js Java Endpoint All

List all upload mappings

URL:

GET /upload_mappings

Ruby:

Cloudinary::Api.upload_mappings

PHP:

$api->upload_mappings();

Python:

cloudinary.api.upload_mappings()

Node.js:

cloudinary.api.upload_mappings(function(result){console.log(result)});

Java:

api.uploadMappings(ObjectUtils.emptyMap());

Endpoint:

/upload_mappings

GET /upload_mappings/:folder

Details of a single upload mapping

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

Result sample:

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

Ruby PHP Python Node.js Java Endpoint All

Upload mapping details by folder

URL:

GET /upload_mappings/wiki

Ruby:

Cloudinary::Api.upload_mapping('wiki')

PHP:

$api->upload_mapping("wiki");

Python:

cloudinary.api.upload_mapping("wiki")

Node.js:

cloudinary.api.upload_mapping('wiki',
    function(result) { console.log(result) });

Java:

api.uploadMapping("wiki",
    ObjectUtils.emptyMap());

Endpoint:

/upload_mappings/wiki

POST /upload_mappings

Create an upload mapping

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

Parameters:

folder - The name of the folder to map.
template - The URL to be mapped to the folder.

Result sample:

{
 "message": "created"
}

Ruby PHP Python Node.js Java Endpoint All

Create upload mapping by folder

URL:

POST /upload_mappings?folder=my_map&template=http://www.example.com/images/

Ruby:

Cloudinary::Api.create_upload_mapping("my_map",
    :template => "http://www.example.com/images/")

PHP:

$api->create_upload_mapping("my_map",
    array("template" => "http://www.example.com/images/"));

Python:

cloudinary.api.create_upload_mapping("my_map",
    template = "http://www.example.com/images/")

Node.js:

cloudinary.api.create_upload_mapping('my_map',
    { template: "http://www.example.com/images/" },
    function(result) { console.log(result) });

Java:

api.createUploadMapping("my_map",
    ObjectUtils.asMap("template", "http://www.example.com/images/"), ObjectUtils.emptyMap());

Endpoint:

/upload_mappings?folder=my_map&template=http://www.example.com/images/

DELETE /upload_mappings/:folder

Delete an upload mapping

Delete an upload mapping by folder name.

Result sample:

{
 "message": "deleted"
}

Ruby PHP Python Node.js Java Endpoint All

Delete an upload mapping by folder

URL:

DELETE /upload_mappings/wiki

Ruby:

Cloudinary::Api.delete_upload_mapping('wiki')

PHP:

$api->delete_upload_mapping("wiki");

Python:

cloudinary.api.delete_upload_mapping("wiki")

Node.js:

cloudinary.api.delete_upload_mapping('wiki',
    function(result) { console.log(result) });

Java:

api.deleteUploadMapping("wiki",
    ObjectUtils.emptyMap());

Endpoint:

/upload_mappings/wiki

PUT /upload_mappings

Update an upload mapping

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

Parameters:

folder - The name of the mapped folder.
template - The new URL to be mapped to the folder.

Result sample:

{
 "message": "updated"
}

Ruby PHP Python Node.js Java Endpoint All

Update an upload mapping

URL:

PUT /upload_mappings?folder=wiki&template=https://u.wiki.com/images/

Ruby:

Cloudinary::Api.update_upload_mapping("wiki",
    :template => "https://u.wiki.com/images/")

PHP:

$api->update_upload_mapping("wiki",
    array("template" => "https://u.wiki.com/images/"));

Python:

cloudinary.api.update_upload_mapping("wiki",
    template = "https://u.wiki.com/images/")

Node.js:

cloudinary.api.update_upload_mapping('wiki',
    { template: "https://u.wiki.com/images/" },
    function(result) { console.log(result) });

Java:

api.updateUploadMapping("wiki",
    ObjectUtils.asMap("template", "https://u.wiki.com/images/"), ObjectUtils.emptyMap());

Endpoint:

/upload_mappings?folder=wiki&template=https://u.wiki.com/images/

Manage upload presets

The Upload Presets feature is used for centrally defining image upload options instead of specifying them in each upload call. Use the upload_presets methods to: retrieve a list of all upload presets, retrieve the details of a single upload preset, delete an upload preset, update an upload preset or create a new upload preset.

See the upload preset documentation for more information.

GET /upload_presets

List upload presets

Parameters:

max_results - Optional. Max number of upload presets to return. Default=10. Maximum=500.
next_cursor - Optional. When a listing 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 listing request.

Result sample:

{
  "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"
        }
    }, 
  ]
}

Ruby PHP Python Node.js Java Endpoint All

List all upload presets

URL:

GET /upload_presets

Ruby:

Cloudinary::Api.upload_presets

PHP:

$api->upload_presets();

Python:

cloudinary.api.upload_presets()

Node.js:

cloudinary.api.upload_presets(function(result){console.log(result)});

Java:

api.uploadPresets(ObjectUtils.emptyMap());

Endpoint:

/upload_presets

GET /upload_presets/:name

Details of a single upload preset

Retrieves the details of an upload preset.

Result sample:

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

Ruby PHP Python Node.js Java Endpoint All

Upload preset details by name

URL:

GET /upload_presets/remote_media

Ruby:

Cloudinary::Api.upload_presets('remote_media')

PHP:

$api->upload_presets("remote_media");

Python:

cloudinary.api.upload_presets("remote_media")

Node.js:

cloudinary.api.upload_presets('remote_media',
    function(result) { console.log(result) });

Java:

api.uploadPresets("remote_media",
    ObjectUtils.emptyMap());

Endpoint:

/upload_presets/remote_media

POST /upload_presets

Create an upload preset

Create a new upload preset.

Parameters:

name - The name to assign to the upload preset.
unsigned - Boolean. Whether this upload preset allows unsigned uploading to Cloudinary.
disallow_public_id - Boolean. Whether this upload preset disables assigning a public_id in the image upload call.
Settings - The upload actions to apply to the images uploaded with this preset.

Result sample:

{
 "message": "created"
}

Ruby PHP Python Node.js Java Endpoint All

Create an upload preset

URL:

POST /upload_presets?name=my_preset&unsigned=true&tags=remote&allowed_formats=jpg,png

Ruby:

Cloudinary::Api.create_upload_preset("my_preset",
    :unsigned => true, :tags => "remote", :allowed_formats => "jpg,png")

PHP:

$api->create_upload_preset("my_preset",
    array("unsigned" => true, "tags" => "remote", "allowed_formats" => "jpg,png"));

Python:

cloudinary.api.create_upload_preset("my_preset",
    unsigned = true, tags = "remote", allowed_formats = "jpg,png")

Node.js:

cloudinary.api.create_upload_preset(function(result) { console.log(result) }, 
  { name: "my_preset", unsigned: true, tags: "remote", allowed_formats: "jpg,png" });

Java:

api.createUploadPreset("my_preset",
    ObjectUtils.asMap("unsigned", true, "tags" => "remote", "allowed_formats" => "jpg,png"), ObjectUtils.emptyMap());

Endpoint:

/upload_presets?name=my_preset&unsigned=true&tags=remote&allowed_formats=jpg,png

DELETE /upload_presets/:name

Delete an upload preset

Delete an existing upload preset.

Result sample:

{
 "message": "deleted"
}

Ruby PHP Python Node.js Java Endpoint All

Delete an upload preset by name

URL:

DELETE /upload_presets/remote_media

Ruby:

Cloudinary::Api.delete_upload_preset('remote_media')

PHP:

$api->delete_upload_preset("remote_media");

Python:

cloudinary.api.delete_upload_preset("remote_media")

Node.js:

cloudinary.api.delete_upload_preset('remote_media',
    function(result) { console.log(result) });

Java:

api.deleteUploadPreset("remote_media",
    ObjectUtils.emptyMap());

Endpoint:

/upload_presets/remote_media

PUT /upload_presets/:name

Update an upload preset

Update an existing upload preset.

Parameters:

unsigned - Boolean. Whether this upload preset allows unsigned uploading to Cloudinary.
disallow_public_id - Boolean. Whether this upload preset disables assigning a public_id in the image upload call.
Settings - The upload actions to apply to the images uploaded with this preset.

Result sample:

{
 "message": "updated"
}

Ruby PHP Python Node.js Java Endpoint All

Update an upload preset

URL:

PUT /upload_presets/wiki?unsigned=true&tags=remote&allowed_formats=jpg,png

Ruby:

Cloudinary::Api.update_upload_preset("wiki",
    :unsigned => true, :tags => "remote", :allowed_formats => "jpg,png")

PHP:

$api->update_upload_preset("wiki",
    array("unsigned" => true, "tags" => "remote", "allowed_formats" => "jpg,png"));

Python:

cloudinary.api.update_upload_preset("wiki",
    unsigned = true, tags = "remote", allowed_formats = "jpg,png")

Node.js:

cloudinary.api.update_upload_preset('wiki',
    { unsigned: true, tags: "remote", allowed_formats: "jpg,png"},
    function(result) { console.log(result) });

Java:

api.updateUploadPreset("wiki",
    ObjectUtils.asMap("unsigned", true, "tags" => "remote", "allowed_formats" => "jpg,png"), ObjectUtils.emptyMap());

Endpoint:

/upload_presets/wiki?unsigned=true&tags=remote&allowed_formats=jpg,png

Manage folders

Use the folders methods to retrieve a list of all root folders or the subfolders of a specified root folder.

GET /folders

List root folders

Lists all the root folders.

Result sample:

 {
    "folders": [
      {
        "name"=>"cloud",
        "path"=>"cloud"
      }, 
      {
        "name"=>"brooks",
        "path"=>"brooks"
      }   
    ]
 }

Ruby PHP Python Node.js Java Endpoint All

List all root folders

URL:

GET /folders

Ruby:

Cloudinary::Api.root_folders

PHP:

$api->root_folders();

Python:

cloudinary.api.root_folders()

Node.js:

cloudinary.api.root_folders(function(result) { console.log(result) });

Java:

api.rootFolders(ObjectUtils.emptyMap());

Endpoint:

/folders

GET /folders/:root_folder

List subfolders

Lists the name and path of all the subfolders of a given root folder.

Result sample:

 {
    "folders": [
      {
        "name"=>"blue",
        "path"=>"cloud/blue"
      }, 
      {
        "name"=>"white",
        "path"=>"cloud/white"
      }   
    ]
 }

Ruby PHP Python Node.js Java Endpoint All

List all subfolders of a given root folder

URL:

GET /folders/cloud

Ruby:

Cloudinary::Api.subfolders("cloud")

PHP:

$api->subfolders("cloud");

Python:

cloudinary.api.subfolders("cloud")

Node.js:

cloudinary.api.sub_folders("cloud", function(result) { console.log(result) });

Java:

api.subfolders("cloud", ObjectUtils.emptyMap());

Endpoint:

/folders/cloud

Manage adaptive streaming profiles

Use the streaming_profiles methods 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.

GET /streaming_profiles

List streaming profiles

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

Result sample:

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

Ruby PHP Python Node.js Java Endpoint All

list all streaming profiles

URL:

GET /streaming_profiles

Ruby:

Cloudinary::Api.list_streaming_profiles

PHP:

$api->list_streaming_profiles();

Python:

cloudinary.api.list_streaming_profiles()

Node.js:

cloudinary.api.list_streaming_profiles(function(result){console.log(result)});

Java:

api.listStreamingProfiles();

Endpoint:

/streaming_profiles

GET /streaming_profiles/:name

Get details of a single streaming profile

Retrieve the details of a single streaming profile by name.

Result sample:

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

Ruby PHP Python Node.js Java Endpoint All

get the details of a specified streaming file

URL:

GET /streaming_profiles/custom_square

Ruby:

Cloudinary::Api.get_streaming_profile('custom_square')

PHP:

$api->get_streaming_profile("custom_square");

Python:

cloudinary.api.get_streaming_profile("custom_square")

Node.js:

cloudinary.api.list_streaming_profile('custom_square', function(result){ console.log(result)});

Java:

api.getStreamingProfile("custom_square");

Endpoint:

/streaming_profiles/custom_square

POST /streaming_profiles

Create a streaming profile

Create a new, custom streaming profile.

Parameters:

name - String. Required. The identification name to assign to the new streaming profile. The name is case-insensitive and can contain alphanumeric characters, underscores (_) and hyphens (-).
display_name - String. A descriptive name for the profile.
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.

Result sample:

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

Ruby PHP Python Node.js Java Endpoint All

Create a streaming profile with 3 representations

URL:

POST /streaming_profiles?name=custom_square

Ruby:

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:

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

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:

cloudinary.api.create_streaming_profile('custom_square',
  {
    display_name: "Custom square resolution",
    representation: [
    {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(result) { console.log(result) });

Java:

api.createStreamingProfile("custom_square", "Custom square resolution",
  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")
  )
);

Endpoint:

/streaming_profiles?name=custom_square

PUT /streaming_profiles/:name

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.

Parameters:

display_name - String. A descriptive name for the profile.
representations - JSON String. An array of structures that defines the updated 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.

Result sample:

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

Ruby PHP Python Node.js Java Endpoint All

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

URL:

PUT /streaming_profiles?name=custom_square

Ruby:

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:

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

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:

cloudinary.v2.api.update_streaming_profile('custom_square',
  {representation: [
    {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:

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

Endpoint:

/streaming_profiles?name=custom_square

DELETE /streaming_profiles/:name

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.

Result sample:

{ "message": "deleted" }

Ruby PHP Python Node.js Java Endpoint All

delete the custom_square streaming file

URL:

DELETE /streaming_profiles/custom_square

Ruby:

Cloudinary::Api.delete_streaming_profile('custom_square')

PHP:

$api->delete_streaming_profile("custom_square");

Python:

cloudinary.api.delete_streaming_profile("custom_square")

Node.js:

cloudinary.api.delete_streaming_profile('custom_square', function(result){ console.log(result)});

Java:

api.deleteStreamingProfile("custom_square");

Endpoint:

/streaming_profiles/custom_square

Usage report

Get a report on your Cloudinary account usage details, including storage, bandwidth, requests and number of images. Note that numbers are updated periodically.

GET /usage

Get account usage details

Result sample:

{
 "plan": "Basic",
 "last_updated": "2013-02-04",
 "objects": { "usage": 11330, "limit": 1000000, "used_percent": 1.13 },
 "bandwidth": { "usage": 9844516305, "limit": 41943040000, "used_percent": 23.47 },
 "storage": { "usage": 704363507, "limit": 10485760000, "used_percent": 6.72 },
 "requests": 877212,
 "resources": 1239,
 "derived_resources": 10091
}

Ruby PHP Python Node.js Java Endpoint All

Get usage details

URL:

GET /usage

Ruby:

Cloudinary::Api.usage

PHP:

$api->usage();

Python:

cloudinary.api.usage()

Node.js:

cloudinary.api.usage(function(result){console.log(result)});

Java:

api.usage(ObjectUtils.emptyMap());

Endpoint:

/usage

Ping Cloudinary

Test the reachability of the Cloudinary API with the ping method.

GET /ping

Ping Cloudinary servers

Result sample:

{
 "status": "ok"
}

Ruby PHP Python Node.js Java Endpoint All

Ping Cloudinary servers

URL:

GET /ping

Ruby:

Cloudinary::Api.ping

PHP:

$api->ping();

Python:

cloudinary.api.ping()

Node.js:

cloudinary.api.ping(function(result){console.log(result)});

Java:

api.ping(ObjectUtils.emptyMap());

Endpoint:

/ping