What are image versions?

One property of each asset uploaded to your account is the version, which indicates the time at which the asset's file was last uploaded or overwritten.

The format of the version property is a UNIX timestamp. For example, for an asset that was uploaded/replaced at midnight on January 1, 2020, the "version" property's value will be 1640995200.

Obtaining an asset's version

The version is part of the asset metadata returned in responses when uploading a new asset via the API or via the Upload Widget, or from other API calls that return the metadata of assets, including methods in our Admin API and Search API.

An asset's version is also part of the media delivery URLs that you can copy from various places in our Media Library UI, including the "copy link" option on an asset, and when viewing the asset details or different derived copies of the asset in the Transformation Editor.

If you're using Cloudinary's backup and restore functionality, both the API and UI options that show a list of previous copies of an asset will also show the version number for the backed-up copies:

Using the version property

When delivering assets from your Cloudinary account, only the newest copy of an asset is available for public delivery. If an asset is overwritten, previous copies of the asset can be downloaded or restored using our Media Library UI or the API, but in the public delivery URLs for an asset, only the newest copy can be returned.

The asset URLs returned by our API and Media Library will include the current version of each asset as part of the URL, but it's an optional part of the delivery URL format and if you're creating URLs using one of our SDKs or using your own code, the version is not required.

Here's a sample URL with the version component:

http://res.cloudinary.com/demo/image/upload/v1312461204/sample.jpg

And a URL for the same asset, without the version component is:

http://res.cloudinary.com/demo/image/upload/sample.jpg

Including the version component in URLs serves two purposes:

• When assets are stored in a subfolder of your account, the presence of a version number in the URL helps us to parse the URL and separate which part of the URL is the transformation options, and which part is the public_id, which includes the folder path.
  • For this reason, many of our SDKs will add a "/v1/" to the path of the URLs it creates for assets in subfolders, even if you didn't include the "version" property when creating the URL.
• Though you can request that Cloudinary's CDN cache is invalidated for an asset when you overwrite it, the old asset may still be stored in caches outside Cloudinary's control such as browser caches, ISP, corporate, or other third-party caches. 
  • By storing the version for each asset, and including the asset's current version when building the URL, you can ensure that users of your site or application will request the asset again when the version number changes, bypassing any third-party caches of the previous asset URL. 

For more information about versions, please see our main documentation:
https://cloudinary.com/documentation/advanced_url_delivery_options#asset_versions