Dynamic folders (BETA)

Dynamic folders provide Cloudinary users the flexibility to organize and manage media assets with high performance and without risk of breaking production content. This mode adds new features and fields that can be used in both the Media Library interface and the API.

However, if you use Cloudinary for both DAM and API capabilities, there are a variety of considerations you should be aware of before migrating from Cloudinary's (default) fixed folders mode.

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

Important

  • To migrate your Cloudinary account or any selected sub-account to dynamic folders mode, contact Cloudinary support.
  • Once your account or sub-account is migrated to the dynamic folders mode, you can't revert that account to the fixed folders mode.
  • It's recommended that you test every element of your Cloudinary implementation on a non-production sub-account before applying this mode to a production account.
  • Cloudinary platform integrations have not yet been fully tested with dynamic folders enabled. It's not recommended to work with platform integrations in this mode during the Beta stage.
  • This page will continue to be updated with new features and fixed issues during the Beta phase.
  • Please send all input and feedback related to dynamic folders to Cloudinary support.

What is dynamic folders mode?

Dynamic folders is a mode that enables Cloudinary users to move assets between asset folders and rename those folders without affecting the asset's public_id value and delivery URL path. Because of this decoupling, asset folder names are not case-sensitive.

Dynamic folders mode also introduces the concept of a display name, which, like the Media Library asset folders, can be freely modified without affecting the public_id and delivery URL.

In contrast, when using Cloudinary's (default) fixed folders mode, the folder and asset name shown in the Media Library together are a direct reflection of the asset's public_id full path, and thus control the delivery URL path and file name. In fixed folders mode, any changes made to 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.

Asset identifiers

The following table summarizes an asset's identifiers in dynamic folders mode:

Identifier Unique? Editable? Description
Public ID Yes 1 Yes The value used to identify the asset when delivering a Cloudinary asset in a URL.

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

The public ID can be edited in the Media Library or programmatically, but if an asset is already being delivered in production, changing the public ID can break production code.

1 The public ID must be unique within its account or sub-account, and for a particular asset type. For example, it's possible, though not recommended, to have the same public ID for an image and a video in the same account or sub-account.

Display Name No Yes The name that's displayed in the Cloudinary Media Library, Cloudinary collections, and Cloudinary media portals. This value can also be retrieved or set programmatically.

Display names can have spaces and special characters, but can't include forward slashes (/).

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

Asset ID Yes No An automatically generated immutable asset identifier that is fully unique and enables developers to reliably reference the asset programmatically, even if the other identifier values change, if the asset is moved to another folder, etc.

New Media Library features

At the top of the Media Library preferences, there's an indicator showing you that your account or sub-account is enabled for dynamic folders:

dynamic folders indicator

Accounts or sub-accounts with dynamic folders enabled have a variety of new features in the Media Library:

Moving assets between asset folders

Since dynamic asset folders are not directly tied to a physical storage location, you can move assets from one folder to another in milliseconds. Even moving thousands of assets, or very large assets has no impact on the move time.

Moving and renaming asset folders

Moving and renaming asset folders is fully supported. Use the folder right-click menu to access these options.

Folder move and rename options

Display name

  • The asset name that's shown at the top of the Media Library Preview Pane and in the Summary pane of the Manage Assets page reflects the asset's display name. When you edit this value, it has no impact on the public ID (delivery URL) of the asset.

Display name and public ID in the Media Library

  • The asset name shown in media portals and collection web pages shared via public links reflect the asset's display name, as well.

Public ID

The asset's complete public ID value is now displayed towards the bottom of the Preview Pane and Summary pane of the Manage Assets page as shown above. For users with permissions to edit public IDs, an edit button is available next to the public ID value, enabling you to modify the public ID.

Editing a public ID in the Media Library

Important
Modifying the public ID value changes its delivery URL and can break links to images and videos in your production applications.

For users with a Media Library user role to edit a public ID:

  • The Enable delivery URL options permission must be turned on for the user (defined in the user settings by an account admin).
  • The asset's folder must be shared with the user with Can edit or Can manage folder permissions.

Note
Depending on your account setup, some accounts may not have the Enable delivery URL options user permission. In this case, all users with a Media Library user role will be able to view public IDs, but won't be able to edit them. You can contact support to get this user permission added to your account.

Upload preset options

The upload preset interface has been redesigned and has new options:

New options in the upload preset interface

  • A new Asset folder field has replaced the Folder field that the fixed folders version of the upload preset UI displays. The value set in this field determines the folder where the asset will be displayed within the Media Library. The value set here does not have any impact on the asset's public ID (unless you also select the Set the public ID path to match the initial asset folder path option).
  • A new Asset naming section has been added. In this section, you can either:
    • Accept the default asset naming settings:
      • The asset's public ID will be a randomly generated unique value without a path (no public ID prefix)
      • The asset's display name will be automatically taken from the filename of the uploaded file
    • Define custom naming preferences for the display name and public ID, including the option to define the URL path (known as public ID prefix) to prepend to the public ID of every asset uploaded using this upload preset. There are two options for setting the public ID prefix:
      • Set the public ID path to match the initial asset folder path: Sets the public ID prefix to match the name of the asset folder the asset is initially uploaded to. (If an asset is later moved to a different folder, the public ID path won't change to reflect the asset's new location.)
      • Prepend this path to the Public ID: Defines a custom public ID prefix.

Upload with existing display name

More than one asset can have the same display name, even within the same folder. However, if you upload one or more assets using a display name that already exists, you'll be asked to decide how to proceed before uploading continues.

This situation will occur if you apply an upload preset with the Use the filename of the uploaded file as the asset's Display Name option selected (either within the Default or Custom options), and the file name of at least one of the assets you're uploading matches the display name of an existing asset or assets.

Depending on the scenario, you'll get different options to choose from:

  • If you're uploading an asset using the same display name as multiple existing assets in the same folder, you'll be asked which one of the following you want to do:

    • Keep the new and existing assets with the same name
    • Enter a different display name for the new asset being uploaded
  • If you're uploading an asset using the same display name as exactly one existing assets in the same folder, you'll be asked which one of the following you want to do:

    • Replace the existing asset with the new one being uploaded
    • Keep the new and existing assets with the same name
    • Enter a different display name for the new asset being uploaded
  • If more than one asset that you're uploading has the same display name as existing asset in that folder, you'll be asked which one of the following you want to do:

    • Keep the new and existing assets with the same display name
    • Add a unique suffix to the display name of the new asset

    You'll be able to apply the selected behavior to all of the assets that fall into this category or to determine the naming option for each uploaded asset individually.

Media Library search

You can now use the free text search box to find assets by display name as well as public ID.

New API options

Accounts or sub-accounts with dynamic folders enabled have a variety of new options in the Cloudinary APIs.

New in the Upload API

This section describes:

New Upload API parameters

  • The following optional parameters have been added to the Upload API method:

    • asset_folder (string): The folder where the asset is stored in the Media Library. This value does not impact the asset’s public ID.
    • display_name (string): The name that’s displayed for the asset in the Media Library. 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 Media Library.
    • use_filename_as_display_name (boolean): Whether to automatically assign the filename of the uploaded asset as the asset's display name in the Media Library. Relevant only if display_name is not passed.

    Note
    If you set use_filename_as_display_name to true (in the upload call or upload preset) and the original filename of the asset includes forward slashes, the upload will fail with an error that the display name can't include slashes.

    These new upload parameters are also supported in all the backend SDKs.

  • The display_name and asset_folder can also be set for existing assets using the Explicit method.

    (These parameters were also added to the Update method of the Admin API as described below.)

  • The following optional parameter has been added to the create/update upload_presets method of the Admin API:

    • use_asset_folder_as_public_id_prefix (boolean): Whether to automatically apply the path specified in the asset_folder parameter (or the folder that's in focus when an asset is uploaded directly to a folder in the Media Library) as a prefix to the public_id value. This ensures that the public ID path will always match the initial Media Library asset folder and can help to retain the behavior that previously existed in fixed folder mode. Relevant only when public_id_prefix (or folder) has not been separately specified.

      For additional information about the folder parameter, see Tips and considerations below.

  • 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 or the Upload Presets UI.

Default upload behavior

  • 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 of the Media Library, even if the public ID includes a path with slashes.

    For additional information about the folder parameter, see Tips and considerations below.

New Upload API response keys

Upload API methods where the response includes full details of the asset (upload, explicit, and rename) now additionally include the asset's display_name (always) and asset_folder (if one was defined) as part of the response.

For example, uploading an image named brown-jacket.jpg, with the following parameters: use_filename:true, unique_filename:false, display_name: "stylish brown jacket", asset_folder: "jackets"

returns:

Copy to clipboard
  {
      "asset_id": "3d6c6a087852da3cb702167d9beeec1b",
      "public_id": "brown-jacket",
      "version": 1650802526,
      "version_id": "4e953edee9b83faba1b0aa466961b3a6",
      "signature": "4afd97d1df985ae0a8097a2364ded44881f7f1bc",
      "width": 900,
      "height": 1600,
      "format": "jpg",
      "resource_type": "image",
      "created_at": "2022-04-24T12:15:26Z",
      "tags": [],
      "pages": 1,
      "bytes": 145543,
      "type": "upload",
      "etag": "bf3b73ebde8ccce43e30b176a08228a6",
      "placeholder": false,
      "url": "http://res.cloudinary.com/my_cloud_name/image/upload/v1650802526/brown_jacket.jpg",
      "secure_url": "https://res.cloudinary.com/my_cloud_name/image/upload/v1650802526/brown_jacket.jpg",
      "asset_folder": "jackets",
      "display_name": "stylish brown jacket",
      "original_filename": "brown-jacket",
      "api_key": "1234567890"
  }

New in the Admin API

This section describes:

New Admin API endpoints

Get resources by asset folder

Returns all assets stored directly in a specified asset 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.

Syntax:

/resources/by_asset_folder

Required parameter:

  • asset_folder: String. The name of the asset folder.

The response is similar to that of the Get resources method.

Get resources by asset IDs

Returns 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: /resources/by_asset_ids

Required parameter:

  • asset_ids[]: String

The response is similar to that of the Get resources method.

Get a single resource by asset ID

Returns the asset with the specified asset ID, including details on all derived resources from this asset. This enables you to get all details of an asset by its immutable identifier, regardless of public ID, display name, or asset folder.

/resources/:asset_id

The response is similar to that of the Get a single resource by public ID.

New Admin API options

  • The update (POST) method of the resources endpoint, now supports the follwing new parameters:

    • asset_folder (string): The folder where the asset will be stored in the Media Library. This enables you to move an asset from one folder to another in the Media Library. This value doesn't impact the asset’s public ID.
    • display_name (string): The name to display for the asset in the Media Library. 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: 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.

    Note
    The asset_folder and display_name parameters are also available for the Upload and Explicit methods of the Upload API as described above.

  • Search API expressions now support the display_name field.

New Admin API response keys

The responses for the /resources and /search endpoints now include the display_name (always) and asset_folder (if one was defined). For example:

Copy to clipboard
"resources": [
    {
        "asset_id": "708db71852a306e903005f29cb9aa3cd",
        "public_id": "CC0_logos/J_favicon",
        "format": "ico",
        ...
        ...
        ...
        "asset_folder": "Logos",
        "display_name": "J_favicon",
        "url": "http://res.cloudinary.com/my_cloud_name/image/upload/v123/logos/J_favicon.ico",
        "secure_url": "https://res.cloudinary.com/my_cloud_name/image/upload/v321/logos/J_favicon.ico"
    },
    {
        "asset_id": "727546c0a4fb70b3e4adfd9b22cf8ae2",
        "public_id": "CC0_logos/logo",
        "format": "png",
        ...
        ...
        ...
        "asset_folder": "Logos",
        "display_name": "Logo",
        "url": "http://res.cloudinary.com/my_cloud_name/image/upload/v456/CC0_logos/logo.png",
        "secure_url": "https://res.cloudinary.com/my_cloud_name/image/upload/v789/CC0_logos/logo.png"
    },

New webhook notifications

  • Changes to display name and asset folder (moving assets) via the UI or API now trigger webhook notifications. For example:

    Copy to clipboard
    {
      "notification_type": "resource_display_name_changed",
      "source": "ui",
      "resources": {
        "CC0_logos/logo": {
          "previous_display_name": "Logo",
          "new_display_name": "name-logo",
          "asset_id": "727546c0a4fb70b3e4adfd9b22cf8ae2",
          "resource_type": "image",
          "type": "upload"
        }
      }
    }
    Copy to clipboard
    {
      "notification_type": "move",
      "source": "api",
      "resources": {
        "CC0_logos/logo": {
          "asset_id": "727546c0a4fb70b3e4adfd9b22cf8ae2",
          "resource_type": "image",
          "type": "upload",
          "from_path": "Logos",
          "to_path": "Icons"
        }
      }
    }
  • The notification payload for asset uploads now includes the asset's display_name (always) and asset_folder (if one was defined).

Tips and considerations

Media Library tips and considerations

  • Folder permissions

    • In dynamic folder mode, folder permissions continue to control the operations a Media Library user is allowed to perform on the assets inside that folder (viewing assets, downloading assets, uploading assets or moving assets into or out of a folder, deleting assets, etc). This is true regardless of the public ID path that an asset has.

      For example, if an asset is uploaded to the animals asset folder with a public ID of animals/dog, the permissions a user has for the animals folder determines what the user can do on that asset. If the asset is moved to the pets folder, the permissions a user has on the pets folder will then control what the user can do, even though the public ID remains animals/dog.

    • Media Library user minimum permission levels for the new dynamic folders capabilities are as follows:

      • Create new asset folders or sub-folders: Can Contribute
      • Rename both public IDs and display names: Can Edit
      • Rename, move, delete, or share asset folders: Can Manage
  • Overriding existing assets: From the Media Library, you can still replace existing assets in the same ways as has always been possible with the fixed folders mode:

    • Make sure the default Media Library upload preset being used is set with use_filename = true (Use the filename of the uploaded file as the Public ID in the upload preset UI) and then make sure the filename of the asset you're uploading exactly matches the existing public ID of the asset to replace (regardless of what its current display name is).

      With this method, you can use the Upload Widget or drag and drop to upload (unless the public ID to replace includes slashes).

    • Specify the exact public ID of the asset to replace using the Advanced Options of the Media Library Upload Widget.

    However, if using an upload preset that generates a random value for the public ID (this is the default setting for new upload presets created via the UI), appends a random value to the filename, or if your public ID includes slashes, the 2nd bullet above is the only method available for replacing assets.

  • Default Media Library upload behavior: When you upload assets to Media Library folders (or drag and drop a set of folders and sub-folders to the Media Library, thus creating new Media Library folders), the public IDs won't automatically get a matching path (public ID prefix).

    If it's important in your organization for public ID paths to match the Media Library folder paths, you can select the Set the public ID path to match the initial asset folder path option in the Upload preset that's being used as the default Media Library upload preset. However, keep in mind that even with this option set for uploads, if an asset is later moved to another folder in the Media Library, the public ID value will keep its original value.

API tips and considerations

  • 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 the slashes do not define the path where the asset is stored in the Media Library. If you don't also pass an asset_folder value, the asset will be displayed in the root folder of the Media Library.

    If you want the asset to be displayed in a Media Library 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 Media Library location.

  • 'folder' parameter: The folder parameter of the Upload method should no longer be used. It will continue to be supported for backward compatibility and will be the equivalent of setting both asset_folder and public_id_prefix (if those values are not explicitly passed). However, for dynamic folder accounts, we recommend updating your code to use asset_folder and/or public_id_prefix where possible.

  • Folders API: In dynamic folders mode, the folders endpoint relates to the asset folders in the Media Library and not to public IDs. Make sure you don't have any code that retrieves folders using this endpoint and then assumes that the folder paths in the response relate to public ID paths.

  • Upload mappings: When working with upload mappings, the folder parameter continues to represent both the Media Library asset folder that will be created at the root level of the Media Library 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 Media Library asset folder, a Media Library 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.

  • Auto-create folders: When dynamic folders mode is enabled, the Auto-create folders option in the Upload page of the account settings is ignored. Instead:

    • When you set an asset_folder (or folder) value in your upload call or the upload preset you use, Media Library folders are always created.
    • If you don't set one of the above, then assets will always upload to the the root folder of the Media Library regardless of whether the public_id value has slashes and/or whether a public_id_prefix value was passed.
  • Fetched and social media assets: Fetched and Social media assets are always located in the Media Library root folder. They can't currently be moved to another asset folder.

Known issues

  • SDKs The following new API options are not yet supported in SDKs:

    • Upload preset method parameter: use_asset_folder_as_public_id_prefix
    • The new endpoints and options in the Admin API
    • The new asset_folder and display_name parameters of the Explicit method.

    Tip
    For endpoints or parameters that are not yet available for the SDK you use, you can experiment with these new API options using the Cloudinary Postman REST API Collections.

✔️ Feedback sent!

Rate this page: