API API Documentation

Welcome to's official documentation portal.In here, you'll find everything you need to:

Get up and running with's public API 🤙
Leverage powerful features like Webhooks and Custom Actions 🚀
Build your own OAuth2.0 app 🚢

Get Started    Guides

Upload an Asset to uses accelerated multipart upload. This guide walks through the process of uploading an Asset via API with full Account, Team, and Project context.


This tutorial covers how to upload assets into can handle all file types, not just video, but also scripts, pictures, maps, and reference files. In more technical terms, an asset in is a robust representation of a file in S3 and its context in, including transcodes, user/team/project context, and metadata. For more information about assets, please refer to the resource definition.​

Core hierarchies

It's also helpful to know how structures its core models.

Accounts, to which Users belong, have many Projects, which all contain Assets. Teams are available to Enterprise accounts only, and provide an additional level of logical separation. Assets do not "know" which Team they belong to -- only which Project and Account -- but Projects are strictly owned by Teams, and not Accounts, making Teams an integral part of the Asset upload process.


For this tutorial, you'll need:

Upload an Asset

This section walks you through the steps for uploading an asset.

  1. Create a developer token at with the following scopes:



Accounts: Read

Fetch the Account list for the requesting User.

Teams: Read

Fetch available Teams for the desired Account.

Projects: Read

Fetch available Projects for the desired Team.

Assets: Create, Read

Create the new Asset record, and fetch available Assets to traverse the folder structure within the Project.

If you need help setting up your token, you can review the instructions for it here - Get a Developer Token.

  1. Locate a destination for your asset. At minimum, an asset needs to be placed within a Project. You'll need to retrieve the root asset ID (root_asset_id) for a project or an asset ID for a folder so you can specify to the API where you want to upload to.



You cannot upload with a project ID.

You can review how to retrieve the ID you'll need here: Find and use the Root Asset ID for a Project . In general you need to retrieve (in the order specified):

  • account ID(s) and choose an account
  • team ID(s) and choose a team
  • projects associated with a team
  • the project ID for the project you want to work with
  • the root asset ID or a folder ID

You can upload directly into the root of a project using the root_asset_id.

List Assets

To choose where you want to upload your new asset to, you can use the API to list all assets in a project or folder within a project. If an asset is a folder, it will contain child assets, which can also be files and folders. When listing assets information, you can use any asset ID, but if you want to review everything associated with a project, use the root_asset_id.

curl --request GET \
  --url<ROOT_ASSET_ID>/children \
  --header 'authorization: Bearer <DEV_TOKEN>'
from frameioclient import FrameioClient
import os

TOKEN = ""

client = FrameioClient(TOKEN)
response_list = client.get_asset_children(ASSET_ID)
assets = response_list.results

for item in assets:
    print(item['id'], item['name'])

From the returned list of assets, you can use an ID for any asset that is a folder, or the root asset ID. You will use this ID to mark where you want to upload your new asset to.

Upload Asset

In this example, we are going to upload a new file. You send your request with the following information:




Enter the size of the file you want to upload


Choose the type of file you're uploading. Choices include video and image. Examples: video/mp4, image/png


Enter a string representing the file's name, with no spaces.


This represents whether you're using a file or a folder. A version stack is when you stack several files onto one another.

If you want to create a new folder, then you do not need to retrieve the filesize, or include filesize or filetype in your request.

For a cURL request, you can quickly upload an asset into by including a link to your file using the "source": { "url":"URL_FOR_VIDEO" } parameter. The link must be publicly accessible. Otherwise, you can use the Python SDK, which handles breaking your file into a chunk for each upload link for you.

curl --request POST \
  --url<ASSET_ID>/children \
  --header 'authorization: Bearer <DEV_TOKEN>' \
  --header 'content-type: application/json' \
  --data '{"filesize":200000,"filetype":"video/mp4","name":"test","source":{"url":"URL_FOR_VIDEO"},"type":"file"}'
filesize = os.path.getsize("Test123.mp4")

asset = client.create_asset(

 # Continued from Python code sample in previous step. 
file = open('Test123.mp4', 'rb')
client.upload(asset, file)
asset = client.create_asset(
  name="My Awesome Folder",


Asset URLs are timed

Upload URLs are signed and expire after 48 hours.

Build your own file uploader

If you want to build your own uploader, for best performance, it's recommended to upload chunks in parallel. Each chunk should be PUT directly to the Amazon S3 urls provided in the response from the API.

Your file chunks must match the order of the provided upload_urls, as they dictate the sequence of the final concatenated and transcoded asset. This means the 1st URL takes the 1st chunk, 2nd URL takes the 2nd chunk, and so on.

The headers for each request to S3 should include the filetype of your new Asset exactly as it's been returned from your initial call to the API, as well as an additional privacy header:

PUT https://frameio-uploads-production.s3/etc/etc
Content-Type: video/mp4
x-amz-acl: private

You can see an example of how this is all handled in our Python SDK here:


AWS errors are all XML

Please note that any errors you get at this stage will be coming from AWS directly, and therefore will be formatted as XML, and not's standard JSON error handling. We generally recommend building retry logic around these uploads for any production usage, as files incompletely-uploaded files (i.e. files with missing chunks) will fail to transcode and display in

That's it! Once you've completed the PUT calls to the upload_urls, you'll have a new Asset in

Updated 7 months ago

Upload an Asset to uses accelerated multipart upload. This guide walks through the process of uploading an Asset via API with full Account, Team, and Project context.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.