Resources

Frame.io Legacy API to V4 Migration Guide

Introduction

The Frame.io V4 API is a 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 while maintaining all the relevant functionality of the Legacy API. This guide outlines the key differences between the Legacy and V4 APIs and provides step-by-step guidance to help you migrate smoothly.

Migration Checklist

1

Authentication

For V4-migrated accounts not yet administered via the Adobe Admin Console, you can continue to use Legacy Developer tokens managed in the Frame.io developer site, but you will need to add a header to your api requests with the key x-frameio-legacy-token-auth and a value of true. Otherwise, you should follow steps in the Authentication section below.

2

Update Existing API Calls

All legacy API routes will need to be mapped to the new V4 API routes and JSON payloads. There is a fairly comprehensive mapping table below to assist with this process.

4

Implement Dedicated Login

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

If there is an endpoint that is not listed in the mapping table below that you have questions about, please reach out to our support team for more at support@frame.io.

Adobe Developer Console Managed Authentication

For V4-migrated accounts that are managed through the Adobe Developer Console, you will need to use the V4 API with OAuth2.0. You will need to follow the steps below.

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. If your V4 account is not yet managed via the Adobe Admin Console, you can skip this step.

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

If you are using legacy developer token authentication, you will need to add a header to your api requests with the key x-frameio-legacy-token-auth and a value of true.

General notes to help with the migration:

1

Payloads

The request and response payloads may be different.
2

Teams → Workspaces

”Teams” in Legacy API are the equivalent of “Workspaces” in V4.
3

Assets

”Assets” in Legacy API are now split into “Files”, “Folders”, and “Version Stacks” in V4.
4

Permissions

Permissions and roles are different in V4, which changes the structure of the endpoints. In V4, you have workspace and project user roles. For more details, see Managing User Permissions.

1. Accounts & User Info

MethodLegacy EndpointMethodV4 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 Account by ID)		N/AN/AInfo about a specific account can be found in list accounts endpoint.
GET/v2/me
(Get Current User)		GET/v4/me
(User details)		Fetch current user’s profile.
GET/v2/accounts/{account_id}/membershipN/AN/ARoles and permissions are handled via workspace and project permissions.

2. Workspaces (Replaced Team Endpoints)

MethodLegacy EndpointMethodV4 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
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
GET/v2/teams/{team_id}/membership
(Get user membership for team)		N/AN/ARoles and permissions are handled via workspace and project permissions.

3. Projects

MethodLegacy EndpointMethodV4 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.
GET/v2/projects/sharedN/AN/AThis is not currently supported 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}/users
(List project user roles)		Returns all the users in a project (closest equivalent to legacy collaborators endpoint)
POST/v2/projects/{project_id}/collaborators
(Add a Collaborator to a Project)		PATCH/v4/accounts/{account_id}/projects/{project_id}/users/{user_id}
(Update user roles for the given project)		Allows for adding or removing users from a project (closest equivalent to legacy collaborators endpoint)

4. Folders

MethodLegacy EndpointMethodV4 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.
N/AN/AGET/v4/accounts/{account_id}/folders/{folder_id}/folders
(List folders)		Lists folders in a given folder. (Get root_folder_id from show project route, and you can use this to list all folders at the highest level.)

5. Version Stacks

MethodLegacy EndpointMethodV4 EndpointNotes
POST/v2/assets/{destination_folder}/copy
(Copy an Asset)		POST/v4/accounts/{account_id}/version_stacks/{version_stack_id}/copy
(Copy version stack)		Legacy: destination folder in path; use with a version stack in request. V4: copy a version stack.
POST/v2/assets/{asset_id}/version
(Version an Asset)		POST/v4/accounts/{account_id}/folders/{folder_id}/version_stacks
(Create version stack)		Create a version stack. Requires 2–10 file IDs in request body.
POST/v2/assets/{asset_id}/version
(Version an Asset)		PATCH/v4/accounts/{account_id}/files/{file_id}/move
(Move file to version stack)		Move a file to an existing version stack. Use the version_stack_id as the parent_id in request body.
GET/v2/assets/{asset_id}/children
(Fetch child Assets)		GET/v4/accounts/{account_id}/version_stacks/{version_stack_id}/children
(List version stack children)		Legacy: use with a version stack asset_id. V4: list children (files/versions) in a version stack.
N/AN/AGET/v4/accounts/{account_id}/folders/{folder_id}/version_stacks
(List version stacks)		List version stacks in a folder.
N/AN/APATCH/v4/accounts/{account_id}/version_stacks/{version_stack_id}/move
(Move version stack)		Move a version stack to another folder.
GET/v2/assets/{asset_id}
(Get an Asset)		GET/v4/accounts/{account_id}/version_stacks/{version_stack_id}
(Show version stack)		Legacy: use with a version stack asset_id. V4: show version stack details.
DELETE/v2/assets/{asset_id}/unversion (Delete unversion)N/AN/AUn-versioning is not currently supported in V4.

6. Files

Note: there are now two endpoints for creating files in V4 (locally and via S3 upload). For more details, see Uploading Files.

MethodLegacy EndpointMethodV4 EndpointNotes
POST/v2/assets/{parent_asset_id}/children
(Create an Asset)		POST/v4/accounts/{account_id}/folders/{folder_id}/files/local_upload
(Create file (local upload))		Legacy API: requires name, type, filetype, filesize, & auto_version_id
V4 API: account_id & folder_id are required in the path parameters, file_size and name required on payload
N/AN/APOST/v4/accounts/{account_id}/folders/{folder_id}/files/remote_upload
(Create file (remote upload))		Account_id & folder_id are required in the path parameters, source url and name required on payload
GET/v2/assets/{asset_id}
(Get an Asset)		GET/v4/accounts/{account_id}/files/{file_id}
(Show file)		Show file details - many includes are available to return additional file details in the response.
N/AN/AGET/v4/accounts/{account_id}/files/{file_id}/status
(Get file metadata)		Get status of a remote upload from a create file remote upload endpoint.
PUT/v2/assets/{asset_id}
(Update an Asset)		PATCH/v4/accounts/{account_id}/files/{file_id}
(Update file)		Update file name.
DELETE/v2/assets/{asset_id}
(Delete an Asset)		DELETE/v4/accounts/{account_id}/files/{file_id}
(Delete file)		204 No Content on success.

7. Comments

Most V4 api comment capabilities are currently supported.

Coming Soon Features:

  • Comment reactions, i.e. emojis
  • Viewing or modifying comment completion status
  • Seeing who has viewed a comment (impressions)

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

MethodLegacy EndpointMethodV4 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.
GET/v2/comments/{comment_id}/impressions
(Get Impressions)		N/AN/AImpressions are not currently supported in V4.

8. Shares (Review Links / Presentations)

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

Note: interacting with legacy review links and presentations via V4 api is not supported.

MethodLegacy EndpointMethodV4 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 (note this doesn’t include legacy review links and presentations)
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)		Adds asset to a share. This supports files, folders, and version stacks.
N/ADoes 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

9. Webhooks

The webhooks that you used in V3 will be migrated over and for the most part will function the same. On migration they will be disabled and will need to be enabled to function. There will be some changes required for asset events, which are now split into files and folders. There are some new V4 specific events to be aware of: metadata.value.updated, collection related events, and share related events.

MethodLegacy EndpointMethodV4 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",...]}}.
GET/v2/accounts/{account_id}/webhooks
(Get Webhooks for and Account)		GET/v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks
(List Webhooks)		Gets all webhooks for a workspace. Note: to get all webhooks for an account you need to get all workspaces for the account and then get all webhooks for those workspaces.
GET/v2/hooks/{hook_id}
(Get Webhook)		GET/v4/accounts/{account_id}/webhooks/{webhook_id}
(List Webhooks)		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.

10. Custom Actions

The custom actions that you used in V3 will be migrated over, but will require some modification to requests and to response handling. On migration they will be disabled and will need to be enabled to function. For more detail please refer to this (document)

Note: the custom actions endpoints are currently in the experimental api and will require a header: “api-version: experimental”.

MethodLegacy EndpointMethodV4 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 Action)Delete a custom action.
PUT/v2/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)GET/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

Adjust unsupported V2 endpoints

Adjust any unsupported Legacy V2 endpoints.

2

Update Base URLs

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

3

Update API Requests

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

4

Update JSON Payloads

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

5

Update Terminology

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

6

Test Endpoints

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

7

Parse Error Responses

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

8

Deploy to Production

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

Error Handling & Common Issues

Some routes give errors with custom descriptions that may differ slightly from examples below.

Client Errors (4xx)
  • 400 Bad Request: Check payload accuracy.
  • 401 Unauthorized: Invalid or missing authorization token.
  • 403 Forbidden: Missing scope or user lacks access.
  • 404 Not Found: Confirm endpoint, API version, or IDs.
  • 422 Unprocessable Entity: Validate request data
  • 429 Too Many Requests: Implement retry with backoff.
Server Errors (5xx)
  • 500 Internal Server Error: Retry after a brief delay.

SDK Support

Similar to the Legacy SDK, there is a Python SDK available for developers to use, and for the first time there is a Typescript SDK available also. These SDKs will have similar functionality but have completely different methods and if you are updating from the Legacy SDK to the V4 SDK, please be sure to update your code accordingly. You can find them at the links below: Getting Started SDKS Python SDK Typescript SDK