Folder modes
Last updated: Sep-02-2024
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.
NoteIn 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.
- 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.
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 ( 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.TipIn dynamic folder mode, if you want your public ID to include slashes, you can either pass the full path as a single string in thepublic_id
parameter, or you can separately pass apublic_id_prefix
value with the path to use. Thepublic_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 anasset_folder
parameter in your upload call with the same path. Alternatively, pass thepublic_id
value without a path, and instead, specify the path in theasset_folder
parameter, while also using theuse_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 initialasset_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. |
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.
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
andasset_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/ordisplay_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.
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.