Programmable Media
Menu

Folder modes

Last updated: May-29-2024

Important
This page describes the ways that dynamic folder mode differs from the legacy fixed folder mode. This page is NOT RELEVANT for new Cloudinary customers that signed up after June 4th, 2024. Since that date, all new Cloudinary accounts are created using dynamic folder mode.

All Cloudinary product environments are set up to work with either dynamic folders or fixed folders. While the majority of supported Cloudinary features are identical for both modes, each of these modes also has a variety of behaviors, supported methods and parameters, response keys, webhook notifications, upload preset settings, and more:

  • In dynamic folder mode, assets are completely decoupled from the folders they are located in. This means that moving assets between asset folders, renaming folders, or even moving entire folders and their assets to a new path, does NOT affect the asset's public ID value or delivery URL path. Dynamic folder mode also provides a display name, which, like asset folders, can be freely modified without affecting the public ID and delivery URL. Dynamic folders provide Cloudinary users the flexibility to organize and manage media assets with high performance and without risk of breaking URLs in production.
  • In fixed folder mode, the folder and asset name are a direct reflection of the asset's public ID full path, and thus determine the delivery URL path and file name. In fixed folder mode, moving an asset to another folder or changing the asset name shown in the Cloudinary Console UI (via the Programmable Media Media Explorer or the Assets Media Library), also modifies the asset's URL, and if not done carefully, risks breaking production content.
    Note
    In fixed folder mode, renaming folders (which would in effect change the public ID of every asset under that folder and of any sub-folders), is not supported.

Important
  • To migrate one or more product environments to dynamic folders mode or to send questions and feedback related to dynamic folders, contact Cloudinary support.
  • Once a product environment is migrated to dynamic folders mode, you can't revert it to fixed folders mode.
  • It's recommended that you test every element of your Cloudinary implementation on a non-production product environment before applying this mode to a production product environment.
  • To find out how folder modes impact Assets, see Folder modes in the Assets admin guide.

On this page:

Checking your product environment folder mode

You can check which folder mode your product environment is using as follows:

  • Console: At the top of the Console UI Dashboard preferences
  • API: Use the config method of the Admin API

Asset identifiers and folder location

The following table summarizes the identifiers and folder locations available for assets in fixed and dynamic folder modes:

Identifier or Property Description Dyamic Folders Fixed Folders
public_id
Unique *
Editable		 Identifies the asset in a Cloudinary delivery URL.

Can include any language character (including non-English letters) as well as characters such as dots (.) dashes (-), forward slashes (/).
Can't include spaces or any of these characters: ? & # \ % < > + '.

Editable in the Console UI or programmatically, but changing it can break production code.

* Must be unique within its product environment and asset type. It's possible, though not recommended, to use the same ID for an image and a video in the same environment.

 Displayed with less prominence in the Console UI to avoid inadvertent edits that could break links to assets in production.

It may contain slashes, but they don't reflect the folder path.

 Acts as the primary identifier in the Console UI, making it more prone to modifications that could potentially break links to assets in production.
display_name
Not Unique
Editable		 A descriptive or user-friendly name for the asset unrelated to the delivery URL path. It's the main name shown for the asset in the Console UI, collections and media portals.

Can be retrieved or set programmatically.

Can include spaces and special characters, but not slashes (/).

It's possible, though not recommended, for the same display name to be used for different assets, even in the same asset folder.

 Supported Not supported
asset_id
Unique
Not Editable		 An automatically generated immutable asset identifier that is fully unique across all product environments and all Cloudinary accounts. Every asset saved to Cloudinary is assigned a unique asset identifier that enables you to reliably reference the asset programmatically, even if other identifier values change. Supported Supported
Folder Location The asset's location within the folder hierarchy as shown in the Console UI. The asset_folder location is not reflected in the public ID, even though the public ID may contain slashes.

Moving assets doesn't affect the asset's public ID or delivery URL, so it doesn't risk breaking links to assets in production. However, discrepancies may occur as the public ID path doesn't update to match the new folder location.

Renaming and moving asset folders is also safe and supported.

 The folder defines both the full path of the folder where the uploaded asset will be placed and also a path value that's prepended to the public ID value with a forward slash.

The folder parameter should not be used in dynamic folder mode. It is officially supported for backward compatibility. See The 'folder' parameter below for more details.

The 'folder' parameter

The folder parameter of the upload and upload_presets methods is a single parameter that sets both the public ID path and the folder placement of the asset.

While this parameter continues to be supported for backward compatibility for accounts that have migrated from fixed folder mode, it should not be added to new code in dynamic folder product environments.

In dynamic folder mode, if necessary for your use case, you can instead set asset_folder and public_id_prefix to the same value. See below for more details on public_id_prefix.

Public IDs with slashes

When passing a public_id value that includes slashes (for example, animals/cats/tiger), the entire passed value is the public_id.

  • In fixed folder mode, the passed path also becomes the asset's folder path, and if the folders don't already exist, they are automatically created.

  • In dynamic folder mode, the path of a public ID can be useful for SEO purposes, but it has no impact on where the asset is placed. In dynamic folder mode, if you want to organize the asset into folders, make sure to also pass an asset_folder value. Otherwise, the asset will be located in the root folder.

    Tip
    In dynamic folder mode, if you want your public ID to include slashes, you can either pass the full path as a single string in the public_id parameter, or you can separately pass a public_id_prefix value with the path to use. The public_id_prefix value will be prefixed to the value specified for the public_id (or the public_id value generated based on your upload preset preferences).

    If you want the asset to be displayed in a folder that matches the public_id path, then also include an asset_folder parameter in your upload call with the same path. Alternatively, pass the public_id value without a path, and instead, specify the path in the asset_folder parameter, while also using the use_asset_folder_as_public_id_prefix: true option in your upload call or upload preset to ensure the two paths match.

    However, keep in mind that this only synchronizes between the public_id path and the initial asset_folder path. If a user later moves the asset to another asset folder, the public ID path won't change to reflect the asset's new location. This avoids changing the public ID and breaking delivery URLs in production.

    Additionally, when your product environment uses dynamic folder mode, your organization may find it useful to implement an asset folder structure that's completely different to your public ID paths. For example, your public ID paths might reflect names and categories of products, while your folder structure might reflect internal company groups or folders relating to steps in the production workflow, since assets can freely move between folders without affecting the delivery URLs.

Default upload naming

In both modes, if you don't manually specify a public ID, the public IDs are generated as random values. If you want descriptive public IDs for SEO purposes, then you need to define the public IDs.

In dynamic folder mode, if the display_name is defined neither explicitly nor via the use_filename_as_display_name option, the initial display name will be the same as the public ID's value (or the last segment of the public ID, if the public ID includes slashes (/) ). If an upload (or upload preset) doesn't define an asset_folder parameter (or folder parameter) the asset will be uploaded to the root folder, even if the public ID includes a path with slashes.

Upload API

Product environments with dynamic folders enabled offer additional parameters.

upload method

Most parameters of the upload method are equally supported in both folder modes. The following optional parameters are available only in dynamic folder mode when using the Upload API method:

Parameter Type Description
asset_folder String The folder where the asset is stored in the Console UI. This value does not impact the asset's public ID and is not case sensitive.
display_name String The name that's displayed for the asset in the Console UI. This value does not impact the asset's public ID, and does not have to be unique, even within the same folder. It can have spaces and special characters, but can't include forward slashes (/).
public_id_prefix String A string that's prepended to the public_id with a forward slash. The value can contain alphanumeric values and 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 in the Console UI.
use_filename_as_display_name Boolean Whether to automatically assign the filename of the uploaded asset as the asset's display name in the Console UI. Relevant only if display_name is not passed. Note that if you set this value to true and the original filename of the asset includes forward slashes, then the upload will fail with an error that the display name can't include slashes.

Tip
As with all upload parameters, you can also use these dynamic mode-specific parameters via the upload_presets method of the Admin API or the Upload Presets UI.

explicit method

Most parameters of the explicit method are equally supported in both folder modes. The following optional parameters are available only in dynamic folder mode when using the Explicit API method:

Parameter Type Description
asset_folder String The folder where the asset will be stored in the Console UI. This enables you to move an asset from one folder to another in the Console UI. This value doesn't impact the asset's public ID.
display_name String The name to display for the asset in the Console UI. This value doesn't impact the asset's public ID, and doesn't have to be unique, even within the same folder (unless unique_display_name is set to true via the update method). It can have spaces and special characters, but can't include forward slashes (/).

rename method

The rename method of the Upload API updates the asset's public_id and is supported for both dynamic and fixed folder modes.

Tip
The rename method is only for modifying the asset public ID. To change only the display_name for product environments using dynamic folder mode, use the display_name parameter of the explicit or update methods.

Upload API responses

The majority of the fields in upload API responses are identical in both modes with the following exceptions:

  • Dynamic folders: All responses that include details of an asset, include display_name and asset_folder
  • Fixed folders: All responses that include details of an asset, include folder

Admin API

Most endpoints and parameters of the Admin API are equally available to both modes.

Product environments using dynamic folder mode have some additional endpoints available, as well as additional parameters for some of the endpoint methods.

Checking the folder mode programmatically (Config method)

If you work with multiple product environments that need to run different code depending on whether the product environment is dynamic or fixed folder mode, you can use the config method of the Admin API to return current product environment settings, including its folder_mode (dynamic or fixed).

For example, to return the product environment configuration including settings info:

The response contains an object with detailed product environment information.

resources methods

The majority of the resources methods are identical in both modes with the following exceptions:

by_asset_folder method

The resources by asset folder method is only available in dynamic folder mode. The method returns all resources in the folder, regardless of the public ID paths of those assets. This method doesn't return assets stored in the sub-folder of the specified folder. The asset folder name isn't case sensitive.

update method

The following optional parameters are only available in dynamic folder mode when using the Update method:

Parameter Type Description
asset_folder String The folder where the asset will be stored in the Console UI. This enables you to move an asset from one folder to another in the Console UI. This value doesn't impact the asset's public ID.
display_name String The name to display for the asset in the Console UI. This value doesn't impact the asset's public ID, and doesn't have to be unique, even within the same folder (unless unique_display_name is set to true). It can have spaces and special characters, but can't include forward slashes (/).
unique_display_name Boolean If true, and you've passed a display name that already exists within the same asset_folder or you specify a new asset_folder for the asset where the same display_name already exists, a random character suffix will be appended to the display name of this asset to ensure it's uniqueness within the asset_folder.
Default: false.

search method

You can search for assets by their asset_id or public_id in both modes when using the Search method. Your search expressions can also use the following identifiers:

  • Dynamic folders: asset_folder and/or display_name
  • Fixed folders: folder

upload_presets methods

In dynamic folder mode, the use_asset_folder_as_public_id_prefix optional parameter is available in the create/update upload_presets method of the Admin API and determines whether to automatically apply the path specified in the asset_folder parameter as a prefix to the public_id value. This ensures that the public ID path will always match the initial asset folder.

As with uploading assets, the asset_folder, public_id_prefix, use_filename_as_display_name, as well as the use_asset_folder_as_public_id_prefix parameter can also be set via the upload_presets method of the Admin API.

upload_mappings methods

When working with upload mappings, the folder parameter is used in the same way for both folder modes.

Important
When using upload mappings in product environments using dynamic folder mode, the specified folder will be created as a new asset folder at the root level when an asset is lazily uploaded upon delivery, and will also be appended as the first segment of the public ID (like a public_id_prefix) for each asset that gets uploaded this way.

As with any other asset folder, a folder created through this process can be renamed without breaking the public ID of the uploaded asset, but if another asset is lazily uploaded to the same upload mapping folder, the defined upload mapping parent folder will be re-created.

folders methods

The folders methods of the Admin API reflect the folder mode:

  • In fixed folder mode, the folders methods relate to public ID paths. The public ID paths of assets are the same as the folder names or path structure where those assets are stored.
  • In dynamic folder mode, the folders methods relate to asset folders and not to public ID paths. The public ID paths of assets are not necessarily the same as the asset folder names or path structure where those assets are located, therefore the update_folder method is only available in this mode.

Make sure you don't have any code that use these methods in dynamic folder mode and then assume that the folder paths in the response relate to public ID paths.

Admin API responses

All responses in both fixed and dynamic modes that include details of assets, include the assets' public_id and asset_id. * In dynamic folder mode, the API responses include the asset's display_name and asset_folder. * In fixed folder mode, the API responses include the asset's folder.

Webhook notifications

Most webhook notifications are relevant for both folder modes. The following notifications are relevant only for actions in dynamic folder mode:

Fetched and social media assets

For both fixed and dynamic folder modes, fetched and social media assets are always located in the root folder. They can't be moved to another asset folder.

Auto-create folders

The Auto-create folders option on the Upload page of the Console Settings only exists for product environments in fixed folder mode. It controls whether folders are created in the Console UI based on the public ID path and is on by default. When turned off, folders are never created in the product environment regardless of the public ID path.

This option is not available and isn't relevant for product environments using dynamic folder mode.

✔️ Feedback sent!

Rate this page: