Getting Started Guide

Adobe Developer Console

The first step in using an Adobe API is to create a Project in the Adobe Developer Console. Projects in the Developer Console correspond to an application you are building to consume the Frame.io Developer API. This is distinct from a Project within Frame.io.

After creating a Project in the Developer Console, add the Frame.io API to it.

What’s New in the Frame.io V4 Developer API?

Just as the Frame.io application has been completely transformed for Version 4, the V4 API has also been redesigned from the ground up. Although some key concepts remain similar to legacy versions, many have been replaced or redesigned to support more powerful collaboration workflows and integrations. The introduction of a completely new API has also provided an opportunity to drastically simplify our operations and prioritize important customer workflows.

Within the V4 API, some resources, such as Workspaces (previously referred to as Teams in the legacy version of Frame.io), have been renamed in order to match Frame.io Version 4, while others, like Assets in the legacy version, have been renamed to refer to specific storage entities (Files, Folders, and Version Stacks) in order to reduce developer confusion. Still others, for example Custom Fields and Shares, are entirely new. Among other substantial changes, we have drastically pared down the amount of data returned by default for resource requests, renamed some property names in our responses to be more accurate and consistent across the entire API surface, and switched to a new, cursor-based pagination mechanism. As such, it is important to realize that, with the exception of the Camera to Cloud (C2C) API, clients that integrate with the legacy API are not compatible with the V4 API.

Additionally, some features remain in-progress and are expected to follow and evolve quickly in response to real-world customer use cases and feedback. Examples include the ability to create custom actions and version stacks. If a feature that was previously available in our legacy API appears to be missing, it’s quite likely that there is an alternative or that it will be available soon, but we’d like to hear from you about it.

Before diving into the V4 API it is helpful to first understand the core concepts expressed in the Frame.io Version 4 application. A good place to start is the Frame.io V4 Knowledge Base. Concepts like Accounts, Users, Workspaces, Projects, Collections, Shares, and Custom Fields (Metadata) are modeled as distinct resources in the V4 API, and understanding their relationships and capabilities in the application will aid in understanding how they work in the V4 API.

API Overview

The Frame.io V4 API is designed to follow RESTful architectural principles, and uses standard HTTP methods and response codes in conjunction with unique, resource-specific URLs. Frame.io publishes an OpenAPI 3.0 specification for our V4 API, which provides detailed information about its endpoints, request parameters, and responses. The OpenAPI spec can be consumed by a variety of third-party code-generation tools to facilitate rapid client application development.

URL and Path Conventions

URL paths published in the OpenAPI specification generally reflect resource ownership and containment relationships. As such, some request parameters (e.g. account ids, folder ids, etc.) are embedded within the resource path. While these paths are intended to be predictable and easy-to-understand, the structure of some URLs returned by API requests (e.g. pre-signed upload URLs or display links) may be subject to change, and should never be composed directly by a client application.

Request Query Parameters

Request parameters that control pagination behavior and the optional inclusion of related resources in response objects are defined as a standard set of query parameters: include, page_size, include_total_count. Some requests may support additional query parameters that are specific to that resource or operation.

1
GET https://api.frame.io/v4/accounts/{account_id}/folders/{folder_id}/children?&include=project&page_size=5&include_total_count=true

Request and Response Payloads

Request and response payloads both are composed as JSON objects, and, as such, the content-type header of an HTTP POST, PUT, or PATCH request must specify the application/json media type. When creating or updating resources, the data property of the request must contain the resource object. Attributes of the resource being created or updated are contained within this object. Similarly, successful responses that include resources will provide these within the data property of the response.

Pagination

Responses that may potentially return large numbers of resource objects (e.g folder or comment listings) are paginated in order to reduce request latency as a result set grows large.. This means that the response to a request may only include a single “page” of results. As mentioned above, a client may choose a specific page size, up to a maximum of 100 elements through the page_size query parameter when making the request. If left unspecified, the page size will default to 50 elements. The V4 API uses a form of pagination known as cursor-based pagination and includes a relative link in the links property of the response object (see example below) that contains an opaque (clients should not attempt to construct this string themselves) cursor string in the after query parameter, which allows the client to retrieve the next page of results (see example response below) by making subsequent requests. At present, the V4 API only supports unidirectional pagination.

1
{
2
    "data": [
3
        {
4
            "created_at": "2024-10-02T00:22:44.887775Z",
5
            "creator_id": "8ea72912-d40d-4b88-8d31-3762e055a2aa",
6
            "file_size": 102432,
7
            "id": "df171f3e-c95f-4454-9071-825cd924b572",
8
            "media_type": "application/pdf",
9
            "name": "sample.pdf",
10
            "parent_id": "e183c7ba-07d9-425a-9467-ebdf0223d9ce",
11
            "project": {
12
                "created_at": "2024-08-21T17:45:41.881596Z",
13
                "description": "For demonstration purposes",
14
                "id": "976dd413-a92b-4af6-b465-98aded0174a8",
15
                "name": "Demo Project",
16
                "owner_id": "8ea72912-d40d-4b88-8d31-3762e055a2aa",
17
                "root_folder_id": "e183c7ba-07d9-425a-9467-ebdf0223d9ce",
18
                "storage": 20881946,
19
                "updated_at": "2024-10-02T00:22:47.168489Z",
20
                "workspace_id": "378fcbf7-6f88-4224-8139-6a743ed940b2"
21
            },
22
            "project_id": "976dd413-a92b-4af6-b465-98aded0174a8",
23
            "status": "created",
24
            "type": "file",
25
            "updated_at": "2024-10-02T00:22:44.927993Z"
26
        }
27
    ],
28
    "links": {
29
        "next": "/v4/accounts/6f70f1bd-7e89-4a7e-b4d3-7e576585a181/folders/e183c7ba-07d9-425a-9467-ebdf0223d9ce/children?after=g3QAAAACZAAGb2Zmc2V0YQVkAAR0eXBlZAANb2Zmc2V0X2N1cnNvcg%3D%3D"
30
    },
31
    "total_count": 21
32
}

Errors

In the event that an error occurs, the errors property in the response object will contain an array of one or more error objects that provide details about the error(s) that occurred. At present, batch operations are not supported by the V4 API so there are no cases where partial success and errors must be handled by the client.

1
{
2
    "errors": [
3
        {
4
            "detail": "Unexpected field: foo",
5
            "source": {
6
                "pointer": "/data/foo"
7
            },
8
            "title": "Invalid value"
9
        }
10
    ]
11
}

The following table lists common status codes used by the V4 API.

Authentication and Authorization

The V4 API relies on OAuth 2.0 and Adobe Identity Management Server (IMS) to authenticate a user (AuthN) and generate access tokens on behalf of that user. An access token must be provided with each API request via the HTTP Authorization header (i.e. Bearer token authentication).

Versions and Backward-Compatibility

The Frame.io V4 API is not backward-compatible with earlier versions of Frame.io APIs and, generally, cannot be used to access or update resources contained within legacy accounts as there have been significant changes to the V4 concepts and data model. As such, the URIs associated with the V4 API all include a /v4 path prefix. However, the V4 API is still evolving quickly and it is possible that new features may occasionally warrant breaking changes. More commonly, Frame.io will release new additions to the API that we consider to be experimental for some period of time, allowing us to receive and respond to customer feedback and usage metrics. Recognizing that backward-compatibility is a major concern for customers managing production-quality integrations with high uptime requirements, we are designing the V4 API to support an additional level of versioning via a custom HTTP header in order to allow clients to opt into using experimental endpoints, avoid breaking changes, and provide backward-compatibility guarantees within the V4 namespace. More details are forthcoming, but for now it is safe to assume that the initial release of the V4 API is considered to be stable and that it will be some time before we contemplate introducing breaking changes.

Rate Limiting

All V4 API calls are rate-limited, and each API resource and operation is configured with its own limit, The limits range from as low as 10 requests per minute to as high as 100 requests per second. At present, each limit is enforced by account, but the policies and limits themselves are subject to change.

The V4 API uses a “leaky bucket” algorithm 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. Requests that exceed the rate limit for a particular endpoint will fail with a 429 HTTP error.

Our recommended strategy for responding to 429 errors is usually referred to as “exponential back-off.” In short:

• When receiving a 429, pause for a period (at least one second) before retrying the request
• If another 429 is received, exponentially increase, or at least double, the previous wait period until normal function resumes

In order to determine the rate limits that apply to a particular request, clients may inspect the the following HTTP headers returned in the response:

API Details

The definitive documentation to the V4 API is our API Reference Guide, but understanding the resource hierarchy as modeled by the V4 API will be helpful before issuing your first requests.

Resource Hierarchy

An Account is typically associated with an organization and represents the fundamental resource that determines a subscription plan, content ownership, user roles / permissions, and Workspace organization. As such, the URL path to almost all of the endpoints in the V4 API include a prefix that identifies the Account in which the resource resides.

Workspaces (previously called Teams in the legacy version of Frame.io) and Projects are used to organize both content and users, including who has access to what content.

The basic hierarchy of content resources within Frame.io is as follows:

Every asset uploaded to Frame.io is ultimately represented as a File, while Folders and Version Stacks are storage resources that act as containers and provide the foundation for a hierarchical storage model that supports versioned assets. Most users are already familiar with the basic concept of a Folder in Frame.io: it simply serves as unordered container of other storage resources (modeled as its children) and represents a node within the folder tree. Every Project has a unique root folder (identified by the root_folder_id key), which serves as the root of the folder tree in which all of a Project’s assets reside.

A Version Stack is an ordered container of Files. Its ordering is strictly linear and determines a version number for each of its children, but clients may reorder the Files within the version stack as they see fit. A File will always be a child of (contained within) exactly one Folder or Version Stack at any given time. Similarly, a Folder or Version Stack will always be a child of exactly one Folder (excluding the Project’s root folder).

See the API Reference Guide for more detail about performing basic CRUD operations on Files and Folders stored within Frame.io. At present the V4 API only supports Version Stacks when listing the contents of a Folder, but endpoints for creating and updating Version Stacks are coming soon.

SDKs

SDKs are available for TypeScript and Python. You can install them using the commands below. The SDK Reference section of the documentation has full references for the Python and TypeScript SDKs.

TypeScript

$
npm i -s frameio

View on npm

Python

$
pip install frameio

View on PyPi