Programmable Media
Menu

Admin API reference

Last updated: Sep-11-2023

The Admin API is a rate-limited RESTful API that provides full control of all media assets (resources), upload presets, named transformations and other product environment entities.

Cloudinary's backend SDKs wrap these REST APIs, handle authentication, and enable you to perform these methods using your preferred programming language or framework. This reference provides both SDK and REST/cURL syntax and examples for each endpoint method.

Tip
MediaFlows, Cloudinary’s drag-and-drop workflow builder for image and video (currently in beta), enables users to easily call admin API methods – including getting tags, contextual metadata, and usage data – in a low-code implementation. See MediaFlow’s documentation on admin API methods here.

On this page:

Overview

By default, the API endpoints use the following format:

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

For example, to list all video assets in the demo product environment:

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

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

Important
Cloudinary may add more fields to API responses and notifications in the future, so please ensure that your response parsing remains backwards compatible and wont be broken by the presence of unknown fields.

Using Postman for Admin REST API calls

Take advantage of our Cloudinary Postman Collections to experiment with our REST APIs and view the responses before adding them to your own code.

Run in Postman

For details on setting up your own fork of our collections and configuring your Postman environment with your Cloudinary product environment credentials, see Using Cloudinary Postman collections.

Using SDKs with the Admin API

Our backend 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:

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

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.

You can check your current plan and limits in Console Settings or programmatically via the usage method.

If you require more flexible limits, don't hesitate to contact us.

Note
This API rate 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:

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

Tip
You can also retrieve rate limits details as well as transformation, bandwidth, and storage limits, and a variety of additional product environment 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 product environment or to delete an entire set of entities that matches your deletion request.

EU or AP data centers and endpoints (premium feature)

Note
This is a premium feature that is supported only for our Enterprise plans and must be arranged when the account is created. Contact our Enterprise support and sales team or your CSM for more information.

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

Tip
When using the Cloudinary SDKs you need to set the upload_prefix configuration parameter.

folders

Run in Postman Learn more about running Postman collections

Enables you to manage your product environment's asset folders.

Note
For product environments using dynamic folder mode, keep in mind that this API relates to asset folders as a separate container entity in the Cloudinary repository, and that the public ID paths of assets are not necessarily the same as the asset folder names or path structure where those assets are stored.
Method Description
GET/folders Lists all the root folders.
GET/folders/:folder Lists the name and full path of all subfolders of a specified folder.
POST/folders/:folder Creates a new folder.
DELETE/folders/:folder Deletes a folder.

Get root folders

Lists all the root folders. Limited to 2000 results.

Syntax

GET /folders

Sample response

The response contains an array of all the root folders.

Get subfolders

Lists the name and full path of all subfolders of a specified parent folder. Limited to 2000 results.

Syntax

GET /folders/:folder

Required parameters

Parameter Type Description
folder String The full path of the parent folder whose subfolders you want to return.

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 the 'product/shoe' folder:

Sample response

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

Create folder

Creates a new empty asset folder.

Syntax

POST /folders/:folder

Required parameters

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

Examples

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

Sample response

Delete folder

Deletes an empty folder.

Tips
The folder must be empty before you can delete it.

Syntax

DELETE /folders/:folder

Required parameters

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

Optional parameters

Parameter Type Description
skip_backup Boolean Allows deletion of the folder even if it contains backed up assets, which are not visible when viewing the folder in the Media Library or Media Explorer. Default: false

Examples

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

Sample response

metadata_fields

Run in Postman Learn more about running Postman collections

Enables you to manage the metadata fields available for your product environment.

The table below provides a quick summary of the methods available for the Admin API metadata_fields endpoint. See the Metadata API documentation for detailed information on the following Metadata methods, as well as detailed information on the Metadata field structure, including how to work with field validation and list (datasource) values.

Methods summary

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

metadata_rules

Enables you to set up dependencies and hierarchical relationships between structured metadata fields and field options.

The table below provides a quick summary of the methods available for the Admin API metadata_rules endpoint. See the Conditional metadata rules API documentation for detailed information on the following Metadata rules methods, as well as detailed information on the Metadata rule structure, including how to work with conditions that evaluate on metadata payloads, and results that are applied to specified metadata fields in the case those conditions are met.

Methods summary

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

ping

Run in Postman Learn more about running Postman collections

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

Method Description
GET/ping Pings Cloudinary servers.

Ping Cloudinary servers

Syntax

GET /ping

Sample response

The response contains the current status of the Cloudinary servers.

resources

Run in Postman Learn more about running Postman collections

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

Method Description
GET/resources/:resource_type(/:type) Lists resources (assets) stored in your product environment.
GET/resources/by_asset_folder Lists resources (assets) located in a specified asset folder.

Supported only for product environments using dynamic folders mode.
GET/resources/by_asset_ids Lists resources (assets) based on the specified asset IDs.
GET/resources/:resource_type/tags/:tag Lists resources (assets) with a specified tag.
GET/resources/:resource_type/context/ Lists resources (assets) with a specified contextual metadata key.
GET/resources/:resource_type/moderations/:moderation_kind/:status Lists resources (assets) with a particular status from a specified moderation type.
GET/resources/:resource_type/:type/:public_id List details of the asset with the specified public ID, as well as all its derived assets.
GET/resources/:asset_id List details of the asset with the specified asset ID, as well as all its derived assets.
GET/resources/search Filters and retrieves information on all the resources (assets) in your product environment.
GET/resources/visual_search Find images based on their visual content.
POST/resources/:resource_type/:type/:public_id Updates one or more of the attributes associated with a specified resource (asset).
POST/resources/:resource_type/:type/restore Restores one or more resources (assets) from backup.
POST/resources/:resource_type/upload/update_access_mode Updates the access mode of resources (assets) by public ID, by tag, or by prefix.
POST/resources/related_assets/:resource_type/:type/:public_id Relates assets by public IDs.
POST/resources/related_assets/:asset_id Relates assets by asset IDs.
DELETE/resources/related_assets/:resource_type/:type/:public_id Unrelates related assets by public IDs.
DELETE/resources/related_assets/:asset_id Unrelates related assets by asset IDs.
DELETE/resources/:resource_type/:type Deletes resources (assets) by public IDs.
DELETE/resources/:resource_type/tags/:tag Deletes resources by tags.
DELETE/derived_resources Deletes derived assets.

Get resources

Lists resources (assets) uploaded to your product environment.

Syntax

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

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, raw, video. Default: image.
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, fetch, facebook, twitter, gravatar, youtube, hulu, vimeo, animoto, worldstarhiphop, dailymotion, list. Default: upload.
prefix String Find all assets with a public ID that starts with the specified prefix. The assets are sorted by public ID in the response.

Note: use this parameter to find public IDs with a + character in them.
public_ids String[] An array of public IDs. Get assets with the specified public IDs (up to 100).

Note: Not supported for SDKs. Instead use the resources_by_ids SDK method. This parameter does not support public IDs with a + character in them (use the prefix parameter to find the assets instead).
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 specified timestamp (ISO 8601 format). Supported unless prefix or public_ids were specified. For example: 2020-12-01
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 contextual metadata associated with each asset. Default: false.
metadata Boolean Whether to include the structured metadata fields and values assigned to each asset. Default: false.
moderation Boolean Whether to include the image moderation status of each asset. Default: false.

Examples

Get all images:

Get images of delivery type 'upload', up to a maximum of 30 results:

Get all uploaded images with a specified prefix:

Get Facebook images:

Get raw uploaded files:

Get all uploaded images with the specified IDs:

Sample response

Note
The sample response below reflects a product environment using fixed folder mode. On product environments using dynamic folder mode, asset_folder and display_name keys are also included in the response.

Get resources by asset folder

Returns all assets stored directly in a specified asset folder, regardless of the public_id paths or resource_type of those assets. This method does not return assets stored in sub-folders of the specified folder. The asset folder name isn't case sensitive.

Note
Supported only for product environments using dynamic folder mode.

Syntax:

GET /resources/by_asset_folder

Required parameters

Parameter Type Description
asset_folder String The name of the asset folder.

Optional parameters

Parameter Type Description
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 contextual metadata associated with each asset. Default: false.
metadata Boolean Whether to include the structured metadata fields and values assigned to each asset. Default: false.
moderations Boolean Whether to include image moderation status of each asset. Default: false.

Example

Get all assets in the 'technology asset folder. In the response, include the tags and metadata associated with each asset:

Get resources by asset IDs

Returns details of the assets with the specified asset IDs. This enables you to get assets by their immutable identifiers, regardless of resource type, type, public ID, display name, or asset folder.

Syntax:

GET /resources/by_asset_ids

Required parameters

Parameter Type Description
asset_ids String[] An array of asset IDs.

Optional parameters

Parameter Type Description
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 contextual metadata associated with each asset. Default: false.
metadata Boolean Whether to include the structured metadata fields and values assigned to each asset. Default: false.
moderations Boolean Whether to include image moderation status of each asset. Default: false.

Example

Get the details of two assets by their specified asset IDs.

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.

Tip
You can also return a JSON listing of resources (assets) by tag in your front-end code using the client-side asset lists delivery option.

Syntax

GET /resources/:resource_type/tags/: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 contextual metadata associated with each asset. Default: false.
metadata Boolean Whether to include the structured metadata fields and values assigned to each asset. Default: false.
moderations Boolean Whether to include image moderation status of each asset. Default: false.

Examples

Get all images by tag:

Get all raw files by tag:

Get resources by context

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

Syntax

GET /resources/:resource_type/context/

Required parameters

Parameter Type Description
key String Only assets with this contextual metadata 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 contextual metadata key are returned. If this parameter is not provided, all assets with the specified contextual metadata 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 contextual metadata associated with each asset. Default: false.
metadata Boolean Whether to include the structured metadata fields and values assigned to each asset. Default: false.
moderations Boolean Whether to include image moderation status of each asset. Default: false.

Examples

Get images by contextual metadata key:

Get video files by contextual metadata key and value:

Get resources in moderation

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

Syntax

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

Required parameters

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

Note: queued and aborted are relevant only when an asset is marked for multiple moderations.

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 contextual metadata associated with each asset. Default: false.
metadata Boolean Whether to include the structured metadata fields and values assigned to each asset. Default: false.
moderations Boolean Whether to include image moderation status of each asset. Default: false.

Examples

Get images pending manual moderation:

Get images automatically approved by the WebPurify add-on:

Sample response

Get details of a single resource by public ID

Retrieves details of the requested resource (asset), the date and time that specific changes were made to asset attributes, and details of all derived assets.

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

Syntax

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, list. Default: upload
colors Boolean Whether to include color information: predominant colors and histogram of 32 leading colors. Default: false.
media_metadata Boolean Whether to include IPTC, XMP, and detailed Exif metadata in the response.
Default: false.

This parameter applies to both image and video asset types (including audio files). The exact set of metadata fields that gets returned for an asset depends on the asset type.

Note: Using this parameter also returns the asset's ETag value for all asset types, including raw.
exif Boolean Deprecated. Use media_metadata instead. Default: false.
image_metadata Boolean Deprecated. Use media_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]. Note that requesting details of backed up versions consumes an additional 10 units of your rate limit for this call (11 total). (backups_and_version_management#versioning) of the asset. Default: false.
related Boolean Whether to include the list of assets related to this asset. Default: false.
related_next_cursor String If there are more than 100 related assets, the related_next_cursor value is returned as part of the response. You can then specify this value as the related_next_cursor parameter of the following request.
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:

Faces, colors, media metadata and versions details:

Facebook picture details:

Uploaded raw file details:

Sample response

This sample response is from a GET resource call that requested faces, colors and versions in the response.

Note
The sample response below reflects a product environment using fixed folder mode. On product environments using dynamic folder mode, asset_folder and display_name keys are also included in the response.

Get details of a single resource by asset ID

Returns the details of the asset with the specified asset ID, including details on all derived assets. This enables you to get all details of an asset by its immutable identifier, regardless of public ID, display name, asset folder, resource type or deliver type.

Syntax

GET /resources/:asset_id

Optional parameters

Parameter Type Description
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 in the response.
Default: false.

This parameter applies to both image and video asset types (including audio files). The exact set of metadata fields that gets returned for an asset depends on the asset type.

Note: Using this parameter also returns the asset's ETag value for all asset types, including raw.
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]. Note that requesting details of backed up versions consumes an additional 10 units of your rate limit for this call (11 total). (backups_and_version_management#versioning) 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

Get details of the asset with the specified asset ID, including faces, colors, image metadata and versions details:

Search for resources

Search allows you fine control on filtering and retrieving information on all the resources (assets) in your product environment 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

Note

Cloudinary implements eventual consistency: any changes made to assets will only be reflected in a search made a few seconds after the change is processed.

Optional parameters

All the parameters of the search method are optional. Including no parameters in the method call will return the 50 most recently created resources in descending order of creation time.

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 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.
Note: you can also sort the results by relevance if you set the key to score and give a sort direction as the value. Results are considered more relevant if the search term appears in multiple fields or the term is an exact match for an entire field.
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 metadata, 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).

Important
  • A new Search query object should be initialized for every distinct query executed. Please avoid reusing the same instance of a Search query object, as that might lead to unexpected behavior, especially when using the sort_by parameter.
  • When iterating through the results using the next_cursor parameter, the query should be reused without changing any of the other parameter values.
  • When making direct calls to the Cloudinary endpoint, make sure to pass any parameters using JSON (with Content-Type: application/json) as in the cURL examples on this page.

Examples

  1. 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:

  2. 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:

    Tip
    For more examples, see the expression examples documentation.

Sample response

Note
The sample response below reflects a product environment using fixed folder mode. On product environments using dynamic folder mode, asset_folder and display_name keys are also included in the response.

Visual search for resources

Important
Visual Search is currently in Beta and available for some customers to try. There may be changes in functionality or appearance before the general access release. Please contact support if you would like to activate this feature.

Visual search helps to improve image discoverability by enabling you to find images based on their visual content, as opposed to their name or metadata.

Tip
This feature is also available for Media Library searches. For details, see DAM visual search.

You can run a visual search by providing one of the following sources:

  • The URL of an image.
  • The asset_id of an image in your account.
  • A textual description, e,g,. "jackets".

Important
Only images that have already been indexed for visual search are included in the results. You can index an image by including the visual_search = true parameter when uploading or updating the asset.

Syntax

GET /resources/visual_search

Required parameters

ONE of the following parameters is required:

Parameter Type Description
image_url String The URL of an image.
image_asset_id String The asset_id of an image in your account.
text String A textual description, e.g., “shirts”

Examples

Do a visual search for 'footwear':

Sample response

The response returns the assets in order of relevance, from most to least similar:

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

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.
display_name String Relevant only for product environments using dynamic folder mode.

A user-friendly name for the asset.

  • Display names can have spaces and special characters, but can't include forward slashes (/). This name can be completely different than the asset's public id and its value doesn't impact the delivery URL in any way.
  • The display name is shown in user interface pages such as the Console Media Library, Cloudinary collections, and Cloudinary media portals.
  • Though not a best practice, it's possible for the same display name to be used for different assets, even in the same asset folder.
unique_display_name Boolean Relevant only for product environments using dynamic folder mode.

If true, and you've passed a display_name that already exists within the same asset_folder or you specify a new asset_folder value (to move the asset) and the same display name already exists in the target asset folder, a random character suffix will be appended to the display name of this asset to ensure it's uniqueness within the asset folder.

Default: false
asset_folder String Relevant only for product environments using dynamic folder mode.

The folder where the asset is placed within the Cloudinary repository.

Setting this value in an update method moves the asset to the specified asset folder, but does not impact the asset’s public ID path.
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 contextual metadata to attach to an uploaded asset. The contextual metadata values of uploaded files can be retrieved 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. For example: in_stock_id=50❘color_id=[\"green\",\"red\"].

SDKs: Supports maps.

Notes:
  • The =, " and ❘ characters can be supported as values when escaped with a prepended backslash (\).
  • For a multi-select field, you can set a maximum of 3000 different metadata values on an asset.
face_coordinates String List of coordinates of faces contained in an uploaded image. The specified 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 specified 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 Automatically assigns tags to an asset according to detected objects or categories with a confidence score higher than the specified value.

Use together with the detection parameter for:

Use together with the categorization parameter for:

Range: 0.0 to 1.0
detection String Invokes the relevant add-on to return a list of detected content.

Set to:

  • <content-aware model>_[<version>] (e.g. coco_v1) to return a list of detected content using the Cloudinary AI Content Analysis add-on. Can be used together with the auto_tagging parameter to apply tags automatically.
  • adv_face to return a list of facial attributes using the Advanced Facial Attribute Detection add-on.
  • aws_rek_face to return a list of detected celebrities and facial attributes using the Amazon Rekognition Celebrity Detection add-on. Can be used together with the auto_tagging parameter to apply tags automatically.

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. Can be used together with the auto_tagging parameter to apply tags automatically. See the Google Automatic Video Tagging, Google Auto Tagging, Imagga Auto Tagging and Amazon Rekognition Auto Tagging add-ons for more details.
visual_search Boolean Whether to index the image for use with visual searchs. Default: false.
Relevant for images only.
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 publicly 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:

Restore resources

Restores one or more resources (assets) from backup.

Syntax

POST /resources/:resource_type/:type/restore

Required parameters

Parameter Type Description
public_ids String[] The public IDs of (deleted or existing) backed up assets to restore (array of up to 100 public_ids). 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: upload.
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':

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

Sample response

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

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 the upload method and Access mode.

Syntax

POST /resources/:resource_type/upload/update_access_mode

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 specified public IDs (array of up to 100 public_ids).
- prefix String Update all assets where the public ID starts with the specified prefix (up to a maximum of 100 matching original assets).
- tag String Update all assets with the specified 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:

Update the access mode of uploaded videos by prefix:

Update the access mode of uploaded images by tag:

Sample response

Add related assets

Relates an asset to other assets by public IDs. This allows you to indicate that the asset is logically related to other assets in some way (e.g., similar content, or a peripheral asset like video/transcript, etc). This is a bidirectional process, meaning that the asset will also be added as a related_asset to all the other assets specified. The relation is also a one to many relationship, where the asset is related to all the assets specified, but those assets are not also related to each other.

Tip
Calling the Get the details of a single resource method with the related parameter set to true, will include the list of related assets in the response.

Syntax

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

Required parameters

Parameter Type Description
public_id The Public ID of the asset.
assets_to_relate Array Relates the asset to all the other assets specified in this array of up to 10 assets, specified as resource_type/type/public_id.
For example: ["image/upload/dog","video/authenticated/cat"]

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 (default), private, or authenticated.

Examples

Relate the asset with a public ID of 'video/upload/dog' to the assets with public IDs of 'image/authenticated/dog_license' and 'raw/upload/dog_subtitles.srt':

Sample response

Add related assets by asset ID

Relates an asset to other assets by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or deliver type.

This method allows you to indicate that the asset is logically related to other assets in some way (e.g., similar content, or a peripheral asset like video/transcript, etc). This is a bidirectional process, meaning that the asset will also be added as a related_asset to all the other assets specified. The relation is also a one to many relationship, where the asset is related to all the assets specified, but those assets are not also related to each other.

Tip
Calling the Get the details of a single resource method with the related parameter set to true, will include the list of related assets in the response.

Syntax

POST /resources/related_assets/:asset_id

URL parameters

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

Required parameters

Parameter Type Description
assets_to_relate Array Relates the asset to all the assets specified in this array of up to 10 assets, specified by their asset IDs.
For example: ["e12345b0efc00c0fcf","f12345a5c7c00c0f12"]

Examples

Relate the asset with a asset ID of 'c789c1234bbb0e' to the assets with IDs of 'f12345a5c789c' and 'bbb0efc00c0f12':

Sample response

Delete related assets

Unrelates the asset from other assets, specified by public IDs. This is a bidirectional process, meaning that the asset will also be removed as a related_asset from all the other assets specified. See Add related assets for more information.

Syntax

DELETE /resources/related_assets/:resource_type/:type/:public_id

Required parameters

Parameter Type Description
public_id String The public ID of the asset to update.
assets_to_unrelate Array Unrelates the asset from all the assets specified in this array of assets, specified as resource_type/type/public_id.
For example: ["image/upload/dog","video/authenticated/cat"]

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 (default), private, or authenticated.

Examples

Unrelate the asset with a public ID of 'image/upload/dog' from the assets with public IDs of 'raw/upload/dog_subtitles.srt' and 'video/authenticated/animals':

Sample response

Delete related assets by asset ID

Unrelates the asset from other assets, specified by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or deliver type. This is a bidirectional process, meaning that the asset will also be removed as a related_asset from all the other assets specified. See Add related assets by asset id for more information.

Syntax

DELETE /resources/related_assets/:asset_id

URL parameters

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

Required parameters

Parameter Type Description
assets_to_unrelate Array Unrelates the asset from all the assets specified in this array of assets, specified by their asset IDs.
For example: ["f12345af123c789c","45a5c789a5c789c5c7"]

Examples

Unrelate the asset with a asset ID of 'c789c1234bbb0e' from the assets with IDs of 'a5c789c5c745a' and 'a1623c3b234a':

Sample response

Delete resources

Deletes resources (assets) uploaded to your product environment

Syntax

DELETE /resources/:resource_type/:type

Required parameters

One of the following:

Parameter Type Description
public_ids String[] Delete all assets with the specified public IDs (array of up to 100 public_ids).
prefix String Delete all assets, including derived assets, where the public ID starts with the specified 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, list. Default: upload.
keep_original Boolean Whether to delete only the derived assets. 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 assets matching this hash of transformation parameters will be deleted.

Examples

Delete uploaded images by public IDs:

Delete Facebook pictures by public IDs:

Delete uploaded images by prefix:

Delete derived images only:

Delete all Facebook pictures:

Sample response

Delete resources by tags

Deletes resources (assets) with a specified tag.

Syntax

DELETE /resources/:resource_type/tags/:tag

Required parameters

Parameter Type Description
tag String Delete all assets (and their derivatives) with the specified 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 assets. 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 assets matching this hash of transformation parameters will be deleted.

Examples

Delete images by tag name:

Sample response

Delete derived resources

Deletes derived assets from your product environment.

Syntax

DELETE /derived_resources

Required parameters

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

Examples

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

resources_last_access_reports

Important
The last access reports feature and methods are currently available upon request, and only for accounts with an Enterprise plan. Please contact our Enterprise support and sales team or your CSM to request this feature.

Last access reports present a list of all the assets (resources) that have been accessed for the last time within a given time range. In addition, all last access reports automatically include any assets that were never accessed. This information can then be used for bulk deleting assets that you determine are no longer needed and thereby free up your storage space.

The last access report is based on an analysis of the CDN access logs for all requests that delivered content from your product environment. An asset's 'last access' date is updated with the timestamp of the most recent HTTP request to the CDN for that asset, either the original or a derived/transformed version of it.

Tip
For customers with the last access feature enabled, bulk deleting assets based on their last access time is also a self-service operation available in the Cloudinary Console.

bulk delete by last access

Note
The last access time cannot be determined for assets used in overlays/underlays and for assets with a public ID that contains characters requiring special encoding, and so these assets are excluded from all last access reports.
Method Description
POST/resources_last_access_reports Create a last access report
GET/resources_last_access_reports Get all last access reports
GET/resources_last_access_reports/:report_id Get the details of a last access report
GET/resources/last_access_report/:report_id Get resources in a last access report

Create a last access report

Creates a last access report.

Syntax

POST /resources_last_access_reports

Required parameters

At least 1 of the following is required.

Parameter Type Description
from_date String All assets accessed after this date, given in the format: yyyy-mm-dd
to_date String All assets accessed before this date, given in the format: yyyy-mm-dd

Optional parameters

Parameter Type Description
resource_type String The type of asset. Possible values: image, raw, or video. Default: all.
Note: Use video for all video and audio assets, such as .mp3.
type String The delivery type. Possible values: Any supported delivery type. Default: all.
exclude_folders String[] An array of up to 50 folders to exclude from the last access report.
sort_by String A string value representing the field to sort by. Possible values: accessed_at (default), resource_type, created_at.
direction String The sort direction, Possible values: asc (default) or desc.

Examples

Create a report for videos last accessed no more recently than the 1st of February 2020, that excludes all assets in the 'docs' and 'website' folders, and sorts the results by the date they were created:

Sample response

Get all last access reports

Retrieves a list of all the last access reports created.

Syntax

GET /resources_last_access_reports

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 the following request.

Examples

Get a list of all the last access reports.

Sample response

Get the details of a last access report

Returns the details of a given report. Does not include the report data.

Syntax

GET /resources_last_access_reports/:report_id

Required parameters

Parameter Type Description
report_id String The ID number of a previously generated report.

Examples

Request the details of a given report id.

Sample response

Get resources in a last access report

Returns the list of resources in a given report.

Syntax

GET /resources/last_access_report/:report_id

Required parameters

Parameter Type Description
report_id String The ID number of a previously generated report.

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 the following request.

Examples

Request the list of resources in a given report id.

Sample response

streaming_profiles

Run in Postman Learn more about running Postman collections

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.

Method Description
GET/streaming_profiles Lists the adaptive streaming profiles.
GET/streaming_profiles/:name Lists the details of a single streaming profile specified by name.
POST/streaming_profiles Creates a new streaming profile.
PUT/streaming_profiles/:name Updates the specified existing streaming profile.
DELETE/streaming_profiles/:name Deletes or reverts the specified streaming profile.

Get adaptive streaming profiles

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

Syntax

GET /streaming_profiles

Sample response

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

Get details of a single streaming profile

Retrieve the details of a single streaming profile by name.

Syntax

GET /streaming_profiles/: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:

Sample response

The response contains details for a single streaming profile.

Create a streaming profile

Create a new, custom streaming profile.

Syntax

POST /streaming_profiles

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:

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

Sample response

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

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

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

Sample response

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

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

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:

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

Sample response

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

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

Required parameters

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

Examples

Delete the custom_square streaming file:

Sample response

tags

Run in Postman Learn more about running Postman collections

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

Method Description
GET /tags Lists tags used for a specified resource type.

Get tags

Syntax

GET /tags/:resource_type

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 specified 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

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

Sample response

transformations

Run in Postman Learn more about running Postman collections

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

Method Description
GET /transformations Lists all transformations.
GET /transformations/:transformation Lists details of a single transformation specified by name or parameters.
POST/transformations/:name Creates a new named transformation.
PUT/transformations/:transformation Updates a specified transformation.
DELETE/transformations/:transformation Deletes a specified transformation.

Get transformations

List all transformations.

Syntax

GET /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:

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.

Get transformation details

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

Syntax

GET /transformations/:transformation

Required parameters

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

Note
If the derived assets do not have an extension, add "/" at the end of the transformation value: For example: f_webp,q_80,b_blue,w_200,h_200 becomes f_webp,q_80,b_blue,w_200,h_200/

Optional parameters

Parameter Type Description
max_results Integer Maximum number of derived 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

Get transformation by name:

Get transformation by parameters:

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

Sample response

Create a named transformation

Create a new named transformation.

Syntax

POST /transformations/:name

Required parameters

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

Optional parameters

Parameter Type Description
allowed_for_strict Boolean Whether to allow this named transformation when strict transformations are enabled. Default: true.

Examples

Create named transformation by string:

Create named transformation by parameters:

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

Sample response

Update transformation

Update a specific transformation.

Important
Before you modify the transformation parameters of a named transformation that's already used in production, make sure you're aware of all existing use cases. To mitigate risk, when you update the parameters of an existing named transformation, existing derived assets using the named transformation are not regenerated. However, if an asset using the named transformation is already in production and is later regenerated for another reason (for example, you invalidate it or adjust transformation parameters outside the named transformation), then the new named transformation definition is applied, and if that definition does not fit with the overall transformation defined for that asset, it could break your production asset.

Syntax

PUT /transformations/:transformation

Required parameters

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

Optional parameters

Parameter Type Description
allowed_for_strict Boolean Whether to allow this named transformation when strict transformations are enabled.
unsafe_update String Required when modifying the transformation parameters of an existing named transformation. The new transformation definition for the named transformation.

Because the changed definition can be unsafe for (significantly change) assets in production, the change is applied only to newly generated derived assets that reference this named transformation.

To apply the change to existing derived assets using this named transformation, invalidate them so that they'll be regenerated with the new definition when next requested.

Examples

Allow transformation by name:

Disallow transformation by parameter listing:

Update the transformation definition for a named transformation:

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

Sample response

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 assets based on this transformation (up to 1000).

If there are more than 1000 derived assets based on this transformation, the method returns a 403 error: Unable to delete transformation because it has too many derived resources.

Syntax

DELETE /transformations/:transformation

Required parameters

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

Note
If the derived assets do not have an extension, add "/" at the end of the transformation value: For example: f_webp,q_80,b_blue,w_200,h_200 becomes f_webp,q_80,b_blue,w_200,h_200/

Examples

Delete transformation by name:

Delete transformation by parameters:

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

Sample response

triggers

Run in Postman Learn more about running Postman collections

Enables you to manage the event triggers and notifications for your product environment. A trigger represents a single triggering event coupled with its corresponding notification URL.

Method Description
GET/triggers Lists all triggers.
POST/triggers Creates a new trigger.
PUT/triggers/:id Updates the notification URL for a trigger.
DELETE/triggers/:id Deletes a trigger.

Note
This endpoint is not currently supported by SDKs.

Get triggers

Lists all triggers.

Syntax

GET /triggers

Example

List all triggers:

Sample response

Create a trigger

Creates a new trigger. You can create up to 260 triggers, which is ten times the number of available event types.

Syntax

POST /triggers

Required parameters

Parameter Type Description
uri String The URL that will receive the notification response.
event_type String The type of event that will trigger the notification response.

Possible values: See the table.

event_type possible values

Note
The Value corresponds to the Notification type(s) in the Webhook Notifications page of the Console Settings and the notification_type in the response.
Value Description Source
all Any of the event types.
access_control_changed Access control for an asset is changed. - resources method of the Admin API

- Console UI operation
bulk_refresh_auto_fetch Refresh of fetched assets is completed. - For more information, see Refreshing fetched assets (images only)
cache_warm_up The cache_warm_up method is called and completed. - cache_warm_up method of the Media Optimizer API
create_folder A new folder is created. - create_folder method of the Admin API

- Console UI operation
delete An asset is deleted. - destroy method of the Upload API

- resources method of the Admin API

- Console UI operation
delete_by_token An asset is deleted using a deletion token. - delete_by_token method of the jQuery SDK
delete_folder A folder is deleted. - delete_folder method of the Admin API call

- Console UI operation
eager An eager transformation is requested and completed. - eager transformation included in an upload method API call
error An error occurs during upload. - upload API call

- Console UI operation

explode Derived images are created from a multi-page file. - explode method of the upload API
generate_archive An archive file is generated. - generate_archive method of the Admin API
info Actions that involve gathering information about an asset (such as background removal and auto-tagging) are completed. - Add-ons applied during a call to the upload method

- Console UI operation
invalidate_custom_cdn Cached copies of an asset are invalidated from a customer owned CDN. - upload API call
moderation An asset is approved or rejected. - Moderations applied during a call to the upload method

- Console UI operation
moderation_summary An asset is marked for multiple moderations is approved or rejected. - Multiple moderations applied during a call to the upload method

- Console UI operation
move An asset is moved between folders (only relevant if your product environment is using dynamic folders). - resources method of the Admin API

- Console UI operation
multi Animated image, video or PDF is created from multiple assets. - multi method of the upload API
publish A public link is generated for sharing an asset via a dedicated website. - Console UI operation
rename An asset is renamed (or, if your product environment is using fixed folder mode, moved to a different folder). - rename method of the Upload API

- resource method of the Admin API (fixed folder mode only)

- Console UI operation

report A last access report is created. - resources last access reports
resource_context_changed Contextual metadata is changed. - resource method of the Admin API

- Console UI operation

resource_display_name_changed An asset's display name is changed (only relevant if your product environment is using dynamic folders). - resource method of the Admin API

- Console UI operation

resource_metadata_changed Structural metadata is changed. - resource method of the Admin API

- Console UI operation
resource_tags_changed Tags are changed. - resource method of the Admin API

- Console UI operation
sprite Multiple images are merged into a single large image. - sprite method of the Upload API
upload An asset is uploaded. - upload method

- create_collage method of the Upload API

- Console UI operation

Note
The response for the explicit method is sent to the notification URL that handles the action specified in the call.

Example

Set up the https://mysite.example.com/my_notification_endpoint URL to receive a notification whenever an upload is completed:

Sample response

Update a trigger

Updates a notification URL for a trigger.

Note
You can't update the event_type for a trigger. If you want to update an event_type for a specific notification URL, delete the relevant trigger and then create a new one.

Syntax

PUT /triggers/:id

Required parameters

Parameter Type Description
id String The ID of the trigger to update.
new_uri String The updated URL that will receive the notification response.

Example

Update the notification URL to https://mysite.example.com/my_new_notification_endpoint URL for a trigger with ID 1ajkfl2389740vml:

Sample response

Delete a trigger

Deletes a trigger.

Syntax

DELETE /triggers/:id

Required parameters

Parameter Type Description
id String The ID of the trigger to delete.

Example

Delete the trigger with ID 1ajkfl2389740vml:

Sample response

upload_mappings

Run in Postman Learn more about running Postman collections

Dynamically retrieves assets from existing online locations and uploads the files to your product environment.

See the Auto upload remote files documentation for more information.

Method Description
GET/upload_mappings/:folder Lists all upload mappings by folder.
GET/upload_mappings/?folder=:folder Lists the details of a single upload mapping.
POST/upload_mappings Creates a new upload mapping folder and its template (URL).
PUT/upload_mappings Updates an existing upload mapping folder with a new template (URL).
DELETE/upload_mappings/?folder=:folder Deletes an upload mapping by folder name.

Get upload mappings

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

Syntax

GET /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

Sample response

Get the details of a single upload mapping

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

Syntax

GET /upload_mappings?folder=:folder

Required parameters

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

Examples

Upload mapping details by folder the 'wiki' folder:

Sample response

Create an upload mapping

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

Syntax

POST /upload_mappings

Required parameters

Parameter Type Description
folder String The name of the folder to map.
template String The URL prefix 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':

Sample response

Update an upload mapping

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

Syntax

PUT /upload_mappings

Required parameters

Parameter Type Description
folder String The name of the folder to map.
template String The URL prefix 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:

Sample response

Delete an upload mapping

Delete an upload mapping by folder name.

Syntax

DELETE /upload_mappings?folder=:folder

Required parameters

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

Examples

Delete an upload mapping to the 'wiki' folder:

Sample response

upload_presets

Run in Postman Learn more about running Postman collections

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

See the upload preset documentation for more information.

Method Description
GET /upload_presets Lists the upload presets defined for your product environment.
GET /upload_presets/:name Lists the details of a single upload preset.
POST/upload_presets Creates a new upload preset.
PUT/upload_presets/:name Updates an existing, specified upload preset.
DELETE/upload_presets/:name Deletes an existing, specified upload preset.

Get upload presets

Lists the upload presets defined for your product environment.

Syntax

GET /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:

Sample response

Get the details of a single upload preset

Retrieves the details of an upload preset.

Syntax

GET /upload_presets/:name

Required parameters

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

Examples

Upload preset details for the 'remote_media' preset:

Sample response

Create an upload preset

Create a new upload preset.

Syntax

POST /upload_presets

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.

Default: false
use_asset_folder_as_public_id_prefix Boolean

Relevant only for product environments using dynamic folders mode.

Whether to automatically apply the path specified in the asset_folder parameter (or the asset folder that's in focus when an asset is uploaded directly to a folder in the Cloudinary Console user interface) as a prefix to the specified or generated public_id value. This ensures that the public ID path will always match the initial asset folder.

This can help to retain the behavior that previously existed in fixed folder mode. However, keep in mind that even when this option is used during upload, an asset with a certain public ID path can later be moved to a completely different asset folder hierarchy without impacting the public ID. This option only ensures path matching for the initial upload.

Relevant only when public_id_prefix (or folder) has not been separately specified.

Default: false
{Upload parameters} All supported upload parameters are also supported for upload presets. Those you include will be applied to all assets uploaded with this preset. If any of the same parameters are also specified directly in the upload call, those values will override the values in the upload 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:

Sample response

Update an upload preset

Update an existing upload preset.

Syntax

PUT /upload_presets/: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:

Sample response

Delete an upload preset

Delete an existing upload preset.

Syntax

DELETE /upload_presets/:name

Required parameters

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

Examples

Delete an upload preset called 'remote_media':

Sample response

usage

Run in Postman Learn more about running Postman collections

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

Method Description
GET /usage Lists product environment usage details.

Get product environment usage details

Syntax

GET /usage

Optional parameters

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

Examples

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

Sample response

The response contains an object with detailed usage information.

✔️ Feedback sent!

Rate this page: