Resources

Frame.io Legacy API to V4 Migration Guide

Introduction

The Frame.io V4 API is a complete redesign of the Legacy API, often referred to as V2 endpoints or Frame.io V3 API. The redesign takes full advantage of the new capabilities and features of Frame V4 and is not backward compatible. This guide outlines the key differences between the Legacy and V4 APIs and provides step-by-step guidance to help you migrate smoothly.

Key Differences

API Management

The V4 APIs are managed through the Adobe Developer Console, whereas the Legacy API was managed in the Frame.io developer site.

Resource Structure

Assets → Folders & Files: Distinct endpoints for files and folders in V4, unlike unified asset endpoints in Legacy.

Authentication

The V4 API exclusively uses OAuth2.0 (authorization_code grant type). The Legacy API which allowed for JWT auth and Developer Tokens are no longer supported.

Feature Parity

Some specialized legacy calls are not yet supported in V4.

Sharing Model

Review and Presentation links → Share links: Review and presentation links have been consolidated into a single “share link” in V4 with support for different custom branding options.

Team Structure

Teams → Workspaces: “Team” endpoints in the Legacy API have been replaced by “Workspace” endpoints in V4.

Migration Checklist

1

Audit Existing API Calls

Audit existing Legacy API calls. Compare existing calls to the tables below. If an endpoint you use is not in this list, it does not yet exist in V4—please submit your feedback via this form.

2

Implement OAuth2.0

Implement OAuth2.0 via the Adobe developer console. Legacy Frame.io developer tokens and existing OAuth apps managed via developer.frame.io will not work on V4 accounts.

3

Refactor Code

Refactor your code. Use the new V4 API routes and JSON payloads (e.g., files/folders vs. assets).

4

Test Thoroughly

Test thoroughly. Test with a V4 account, focusing on uploads, comments, and webhooks.

5

Remove Legacy Code

Remove legacy code paths. Remove any code paths that leverage Legacy API endpoints as they will fail in V4.

6

Implement Dedicated Login

Implement a dedicated login method for V4 due to separate Auth URLs. Since the V4 Auth URL is different than the Legacy API, it will not return Legacy accounts in the response and should be treated as a separate integration.

This list is not exhaustive of the direct correlation of Legacy APIs to the V4 APIs and will be updated regularly as new endpoints are released, potentially via Experimental version. If there is an endpoint that is not listed here that you have questions about, please reach out to our support team for more at support@frame.io.

Authentication

1

Create Adobe Project

Create a project in the Adobe Developer Console and add Frame.io as a product.

2

Choose Authentication Type

Authenticate. See the Authentication Guide for more information.

  • User authentication: Connects to Frame using a Client ID and/or Client Secret, and requires a user to login with their username and password.
  • Server to server authentication: Connects to Frame using Client ID and Client Secret, but does not require a user in the loop to login via a browser.
3

Implement Bearer Auth

JWT Bearer Auth: For every API request, pass the auth token via a header with key Authorization and a value of Bearer <IMS_ACCESS_TOKEN>.

Endpoint Mappings (Legacy API to V4)

The table below only includes Legacy API endpoints that do have a V4 equivalent. If you don’t see your Legacy API call here, it’s likely deprecated with no direct migration path.

1. Accounts & User Info

Legacy MethodLegacy EndpointV4 MethodV4 EndpointNotes
GET/v2/accounts
(Get Accounts for User)		GET/v4/accounts
(List accounts)		V4 returns all accounts the user can access.
GET/v2/accounts/{account_id}GET/v4/accounts/{account_id}Does not exist in V4
Retrieves info about a specific account. In V4, references to “teams” are replaced by “workspaces.”
GET/v2/meGET/v4/meFetch current user’s profile.

2. Workspaces (Replaced Team Endpoints)

Legacy MethodLegacy EndpointV4 MethodV4 EndpointNotes
GET/v2/accounts/{account_id}/teams
(Get all Teams on an Account)		GET/v4/accounts/{account_id}/workspaces
(List workspaces)		Legacy API concept of “teams” → “workspaces” in V4.
POST/v2/accounts/{account_id}/teams
(Create a Team for the given account)		POST/v4/accounts/{account_id}/workspaces
(Create workspace)		Body is similar (name, etc.). Response is a workspace object, not a team object.
GET/v2/teams/{team_id}
(Get a Team)		GET/v4/accounts/{account_id}/workspaces/{workspace_id}
(Show Workspace)		Team ID → Workspace ID in V4.
GET/v2/teams/{team_id}/members
(Get Team Members)		GET/v4/accounts/{account_id}/workspaces/{workspace_id}/users
(Get Workspace Members)		Returns all users in a workspace (available in the experimental API)
POST/v2/teams/{team_id}/members
(Add a Team Member))		PATCH/v4/accounts/{account_id}/workspaces/{workspace_id}/users/{user_id}
(Add Or Update User Role In Workspace)		Allows for adding or removing users from a workspace (available in the experimental API)

3. Projects

Legacy MethodLegacy EndpointV4 MethodV4 EndpointNotes
GET/v2/teams/{team_id}/projects
(Get Projects by Team)		GET/v4/accounts/{account_id}/workspaces/{workspace_id}/projects
(List Projects)		Must provide both account_id & workspace_id in V4.
POST/v2/teams/{team_id}/projects
(Create a Project)		POST/v4/accounts/{account_id}/workspaces/{workspace_id}/projects
(Create project)		Body is similar: { "name": "MyProject", ... }.
GET/v2/projects/{project_id}
(Get Project by ID)		GET/v4/accounts/{account_id}/projects/{project_id}
(Show project)		Requires account_id & project_id
PUT/v2/projects/{project_id}
(Update a Project)		PATCH/v4/accounts/{account_id}/workspaces/{workspace_id}/projects/{project_id}
(Update project)		V4 uses PATCH for partial updates.
DELETE/v2/projects/{project_id}
(Delete Project by ID)		DELETE/v4/accounts/{account_id}/workspaces/{workspace_id}/projects/{project_id}
(Delete Project)		Removes project.
GET/v2/projects/{project_id}/collaborators
(Get Project Collaborators)		GET/v4/accounts/{account_id}/projects/{project_id}/usersReturns all the users in a project (available in the V4 experimental API)
POST/v2/projects/{project_id}/collaborators
(Add a Collaborator to a Project)		PATH/v4/accounts/{account_id}/projects/{project_id}/users/{user_id}Allows for adding or removing users from a project (available in the V4 experimental API)

4. Folders

Legacy MethodLegacy EndpointV4 MethodV4 EndpointNotes
GET/v2/assets/{asset_id}/children
(Fetch child Assets)		GET/v4/accounts/{account_id}/folders/{folder_id}/children
(List folder children)		If your asset_id in Legacy API was a folder, it’s now folder_id in V4.
POST/v2/assets/{parent_asset_id}/children
(Create an Asset)		POST/v4/accounts/{account_id}/folders/{folder_id}/folders
(Create folder)		In Legacy API you used "type": "folder", in V4 you do {"data": {"name": "Folder name"}}.
GET/v2/assets/{asset_id}
(Get an Asset)		GET/v4/accounts/{account_id}/folders/{folder_id}
(Show folder)		Legacy API requires “type”: “folder”
V4 API requires folder_id & account_id in path parameters
PUT/v2/assets/{asset_id} (Update an Asset)PATCH/v4/accounts/{account_id}/folders/{folder_id}
(Update folder)		Legacy API: asset_id will be your folder id
V4 API: Body: {"data": {"name": "New Folder Name"}}.
DELETE/v2/assets/{asset_id}
(Delete an Asset)		DELETE/v4/accounts/{account_id}/folders/{folder_id}
(Delete folder)		Removes folder.

5. Files

Legacy MethodLegacy EndpointV4 MethodV4 EndpointNotes
POST/v2/assets/{parent_asset_id}/children
(Create an Asset)		POST/v4/accounts/{account_id}/folders/{folder_id}/files
(Create file)		Legacy API: requires name, type, filetype, filesize, & auto_version_id
V4 API: account_id & folder_id are required in the path parameters, file_size, media_type_name required on payload
GET/v2/assets/{asset_id}
(Get an Asset)		GET/v4/accounts/{account_id}/files/{file_id}
(Show file)		V4 API: api-version:experimental is required to return media_links in response to enable downloading assets from Frame.io
PUT/v2/assets/{asset_id}
(Update an Asset)		PATCH/v4/accounts/{account_id}/files/{file_id}
(Update file)		Requires api-version:experimental for V4
DELETE/v2/assets/{asset_id}
(Delete an Asset)		DELETE/v4/accounts/{account_id}/files/{file_id}
(Delete file)		204 No Content on success.
POST/v2/assets/{asset_id}/version
(Version an Asset)		POST/v4/accounts/{account_id}/folders/{folder_id}/version_stacks
(Create version stack)		Requires api-version:experimental for V4

6. Comments

Initial support for Commenting endpoints has been released. There are several additional capabilities that will be released soon. Support for coming soon capabilities includes:

Coming Soon Features:

  • Range-based comments
  • Leaving comment replies
  • Comment attachments
  • Comment reactions, i.e. emojis
  • Viewing or modifying comment completion status
  • Hyperlinks or @mentions (comment entities)
  • Seeing who has viewed a comment (impressions)

The “timestamp” field represents the framestamp the comment is left on (starting from 1), not the timestamp

Legacy MethodLegacy EndpointV4 MethodV4 EndpointNotes
GET/v2/assets/{asset_id}/comments
(Get all the Comments and Replies from a Comment thread)		GET/v4/accounts/{account_id}/files/{file_id}/comments
(List comments)		Lists comments on a file.
POST/v2/assets/{asset_id}/comments
(Create a Comment)		POST/v4/accounts/{account_id}/files/{asset_id}/comments
(Create comment)		Create a comment. Body is similar: {"text":"Nice","timestamp":12.3}.
GET/v2/comments/{comment_id}
(Get a Comment by ID)		GET/v4/accounts/{account_id}/comments/{comment_id}
(Show comment)		Fetch single comment by ID.
PUT/v2/comments/{comment_id}
(Update a Comment)		PATCH/v4/accounts/{account_id}/comments/{comment_id}
(Update comment)		Update text, time, etc.
DELETE/v2/comments/{comment_id}
(Delete a Comment)		DELETE/v4/accounts/{account_id}/comments/{comment_id}
(Delete comment)		Remove comment.

7. Shares (Review Links / Presentations)

In Frame V4 share links are no longer split between review and presentation links. In V4 the same link can now be configured with different styling to match the review or presentation experience.

Legacy MethodLegacy EndpointV4 MethodV4 EndpointNotes
GET/v2/projects/{project_id}/review_links
(List Review Links in a project)		GET/v4/accounts/{account_id}/projects/{project_id}/shares
(List shares)		Lists shares in a project
POST/v2/projects/{project_id}/review_links
(Create a Review Link))		POST/v4/accounts/{account_id}/projects/{project_id}/shares
(Create share)		Creates a new share link. Body might be {"data":{"name":"Review Link","type":"review"}}.
POST/v2/review_links/{link_id}/assets
(Add Asset to a Review Link)		POST/v4/accounts/{account_id}/shares/{share_id}/assets
(Add new asset to share)		Unclear if this supports files, folders, version stacks, etc - the API reference should be updated to clarify that
DELETEDoes not existDELETE/v4/accounts/{account_id}/shares/{share_id}/assets/{asset_id}
(Delete Share)		Remove asset from share
DELETE/v2/review_links/{link_id}
(Delete a Review Link)		DELETE/v4/accounts/{account_id}/shares/{share_id}
(Delete Share)		Delete the share link.
PUT/v2/review_links/{review_link_id}
(Update a Review Link)		PATCH/v4/accounts/{account_id}/shares/{share_id}
(Update Share)		Update the share link

8. Webhooks

Given the many changes to resources in Frame.io V4, and the experimental state of Webhooks for V4, the number of supported “events” that you trigger Webhooks off of is very different.

Legacy MethodLegacy EndpointV4 MethodV4 EndpointNotes
POST/v2/teams/{team_id}/hooks
(Create Webhook)		POST/v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks
(Create Webhook)		Provide {"data":{"url":"...","events":["file.created",...]}}.
N/AN/AGET/v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks
(Get List)		Gets all webhooks for workspace
GET/v2/hooks/{hook_id}
(Get Webhook)		GET/v4/accounts/{account_id}/webhooks/{webhook_id}
(Get Webhook)		Get webhook info
PUT/v2/hooks/{hook_id}
(Update Webhook)		PATCH/v4/accounts/{account_id}webhooks/{webhook_id}
(Update Webhook)		Update webhook settings
DELETE/v2/hooks/{hook_id}
(Delete Webhook)		DELETE/v4/accounts/{account_id}/webhooks{webhook_id}
(Delete Webhook)		Removes the webhook.

9. Custom Actions

Legacy MethodLegacy EndpointV4 MethodV4 EndpointNotes
POST/v2/teams/{team_id}/actions (Create a Custom Action)POST/v4/accounts/{account_id}/workspaces/{workspace_id}/actions (Create Custom Action)Create a custom action in a workspace.
DELETE/v2/actions/{action_id} (Delete a Custom Action)DELETE/v4/accounts/{account_id}/actions/{action_id} (Delete Custom ActionDelete a custom action.
PUTv2/actions/{action_id} (Update a Custom Action)PATCH/v4/accounts/{account_id}/actions/{action_id} (Update Custom Action)Update custom action details.
GET/v2/teams/{team_id}/actions (Get Custom Actions for a Team)GETGET /v4/accounts/{account_id}/workspaces/{workspace_id}/actions (List Custom Actions)List Custom Actions in a given Workspace.
GET/v2/actions/{action_id} (Get a Custom Action by ID)GET/v4/accounts/{account_id}/actions/{action_id} (Show Custom Action Details)Show custom action details.

Migration Steps

1

Remove Unsupported Endpoints

Remove any unsupported Legacy endpoints.

2

Create Adobe Project

Create a new Project in Adobe Developer Console, choose your user authentication type, & implement OAuth support in your app.

3

Update Base URLs

Update base URLs from api.frame.io/v2/... to api.frame.io/v4/....

4

Update API Requests

Update API requests in your code to reference the new endpoints schema.

5

Update JSON Payloads

Update JSON payloads of request/response schemas to ensure you’re producing and consuming the correct fields.

6

Update Terminology

Update terminology: “teams” → “workspaces”; “assets” → “files/folders”; “review links” or “presentation links” → “shares” in your code and your front-end.

7

Test Endpoints

Test all newly updated endpoints. If you see 403, 404, 422, confirm endpoints, request payload shape, etc.

8

Parse Error Responses

Parse the new detailed error responses, looking for the issue in the {"errors": [...]} JSON response if your API call fails.

9

Add Test Users

Add test users to your project via Adobe Developer Console.

10

Deploy to Production

Deploy to Production once validated with a V4 Frame.io account.

Error Handling & Common Issues

Client Errors (4xx)
  • 400 Bad Request: Check payload accuracy.
  • 401 Unauthorized: Refresh or re-authenticate OAuth tokens.
  • 403 Forbidden: Missing scope or user lacks access.
  • 404 Not Found: Confirm endpoint, API version, or IDs.
  • 422 Unprocessable Entity: Validate request data
  • 429 Rate limited: Implement retry with backoff.
Server Errors (5xx)
  • 500 server error: Retry after a brief delay.

Legacy API endpoints currently unavailable in V4 API:

The following Legacy API endpoints are currently unavailable in V4 API:

1. Accounts & User Info

  • GET /v2/accounts/{account_id}
  • GET /v2/projects/shared
  • GET /v2/accounts/{account_id}/membership

2. Files & Folders

  • POST /v2/assets/{destination_folder}/move
  • POST /v2/assets/{destination_folder}/copy
  • DELETE /v2/assets/{asset_id}/unversion

3. Teams / Workspaces

  • GET /v2/teams/{team_id}/membership

4. Comments

  • GET /v2/comments/{comment_id}/impressions

5. Shares

  • GET /v2/review_links/{link_id}

6. Webhooks

  • GET /v2/accounts/{account_id}/webhooks

7. Custom Actions

  • GET /v2/accounts/{account_id}/actions