Frame.io API (2.0.0)

Not every creative team, process, or software stack is exactly the same. That's where our Developer Platform comes in. The Frame.io Developer Platform allows you to handle common tasks using our API. Some popular use cases developers have used our API for include automatically adding existing files or folders to the Frame.io app, uploading new content, and managing teams.

Camera to Cloud is a unique type of integration. These integrations are purpose built for any device or application that is generating data. If you are building a C2C integration then you will want to use the C2C Integration guides. There you can find all the information you need to get started connecting to the cloud with Frame.io!

• Python SDK: Frame.io offers an SDK in Python to make getting started with our API easier, including abstraction of key concepts like pagination and rate limiting. This project is available on PyPI, so pip install frameioclient and off you go!
• Python CLI: If you'd prefer to work from the command line FIOCTL is also available on PyPI.

If you want to get started right away, just click this button to bring our API into Postman!

Otherwise, read on. As a starting point, you'll need to ensure that you have a Frame.io account that you can sign in with.

From there:

• Sign into the Developer Portal using your Frame.io credentials
• Create a Developer Token

To confirm that your token is working, go ahead and make a test call using a language, tool, or proxy of your choice:

curl --request GET \
    --url https://api.frame.io/v2/me \
    --header 'authorization: Bearer <DEV_TOKEN>'

import requests

url = "https://api.frame.io/v2/me"
headers = {
"Authorization": "Bearer <DEV_TOKEN>"
}

requests.GET(url,headers=headers)

In response, you should see your user information.

The Frame.io API may return the following common errors:

HTTP Status	Details	Reason(s)
401	Unauthorized	Invalid API token. Check to make sure you're using Bearer Token authentication, and passing your token via the Authorization header.
402	Usage exceeded	You have gone over your Frame.io plan limits.
403	Forbidden	You do not have access to that resource. Returned for both user access and token scope.
404	Not Found	Resource has been moved or deleted.
409	Conflict	That resource already exists.
422	Invalid arguments	One or more parameters supplied were invalid.
429	Rate Limited	You have hit the rate limit for the API.
500	Server Error	Our server doesn't know how to interpret your request, or was unable to complete your request within the available timeframe (30 seconds).

When using a valid API token to perform common tasks, the most common errors are 403, 404 and 500.

A 403 error will usually indicate one of three scenarios:

1. The token used in the request, and/or the User to which the token belongs, does not have sufficient access to the area of the Frame.io Account where the resource was requested.
2. The token does not have sufficient Scopes for the resource requested. For example: calling GET /comments/ without the comments.read scope.
3. A network traffic problem is preventing the Frame.io API from processing the request. If you suspect your requests are being blocked by a network traffic problem, please contact Customer Support.

A 404 error will usually indicate a resource no longer exists -- it has been moved or deleted.

A 500 error usually indicates a malformed request URL or body, but could also happen when we're unable to complete the request within the available timeframe (30s).

Whether you're using a Developer Token, accessing via an OAuth App, or you're interacting with our API using any of our internal apps, all API calls to Frame.io are rate limited.

Rate limits apply are applied across any and all API requests from an individual user (irrespective of which token or auth method is used), are depleted and refilled progressively, and are reflected in the response headers of every request made to the Frame.io API. Each endpoint is configured with its own limits, which range from as low as 10 requests/minute, to as high as 100 requests/second.

Requests that have exceeded the rate limit for a particular endpoint will receive a 429 HTTP error in response.

Limit depletion and refill

The Frame.io API uses a leaky bucket strategy of progressive rate limiting, in which limits refresh gradually during their allotted time window. In other words, there is not a concept of any hard cutoff after which limits refresh for a particular resource (i.e. "fixed" and "sliding window" enforcement strategies). Rather, remaining limits are constantly refreshing at a pace relative to a resource's limit and time window.

Exponential backoff

Our recommended strategy for managing rate limits is usually referred to as "exponential backoff."

In short:

• When receiving a 429, pause for a period (normally one second)
• If another 429 is received, exponentially increase the wait period until normal function resumes

Headers

Responses to API requests will always include the following three headers that should be utilized to limit your outbound requests:

Header	Value
x-ratelimit-limit	The rate limit for this resource path, measured in requests.
x-ratelimit-remaining	The number of requests remaining in the current time window.
x-ratelimit-window	The time window for this resource path's limits, measured in milliseconds (ms).

Example

The following example is from the response to GET v2/assets/:id/children, to fetch the child assets of a Project root, folder, or Version Stack. The limit for that path is 40 requests per 60,000 ms (one minute), and there are 39 requests remaining after one has been made.

x-ratelimit-limit → 40
x-ratelimit-remaining → 39
x-ratelimit-window → 60000

Details

Rate limits vary greatly across resource paths in the Frame.io API. Below are some select details, expressed for readability as resource and action (e.g. "Assets -- Update" instead of PUT /assets/:id).

As a general rule, resource paths that create new data are limited at or below 100 calls per minute, and resource paths that fetch lists of assets are limited to 200 calls per minute.

Resource	Action	Limit (requests)	Limit window (ms)
Assets	create	5	1,000
Assets	update	10	1,000
Assets	read	5	1,000
Comments Presentations Projects Review Links Teams Team Members	create	100	60,000
Search	read	200	60,000