Backups and version management

Backing up your assets allows you to maintain a version history of individual assets, letting you view, download or restore previous revisions as well as retrieving deleted assets if needed. When you upload an asset while backups are enabled, the uploaded file is automatically backed up. You can either use Cloudinary's default backup storage, or set up your own storage bucket (paid accounts only).

Overview

Watch this video tutorial for an overview:

Enabling automatic backup

By default, backup is turned off. Enabling automatic backup means that every uploaded asset is also copied to a secondary write-protected location, while keeping multiple revisions per file. If using Cloudinary's default backup storage, this counts against your storage usage.

Important
If you intend to use your own backup storage, do not enable automatic backup until you set up your storage bucket.

To enable backup of your Cloudinary-managed assets, set Automatic backup to Enabled in the Upload tab of the console Settings page and click Save to activate backups for all newly uploaded assets.

Screenshot of automatic backup setting

To back up the existing files in your account, click Perform initial backup. When the backup is complete, an email is sent to the notification email address that you specify in the confirmation box.

Notes

  • If you have many assets in your account at the time you initiate the backup, you will be routed to a page where you can request for Cloudinary customer support to perform the initial backup.
  • An asset backup occurs when the asset itself is replaced with a new version. Other changes to an asset, such as updates to tags or metadata do not trigger a backup.
  • Remotely fetched assets, including Facebook and Twitter profile pictures, are not backed up because they can be automatically re-created at any time. In addition, Cloudinary keeps backup copies only for your original assets and not the derived (transformed) versions of these originals, as these too can be re-generated on demand.

Using your own backup storage

Paid accounts have the option to back up to a designated storage bucket, either through Amazon Simple Storage Service (Amazon S3) or Google Cloud Storage, instead of using Cloudinary's default backup location. These backups do not count against your Cloudinary storage usage.

Notes

  • When using your own backup storage, the backup location should not be touched or modified in any way. Additionally, no archiving policy should be enforced on that location (such as an archive policy to a glacier on S3 buckets).
  • If you have already backed up files to one storage location (including Cloudinary's default backup), then change to a different storage bucket, we recommend contacting support to ensure that a full backup is written to your new bucket.

Backing up to Amazon S3

To configure automatic backups to an Amazon S3 bucket:

  1. Create your Amazon S3 bucket using this naming convention:
    {XXX}-{region}, for example: mybucket-eu-central-1

    For {region}, use the AWS list of supported regions.

  2. Grant full access permissions to Cloudinary's AWS account, info@cloudinary.com. Follow the instructions for granting Access for other AWS accounts, entering either info@cloudinary.com or our Canonical ID a6cb2907a1f29bc5207045273827a60922bfc149c91d024f39d243aa7d1a4110 in the Grantee field.

    Note
    If you use AWS CloudFormation, you can create the backup bucket using CloudinaryS3Backup.json.

  3. In your Cloudinary management console, go to the Settings page and select the Upload tab. Enter the name of your S3 bucket in the Backup S3 bucket field and click Save.

    Screenshot of setting S3 bucket

  4. Enable automatic backup and click Perform initial backup to back up your current assets to your S3 bucket. Any new uploaded assets will be automatically backed up to this bucket.

Backing up to Google Cloud Storage

To configure automatic backups to a Google Cloud storage bucket:

  1. Create a Google Cloud storage bucket using this naming convention:
    {XXX}-gs-cld, for example: mycloud-gs-cld

    Make sure to select the Fine-grained access control method when creating the bucket.

  2. Grant full access permissions to Cloudinary by adding service@cloudinary-gcs-production.iam.gserviceaccount.com as a member with the Storage Object Admin role.

  3. In your Cloudinary management console, go to the Settings page and select the Upload tab. Enter the name of your Google Cloud bucket in the Backup S3 bucket field and click Save.

    Screenshot of setting S3 bucket

  4. Enable automatic backup and click Perform initial backup to back up your current assets to your Google Cloud storage bucket. Any new uploaded assets will be automatically backed up to this bucket.

Overriding the global backup setting

You can selectively override the global backup setting when uploading a specific file by setting the backup parameter in the upload API call.

For example, if the global backup setting isn't enabled, setting the backup parameter to true when uploading the file sample.jpg, ensures that the uploaded file is backed up:

Ruby:
Copy to clipboard
Cloudinary::Uploader.upload("sample.jpg", 
  :backup => true)
PHP:
Copy to clipboard
\Cloudinary\Uploader::upload("sample.jpg", 
  array("backup" => true));
Python:
Copy to clipboard
cloudinary.uploader.upload("sample.jpg", 
  backup = True)
Node.js:
Copy to clipboard
cloudinary.v2.uploader.upload("sample.jpg", 
  { backup: true }, 
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
cloudinary.uploader().upload("sample.jpg", 
  ObjectUtils.asMap("backup", true));
.Net:
Copy to clipboard
var uploadParams = new ImageUploadParams(){
  File = new FileDescription(@"sample.jpg"),
  Backup = true};
var uploadResult = cloudinary.Upload(uploadParams);
iOS:
Copy to clipboard
let params = CLDUploadRequestParams()
  .setBackup(true)
var mySig = MyFunction(params)  // your own function that returns a signature generated on your backend
params.setSignature(CLDSignature(signature: mySig.signature, timestamp: mySig.timestamp))
let request = cloudinary.createUploader().signedUpload(
  url: "sample.jpg", params: params)

Deleting backups

To delete backup storage that you no longer require:

  • If you are using Cloudinary's default backup storage, contact the support team with your cloud name and last four characters of your API secret. The backup will be deleted, freeing up space in your account.

  • If you are using your own backup storage, you can delete this yourself, but you should contact the support team to update the database records for your backups.

Note
You cannot pick and choose individual files to be deleted from your backup storage.

Versioning

You can list and restore assets from backup either programmatically, or via the Media Library.

Managing asset versions programmatically

Programmatically, you can:

Getting details of an asset's versions

To see details of backed up versions for a specific asset, use the resource method of the admin API, setting the versions parameter to true. For example:

Ruby:
Copy to clipboard
Cloudinary::Api.resource('toy_dr4lvl',
  :versions => true)
PHP:
Copy to clipboard
$api->resource("toy_dr4lvl",
  array("versions" => TRUE));
Python:
Copy to clipboard
cloudinary.api.resource("toy_dr4lvl",
  versions = True)
Node.js:
Copy to clipboard
cloudinary.v2.api.resource('toy_dr4lvl', 
  { versions: true},
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
api.resource("toy_dr4lvl",
  ObjectUtils.asMap("versions", true));
.Net:
Copy to clipboard
var getResource = new GetResourceParams("toy_dr4lvl"){
Versions = true };
var info = cloudinary.GetResource(getResource);
cURL:
Copy to clipboard
curl \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/toy_dr4lvl?versions=true
CLI:
Copy to clipboard
cld admin resource toy_dr4lvl versions=true

Sample response:

Copy to clipboard
  "asset_id": "1c827f8b0ea0dff67945e288483ce5c0",
  "public_id": "toy_dr4lvl",
  "format": "jpg",
  "version": 1589464726,
  "resource_type": "image",
  ...
  ...
  "versions": [
    {
      "version_id": "742ff6d17e189a453bdd4a74ead3e08e",
      "version": "1589357114",
      "format": "jpg",
      "size": 72661,
      "time": "2020-05-13T08:05:14+00:00",
      "restorable": true
    },
    {
      "version_id": "c3fe4be5921eb89acd9af738c892f654",
      "version": "1589464242",
      "format": "jpg",
      "size": 50127,
      "time": "2020-05-14T13:50:42+00:00",
      "restorable": true
    },
    {
      "version_id": "8f91be6973e5d7a54318dcdf000c1f19",
      "version": "1589464726",
      "format": "jpg",
      "size": 72661,
      "time": "2020-05-14T13:58:46+00:00",
      "restorable": false
    }
  ]
}

Restoring a version of an asset

To restore a specific version of an asset, use the restore method of the admin API together with the versions parameter set to the version_id of the specific version. You can use arrays to specify more than one asset and each asset's corresponding version to restore. For example:

Ruby:
Copy to clipboard
Cloudinary::Api.restore(["image1", "image2"], versions => ["c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f"])
PHP:
Copy to clipboard
$api->restore(array("image1", "image2"), "versions" => array("c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f"));
Python:
Copy to clipboard
cloudinary.api.restore(["image1", "image2"], versions = ["c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f"])
Node.js:
Copy to clipboard
cloudinary.v2.api.restore(["image1", "image2"], versions: ["c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f"],
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
cloudinary.api().restore(Arrays.asList("image1", "image2"), ObjectUtils.asMap("versions", Arrays.asList("c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f")),
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
var publicIds = new List<string>(){"image1", "image2"};
var versionIds = new List<string>(){"c3fe4be5921eb89acd9af738c892f654", "d214063097a43d1d1293db61a397f60f" };
var restoreParams = new RestoreParams(){
  PublicIds = publicIds,
  Versions = versionIds};
cloudinary.Restore(restoreParams);
cURL:
Copy to clipboard
curl \
 -d "public_ids[]=image1&public_ids[]=image2&versions[]=c3fe4be5921eb89acd9af738c892f654&versions[]=d214063097a43d1d1293db61a397f60f" \
 -X POST \
 https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/restore
CLI:
Copy to clipboard
cld admin restore "image1","image2" versions="c3fe4be5921eb89acd9af738c892f654","d214063097a43d1d1293db61a397f60f"

Downloading a version of an asset

To download a backed up version of an asset without restoring it, use the download_backup method.

  • The endpoint returns the specified version of the asset in bytes.
  • The SDKs return a URL of the asset that can be used to download that version of the asset (within an hour of the request).

For example, to return the URL of a backed up version of an asset with asset_id of 62c2a18d622be7e190d21df8e05b1416 and version_id of 26fe6d95df856f6ae12f5678be94516a, use the following syntax (the cURL example returns the asset in bytes):

Ruby:
Copy to clipboard
Cloudinary::Utils.download_backedup_asset('62c2a18d622be7e190d21df8e05b1416', '26fe6d95df856f6ae12f5678be94516a')
PHP:
Copy to clipboard
\Cloudinary::download_backedup_asset('62c2a18d622be7e190d21df8e05b1416', '26fe6d95df856f6ae12f5678be94516a');
Python:
Copy to clipboard
cloudinary.utils.download_backedup_asset('62c2a18d622be7e190d21df8e05b1416', '26fe6d95df856f6ae12f5678be94516a')
Node.js:
Copy to clipboard
cloudinary.v2.utils.download_backedup_asset('62c2a18d622be7e190d21df8e05b1416', '26fe6d95df856f6ae12f5678be94516a');
Java:
Copy to clipboard
cloudinary.downloadBackedupAsset("62c2a18d622be7e190d21df8e05b1416", "26fe6d95df856f6ae12f5678be94516a",
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
var backupParams = new BackupParams() 
{AssetId = "62c2a18d622be7e190d21df8e05b1416", VersionId = "26fe6d95df856f6ae12f5678be94516a"};
var url = cloudinary.DownloadBackedupAsset(backupParams);
cURL:
Copy to clipboard
curl https://api.cloudinary.com/v1_1/demo/download_backup?timestamp=173719931&asset_id=62c2a18d622be7e190d21df8e05b1416&version_id=26fe6d95df856f6ae12f5678be94516a&signature=c9937fe93eb655ce04633034f921b83969eff9aa&api_key=323127161127519
CLI:
Copy to clipboard
cld utils download_backedup_asset "62c2a18d622be7e190d21df8e05b1416" "26fe6d95df856f6ae12f5678be94516a"

The SDK methods return the URL to download the requested backed up version of the asset, as follows:

Copy to clipboard
https://api.cloudinary.com/v1_1/demo/download_backup?timestamp=173719931&asset_id=62c2a18d622be7e190d21df8e05b1416&version_id=26fe6d95df856f6ae12f5678be94516a&signature=c9937fe93eb655ce04633034f921b83969eff9aa&api_key=323127161127519

The URL returned in the response is valid for an hour.

Managing asset versions via the Media Library

You can list, preview and restore previous versions of an asset from the asset management drill down page by clicking Version History, either from the Summary tab, or from the kebab menu:

screenshot of manage page with 'Version History' highlighted

To preview a specific version of the asset, click its preview icon. To restore a previous version, click the Restore link next to the listed version.

screenshot of revisions

You can do the same from the Edit page by clicking View backed up versions. This page has an additional indication of the asset's backup status: a small gray safe icon means the asset is backed up, whereas a red safe icon means the asset has additional historical revisions.

screenshot of edit page with 'View backed up version' highlighted

Restoring deleted assets from backup

You can restore deleted assets from backup either programmatically, or via the Media Library.

Restoring deleted assets programmatically

To find specific assets that you want to restore from backup programmatically, you can use the Search API with status=deleted together with other search options to narrow down the results.

Once you have found your deleted assets, you can restore them from backup programmatically using the restore method of the Admin API. If no versions are specified, the latest backed up version of the asset is restored. For example, to restore deleted assets with the public_ids 'image1' and 'image2':

Ruby:
Copy to clipboard
Cloudinary::Api.restore(["image1", "image2"])
PHP:
Copy to clipboard
$api->restore(array("image1", "image2"));
Python:
Copy to clipboard
cloudinary.api.restore(["image1", "image2"])
Node.js:
Copy to clipboard
cloudinary.v2.api.restore(["image1", "image2"],
  function(error, result) {console.log(result, error); });
Java:
Copy to clipboard
cloudinary.api().restore(Arrays.asList("image1", "image2"),
  ObjectUtils.emptyMap());
.Net:
Copy to clipboard
var publicIds = new List<string>(){"image1", "image2"};
cloudinary.Restore(publicIds);
cURL:
Copy to clipboard
curl \
 -d "public_ids[]=image1&public_ids[]=image2" \
 -X POST \
 https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/restore
CLI:
Copy to clipboard
cld admin restore "image1","image2"

To restore a specific version of a deleted asset, use the versions parameter, as shown in Restoring a version of an asset.

Restoring deleted assets via the Media Library

To restore deleted assets through the Media Library, use the advanced search to find assets of type, Deleted asset.

screenshot of deleted assets

You can optionally narrow the search down further using other Advanced Search options, then double-click the asset you want to restore. Select a specific version to restore as described in Versioning, either by clicking Restore in the Preview area, or Version History in the Summary tab.

✔️ Feedback sent!

Rate this page: