Managing Multiple Versions

Versioning allows you to keep all your revisions in one place, so you can access notes from the review process and track changes from one iteration to the next. For example, you upload a rough cut to MediaSilo for review; later, you make changes and want to upload the latest cut. The MediaSilo API allows you to combine these cuts into a single asset with two (or more) versions.

There are two paths to creating a new version in MediaSilo. You can combine files that were already uploaded to MediaSilo, or you can upload a file as a new version of an existing file. We will cover both workflows below.

1 - Create a New Version from Existing Files
2 - Upload as a New Version
3 - Update a Version
4 - Remove a Version

1. Create a New Version from Existing Files

If you’ve already uploaded files to MediaSilo, you can combine them into a versioned asset. In the MediaSilo UI, this is accomplished by dragging one thumbnail on top of another thumbnail. A popup window asks you to name the new version and click “Confirm.”

To create a new version using the MediaSilo API, you would call Add a new version, and pass in the following three body parameters:

  • currentAssetId: The id of the original asset
  • newAssetId: The id of the asset that will become the new version
  • versionId: A name for this new version. The versionId is displayed here in the MediaSilo Projects UI:

Here is an example:

POST /v3/assets/versions
{
    "currentAssetId":"29de9042-XXXX-XXXX-XXXX-d124db6a033",
    "newAssetId":"50aaa0b8-XXXX-XXXX-XXXX-58cfad70b07b",
    "versionId":"v2_dunes getaway"
}

A 204 code is returned when the new version is successfully added.

Note that the files you are about to combine must belong to the same project; attempting this call with files from different projects will result in a 400 code. If the files are in different folders prior to versioning, then the versioned asset will live in the folder that corresponds to the “new” version (version 2).

2. Upload as a New Version

You can upload a file as a new version of an existing file. In the MediaSilo Projects UI, this is done by opening a file, going to the Versions tab, and clicking the blue “+” button. You would then choose a file from your computer to upload as the new version.

This method of creating a new version uses the Create asset call. To upload a new version, you would pass in the same parameters used when uploading a standalone file, plus these additional parameters:

  • versionAssetId: The id of the original asset in MediaSilo
  • versionId: A name for this new version. The versionId is displayed here in the MediaSilo Projects UI:

In addition to the id of the original asset, you must pass in its projectId. This parameter is required by the “Create asset” call. If you are uploading to a specific folder, then you would need to pass in the folderId as well. If you do not provide a folderId, then the versioned asset will live in the root level of the project.

Here is an example of uploading a new version from cloud storage:

POST /v3/assets
{
    "sourceUrl": "http://example.com/v3_American_Ringtail.jpg",
    "projectId": "bb1288f9-XXXX-XXXX-XXXX-ea8d2d6819bb",
    "folderId" : "179014a2-XXXX-XXXX-XXXX-92404345422d",
    "versionAssetId": "4e8466e1-XXXX-XXXX-XXXX-1665e617f898",
    "versionId": "V3-American Ringtail"
}

A 200 code is returned when the new version is successfully added; the response contains the id of the new file.

3. Update a Version

You can use the MediaSilo API to rename the versions in a versioned asset. When managing versions, we refer to the newest version as the “active” version; older versions are “inactive.” In the MediaSilo UI, the active version is the first one that users see when they open a file. Inactive versions are accessed via the Versions tab in Projects or the dropdown menu at the top of a Review Link:

You can change a version’s name using Update a version. In this scenario, you would pass in the version’s id using assetId and the updated name using versionId. You can update the name of an active version or the name of an inactive version.

📘

To obtain the assetId of each version in a versioned asset, please see Get versions.

4. Remove a Version

To delete an older, inactive version from a versioned file, please use Delete a version. Keep in mind that this call will permanently delete the inactive version– it will no longer exist in your MediaSilo workspace. If you need to delete a versioned asset in its entirety, then you would need to call Delete asset by ID; “Delete a version” is only intended for the removal of inactive versions.

You also have the option to rearrange versions without having to delete any of them. To restore an inactive version to the status of active version, please use Change the active version. This call simply requires that you pass in the assetId of any inactive version. The inactive version then becomes the active version, and the file that was previously active becomes inactive. In the MediaSilo UI, this is accomplished by clicking Restore Version in the Versions tab:

Note that changing a version’s status does not change its name (versionId). Therefore, if an inactive version is named “Version 1-Not Final,” then its name will remain intact after it becomes the active version.


What’s Next