Last updated: Dec-22-2024
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.
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 cld-docs
product environment:
The API uses Basic Authentication over secure HTTP. Your Cloudinary API Key and API Secret (which can be found on the API Keys page of your Cloudinary Console Settings) 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:
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.
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.
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:
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)
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
config
Enables you to get the details on your product environment configuration and current settings including information on the folder_mode
(dynamic or fixed).
Method | Description |
---|---|
GET /config
|
Lists product environment config details. |
Get product environment config details
Syntax
GET /config
Optional parameters
Parameter | Type | Description |
---|---|---|
settings | Boolean | Whether to include the current configuration settings in the response. Currently returns information on the folder_mode (dynamic or fixed). Default: false
|
Examples
Return the product environment configuration including settings info:
Sample response
The response contains an object with detailed product environment information.
folders
Enables you to manage your product environment's asset folders.
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. |
PUT/folders/:folder
|
Updates a 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
Update folder
Updates an existing asset folder.
Syntax
PUT /folders/:folder
Required parameters
Parameter | Type | Description |
---|---|---|
folder | String | The full path of an existing asset folder. |
to_folder | String | The full path of the new asset folder. Updates as follows:
|
Examples
Update a folder called 'product/test' to 'product1/test1':
Sample response
Delete folder
Deletes an empty folder.
- To find all assets currently in a folder:
- In dynamic folder mode, use the get resources by asset folder method.
- In fixed folder mode, use the get resources method with the
prefix
parameter to find all assets with a specified path in the public ID.
- To move assets out of a folder:
- In dynamic folder mode, use the update method with the
asset_folder
parameter to change the asset's asset folder. - In fixed folder mode, use the rename method to change the public ID path.
- In dynamic folder mode, use the update method with the
- To delete assets: use the Delete resources method.
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
Enables you to manage the metadata fields available for your product environment.
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. |
POST/metadata_fields/:external_id/datasource/order
|
Order a metadata field datasource. |
PUT/metadata_fields/:external_id
|
Updates a metadata field definition by external ID. |
PUT/metadata_fields/:external_id/datasource
|
Updates a metadata field datasource by external ID. |
DELETE/metadata_fields/:external_id
|
Deletes a metadata field by external ID. |
DELETE/metadata_fields/:external_id/datasource
|
Deletes entries in a metadata field datasource for a specified metadata field definition. |
Get metadata fields
Returns a list of all metadata field definitions as an array of JSON objects.
See also: Metadata field structure
Syntax
GET /metadata_fields
Sample response
Get a metadata field by external ID
Returns a single metadata field definition.
See also: Metadata field structure
Syntax
GET /metadata_fields/:external_id
Required parameters
Parameter | Type | Description |
---|---|---|
external_id |
String | The ID of the metadata field (included in the endpoint URL when using the REST API). |
Examples
Return the information for the metadata field with the ID of 'in_stock':
Sample response
Create a metadata field
Creates a new metadata field definition. Expects a single JSON object which defines the field, according to the structure for the required field type.
See also: Metadata field structure
Syntax
POST /metadata_fields
Required parameters
Parameter | Type | Description |
---|---|---|
field |
Object | The metadata field to add. For details see Metadata field structure. |
Optional parameters
Parameter | Type | Description |
---|---|---|
allow_dynamic_list_values |
Boolean | Sets whether DAM users can add list values dynamically. For more information, see Adding structured metadata fields. Default: false
|
Examples
Add a new mandatory metadata set
(multi-select) field with an external_id of 'color_id', labeled 'Colors', and with 4 available colors: red, green, blue and yellow, where red and green are the default values:
\
or "
, for example, \"text\"
or ""text""
.Sample response
Restore entries in a metadata field datasource
Restores (unblocks) any previously deleted datasource entries for a specified metadata field definition. Sets the state of the entries to active.
See also: Metadata field structure
Syntax
POST /metadata_fields/:external_id/datasource_restore
Required parameters
Parameter | Type | Description |
---|---|---|
external_id |
String | The ID of the metadata field (included in the endpoint URL when using the REST API). |
external_ids |
String[] | An array of IDs of datasource entries to restore (unblock). |
Examples
Restore (unblock) the datasource entry with external_id 'color1' from the metadata field with external_id 'color_id':
Sample response
Order a metadata field datasource
Updates the ordering of a datasource of a supported field type (currently only enum and set).
Syntax
PUT /metadata_fields/:external_id/datasource/order
Required parameters
Parameter | Type | Description |
---|---|---|
external_id |
String | The ID of the metadata field (included in the endpoint URL when using the REST API). |
order_by |
String | The criteria for the sort. Currently supports only value . |
direction |
String | Control the ordering direction. Possible values: desc or asc . |
Examples
Reorder the datasource values in ascending order for the metadata field with the ID of 'color_id':
Sample response
Update a metadata field by external ID
Updates a metadata field definition (partially, no need to pass the entire object) passed as JSON data.
See also: Metadata field structure
Syntax
PUT /metadata_fields/:external_id
Required parameters
Parameter | Type | Description |
---|---|---|
external_id |
String | The ID of the metadata field (included in the endpoint URL when using the REST API). |
field |
Object | The metadata field to update. For details see Metadata field structure. |
Optional parameters
Parameter | Type | Description |
---|---|---|
allow_dynamic_list_values |
Boolean | Sets whether DAM users can add list values dynamically. For more information, see Adding structured metadata fields. Default: false
|
Examples
Update the metadata field with the ID of 'in_stock':
\
or "
, for example, \"text\"
or ""text""
.Sample response
Update a metadata field datasource
Updates the datasource of a supported field type (currently only enum and set), passed as JSON data. The update is partial: datasource entries with an existing external_id will be updated and entries with new external_id's (or without external_id's) will be appended.
See also: Metadata field structure
Syntax
PUT /metadata_fields/:external_id/datasource
Required parameters
Parameter | Type | Description |
---|---|---|
external_id |
String | The ID of the metadata field (included in the endpoint URL when using the REST API). |
entries |
Object | The datasource entries to update. For details see Datasource values. |
Examples
Update the datasource for the metadata field with the ID of ''color_id':
\
or "
, for example, \"text\"
or ""text""
.Sample response
Delete a metadata field by external ID
Deletes a metadata field definition. The field should no longer be considered a valid candidate for all other endpoints (it will not show up in the list of fields, etc).
external_id
s can be reused after fields are deleted, but if the fields had many assignments, the process can take a few minutes and the external_id
will be reserved until the asynchronous deletion is complete.See also: Metadata field structure
Syntax
DELETE /metadata_fields/:external_id
Required parameters
Parameter | Type | Description |
---|---|---|
external_id |
String | The ID of the metadata field (included in the endpoint URL when using the REST API). |
Examples
Delete the metadata field with the ID of 'in_stock':
Sample response
Delete entries in a metadata field datasource
Deletes (blocks) the datasource entries for a specified metadata field definition. Sets the state of the entries to inactive
. This is a soft delete, so the entries still exist under the hood but are marked as having an inactive state
. The entries can be activated again with the restore datasource entries method.
state
property set to inactive
. See also: Metadata field structure
Syntax
DELETE /metadata_fields/:external_id/datasource
Required parameters
Parameter | Type | Description |
---|---|---|
external_id |
String | The ID of the metadata field (included in the endpoint URL when using the REST API). |
external_ids |
String[] | An array of IDs of datasource entries to delete. |
Examples
Delete (block) the datasource entry with external_id 'color4' from the metadata field with external_id 'color_id':
Sample response
Metadata field structure
Metadata fields have the following structure:
Parameter | Required | Description |
---|---|---|
external_id |
No | A unique immutable identification string for the metadata field. Default: auto-generated by Cloudinary (although it's recommended to specify a descriptive name). Max character length: 255. |
type |
Yes | The type of value that can be assigned to the metadata field, possible types are limited to: * string - a single string value* integer - a single integer value* date - a custom date in the following format: {yyyy-mm-dd}* enum - a single value referenced by an external_id from a given list, predefined with the datasource parameter* set - multiple values referenced by external_id s from a given list, predefined with the datasource parameter |
label |
Yes | The label of the metadata field for display purposes. |
mandatory |
No | Whether a value must be given for this field, either when an asset is first uploaded, or when it is updated. Default: false
|
restrictions |
No | Any restrictions to apply. Currently can set the readonly_ui boolean parameter to mark this metadata field as read only in the UI (only relevant if mandatory is false). Default: {"readonly_ui": false}
|
default_value |
Yes (if mandatory is true) |
The default value for the field (a set can have multiple default values defined by an array). Default: null
|
validation |
No | Any validation rules to apply when values are entered (or updated) for this field. See Validating data for more details. Default: null
|
datasource |
Yes (for the enum and set type ) |
The predefined list of values, referenced by external_id s, available for this field. See Datasource values for more details. |
Validating data
The validation
parameter defines a validation object with the logic to apply when a value is entered for the field. The boolean validations also allow for combinations of more than one rule. The following validations are supported:
greater_than validation
Relevant for integer
and date
types:
Property | Type | Description |
---|---|---|
value |
String | The value for validation. |
equals |
Boolean | Whether to check if greater than or equals. Default: false
|
For example:
less_than validation
Relevant for integer
and date
types:
Property | Type | Description |
---|---|---|
value |
String | The value for validation. |
equals |
Boolean | Whether to check if less than or equals. Default: false
|
For example:
strlen validation
Relevant only for string
types:
Property | Type | Description |
---|---|---|
min |
Integer | The minimum string length. Default: 0
|
max |
Integer | The maximum string length. Default: 1024
|
For example:
and validation
Relevant for all field types. Allows you to include more than one validation rule to be evaluated:
Property | Type | Description |
---|---|---|
validation_object |
Object | One of the other validations above: greater_than , less_than or strlen
|
For example:
Datasource values
The datasource
parameter is relevant for fields where the selected values must come from a predefined list of values (enum
or set
type fields). The parameter contains the values
property, which defines the values for the enum
or set
list. Up to 3000 values can be defined for a list.
Each datasource_entry
defines a single possible value for the field:
Property | Type | Description |
---|---|---|
external_id |
String | (optional) A unique immutable identification string for the datasource entry, (required if the value is referenced by the default_value field). Default: auto-generated by Cloudinary |
value |
String | (mandatory) The value for this datasource. |
state |
String | (read only) Only given as part of a response - ignored on requests. It is immutable unless changed via DELETE of a datasource entry. |
For example:
metadata_rules
Enables you to set up dependencies and hierarchical relationships between structured metadata fields and field options.
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. |
Get metadata rules
Returns an index of all metadata rules (active and inactive) as an array of JSON objects. The rules are sorted by the dependent metadata field id, and then by their internal order (currently the order of insertion).
Syntax
GET /metadata_rules
Example
Sample response
Create a metadata rule
Creates a new metadata rule definition. Expects a JSON object which defines the rule.
Syntax
POST /metadata_rules
Required parameters
Parameter | Type | Description |
---|---|---|
rule | Object |
The
|
Example
When the category
metadata field value is equal to 'employee', enable the team
metadata field and activate all the available values:
Sample response
Update a metadata rule by ID
Updates an existing metadata rule definition. Expects a JSON object which defines the updated rule.
Syntax
PUT /metadata_rules/:external_id
Required parameters
Parameter | Type | Description |
---|---|---|
external_id | String | The ID of the metadata rule (included in the endpoint URL when using the REST API). |
rule | Object |
The
|
Example
Update the rule with id "eae809b91168cf3877743713a9dd4b9428bb6f9c37385f6a4897f227b4b86d14" as follows: when the category
metadata field value is equal to 'employee', enable the team
metadata field and activate all the available values:
Sample response
Delete a metadata rule by ID
Deletes a metadata rule definition. The rule should no longer be considered a valid candidate for all other endpoints (it will not show up in the list of rules, etc).
Syntax
DELETE /metadata_rules/:external_id
Required parameters
Parameter | Type | Description |
---|---|---|
external_id | String | The ID of the metadata rule (included in the endpoint URL when using the REST API). |
Example
Delete the metadata rule with an external_id of 'eae809b91168cf3877743713a9dd4b9428bb6f9c37385f6a4897f227b4b86d14':
Sample response
Metadata rule structure
Each metadata rule connects a specified metadata field with a condition to evaluate on a metadata payload (based on other fields' values), and then with a result to apply to the specified metadata field in the case that the condition is met.
Metadata rule = Metadata field + condition + result
Condition structure
The condition that must be met in order to activate the result. Each of the conditions must include the metadata_field_id
(external_id of a metadata field) to evaluate, and the specific criteria to evaluate.
Syntax
Parameters
Property | Type | Description |
---|---|---|
metadata_field_id | String | Required. The external_id of the metadata field to evaluate. |
populated | Boolean | Whether the metadata field is currently populated. |
includes | array of Strings | For multi-select (set) fields - an array of datasource external ids specifying the current values of the metadata field. |
equals | String | The current value of the metadata field. |
You can set multiple conditions by defining them as and
conditions that must all be met for the result to be applied, or as or
conditions where it is enough that one of the conditions is met.
and
or or
expression by including it as another condition.Examples
Result structure
The result options are applied to the metadata field when the condition is met.
Syntax
Parameters
One or more of the following actions can be applied:
Action | Type | Description |
---|---|---|
enable | Boolean | Whether to enable the metadata field. You can set a metadata field to be disabled by default by updating the metadata field and setting the default_disabled parameter to true. See the note below. |
activate_values | Object | The values that will be available for an 'enum' or 'set' metadata field. Optionally, can use a string value of "all" to activate all the possible values. |
apply_value | Object | The value to apply to the metadata field. |
set_mandatory | Boolean | Whether to set the metadata field as mandatory. |
enable: true
action, a field should first be set to disabled by default. This is done by using the update metadata field method and setting the default_disabled
parameter to true
. Note that this parameter is not documented in the update method, and should only be used together with a conditional metadata rule that can enable the field when a condition is met.For example, to set a metadata field with the external_id 'category_id' to disabled by default:
activate_values
The activate_values
action can be set to either activate all the values available ("all"
) or you can specify an object detailing the list of available external IDs as an array of datasource values by their external ids, and the mode
to either 'override' the existing values or to 'append' them to the current values.
apply_value
The apply_value
action is used to apply a specified value for the metadata field. For multi-select (set) fields you can apply multiple values by giving an array of datasource external ids, and the mode
to either apply them as the 'default' values or to 'append' them to the currently selected values.
Examples:
ping
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
Enables you to manage all the resources (assets) stored in your product environment.
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 |
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 |
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 . |
fields | String | A comma-separated list of fields to include in the response. Notes: |
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
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.
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 . |
fields | String | A comma-separated list of fields to include in the response. Notes: |
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 . |
fields | String | A comma-separated list of fields to include in the response. Notes: |
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.
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 . |
fields | String | A comma-separated list of fields to include in the response. Notes: |
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 . |
fields | String | A comma-separated list of fields to include in the response. Notes: |
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 , aws_rek_video , perception_point , google_video_moderation , duplicate . |
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 . |
fields | String | A comma-separated list of fields to include in the response. Notes: |
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 of the asset. Note that requesting details of backed up versions consumes an additional 10 units of your rate limit for that call (11 total). 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.
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 unique and 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 of the asset. Note that requesting details of backed up versions consumes an additional 10 units of your rate limit for that call (11 total). 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.
Syntax
GET /resources/search
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 ). To learn about building search queries, see the search expressions guide, and for details on using fields in your expressions, see the Expressions fields reference below. |
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. |
fields | String | A comma-separated list of fields to include in the response. Notes: |
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). |
- A new Search query object should be initialized for every distinct query executed. 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 below. - 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.
Expression Fields
You can use the following fields to limit your search criteria. The operators that you can use with a field depend on the field's value type. For details, see Field types and supported operators below. You can use all fields for all resource types (image, video, raw) unless otherwise specified. Additionally, all string fields support both exact and tokenized search unless otherwise specified.
Field Name | Type | Examples | Details |
---|---|---|---|
Asset Management | |||
access_mode |
String (fixed list) | access_mode:authenticated | The authentication level currently set for the resource. Possible values: public , authenticated Case-sensitive |
asset_id |
String | asset_id=abcd10ef1234ab1c678def9a0c123 | The immutable ID of the asset. An asset's asset_id is returned when assets are uploaded as well as when they are retrieved, such as when using the resources method. Not supported for product environments using the legacy fixed folder mode. |
asset_folder |
String | asset_folder=test/sample // exact folder, no subfolders asset_folder:sample/* // prefix, all contents of 'sample' under root asset_folder:"my folder with spaces" // folder name containing spaces |
You can search for an exact folder path, or you can search for a folder prefix, which returns all contents of the specified folder and all its subfolders. Case-sensitive. Not supported for product environments using the legacy fixed folder mode. |
context |
String | context.productType:shoe context.productType=shoe context."key with spaces":myValue context:keyname //check for key existence |
You can search for a specific key-value pair, or for all resources with a particular key regardless of the value, or with a particular value regardless of the key. - To search for the value of a key, specify the key value of the context using the dot (.) notation, and the value using a colon (:). - To check for the existence of a key name, specify the keyname you are searching for after an equal sign (=). - Key names are exact match only and are case-sensitive. - Values can be tokenized or exact match. - Exact match (=) searches are case-sensitive. - Tokenized searches (:) are case insensitive. |
created_at |
Date | created_at:["2022-11-12T12:00:00Z" TO 1w] created_at:[4w TO 1w] created_at>10d created_at<1w created_at<=2023-01-01 created_at<1486929412 |
Note: If you include the time, the entire date and time need to be enclosed in quotation marks. |
last_updated |
Date | last_updated.tags_updated_at:["2022-10-22T12:00:00Z" TO "2022-11-22T12:00:00Z"] last_updated.context_updated_at>"2022-10-22T12:00:00Z" |
You can search within any of the last_updated fields: access_control_updated_at , context_updated_at , metadata_updated_at , public_id_updated_at , tags_updated_at , or updated_at .Note: If you include the time, the entire date and time need to be enclosed in quotation marks. |
display_name |
String | display_name="small white dog" display_name:"small white" public_id:dog* |
The user-friendly display name of the asset. Not supported for product environments using the legacy fixed folder mode. |
folder |
String | folder=test/sample // exact folder, no subfolders folder:sample/* // prefix, all contents of 'sample' under root folder:"my folder with spaces" // folder name containing spaces |
You can search for an exact folder path, or you can search for a folder prefix, which returns all contents of the specified folder and all its subfolders. Case-sensitive. Supported only for product environments using the legacy fixed folder mode. |
metadata |
String | metadata.quantity_id<10 //int metadata.name_id:john //string metadata.city_id=paris_id //enum metadata.exp_date>2021-01-01 //date metadata.color_id:red_id //set |
Specify the external_id of any structured metadata field using the dot (.) notation, where the external ID is compared with a specified value according to the field's defined type (use the datasource external_id instead of a value for enum and set types). See metadata fields for details. |
moderation_kind |
String | moderation_kind=perception_point | The moderation applied to the asset. For assets marked for multiple moderations: - During moderation: The moderation currently being applied to the asset. - If the asset was rejected: The moderation that rejected the asset. - If the asset was approved: The last moderation that was applied. Possible values: |
moderation_status |
String | moderation_status=approved | The current moderation status. Possible values: pending , approved , rejected Case-sensitive. |
public_id |
String | public_id=test/sample/dog public_id:test/sample/dog public_id:test/sample/dog* |
The full public ID, including slashes when relevant. You can search for an exact public_id, or you can search for a public_id prefix using the * operator. Case-sensitive |
tags |
String | tags:siamese //tokenized search tags=siamese //exact search -tags=siamese //doesn't have the tag tags="siamese cats" //tag includes a space -tags //has no tags at all |
Exact match (=) searches are case-sensitive. Tokenized searches (:) are case insensitive. |
type |
String (fixed list) | type:private | The asset type. Possible values: upload , private , authenticated , fetch , facebook , twitter , etc.Exact match only. Case-sensitive. |
uploaded_at |
Date | uploaded_at<1d // uploaded date is smaller than the date one day ago = longer than 1 day ago. | |
Media Properties | |||
aspect_ratio |
Number or String | aspect_ratio="16:9" aspect_ratio<=1 |
You can specify the aspect ratio as a decimal number (comparisons round all aspect ratios to 5 decimal places for purposes of the check), or a string in the format "Width:Height". Exact match only. Case-sensitive. |
bytes |
Number | bytes:[1000 TO 5000000]1 bytes>100000 |
The file's size. You can append a b for bytes (default), a kb for kilobytes, a mb for megabytes, and a gb for gigabytes. |
duration |
Number or String | duration:[30s TO 2m]1 duration>5 duration<30s duration<3m |
The duration of the video. You can append an s for seconds (default) or an m for minutes. Video resources only. |
filename |
String | filename="hound-dog" filename:(dog cat) filename:hound* |
Refers to the last element of the public ID without a format extension. You can search for an exact or tokenized filename, or you can search for a filename prefix using the * operator. Exact match (=) searches are case-sensitive. Tokenized searches (:) are case insensitive. |
format |
String | format=(jpg OR mp4) | Exact match only. Case-insensitive. |
height |
Number | height<=100 | Not relevant for raw files. |
pixels |
Number | pixels>400000 | Number of total pixels (width x height). You can append a p for pixels (default) or an m for megapixels. Not relevant for raw files. |
resource_type |
String (fixed list) | resource_type:image resource_type:video |
Possible values: image , video , raw Exact match only. Case-sensitive. |
width |
Number | width>100 width=1028 |
Not relevant for raw files. |
System | |||
backup_bytes |
Number | backup_bytes>0 // all resources that are backed up. | If the resource is backed up, indicates the space taken in the backup system by all backed up versions. You can append a b for bytes (default), a kb for kilobytes, or a mb for megabytes. |
status |
String (fixed list) | status=deleted status=deleted OR active |
Possible values: active , deleted Notes: - Resource data is stored in the database with status deleted only if the resource has a backup. - By default, when you conduct a search, the response includes only resources with active status. If you want the response to include resources with a deleted status, you must use this field to specify it. Exact match only. Case-sensitive. |
Asset analysis and embedded metadata (Tier 2) |
|||
accessibility_analysis.colorblind_accessibility_score |
Number | accessibility_analysis.colorblind_accessibility_score>0.8 | A score between 0 and 1 that is a measure of the accessibility of the image to color blind people. Available only for images for which accessibility_analysis was set to true during upload (in the upload request or upload preset). Note: The accessibility_analysis.colorblind_accessibility_score field is returned in searches including a with_field parameter specifying accessibility_analysis . |
colors |
String | colors:blue //images that contain blue colors.blue>=2 //images that are at least 2% blue |
To search for images that contain a specified color (as one of the detected predominant colors), use the colon notation. Supported colors: green, blue, lightblue, black, white, red, gray, lime, yellow, olive, cyan, teal, purple, orange, pink, and brown To search for images that have a specified % of the specified color, use the dot (.) notation. Image resources only. Note: The colors field is returned in searches including a with_field parameter specifying image_analysis . |
etag |
String | etag=d8ee49a7e9fb633c91cd4d4b2b | Exact match only. Case-sensitive. Note: The etag field is returned in searches including a with_field parameter specifying image_analysis . |
face_count |
Number | face_count>=1 | Image resources only. Note: The face_count field is returned in searches including a with_field parameter specifying image_analysis . |
grayscale |
Boolean | grayscale:true | Image resources only. Note: The grayscale field is returned in searches including a with_field parameter specifying image_analysis . |
illustration_score |
Number | illustration_score>0.5 | The likelihood that the image is an illustration (as opposed to a photo). Values between 0 (photo) and 1 (illustration). Image resources only. Note: The illustration_score field is returned in searches including a with_field parameter specifying image_analysis . |
image_metadata |
String | image_metadata.license=a1s3d5f7a9s2d4f | Accesses the specified type of embedded metadata from the image, such as from the Exif data or XMP. Specify any embedded metadata element using the dot (.) notation. Embedded metadata element values are case-sensitive. Specify their names exactly as stored inside the actual image metadata. Image resources only. |
location |
String | location:"40.73,-74.1|41.73,-74.1|41.73,-75.1|42.73,-75.1|41.73,-74.1" // within a bounding polygon location:"40.73,-74.1|40.73,-74.1" // within a bounding box location:"40.73,-74.1 5km" // within distance of a point |
Matches the GPS location stored with the image metadata to within a specified bounding polygon, bounding box, or within distance from a specified point (distance can be specified in: mi (miles), yd (yards), m (meters), or km (kilometers)). |
quality_analysis.color_score |
Number | quality_analysis.color_score>0.6 | A component of extended quality analysis, the quality_analysis.color_score takes into account factors such as exposure, white balance, contrast and saturation. Downscaling makes no difference to the perceived color quality. Available only for images for which quality_analysis was set to true during upload (in the upload request or upload preset). Note: The quality_analysis.color_score field is returned in searches including a with_field parameter specifying quality_analysis . |
quality_analysis.pixel_score |
Number | quality_analysis.pixel_score>0.6 | A component of extended quality analysis, the quality_analysis.pixel_score is a measure of how the image looks in terms of compression artifacts (blockiness, ringing etc.) and in terms of capture quality (focus and sensor noise). Downscaling can improve the perceived visual quality of an image with a poor pixel score. Available only for images for which quality_analysis was set to true during upload (in the upload request or upload preset). Note: The quality_analysis.pixel_score field is returned in searches including a with_field parameter specifying quality_analysis . |
quality_score |
Number | quality_score>0.7 | The overall weighted quality score. Available only for images for which quality_analysis was set to true during upload (in the upload request or upload preset) and only for paid accounts taking part in the extended quality analysis Beta trial. Note: The quality_score field is returned in searches including a with_field parameter specifying image_analysis . |
taken_at |
Date | taken_at:[2017-10-10T12:00:00Z TO 1w] taken_at:[1w TO 4w] taken_at>10d taken_at<1w taken_at<=2016-01-01 taken_at<1486910712 |
The date the photograph was taken according to the EXIF data. |
transparent |
Boolean | transparent:true | Returns any asset where one or more pixels has an alpha channel. This does not necessarily mean there are any visibly transparent or semi-transparent areas in the image. Image resources only. Note: The transparent field is returned in searches including a with_field parameter specifying image_analysis . |
Field types and supported operators
Field type | Supported operators | Notes |
---|---|---|
Boolean | = |
Possible values: true , false
|
Date | = > >= < <= [ ] { } |
The date can be given as: - Unix time e.g., 1515911870 - UTC date (and optional time) in ISO8601 syntax: {yyyy-mm-dd}[T{hh:mm:ss}Z] - Relative time: a relative amount of time ago from today, such as an hour, day, week, month ago: 1h, 1d, 1w, 1m. Notes: - When specifying ranges, it is possible to specify each element of the range in a different date format. For example, a range from January the 15th 2016 until 1 week ago: created_at:[2016-01-15T12:00:00Z TO 1w]. The results for a range will include all matches from and including the minimum date specified, and up to but not including the maximum date specified. - When using operators such as greater than or less than with relative times, the comparison is in unix time. For example, 'greater than' indicates a unix time that is larger than the specified relative time. Therefore >3d indicates a date within the last 3 days. |
Number | = > >= < <= [ ] { } |
|
String | : = [ ] { } |
Some string fields support both tokenized searches using the colon (:) operator, and exact searches using the equal sign (=) operator. Other fields support only exact searches. In these cases, regardless of whether you use a colon or equal sign operator, an exact search is performed. You can use the [ ] or { } range operators to search for strings falling into an alphabetical range. Note: The following string fields are not included in global searches. To search in these fields, you must explicitly specify the field in the search criteria: type , status , resource_type
|
Examples
-
Find assets containing 'shirt' in any field (attribute), include only the context metadata and tags fields in the details of each resource, and limit the returned results to 10 resources:
-
Find assets containing 'shirt' in any field but not 'blue' 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:
-
Find the next page of 500 results, using the 'next_cursor' from the previous call (b16b8bd80426df43a107f26b0348), of a search for images tagged with 'shirt', that have been uploaded within the last day, and sort the results by
public_id
in descending order:
Sample response
status
field in the response tells you whether the asset is active
and visible with working delivery URLs or not_found
if it’s deleted but also backed up.Visual Search for resources
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.
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".
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 by public ID
Update one or more attributes of a specified resource (asset) identified by its public ID. 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 |
Not relevant for product environments using the legacy fixed folder mode. A user-friendly name for the asset.
|
unique_display_name | Boolean |
Not relevant for product environments using the legacy fixed folder mode. If true, and you've passed a Default: |
asset_folder | String |
Not relevant for product environments using the legacy fixed folder mode. The folder where the asset is placed within the Cloudinary repository. Setting this value in an |
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:
|
clear_invalid | Boolean | (Relevant for cascading metadata, and assets with multiple metadata fields) When updating the value of a metadata field results in another metadata field’s value becoming invalid, that invalid value is cleared instead of resulting in an error. Default: false . |
face_coordinates | String | A list of coordinates of faces contained in an uploaded image. The specified coordinates are used for cropping or adding overlays to 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 (| ). For example: 10,20,150,130|213,345,82,61 . |
custom_coordinates | String | The coordinates of a region contained in an uploaded image that can be subsequently used for cropping or adding layers 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, as a comma-separated list. For example: 85,120,220,310 . Relevant for images only.
SDKs: Supports arrays. For example: [85, 120, 220, 310] .
|
regions | JSON | The coordinates of one or more named regions contained in an uploaded image that can be subsequently used for cropping using the region gravity mode. Each region is specified by a name (alphanumeric characters and hyphens permitted) and an array of at least two X,Y coordinate pairs, e.g., { "name1": [[1, 2], [3, 4]], "name2": [[5,6], [7,8], [9,10]] } . If two pairs are specified, these refer to the top left and bottom right coordinates of a rectangle. Otherwise, if more pairs are specified, they refer to the corners of a custom region.Relevant for images only. |
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 Use together with the |
detection | String | Invokes the relevant add-on to return a list of detected content. Set to:
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 | Generates a related file based on the uploaded file.
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 search. Default: false. Relevant for images only. |
background_removal | String | Automatically remove the background of an image using an add-on.
|
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:
|
Examples
Update tags and moderation status of an uploaded image:
Update details of an existing resource by asset ID
Update one or more attributes of a specified resource (asset) by its asset ID. This enables you to update details of an asset by its unique and immutable identifier, regardless of public ID, display name, asset folder, resource type or deliver type.
Note that you can also update many attributes of an existing asset using the explicit method, which is not rate-limited.
Syntax
POST /resources/:asset_id
Required parameters
Parameter | Type | Description |
---|---|---|
asset_id | String | The immutable, unique identifier of the asset. |
Optional parameters
Parameter | Type | Description |
---|---|---|
display_name | String |
Not relevant for product environments using the legacy fixed folder mode. A user-friendly name for the asset.
|
unique_display_name | Boolean |
Not relevant for product environments using the legacy fixed folder mode. If true, and you've passed a Default: |
asset_folder | String |
Not relevant for product environments using the legacy fixed folder mode. The folder where the asset is placed within the Cloudinary repository. Setting this value in an |
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:
|
clear_invalid | Boolean | (Relevant for cascading metadata, and assets with multiple metadata fields) When updating the value of a metadata field results in another metadata field’s value becoming invalid, that invalid value is cleared instead of resulting in an error. Default: false . |
face_coordinates | String | A list of coordinates of faces contained in an uploaded image. The specified coordinates are used for cropping or adding overlays to 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 (| ). For example: 10,20,150,130|213,345,82,61 . |
custom_coordinates | String | The coordinates of a region contained in an uploaded image that can be subsequently used for cropping or adding layers 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, as a comma-separated list. For example: 85,120,220,310 . Relevant for images only.
SDKs: Supports arrays. For example: [85, 120, 220, 310] .
|
regions | JSON | The coordinates of one or more named regions contained in an uploaded image that can be subsequently used for cropping using the region gravity mode. Each region is specified by a name (alphanumeric characters and hyphens permitted) and an array of at least two X,Y coordinate pairs, e.g., { "name1": [[1, 2], [3, 4]], "name2": [[5,6], [7,8], [9,10]] } . If two pairs are specified, these refer to the top left and bottom right coordinates of a rectangle. Otherwise, if more pairs are specified, they refer to the corners of a custom region.Relevant for images only. |
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 Use together with the |
detection | String | Invokes the relevant add-on to return a list of detected content. Set to:
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 | Generates a related file based on the uploaded file.
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 search. Default: false. Relevant for images only. |
background_removal | String | Automatically remove the background of an image using an add-on.
|
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:
|
Examples
Update tags and moderation status of an image:
Restore resources (by public ID)
Restores one or more resources (assets), identified by the public ID, 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):
Restore resources (by asset ID)
Restores one or more resources (assets) from backup by their asset IDs. This enables you to restore assets by their unique and immutable identifier, regardless of public ID, display name, asset folder, resource type or deliver type.
Syntax
POST /resources/restore
Required parameters
Parameter | Type | Description |
---|---|---|
asset_ids | String[] | The unique and immutable asset IDs of (deleted or existing) backed up assets to restore (array of up to 100 asset IDs). By default, the latest backed up version of the asset is restored. If the versions parameter is specified, the corresponding version of each asset ID is restored. |
Optional parameters
Parameter | Type | Description |
---|---|---|
versions | String[] | The version of each of the assets to restore. Specify the version_id for each asset ID. Use the resource method to list details of backed up versions of an asset. |
Examples
Restore deleted resources by asset_ids '2262b0b5eb88f1fd7724e29b0e57d730' and 'd23c0526e6feca2c343e40c2fce5231a':
Restore specific versions of deleted resources by asset_ids '2262b0b5eb88f1fd7724e29b0e57d730' and 'd23c0526e6feca2c343e40c2fce5231a':
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.
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.
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.
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 by public ID
Deletes resources (assets) uploaded to your product environment, identified by their public IDs.
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 | (Only when deleting by prefix or all) 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. You can include multiple transformations separated by a pipe character (| ). |
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 asset ID
Deletes resources (assets) uploaded to your product environment by their asset IDs. This enables you to delete assets by their unique and immutable identifier, regardless of public ID, display name, asset folder, resource type or deliver type.
Syntax
DELETE /resources
Required parameters
One of the following:
Parameter | Type | Description |
---|---|---|
asset_ids | String[] | Delete all assets with the specified asset IDs (array of up to 100 asset_ids). |
Optional parameters
Parameter | Type | Description |
---|---|---|
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 | (Only when deleting by prefix or all) 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. You can include multiple transformations separated by a pipe character (| ). |
Examples
Delete uploaded images by asset IDs:
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):
Delete backed up versions of a resource
Deletes backed up versions of an asset (resource) from your product environment.
Syntax
DELETE /resources/backup/:asset_id
Required parameters
Parameter | Type | Description |
---|---|---|
asset_id | String | The asset ID of the asset with backed up versions to delete. |
version_ids | String[] | An array of version IDs to delete for the specified asset ID. You can call the resource method (with versions = true ) to list details of backed up versions of an asset. |
Examples
Delete versions 383e22a57167445552a3cdc16f0a0c85 and 5552aa57e67445552a3cdc1110a0115 of the asset with ID 8267a869b62a93a59248f35d7f124c1f:
resources_last_access_reports
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.
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
pending
until it completes and then has a status of done
.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
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:
\
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:
\
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:
\
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
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
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. |
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:
\
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:
\
or "
, for example, \"text\"
or ""text""
.Sample response
Update transformation
Update a specific transformation.
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:
\
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.
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. |
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:
\
or "
, for example, \"text\"
or ""text""
.Sample response
triggers
Enables you to manage event triggers and notifications within your product environment. Each trigger
denotes a unique event type linked to its notification URL. Your product environment supports triggers up to a maximum determined by multiplying the number of unique event types by the limit of ten notification URLs.
Because a trigger
consists of a single triggering event paired with a single notification URL, whereas in the Console each notification URL is linked to all configured Notification Types (triggering events), programmatically creating a trigger reflects in the Console by either generating a new notification URL with a single Notification Type or appending a new Notification Type to an existing URL's list of notifications.
For more information, see Managing webhook notifications from the Console.
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. |
Get triggers
Lists all triggers.
Syntax
GET /triggers
Optional parameters
Parameter | Type | Description |
---|---|---|
event_type |
String | Filters and retrieves triggers for a specific event_type. |
Example
List all triggers associated with the "upload" event_type
:
Sample response
Create a trigger
Creates a new trigger. Your product environment supports triggers up to a maximum determined by multiplying the number of unique event types by the limit of ten notification URLs.
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
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) |
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 (not relevant if your product environment is using the legacy fixed folder mode). | - resources method of the Admin API - Console UI operation |
move_or_rename_asset_folder |
A folder is moved to a different location within the folder hierarchy or renamed (not relevant if your product environment is using the legacy fixed folder mode). | - 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 the legacy 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 (not relevant if your product environment is using the legacy fixed folder mode). | - 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 |
restore_asset_version |
A previous version of an asset is restored within the Media Library. | - 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 |
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.
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
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
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: |
use_asset_folder_as_public_id_prefix | Boolean |
Not relevant for product environments using the legacy fixed folder mode. Whether to automatically apply the path specified in theasset_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 Default: |
{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
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.