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.

About the Frame.io Developer API

The Frame.io API supports creative collaboration workflows and integrations. Its operations and resource model are designed around customer workflows. Some concepts are shared with the legacy API, while others have been renamed or redesigned.

The Frame.io API models resources such as Workspaces, Files, Folders, Version Stacks, Custom Fields, and Shares. Workspaces correspond to Teams in the legacy API, while Files, Folders, and Version Stacks represent the storage entities previously grouped as Assets. The API returns a reduced set of data by default, uses consistent property names, and supports cursor-based pagination. With the exception of the Camera to Cloud (C2C) API, clients that integrate with the legacy API are not compatible with the Frame.io 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 using the API, familiarize yourself with the core concepts in the Frame.io application. The Frame.io Knowledge Base is a good place to start. Accounts, Users, Workspaces, Projects, Collections, Shares, and Custom Fields (Metadata) are modeled as distinct API resources. Understanding their relationships and capabilities in the application will help you work with them through the API.

API Overview

The Frame.io API follows RESTful architectural principles and uses standard HTTP methods and response codes with unique, resource-specific URLs. Frame.io publishes an OpenAPI 3.0 specification with detailed information about endpoints, request parameters, and responses. Third-party code-generation tools can use the specification to help build client applications.

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.

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 return large numbers of resources, such as folder or comment listings, are paginated to reduce request latency. Each response may contain only one page of results. Use the page_size query parameter to request up to 100 elements per page; the default is 50. The API uses cursor-based pagination: the links property contains a relative URL with an opaque cursor in the after query parameter. Follow this link to retrieve the next page rather than constructing the cursor yourself. Pagination is unidirectional.

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

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 API so there are no cases where partial success and errors must be handled by the client.

{
    "errors": [
        {
            "detail": "Unexpected field: foo",
            "source": {
                "pointer": "/data/foo"
            },
            "title": "Invalid value"
        }
    ]
}

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

Authentication and Authorization

The Frame.io 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 API is not backward-compatible with the legacy API and generally cannot access or update resources in legacy accounts because their concepts and data models differ. API URIs include a /v4 path prefix. The API continues to evolve, and some features may warrant breaking changes. More commonly, additions are offered as experimental endpoints so we can gather feedback and usage metrics. To support production integrations with high uptime requirements, we are designing an additional level of versioning through a custom HTTP header. This is intended to let clients opt into experimental endpoints, avoid breaking changes, and provide backward compatibility guarantees within the /v4 namespace. The API’s initial release is considered stable; details of the additional versioning mechanism are forthcoming.

Rate Limiting

All Frame.io 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 user, but the policies and limits themselves are subject to change.

The Frame.io 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 API Reference Guide is the definitive documentation for the Frame.io API. Understanding the resource hierarchy will help you make 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 Frame.io API includes a prefix that identifies the Account in which the resource resides.

Workspaces and Projects organize content and users, including access to content. Workspaces correspond to Teams in the legacy product.

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 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