Overview

Whether the end goal is publishing, editing, or simply pushing Assets into Frame.io for review, the first step to the majority of useful OAuth App integrations with Frame.io will involve listing out a user’s context, and ultimately, a directory view.

The basic hierarchy of a Frame.io account context goes like so:

• Account
  • Team
    • Project
      • Assets

Accordingly, that’s the hierarchy we’ll be building out with sequential API calls. And then once we’re inside a project, we’ll list out folders, and inside of them, Assets and Version Stacks.

There’s only one potential wrinkle before we get started:

Shared projects

One of the key user roles in Frame.io is the Collaborator — a User with Project access who may or may not belong to that Project’s owning organization.

Leaving aside the permissions / allowed actions side of the conversation, the key difference between a Team Member and a Collaborator is that a Collaborator’s membership is strictly to a Project, and not necessarily to a Team. This presents a small wrinkle for directory listings.

While the basic hierarchy above (Account > Team > Project > Assets) should work for the majority of use cases, it won’t include the list of Projects on which an authenticated user is a Collaborator, but not a Team Member.

To steer around this when listing directories, you can either:

• Fetch a User’s shared projects, unpack the Team and Account hierarchy, and zip it all together, or
• Fetch a User’s shared projects, and list them all together as a separate context.

Either method is fine; the latter is a bit easier, but the former is closer to how Frame.io's web app presents similar information. In any case, the methods covered in this guide apply to both.

📘

Note: single user context

This guide assumes you’re working within the context of a single user’s permissions — either your own via token, or a logged in user’s via OAuth grant.

Building out the directory structure

1) Fetch the user’s accounts

GET https://api.frame.io/v2/accounts

To get a User’s Accounts, make the above call with a valid bearer token. In response, you’ll get a list of every Account on which the user has Team Member or Team Manager access to at least one Team. You may also receive Teams for which a user has billing/Admin rights, but no Team access, but this is rare, and will be washed out in the next step.

While the full payload for a Frame.io Account is fairly verbose, the most important pieces of information you’ll want to grab for each Account are:

• id
• display_name
• owner
  • email
  • name
• (optionally) image

Of the above non-id fields, only owner.email is required, so that batch will give you enough context to apply a bit of conditional logic for presenting Accounts. Our recommendation is to check, and if not null, display the Account with the following order of preference:

1. "display_name"
2. "owner.name's Account"
3. "owner.email's Account"

Once your user chooses an Account, you can fetch the Teams.

📘

Account Images are temporary URLs

Note: the Account’s image returned by our API will be a pre-signed S3 key, so the URL returned will “die” after about a day. To work around this, you should either re-fetch the image every time your service loads, or ideally, store it locally.

2) Fetch the Account’s Teams

GET https://api.frame.io/v2/accounts/{{account_id}}/teams

Teams in Frame.io may be “public” (discoverable to any Team Member in the Account), or “private” (discoverable only to specific Team Members). The good news is, the Frame.io API will handle all of that, so all you need to do, given an account_id, is make the above call with a valid bearer token.

In response, you’ll receive a list of Teams.

📘

Don't forget to paginate

While it’s unlikely that a user will be on more than a few Accounts, Teams are a resource that can scale pretty quickly. While the Frame.io API's default limits are fairly high, it's always good to check response headers, and if necessary, paginate.

You can find more info on pagination by reading Pagination and Errors.

From each Team, grab the following attributes:

• id
• name
• (optionally) team_image

Now, when a Team is selected, you’ll want to get all its constituent Projects.

Note: if you wish, you may also GET https://api.frame.io/v2/teams for a user, and our API will return every Team a user belongs to, regardless of Account context. While this will technically work, it runs the risk of looking a little messy unless you:

1. Reestablish context by reflecting the Account name next to each Team
2. Ideally, allow your user to search the text of the list

If you're going to list out shared Projects from the Account level down, this is when you'll want to start that ball rolling by calling GET https://api.frame.io/v2/projects/shared. Each Project response in that list will have the following attributes, which you can carry forward as your build your directory:

• id (of the Project itself)
• team_id
• team.account_id

Alternatively, this is where you can make an affordance for "Shared Projects" simply by adding it as a "Team" on any chosen Account context. If you do choose to do that, it's helpful to the end user if you visually separate Shared Projects from true Team-scoped Projects, as the single Shared Projects list may include many different true Account and Team contexts under the hood.

3) Fetch the Team’s Projects

GET https://api.frame.io/v2/teams/{{team_id}}/projects

Now that you’re in a Team, the next step is to make the above call (with a valid bearer token), and fetch all the Projects within the Team.

For each Project, you’ll want to grab:

• id
• name
• root_asset_id
• (optionally) private, in case you want to differentiate for the user in your UI

The root_asset_id is an important piece of Frame.io’s resource architecture: it’s essentially a dummy Asset that stands in for the root of a Project, and enables you to easily recurse through a folder structure.

And that is exactly what we’re going to do next!

Listing folders and assets

To quickly recap — if we’ve gotten this far, it means we’ve established the combined context of:

• Account
• Team
• Team Projects (and root_asset_ids)
• Shared Projects (and root_asset_ids)

And that’s all we need to create or fetch an Asset.

4) Build the initial folder structure

GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder

This will list out all the folders in a project, starting from the root_asset_id. If there are no folders, you’ll get back an empty list. If you want to include both files and folders (e.g. if your next step would be to GET an Asset from Frame.io, simply omit the query string parameter.

The other two filter options available for the type parameter are file and version_stack. All three filters are mutually exclusive, and an unfiltered call will return all three types mixed together.

5) Dig through the directory tree

For each folder that comes back, you’ll need to capture:

• id
• name

As each folder is an Asset, your workflow for drilling through a folder structure will look like this:

1. GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder
   1. Render out the folder names in a list
   2. When a user clicks on a folder pass the folder’s id into the following query:
2. GET https://api.frame.io/v2/assets/{{folder_id}}/children?type=folder

6) Create and upload

Into a folder:
POST https://api.frame.io/v2/{{folder_id}}/children

Once you have the id of the folder you’d like to upload into, simply make a POST to its children, per the resource documentation and guide. This will create a placeholder Asset, and (depending on the method you choose), return:

• An id that you can use for tracking
• (If you’re loading a local file) a list of one or more upload_urls that you can use to PUT your file directly to Frame.io's S3 bucket.

That’s it! You’re done!

Into a Version Stack:
Version Stacks present a similar workflow, with one added step covered in this guide, summarized below. The keys are remembering that a Version Stack is a container that looks like an Asset, but behaves like a folder; and that you have to upload your Asset first, and then stack it into your Version Stack as separate actions.

Accordingly, if you want to upload an Asset into a Version Stack, you’ll need:

• The Version Stack’s id
• The Version Stack’s parent_id (e.g. its containing folder or Project root)

First, POST https://api.frame.io/v2/assets/{{parent_id}}/children to create your new Asset. Capture the new id in your response.

Now, you can use your new Asset’s id and POST https://api.frame.io/v2/assets/{{version_stack_id}}/version, with a body payload of:

{
"next_asset_id": "<new-asset-id>"
}

And you’re done!