Folder modes in integrations

All Cloudinary product environments are set up to work with either dynamic folders or fixed folders. The majority of supported Cloudinary features are identical for both modes, but each of these modes also have a variety of different behaviors, supported methods and parameters, response keys, webhook notifications, upload preset settings and more. Therefore, you must make sure all code in your integration will work as expected for both modes:

• In fixed folder mode, the folder and asset name are a direct reflection of the asset's public_id full path, and thus control the delivery URL path and file name. In fixed folder mode, moving the asset to another folder or changing the folder or asset 'name' shown in the Media Library interface, also modifies the asset's URL, and if not done carefully, risks breaking production content.
• In dynamic folder mode, moving assets between asset folders and renaming those folders, or even moving entire folders and the assets currently "in" them to a new path, DO NOT affect the asset's public ID value or delivery URL path. Dynamic folder mode also introduces the concept of 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 production content.

This page describes the ways that the dynamic folders mode impacts your Cloudinary integration. It assumes you're familiar with both the Cloudinary Console and API capabilities that were available prior to this new option.

Checking the folder mode (Config method)

If you 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 the current settings, including information on the folder_mode (dynamic or fixed).

It's recommended to run this method immediately after a product environment connects to your integration, and then use the returned value as the basis for all other code that can be impacted by the folder mode. For example, to return the product environment configuration including settings info:

The response contains an object with detailed product environment information.

Important considerations

If you are integrating with Cloudinary and your integration has any code that relates to public ID path or folder structure in any way, then there are a variety of considerations you should be aware of, and you must ensure that your integration will fully support both fixed folder AND dynamic folder product environments.

Take note of the following important considerations when integrating with dynamic and fixed folder product environments.

Uploading assets

Dynamic folder mode introduces the concept of display_name and asset_folder that can be freely modified without affecting the public_id and delivery URL.

When uploading files, the following parameters can also be defined:

• public_id_prefix to prepend a string to the public_id with a forward slash. 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 folder location where the asset is placed. This value is NOT returned in the response as it's just an optional technique for building the public ID value from two separate parts: the returned public ID in the response represents the full path.
• use_filename_as_display_name to automatically assign the filename of the uploaded asset as the asset's display name. If desired, this option can be used in addition to use_filename, which controls the last segment of the public ID.`

The 'folder' parameter

The folder parameter of the Upload method should not be used in dynamic folder mode. It is officially supported for backward compatibility and is the equivalent of setting both asset_folder and public_id_prefix to the same value (if those values are not explicitly passed).

However, keep in mind that many dynamic mode customers may have their assets organized in a deep folder structure, while their public IDs may have no slashes in them (this is the default behavior for all dynamic mode accounts) or their public ID paths may intentionally use public ID paths intended for SEO purposes that are completely different than their folder structure.

If you pass the folder parameter when uploading assets to a dynamic folder product environment, it would apply a path to the public ID that the customer may not expect.

Public IDs with slashes

When passing a public_id value that includes slashes (for example, animals/cats/tiger), the entire passed value continues to be the public_id, but in dynamic folder mode, the slashes do not define the path where the asset is placed. If you don't also pass an asset_folder value, the asset will be displayed in the root folder.

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.

Default upload behavior

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 (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 presets

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 and can help to retain the behavior that previously existed in fixed folder mode.

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

In dynamic folder mode with upload mappings, the folder parameter continues to represent both the asset folder that will be created at the root level when an asset is lazily uploaded upon delivery, and also the first segment of the public ID of 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.

Updating assets

In dynamic folder mode, the display_name and asset_folder can also be set for existing assets using the Explicit method. These parameters are also available in the Update method of the Admin API.

Renaming assets

If your integration includes management functionality, keep in mind the difference between a public ID and a display name, especially when updating assets. The rename method changes the public ID and resulting delivery URL, so to only change the display name use the explicit or update methods.

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.

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.

In dynamic folder mode, you also have access to the following methods:

• Get resources by asset folder method that returns all assets located directly in a specified asset folder, regardless of the public ID paths of those assets.
• Update folder method that updates the full path of an existing asset folder.

Asset IDs

In both fixed and dynamic folder modes, you also have access to methods that refer to the asset ID, an immutable identifier, regardless of resource type, type, public ID, display name, or asset folder:

• Get resources by asset IDs: Returns the assets with the specified asset IDs.
• Get a single resource by asset ID: Returns the asset with the specified asset ID, including details on all derived assets from this asset.

Webhook notifications

In dynamic folder mode, changes to the display name and asset folder (moving assets) via the Console or API trigger webhook notifications. New events include:

• resource_display_name_changed
• move
• move_asset_folder
• delete_asset_folder

The create_folder, create_asset_folder, delete, rename and upload events are also still relevant for dynamic folder mode, and the notification payloads now additionally include the asset's display_name and asset_folder.

API responses

In dynamic folder mode, the API methods now additionally include the asset's display_name and asset_folder as part of the response.

Integration scenario check list

The following integration use cases include important information to take into consideration when integrating with both dynamic and fixed folder modes.

Syncing asset and folder structure with Cloudinary

The biggest change will be if your integration has relied on using the URL path (public ID) as an indicator of folder structure or asset location. This is only true for product environments using fixed folder mode. In dynamic folder mode, users can move assets between asset folders and rename those folders without affecting the asset's public ID value and delivery URL path.

Dynamic folder mode introduces the concept of display_name and asset_folder that can be freely modified without affecting the public_id and delivery URL.

Use the folders method to get lists of existing folders instead of relying on URL paths and then use the Get resources by asset folder method to retrieve the list of assets in each folder.

If you use webhooks to mirror the Cloudinary Assets product folder structure and assets, the notifications triggered for various operations and their responses are slightly different in dynamic and fixed folder modes.

Searching for assets

Search expressions that include the folder field are only useful for searching within fixed folder mode product environments. In dynamic folder mode, the search expressions should use the asset_folder field. You can also search for assets by their asset_id.

Media Library Widget

If your integration includes the Media Library Widget, take note of the changes to the JSON response, especially if you are syncing using webhook notifications.

Set asset folder based on public ID

If your integration sets the folder based on the public_id parameter, where the portion of the public ID that sets the folder is the prefix and is separated by a slash, you can use the following script together with the eval upload parameter to set the asset_folder and display_name in dynamic folder mode: