Version Stacks are an organizational principle in Frame.io that enable Assets to be vertically "stacked" without being put into folders. Stacked versions make for easier Asset-to-Asset navigation within the Frame.io UI, and support side-by-side review.
We do not currently support uploading directly into a Stack, so the API sequence for managing basic Version Stack workflow will follow the same sequence as the Frame.io UI:
- Upload the Asset (optionally: mark as private).
- Assign the Asset into Stack.
Existing Version Stacks can be reordered, and individual versions can be knocked out a stack. Finally, Version Stacks can be deleted without deleting any of their constituent assets.
Version Stacks will always have an attribute called
cover_asset_id at their top level. This is the
id of the Asset whose thumbnail is displayed in the Frame.io web UI, and is the highest-numbered version in the stack.
Version Stacks -- like Folders -- are special
types of Assets. You can fetch them with the same endpoints, and based on the value of the
type key in the API response, parse and route accordingly. This is generally straightforward in practice, but can present a couple of wrinkles when managing Stacks at scale.
The key to working with Version Stacks is separating the four most common scenarios:
- An Asset can be added to an Asset, which will create a Stack with a new
- An Asset can be added to an existing Stack.
- A Stack can be reordered.
- Individual Versions can be removed.
The first two scenarios use the same endpoint call, so the only real nuance is knowing whether you're creating a new Stack (from two Assets), or adding your Asset to an existing Stack. Aside from that, the constraints are predictable:
- Stacks must match on
asset_type(e.g. you can't stack an image on a stream).
- The acting User must have permissions for both the source Asset and destination Asset or Stack.
- Asset Stack sequentially.
- You can't stack a Stack on a Stack.
- Folders are right out.
The latter two scenarios are also pretty simple, but require knowing a bit more about the Stack itself. For example, to reorder an Asset in a Stack, you'll need to know the
ids of the Assets on either side of where you want your target Asset to land; and that will generally mean you've fetched the entire Stack already.
Before beginning this guide, you'll need to make sure you have a token that includes the following scopes:
|Assets: Read, Update
|- Fetch source and destination Assets.
- Add an Asset to a Version Stack.
- Reorder a Stack.
- Remove an Asset from a Stack.
- Delete a Stack.
The first step is to identify which of the two key scenarios you're in -- adding an Asset to another Asset to create a Stack, or adding an Asset to a Stack to extend that Stack.
If you know that you're working with an unversioned Asset, or you already have a Version Stack
id, you can move onto Step 2.
If not, the easiest way to determine whether or not a destination Asset is already part of a stack is to:
GETyour target Asset via call to
- Check the
typethat comes back.
- If it's version_stack, the uuid you've just checked is your destination uuid. Move onto Step 2.
- If the
typeis file, grab the
- GET the parent via the same endpoint, and check its
If the parent's
type is version_stack, use its
id as your destination.
type is anything else, you're dealing with a regular Asset and can use the original id as your destination.
Now that you have your destination uuid, you need to know the uuid of the Asset you're adding to the Stack.
- If you're uploading a new Asset, simply use the id returned with the success response when you create the Asset.
- If you're stacking an existing Asset, you should have the
idvia the process described above.
The only body parameter required for a Version Stack addition is
Now that you have both Asset
id parameters, you're ready to
/assets/:id/version, where the :id is your destination Asset or Version Stack, and your source (new) Asset is in the body payload.
Version Stacks rely on a simple ordinal concept of each asset have
prev_asset_id neighbors, where the order refers not the version numbering, but each Assets's
index attribute. The
index runs opposite the version numbers, so accordingly:
- The first (lowest numbered) Version in the Stack has a
prevAsset, but no
- The more recent (highest numbered) Version in the Stack has a
nextAsset, but no
- All "inner" versions have both a
nextAsset, which are the Assets with higher and lower Version IDs, respectively.
This gives us three distinct scenarios, all of which rely on the same endpoint call:
In all cases, the
id in the URL path will be the Asset you're moving.
|Move to top of Stack
id of the previous top Asset (highest version number).
|Move to bottom of Stack
id of the previous bottom Asset (v1).
|Move Version within a stack
id of the Asset just above where you'd like to move your Asset.
id of the Asset just below where you'd like to move your new Asset.
When an Asset is moved into a Version Stack, it becomes a child of the Stack itself. The move an Asset out of a Version Stack, what you'll need to do is effectively re-parent it back into the Stack's containing folder.
GETthe Version Stack itself via call to
- Grab the
parent_idof the Stack itself (which becomes your new target folder
- Move the your target Asset into the folder as follows:
Deleting a Version Stack is extremely straight-forward:
That's it. Deleting a Stack will return all its constituent Assets to the Stack's containing folder.
If you remove all elements from a Version Stack, you'll end up with a Version Stack with a single element in it. This is easy to spot -- if you
GET the Version Stack by its
id, you'll see that it has an attribute of
All of this is technically ok -- the singleton version will load and play, new versions can be added, and everything will carry on as normal; but to avoid presenting a confusing scenario for users in Frame.io's web and other applications, we recommend deleting singleton Stacks.
For more information on the Version Stacking endpoint, please refer to the Assets documentation.