@cloudinary/environment-config-mcpv0.6.3

Cloudinary Environment Config MCP Server - manage named transformations, upload presets, streaming profiles, webhooks (triggers), and upload mappings through AI assistants (Claude Desktop, Cursor, Gemini, Windsurf, VS Code)

Documentation All MCP Servers Package Repository

Endpoints

EndpointMethodDescription
/mcp POST Streamable HTTP transportRecommended
/sse GET SSE transportDeprecated

Server URL

https://environment-config.mcp.cloudinary.com/mcp

Configuration

Add this to your MCP client configuration. OAuth is used by default when no headers are provided.

Minimal (OAuth)
{ "mcpServers": { "@cloudinary/environment-config-mcp": { "url": "https://environment-config.mcp.cloudinary.com/mcp" } } }
With API Key
{ "mcpServers": { "@cloudinary/environment-config-mcp": { "url": "https://environment-config.mcp.cloudinary.com/mcp", "headers": { "cloudinary-url": "cloudinary://api_key:api_secret@cloud_name" } } } }

Authentication

MethodDescription
OAuth 2.0 Default. The OAuth flow is initiated automatically when the client connects with no auth headers.
API Key Pass cloudinary-url header, or individual cloudinary-cloud-name, cloudinary-api-key, cloudinary-api-secret headers.

Configuration Headers

Optional headers to customize server behavior. Applied at session creation time.

HeaderDescription
cloudinary-region API region: api, api-eu, or api-ap
cloudinary-tools Comma-separated list of tools to enable (e.g. search-assets,list-images)

Response Headers

API response headers are collected into _meta.headers on each tool result. The debug preset is active by default.

HeaderDescription
cloudinary-collect-headers Control which response headers are returned. Accepts:
debug — rate-limit + request ID (default)
ratelimit — rate-limit headers only
all — every response header
Or a comma-separated list of exact names, prefix:<value>, regex:<pattern>, and preset names
cloudinary-embed-headers Set to true to also include collected headers in the response body as _headers, for clients that don't surface _meta
Tool result structure
{ "_meta": { "headers": { "x-featureratelimit-limit": "5000", "x-featureratelimit-remaining": "4998", "x-featureratelimit-reset": "Thu, 13 Feb 2026 00:00:00 GMT", "x-request-id": "bfeaccc60050594832508590a358a1a4" } }, "content": [{ "type": "text", "text": "{...}" }] }

Available Tools (24)

list-transformations get-transformation-details create-transformation update-transformation delete-transformation create-upload-preset list-upload-presets get-upload-preset-details update-upload-preset delete-upload-preset list-upload-mappings create-upload-mapping update-upload-mapping delete-upload-mapping list-triggers create-trigger update-trigger delete-trigger test-trigger create-streaming-profile list-streaming-profiles get-streaming-profile update-streaming-profile delete-streaming-profile
destructiveidempotentopenWorldreadOnly

Lists all transformation definitions in your account, including named transformations

Retrieves a list of all transformations, which can be filtered to show either only named or unnamed transformations.

ParameterTypeDescription
named ◉boolean

Whether to return only named (true) or unnamed (false) transformations. If this parameter isn't included, both named and unnamed transformations will be returned.

max_results #integer

The maximum number of results to return. Default is 10.

next_cursor Abcstring

The cursor for pagination. Use the next_cursor value from a previous response to get the next page of results.

destructiveidempotentopenWorldreadOnly

Retrieves details of a specific transformation

Retrieves details for a named or unnamed transformation.

ParameterTypeDescription
transformation required Abcstring

The transformation identifier. Can be either a named transformation (e.g., 'small_profile_thumbnail') or a transformation string (e.g., 'w_100,h_150,c_fill,g_auto').

destructiveidempotentopenWorldreadOnly

Creates a new named transformation by assigning a custom name to a set of transformation parameters

Creates a new named transformation with the given name and transformation string.

ParameterTypeDescription
transformation required Abcstring

The valid transformation name to create.

create_request required { }object

The named transformation definition.

allowed_for_strict ◉boolean

Whether to allow this named transformation when strict transformations are enabled. Strict transformations prevent transformations from being dynamically applied to media assets.

transformation required Abcstring

A valid transformation string.

destructiveidempotentopenWorldreadOnly

Updates the definition of an existing transformation

Updates a named or unnamed transformation.

ParameterTypeDescription
transformation required Abcstring

The transformation identifier. Can be either a named transformation (e.g., 'small_profile_thumbnail') or a transformation string (e.g., 'w_100,h_150,c_fill,g_auto').

update_request required { }object

The updated transformation definition.

allowed_for_strict ◉boolean

Whether to allow this named transformation when strict transformations are enabled. Strict transformations prevent transformations from being dynamically applied to media assets.

unsafe_update Abcstring

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.

destructiveidempotentopenWorldreadOnly

Deletes a named transformation from your account

Delete a named or unnamed transformation. Optionally invalidate derived resources generated using the named transformation.

ParameterTypeDescription
transformation required Abcstring

The transformation identifier. Can be either a named transformation (e.g., 'small_profile_thumbnail') or a transformation string (e.g., 'w_100,h_150,c_fill,g_auto').

invalidate ◉boolean

Invalidate derived resources generated using the deleted transformation from CDN.

destructiveidempotentopenWorldreadOnly

Creates a new upload preset with specified configuration settings

ParameterTypeDescription
request required { }object

The upload preset configuration.

access_control [ ]array

Restricts access to the asset by specifying one or more access types.
The asset is restricted unless at least one listed access type is valid.

access_mode Abcstring

Deprecated. Use access_control instead. Allows the asset to behave as if it's of the authenticated delivery type while still using the default 'upload' type in delivery URLs. The asset can later be made public by changing its access_mode via the Admin API, without having to update any delivery URLs.

accessibility_analysis ◉boolean

Whether to return accessibility analysis values for the image.

allowed_formats Abcstring

A comma-separated list of file formats that are allowed for uploading. Files of other types will be rejected. The formats can be any combination of image types, video formats or raw file extensions.
Note: You can also add the format parameter to convert other file types instead of rejecting them. In this case, only files that would normally be rejected are converted, any file format allowed for upload won't be converted.

asset_folder Abcstring

The asset folder to assign to the asset.

async ◉boolean

When set to true, returns the uploaded asset's public_id immediately in the response, before the upload is completed (asynchronously). Default: false.

auto_chaptering ◉boolean

Whether to trigger automatic generation of video chapters. Chapters will be generated and saved as a .vtt file with -chapters appended to the public ID of the video. You can enable chapters as part of the Cloudinary Video Player. Relevant for videos only.

auto_tagging #number

Automatically assigns tags to an asset according to detected objects or categories with a confidence score higher than the specified value.
Use together with the detection parameter for:
Use together with the categorization parameter for:

  • Cloudinary AI Content Analysis
  • Amazon Rekognition Celebrity Detection
  • Google Automatic Video Tagging
  • Google Auto Tagging
  • Imagga Auto Tagging
  • Amazon Rekognition Auto Tagging
auto_transcription ◉boolean{ }object

background_removal Abcstring

Automatically remove the background of an image using an add-on.
Optionally append a template suffix (e.g., cloudinary_ai:fine_edges).
Relevant for images only.

  • Set to cloudinary_ai to use the deep-learning based Cloudinary AI Background Removal add-on.
  • Note: this feature has been superseded by background removal on the fly.
  • Set to pixelz to use the human-powered Pixelz Remove-The-Background Editing add-on service.
backup ◉boolean

Whether to backup the uploaded asset. When set to true, backs up uploaded assets to a secondary storage bucket.

callback Abcstring

A URL to redirect to after the upload/explicit is completed instead of returning the upload response.
Signed upload result parameters are added to the callback URL. This parameter is ignored for XHR (Ajax XMLHttpRequest) or JavaScript Fetch API upload requests.
Note: This parameter is relevant for direct uploads from a form in the browser. It is automatically set if you perform direct upload from the browser using Cloudinary's SDKs and the jQuery plugin.

categorization Abcstring

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.
Optionally append a language code suffix (e.g., google_tagging:fr).

cinemagraph_analysis ◉boolean

Whether to return a cinemagraph analysis value for the media asset between 0 and 1, where 0 means the asset is not a cinemagraph and 1 means the asset is a cinemagraph. Relevant for animated images and video only. A static image will return 0.

clear_invalid ◉boolean

Whether to clear metadata field values that have become invalid due to a change in metadata rules. If false, the API returns an error if any existing metadata value is no longer valid. Default: false.

colors ◉boolean

Whether to retrieve predominant colors & color histogram of the uploaded image. Note: If all returned colors are opaque, then 6-digit RGB hex values are returned. If one or more colors contain an alpha channel, then 8-digit RGBA hex quadruplet values are returned.

context Abcstring

A pipe-separated list of key-value pairs of general textual context metadata to attach to the asset (e.g., "alt=My image|caption=Nice photo"). The =, ", and | characters can be escaped with a prepending backslash (\).

custom_coordinates Abcstring

Custom coordinates as comma-separated values, with multiple coordinates separated by pipes.

detection Abcstring

Invokes the relevant add-on to return a list of detected content.
Set to:

  • <content-aware model>_[<version>] (e.g. coco_v2) to return a list of detected content using the Cloudinary AI Content Analysis add-on. Can be used together with the auto_tagging parameter to apply tags automatically.
  • captioning to analyze an image and suggest a caption based on the image's contents.
  • iqa to analyze the quality of an image.
  • watermark-detection to detect watermarks in an image.
  • adv_face to return a list of facial attributes using the Advanced Facial Attribute Detection add-on.
  • aws_rek_face to return a list of detected celebrities and facial attributes using the Amazon Rekognition Celebrity Detection add-on. Can be used together with the auto_tagging parameter to apply tags automatically.
disallow_public_id ◉boolean

When using unsigned upload with an upload preset, this parameter prevents specifying a public ID. Relevant only for unsigned upload presets.

discard_original_filename ◉boolean

Whether to discard the name of the original uploaded file. Relevant when delivering assets as attachments (setting the flag disposition:attachment in delivery URLs).

display_name Abcstring

A display name for the asset.

eager Abcstring

A list of transformations to eagerly generate for the asset. Accepts either a single transformation or a pipe-separated list of transformations.

eager_async ◉boolean

Whether to generate the eager transformations asynchronously in the background after the upload request is completed rather than before the upload is completed.

eager_notification_url Abcstring

A URL to notify when eager transformations are completed.

eval Abcstring

Allows you to modify upload parameters by specifying custom logic with JavaScript. This can be useful for conditionally adding tags, contextual metadata, structured metadata or eager transformations depending on specific criteria of the uploaded file.

face_coordinates Abcstring

Face coordinates as comma-separated values, with multiple faces separated by pipes.

faces ◉boolean

Whether to detect faces in the asset.

filename_override Abcstring

Overrides the originally uploaded asset's file name in downloads that use flags like fl_attachment or fl_force_original.

folder Abcstring

Folder name where the uploaded asset will be stored. This parameter applies when using the Admin API, or when specifying the upload preset for unsigned uploading with the Upload API.

format Abcstring

An optional format to convert the uploaded asset to before saving in the cloud.

headers Abcstring

An HTTP header or a list of headers lines for adding as response HTTP headers when delivering the asset to your users. Supported headers: Link, Authorization, X-Robots-Tag.

invalidate ◉boolean

Whether to invalidate CDN cache copies of a previously uploaded asset that shares the same public ID. Default: false.

media_metadata ◉boolean

Whether to return IPTC, XMP, and detailed Exif metadata of the uploaded asset in the response.
Supported for images, video, and audio.

  • Returned metadata for images includes: PixelsPerUnitX, PixelsPerUnitY, PixelUnits, Colorspace, and DPI.
  • Returned metadata for audio and video includes: audio_codec, audio_bit_rate, audio_frequency, channels, channel_layout.
  • Additional metadata for video includes: pix_format, codec, level, profile, video_bit_rate, dar.
metadata Abcstring{ }object

A pipe-separated list or a map of custom metadata fields (by external_id) and the values to assign to each of them. The = " and | characters can be supported as values when escaped with a prepended backslash (\). For a multi-select field, you can set a maximum of 3000 different metadata values on an asset.

moderation Abcstring

For all asset types, set to:

  • manual to add the uploaded asset to a list of pending assets that can be moderated using the Admin API or the Cloudinary Console.
  • perception_point to automatically moderate the uploaded asset using the Perception Point Malware Detection add-on.

For images only, set to:

  • webpurify to automatically moderate the uploaded image using the WebPurify Image Moderation add-on.
  • aws_rek to automatically moderate the uploaded image using the Amazon Rekognition AI Moderation add-on.
  • duplicate:<threshold> to detect if the same or a similar image already exists using the Cloudinary Duplicate Image Detection add-on. Set threshold to a float greater than 0 and less than or equal to 1.0 to specify how similar an image needs to be in order to be considered a duplicate. Set threshold to 0 to add an image to the index of images that are searched when duplicate detection is invoked for another image.

For videos only, set to:

  • aws_rek_video to automatically moderate the uploaded video using the Amazon Rekognition Video Moderation add-on.
  • google_video_moderation automatically moderate the uploaded video using the Google AI Video Moderation add-on.

To request multiple moderations in a single API call:

  • Send the desired list of moderations as a pipe-separated string with manual moderation, if relevant, being last.

Note: Rejected assets are automatically invalidated on the CDN within approximately ten minutes.

name Abcstring

The name of the upload preset. If not provided on create, a random name is generated.

notification_url Abcstring

A URL to notify when the asset is ready.

ocr Abcstring

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.
Optionally append options (e.g., adv_ocr:document).

on_success Abcstring

Allows you to update an asset by specifying custom logic with JavaScript that is executed after the upload to Cloudinary is completed successfully. This can be useful for conditionally adding tags, contextual metadata, and structured metadata, depending on the results of using the detection parameter on upload.

overwrite ◉boolean

Whether to overwrite existing assets with the same public ID. When set to false, return immediately if an asset with the same public ID already exists. Default: true (when using unsigned upload, the default is false and cannot be changed to true).

parameter_whitelist [ ]arrayAbcstring

The parameters that are allowed to be used in an upload request utilizing this preset. If not specified or empty array, all parameters are allowed. If "none", no parameters are allowed.

phash ◉boolean

Whether to return the perceptual hash (pHash) on the uploaded image for image similarity detection.

proxy Abcstring

A proxy to use for fetching remote URLs. The format should be http://hostname:port.

public_id Abcstring

The identifier that is used for accessing the uploaded asset. If not specified, a unique ID is generated automatically.

public_id_prefix Abcstring

A string or path that's automatically prepended to the public_id with a forward slash. The value can contain the same characters as the public_id including additional forward slashes. This prefix can be useful to provide context and improve the SEO of an asset's filename in the delivery URL, but the value does not impact the location where the asset is stored.

quality_analysis ◉boolean

Whether to return a quality analysis value for the image between 0 and 1, where 0 means the image is blurry and out of focus and 1 means the image is sharp and in focus. Relevant for images only.

raw_convert Abcstring

Generates a related file based on the uploaded file.

  • Set to aspose to automatically create a PDF or other image format from a raw Office document using the Aspose Document Conversion add-on. (Asynchronous)
  • Set to google_speech to instruct the Google AI Video Transcription add-on to generate an automatic transcript raw file from an uploaded video. (Asynchronous)
  • Set to extract_text to extract all the text from a PDF file and store it in a raw JSON file with a public ID in the format: [pdf_public_id].extract_text.json. The full URL of the generated JSON file is included in the API response. Unlike the above raw_convert options, this option doesn't require registering for an add-on.(Synchronous)
  • Set to azure_video_indexer to generate AI-powered video insights from Microsoft Azure. (Asynchronous)
regions Abcstring{ }object

Named region coordinate groups for cropping with region gravity.
Can be a JSON-encoded string or an object. Each region name may contain
only letters, numbers, or hyphens, and must have at least two coordinate pairs.

responsive_breakpoints [ ]array{ }object

Settings to automatically generate breakpoints for responsive images.

return_delete_token ◉boolean

Whether to return a deletion token in the upload response. The token can be used to delete the uploaded asset within approximately 10 minutes using an unauthenticated API call.

tags Abcstring[ ]array

A comma-separated list of tag names, or an array of tag names.

transformation Abcstring

An incoming transformation to run on the uploaded asset before its storage. In contrast to eager, this parameter is applied before the file is stored.

type Abcstring

The delivery type that defines if and how the uploaded asset is available for public delivery. By default, all uploaded assets are public (upload).

unique_display_name ◉boolean

Whether the display name should be unique.

unique_filename ◉boolean

When set to false and used together with use_filename, if an asset with the same file name already exists, no random characters are appended to the file name. Instead, the asset is overwritten. Default: true (random characters are added to the file name if needed).

unsigned ◉boolean

Whether the upload preset allows unsigned uploads.

upload_preset Abcstring

Name of an upload preset that you defined for your Cloudinary product environment. An upload preset consists of upload parameters centrally managed using the Admin API or from the Upload Presets page of the Console Settings.

use_asset_folder_as_public_id_prefix ◉boolean

Whether to add the asset_folder value as a prefix to the public_id value (prepended with a forward slash). This ensures that the public ID path will always match the initial asset folder, and can help to retain the behavior that previously existed in fixed folder mode. However, keep in mind that even when this option is used during upload, an asset with a certain public ID path can later be moved to a completely different asset folder hierarchy without impacting the public ID. This option only ensures path matching for the initial upload. Relevant only when public_id_prefix (or folder) has not been separately specified.

use_filename ◉boolean

Whether to use the original file name of the uploaded asset if available for the public ID. The file name is normalized and random characters are appended to ensure uniqueness if the file name already exists. Default: false.

use_filename_as_display_name ◉boolean

Whether to automatically assign the original filename of the uploaded asset as the asset's display name. Relevant only if the display_name parameter isn't set.

visual_search ◉boolean

Whether to index the image for use with visual searches. Relevant for images only.

destructiveidempotentopenWorldreadOnly

Lists all upload presets configured in the account

ParameterTypeDescription
order_by Abcstring

The field to sort presets by.

direction Abcstring

The sort direction for the results. Default is "desc".

max_results #integer

The maximum number of results to return. Default is 10.

next_cursor Abcstring

The cursor for pagination. Use the next_cursor value from a previous response to get the next page of results.

destructiveidempotentopenWorldreadOnly

Retrieves details of a single upload preset

ParameterTypeDescription
name required Abcstring

The name of the upload preset.

destructiveidempotentopenWorldreadOnly

Updates an existing upload preset's configuration settings

ParameterTypeDescription
name required Abcstring

The name of the upload preset.

upload_preset_input required { }object

The updated upload preset configuration.

access_control [ ]array

Restricts access to the asset by specifying one or more access types.
The asset is restricted unless at least one listed access type is valid.

access_mode Abcstring

Deprecated. Use access_control instead. Allows the asset to behave as if it's of the authenticated delivery type while still using the default 'upload' type in delivery URLs. The asset can later be made public by changing its access_mode via the Admin API, without having to update any delivery URLs.

accessibility_analysis ◉boolean

Whether to return accessibility analysis values for the image.

allowed_formats Abcstring

A comma-separated list of file formats that are allowed for uploading. Files of other types will be rejected. The formats can be any combination of image types, video formats or raw file extensions.
Note: You can also add the format parameter to convert other file types instead of rejecting them. In this case, only files that would normally be rejected are converted, any file format allowed for upload won't be converted.

asset_folder Abcstring

The asset folder to assign to the asset.

async ◉boolean

When set to true, returns the uploaded asset's public_id immediately in the response, before the upload is completed (asynchronously). Default: false.

auto_chaptering ◉boolean

Whether to trigger automatic generation of video chapters. Chapters will be generated and saved as a .vtt file with -chapters appended to the public ID of the video. You can enable chapters as part of the Cloudinary Video Player. Relevant for videos only.

auto_tagging #number

Automatically assigns tags to an asset according to detected objects or categories with a confidence score higher than the specified value.
Use together with the detection parameter for:
Use together with the categorization parameter for:

  • Cloudinary AI Content Analysis
  • Amazon Rekognition Celebrity Detection
  • Google Automatic Video Tagging
  • Google Auto Tagging
  • Imagga Auto Tagging
  • Amazon Rekognition Auto Tagging
auto_transcription ◉boolean{ }object

background_removal Abcstring

Automatically remove the background of an image using an add-on.
Optionally append a template suffix (e.g., cloudinary_ai:fine_edges).
Relevant for images only.

  • Set to cloudinary_ai to use the deep-learning based Cloudinary AI Background Removal add-on.
  • Note: this feature has been superseded by background removal on the fly.
  • Set to pixelz to use the human-powered Pixelz Remove-The-Background Editing add-on service.
backup ◉boolean

Whether to backup the uploaded asset. When set to true, backs up uploaded assets to a secondary storage bucket.

callback Abcstring

A URL to redirect to after the upload/explicit is completed instead of returning the upload response.
Signed upload result parameters are added to the callback URL. This parameter is ignored for XHR (Ajax XMLHttpRequest) or JavaScript Fetch API upload requests.
Note: This parameter is relevant for direct uploads from a form in the browser. It is automatically set if you perform direct upload from the browser using Cloudinary's SDKs and the jQuery plugin.

categorization Abcstring

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.
Optionally append a language code suffix (e.g., google_tagging:fr).

cinemagraph_analysis ◉boolean

Whether to return a cinemagraph analysis value for the media asset between 0 and 1, where 0 means the asset is not a cinemagraph and 1 means the asset is a cinemagraph. Relevant for animated images and video only. A static image will return 0.

clear_invalid ◉boolean

Whether to clear metadata field values that have become invalid due to a change in metadata rules. If false, the API returns an error if any existing metadata value is no longer valid. Default: false.

colors ◉boolean

Whether to retrieve predominant colors & color histogram of the uploaded image. Note: If all returned colors are opaque, then 6-digit RGB hex values are returned. If one or more colors contain an alpha channel, then 8-digit RGBA hex quadruplet values are returned.

context Abcstring

A pipe-separated list of key-value pairs of general textual context metadata to attach to the asset (e.g., "alt=My image|caption=Nice photo"). The =, ", and | characters can be escaped with a prepending backslash (\).

custom_coordinates Abcstring

Custom coordinates as comma-separated values, with multiple coordinates separated by pipes.

detection Abcstring

Invokes the relevant add-on to return a list of detected content.
Set to:

  • <content-aware model>_[<version>] (e.g. coco_v2) to return a list of detected content using the Cloudinary AI Content Analysis add-on. Can be used together with the auto_tagging parameter to apply tags automatically.
  • captioning to analyze an image and suggest a caption based on the image's contents.
  • iqa to analyze the quality of an image.
  • watermark-detection to detect watermarks in an image.
  • adv_face to return a list of facial attributes using the Advanced Facial Attribute Detection add-on.
  • aws_rek_face to return a list of detected celebrities and facial attributes using the Amazon Rekognition Celebrity Detection add-on. Can be used together with the auto_tagging parameter to apply tags automatically.
disallow_public_id ◉boolean

When using unsigned upload with an upload preset, this parameter prevents specifying a public ID. Relevant only for unsigned upload presets.

discard_original_filename ◉boolean

Whether to discard the name of the original uploaded file. Relevant when delivering assets as attachments (setting the flag disposition:attachment in delivery URLs).

display_name Abcstring

A display name for the asset.

eager Abcstring

A list of transformations to eagerly generate for the asset. Accepts either a single transformation or a pipe-separated list of transformations.

eager_async ◉boolean

Whether to generate the eager transformations asynchronously in the background after the upload request is completed rather than before the upload is completed.

eager_notification_url Abcstring

A URL to notify when eager transformations are completed.

eval Abcstring

Allows you to modify upload parameters by specifying custom logic with JavaScript. This can be useful for conditionally adding tags, contextual metadata, structured metadata or eager transformations depending on specific criteria of the uploaded file.

face_coordinates Abcstring

Face coordinates as comma-separated values, with multiple faces separated by pipes.

faces ◉boolean

Whether to detect faces in the asset.

filename_override Abcstring

Overrides the originally uploaded asset's file name in downloads that use flags like fl_attachment or fl_force_original.

folder Abcstring

Folder name where the uploaded asset will be stored. This parameter applies when using the Admin API, or when specifying the upload preset for unsigned uploading with the Upload API.

format Abcstring

An optional format to convert the uploaded asset to before saving in the cloud.

headers Abcstring

An HTTP header or a list of headers lines for adding as response HTTP headers when delivering the asset to your users. Supported headers: Link, Authorization, X-Robots-Tag.

invalidate ◉boolean

Whether to invalidate CDN cache copies of a previously uploaded asset that shares the same public ID. Default: false.

media_metadata ◉boolean

Whether to return IPTC, XMP, and detailed Exif metadata of the uploaded asset in the response.
Supported for images, video, and audio.

  • Returned metadata for images includes: PixelsPerUnitX, PixelsPerUnitY, PixelUnits, Colorspace, and DPI.
  • Returned metadata for audio and video includes: audio_codec, audio_bit_rate, audio_frequency, channels, channel_layout.
  • Additional metadata for video includes: pix_format, codec, level, profile, video_bit_rate, dar.
metadata Abcstring{ }object

A pipe-separated list or a map of custom metadata fields (by external_id) and the values to assign to each of them. The = " and | characters can be supported as values when escaped with a prepended backslash (\). For a multi-select field, you can set a maximum of 3000 different metadata values on an asset.

moderation Abcstring

For all asset types, set to:

  • manual to add the uploaded asset to a list of pending assets that can be moderated using the Admin API or the Cloudinary Console.
  • perception_point to automatically moderate the uploaded asset using the Perception Point Malware Detection add-on.

For images only, set to:

  • webpurify to automatically moderate the uploaded image using the WebPurify Image Moderation add-on.
  • aws_rek to automatically moderate the uploaded image using the Amazon Rekognition AI Moderation add-on.
  • duplicate:<threshold> to detect if the same or a similar image already exists using the Cloudinary Duplicate Image Detection add-on. Set threshold to a float greater than 0 and less than or equal to 1.0 to specify how similar an image needs to be in order to be considered a duplicate. Set threshold to 0 to add an image to the index of images that are searched when duplicate detection is invoked for another image.

For videos only, set to:

  • aws_rek_video to automatically moderate the uploaded video using the Amazon Rekognition Video Moderation add-on.
  • google_video_moderation automatically moderate the uploaded video using the Google AI Video Moderation add-on.

To request multiple moderations in a single API call:

  • Send the desired list of moderations as a pipe-separated string with manual moderation, if relevant, being last.

Note: Rejected assets are automatically invalidated on the CDN within approximately ten minutes.

name Abcstring

The name of the upload preset. If not provided on create, a random name is generated.

notification_url Abcstring

A URL to notify when the asset is ready.

ocr Abcstring

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.
Optionally append options (e.g., adv_ocr:document).

on_success Abcstring

Allows you to update an asset by specifying custom logic with JavaScript that is executed after the upload to Cloudinary is completed successfully. This can be useful for conditionally adding tags, contextual metadata, and structured metadata, depending on the results of using the detection parameter on upload.

overwrite ◉boolean

Whether to overwrite existing assets with the same public ID. When set to false, return immediately if an asset with the same public ID already exists. Default: true (when using unsigned upload, the default is false and cannot be changed to true).

parameter_whitelist [ ]arrayAbcstring

The parameters that are allowed to be used in an upload request utilizing this preset. If not specified or empty array, all parameters are allowed. If "none", no parameters are allowed.

phash ◉boolean

Whether to return the perceptual hash (pHash) on the uploaded image for image similarity detection.

proxy Abcstring

A proxy to use for fetching remote URLs. The format should be http://hostname:port.

public_id Abcstring

The identifier that is used for accessing the uploaded asset. If not specified, a unique ID is generated automatically.

public_id_prefix Abcstring

A string or path that's automatically prepended to the public_id with a forward slash. The value can contain the same characters as the public_id including additional forward slashes. This prefix can be useful to provide context and improve the SEO of an asset's filename in the delivery URL, but the value does not impact the location where the asset is stored.

quality_analysis ◉boolean

Whether to return a quality analysis value for the image between 0 and 1, where 0 means the image is blurry and out of focus and 1 means the image is sharp and in focus. Relevant for images only.

raw_convert Abcstring

Generates a related file based on the uploaded file.

  • Set to aspose to automatically create a PDF or other image format from a raw Office document using the Aspose Document Conversion add-on. (Asynchronous)
  • Set to google_speech to instruct the Google AI Video Transcription add-on to generate an automatic transcript raw file from an uploaded video. (Asynchronous)
  • Set to extract_text to extract all the text from a PDF file and store it in a raw JSON file with a public ID in the format: [pdf_public_id].extract_text.json. The full URL of the generated JSON file is included in the API response. Unlike the above raw_convert options, this option doesn't require registering for an add-on.(Synchronous)
  • Set to azure_video_indexer to generate AI-powered video insights from Microsoft Azure. (Asynchronous)
regions Abcstring{ }object

Named region coordinate groups for cropping with region gravity.
Can be a JSON-encoded string or an object. Each region name may contain
only letters, numbers, or hyphens, and must have at least two coordinate pairs.

responsive_breakpoints [ ]array{ }object

Settings to automatically generate breakpoints for responsive images.

return_delete_token ◉boolean

Whether to return a deletion token in the upload response. The token can be used to delete the uploaded asset within approximately 10 minutes using an unauthenticated API call.

tags Abcstring[ ]array

A comma-separated list of tag names, or an array of tag names.

transformation Abcstring

An incoming transformation to run on the uploaded asset before its storage. In contrast to eager, this parameter is applied before the file is stored.

type Abcstring

The delivery type that defines if and how the uploaded asset is available for public delivery. By default, all uploaded assets are public (upload).

unique_display_name ◉boolean

Whether the display name should be unique.

unique_filename ◉boolean

When set to false and used together with use_filename, if an asset with the same file name already exists, no random characters are appended to the file name. Instead, the asset is overwritten. Default: true (random characters are added to the file name if needed).

unsigned ◉boolean

Whether the upload preset allows unsigned uploads.

upload_preset Abcstring

Name of an upload preset that you defined for your Cloudinary product environment. An upload preset consists of upload parameters centrally managed using the Admin API or from the Upload Presets page of the Console Settings.

use_asset_folder_as_public_id_prefix ◉boolean

Whether to add the asset_folder value as a prefix to the public_id value (prepended with a forward slash). This ensures that the public ID path will always match the initial asset folder, and can help to retain the behavior that previously existed in fixed folder mode. However, keep in mind that even when this option is used during upload, an asset with a certain public ID path can later be moved to a completely different asset folder hierarchy without impacting the public ID. This option only ensures path matching for the initial upload. Relevant only when public_id_prefix (or folder) has not been separately specified.

use_filename ◉boolean

Whether to use the original file name of the uploaded asset if available for the public ID. The file name is normalized and random characters are appended to ensure uniqueness if the file name already exists. Default: false.

use_filename_as_display_name ◉boolean

Whether to automatically assign the original filename of the uploaded asset as the asset's display name. Relevant only if the display_name parameter isn't set.

visual_search ◉boolean

Whether to index the image for use with visual searches. Relevant for images only.

destructiveidempotentopenWorldreadOnly

Deletes an upload preset from the account

ParameterTypeDescription
name required Abcstring

The name of the upload preset.

destructiveidempotentopenWorldreadOnly

Retrieves a list of all upload mapping rules configured in your Cloudinary product environment

Returns a list of all upload mappings defined for your account.
Upload mappings allow you to map an upload preset to a specific folder and URL template.

ParameterTypeDescription
folder Abcstring

Get details of a specific mapping by folder name

next_cursor Abcstring

The cursor for pagination. Use the next_cursor value from a previous response to get the next page of results.

max_results #integer

The maximum number of results to return. Default is 10.

destructiveidempotentopenWorldreadOnly

Creates a new upload mapping

Creates a new upload mapping for the specified folder

ParameterTypeDescription
request required { }object

The upload mapping folder and URL template.

folder required Abcstring

The folder name for the mapping.

template required Abcstring

The template URL.

destructiveidempotentopenWorldreadOnly

Updates an existing upload mapping by changing its remote URL template for a given folder

Updates the URL template for an existing folder mapping

ParameterTypeDescription
request required { }object

The updated upload mapping folder and URL template.

folder required Abcstring

The folder name for the mapping.

template required Abcstring

The template URL.

destructiveidempotentopenWorldreadOnly

Deletes a folder upload mapping

Permanently deletes the upload mapping for the specified folder

ParameterTypeDescription
folder required Abcstring

The folder name of the mapping to delete

destructiveidempotentopenWorldreadOnly

Lists all webhook notification triggers configured for your product environment

Retrieves a list of all event triggers and notifications within your product environment.

ParameterTypeDescription
event_type Abcstring

The type of event that will trigger the notification response.

destructiveidempotentopenWorldreadOnly

Creates a new notification trigger (webhook) by specifying an event type and a destination

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 30 notification URLs.

ParameterTypeDescription
request required { }object

The webhook notification trigger to create.

event_type required Abcstring

The type of notification event.

uri required Abcstring

The URL that will receive the notification response.

destructiveidempotentopenWorldreadOnly

Updates the callback URL of an existing webhook trigger in your Cloudinary account

Updates a notification URL for a trigger.

ParameterTypeDescription
id required Abcstring

The ID of the trigger.

update_trigger_request required { }object

The updated trigger configuration.

new_uri required Abcstring

The updated URL that will receive the notification response.

destructiveidempotentopenWorldreadOnly

Deletes a notification trigger

Deletes a trigger.

ParameterTypeDescription
id required Abcstring

The ID of the trigger.

destructiveidempotentopenWorldreadOnly

Tests an existing trigger's filter against sample data

Evaluates an existing trigger's filter against provided sample data.
Use this endpoint to verify that a trigger's filter will match expected events.

ParameterTypeDescription
id required Abcstring

The ID of the trigger to test.

test_trigger_request { }object

The test data for the trigger.

sample_data { }object

Sample notification data to evaluate the filter against.

destructiveidempotentopenWorldreadOnly

Creates a new adaptive streaming profile in your Cloudinary account

ParameterTypeDescription
request required { }object

The streaming profile configuration.

display_name Abcstringnull

The display name of the streaming profile

name required Abcstring

The name of the streaming profile

representations required Abcstring

A JSON string containing the list of representations with transformation parameters as strings

destructiveidempotentopenWorldreadOnly

Lists all adaptive streaming profiles (both built-in and custom) defined in your Cloudinary account

ParameterTypeDescription
request { }object

destructiveidempotentopenWorldreadOnly

Retrieves the details of a single adaptive streaming profile by its name

ParameterTypeDescription
name required Abcstring

The name of the streaming profile.

destructiveidempotentopenWorldreadOnly

Modifies an existing adaptive streaming profile's configuration

ParameterTypeDescription
name required Abcstring

The name of the streaming profile.

streaming_profile_update required { }object

The updated streaming profile configuration.

display_name Abcstringnull

The display name of the streaming profile

representations required Abcstring

A JSON string containing the list of representations with transformation parameters as strings

destructiveidempotentopenWorldreadOnly

Delete custom streaming profile or revert built-in profile to the original settings

ParameterTypeDescription
name required Abcstring

The name of the streaming profile.