Postman Collection | Frame.io API Documentation

This guide covers the basics of the official Frame.io Developer API Postman collection, a set of prebuilt requests you can use to get started with the Frame.io V4 API.

The collection covers the full range of V4 API endpoints, split into stable and experimental categories. Stable endpoints are production-ready, and experimental endpoints are newer additions that are functional but may change based on feedback before being promoted to stable.

Getting Started with Postman

This guide assumes you have generated credentials for the API. If you haven’t, start here first

Create a Postman Account + Choose Your Setup

Create your Postman account at postman.com, and choose your setup. You can download the Postman app here or use Postman on the web.

Import the Frame.io Developer API Postman Collection

Frame.io Developer API Collection

Fork or download here

Setting Up Your Environment

The Frame.io Developer API Collection has a default environment with a number of environment variables defined. BASE_URL and IMS_BASE_URL values are static. Additional environment variables can be configured according to your account information.

Below is a table with a description of each variable found in the collection’s Default and Stage environments:

Variable	Description	How to Retrieve	Environment
`BASE_URL`	Base URL for all V4 API requests	Preconfigured, do not edit	Default
`IMS_BASE_URL`	Adobe IMS authentication base URL	Preconfigured, do not edit	Default, Stage
`IMS_CLIENT_ID`	Your Frame.io App Client ID	Credential page in Adobe Developer Console	Stage
`IMS_CLIENT_SECRET`	Your Frame.io App Client Secret	Credential page in Adobe Developer Console	Stage
`FOLDER_ID`	Unique ID for the destination folder	Returned in folder response object	Default
`WEBHOOK_ID`	Unique ID for a configured webhook	Returned in webhook response object	Default
`ASSET_ID`	Unique ID for a file or folder asset	returned in file or folder response object	Default
`SHARE_ID`	Unique ID for a share link	returned in share response object	Default

Setting Up Authorization

This guide uses OAuth 2.0 to authenticate with the Frame.io V4 API. For information on other authentication methods, such as Server-to-Server (S2S), see the Authentication Guide.

The IMS_CLIENT_ID and IMS_CLIENT_SECRET environment variables should be set to the values retrieved from your project’s Credential details in the Adobe Developer Console.

In your project’s Credential details section, set the Redirect URI and Redirect URL Pattern to Postman’s public callback endpoint:

Redirect URI

https://oauth/pstmn.io/v1/callback

Redirect URI Pattern

https://oauth\\.pstmn\\.io

Once environment variables have been set and saved, the next step is configuring authorization settings. To do so, click the Collections icon at the top of the left sidebar to open your collection browser.

From the collection browser, select the root of the Frame.io V4 Developer API collection (usually titled ‘Frame.io Developer API Collection’ followed by your fork name) and select the Authorization tab. alt image

OAuth scopes are pre-configured in the collection. With your environment variables set, use the Get New Access Token button to start the OAuth 2.0 flow. This will open a browser window to complete the authentication process and return the token to Postman.

To verify your authorization configuration, select the GET user details request in the Users folder and click Send.

A 200 OK response confirms both that your collection is configured correctly and that you’ve authenticated to the correct account. If you encounter an error, see this section of the Getting Started guide for information on errors and warnings.

Example Response

{
  "data": {
    "avatar_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN",
    "email": "user_email@example.com",
    "id": "00000000-1111-2222-3333-444444444444",
    "name": "Name"
  }
}

Obtaining Your Account ID

account_id is a required path parameter for most V4 API endpoints, and is something you’ll need to test other requests. You can obtain your account_id with the GET List accounts request, located in the collection’s Accounts folder. API Reference

Example Response

{
  "data": [
    {
      "created_at": "2023-09-25T19:18:29.614189Z",
      "display_name": "Integration Account",
      "id": "11111111-2222-3333-4444-555555555555",
      "roles": [
        "admin"
      ],
      "storage_limit": 300,
      "storage_usage": 300,
      "updated_at": "2024-02-07T16:44:41.986478Z",
      "image": null
    }
  ],
  "links": {
    "next": "/v4/accounts"
  }
}

If you have multiple Frame.io accounts, each will appear as a separate object in the response

Once you have obtained your Account ID, copy the id value from the response and save it as an environment variable. You’ll reference it as the account_id path parameter using {{ACCOUNT_ID}} in future requests.

Workspace and Project Operations

Your Frame.io files are stored in folders, organized into Projects within Workspaces. For a full overview of the V4 resource hierarchy, see this guide.

Listing Workspaces

The GET list workspaces request in the Workspaces folder calls /v4/accounts/:account_id/workspaces and returns a list of Workspaces your account has access to.

Some Project operations require workspace_id as a path parameter, so save your Workspace ID first if you plan to list or retrieve Projects.

A successful request will return a 200 OK status and a response body similar to the example below.

Example Response

{
  "data": [
    {
      "account_id": "11111111-2222-3333-4444-555555555555",
      "created_at": "2024-01-25T19:18:29.614189Z",
      "id": "88888888-bbbb-4444-aaaa-ffffffffffff",
      "name": "My Workspace",
      "updated_at": "2024-02-07T16:44:41.986478Z",
      "creator": {
        "active": true,
        "avatar_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN",
        "email": "user_email@example.com",
        "id": "196C1A5777BF4CV00A49411B@176719f5667d82g5594324.e",
        "name": "Name"
      }
    }
  ],
  "links": {
    "next": "/v4/accounts/123/workspaces"
  }
}

Creating a Workspace

The POST create workspace request calls /v4/accounts/:account_id/workspaces to create a new Workspace for your account.

In the request editor, select the Body tab to set the name of your Workspace within the data object.

A successful request will return a 201 Created status and a response body similar to the example below.

Example Response

{
  "data": {
    "account_id": "11111111-2222-3333-4444-555555555555",
    "created_at": "2024-01-25T19:18:29.614189Z",
    "id": "77777777-999-4444-8888-000000000000",
    "name": "My New Workspace",
    "updated_at": "2024-02-07T16:44:41.986478Z"
  }
}

Updating a Workspace

The PATCH update workspace request calls /v4/accounts/:account_id/workspaces/:workspace_id to update the name of a Workspace.

In the request editor, select the Body tab to set the new name of your Workspace within the data object.

A successful request will return a 200 OK status and a response body similar to the example below.

Example Response

{
    "data": {
        "id": "77777777-9999-4444-8888-000000000000",
        "name": "New Workspace Name",
        "updated_at": "2026-05-01T02:42:00.462467Z",
        "account_id": "11111111-2222-3333-4444-555555555555",
        "created_at": "2025-09-22T19:17:02.565496Z"
    }
}

Creating a Project

The POST create project request calls /v4/accounts/:account_id/workspaces/:workspace_id/projects to create a new Project in a given Workspace.

In the request editor, select the Body tab to set the name of your Project within the data object. The optional restricted property is a Boolean used to create a restricted Project.

A successful request will return a 201 Created status and a response body similar to the example below.

Example Response

{
    "data": {
        "id": "fd26defb-8bdf-5c39-9746-24d38f109cc3",
        "name": "test",
        "status": "active",
        "restricted": true,
        "updated_at": "2026-05-01T03:39:58.910884Z",
        "storage": 0,
        "workspace_id": "77777777-999-4444-8888-000000000000",
        "created_at": "2026-05-01T03:39:58.853797Z",
        "root_folder_id": "d4fca8b4-5fd8-4a94-90aa-de13de4b2021",
        "view_url": "https://next.frame.io/project/fd26defb-8bdg-5c39-9746-24d38f109cc3"
    }
}

Copy the root_folder_id from the response and set it as the value for your FOLDER_ID environment variable. You’ll need this for the remaining sections of this guide.

You can add a user to a newly created restricted Project with a subsequent PATCH Update user role in a Project request located in the Project Permissions folder. (API Reference)

Folder and File Operations

Listing Folder Children

The GET list folder children request calls /v4/accounts/:account_id/folders/:folder_id/children to list the children in a given folder. In this case, the project root folder set as your FOLDER_ID environment variable.

You can use the following optional query parameters to refine your response:

Parameter	Type	Description
`page_size`	Integer	Limits the number of returned folders 1-100. Defaults to 50
`type`	String	Filters folder children by resource type: `file`, or `folder`
`after`	String	Opaque Cursor for requests returning paginated results. This is auto-generated and returned in the `links` object of the previous response. It is not intended to be human readable.
`include_total_count`	Boolean	Returns the total count of all entities Defaults to False
`include`	Enum	Appends additional data to each returned object such as `creator`, `project`, `media_links`. For a full list of supported parameters, see API Reference

A successful request will return a 200 OK status and a response body similar to the example below.

Example Response

{
  "data": [
    {
      "type": "file",
      "created_at": "2023-09-25T19:18:29.614189Z",
      "file_size": 1137444,
      "id": "cba3b1c5-c644-4592-91c5-0d0b91f4895d",
      "media_type": "image/png",
      "name": "asset.png",
      "parent_id": "2559e2c4-9bb9-4284-b616-a97700a579a4",
      "project_id": "955c0511-656a-4859-b824-ebdbfdcb615b",
      "status": "created",
      "updated_at": "2024-02-07T16:44:41.986478Z",
      "view_url": "https://next.frame.io/project/d5e6011c-2bc9-4596-be05-77d562627112/view/5a89a9fb-0900-4b23-826b-127b90e4db4c",
      "creator": {
        "active": true,
        "avatar_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN",
        "email": "user_email@example.com",
        "id": "196C1A5666BF4EB00A49411B@176719f5667c82b4494214.e",
        "name": "Jon Doe"
      },
      "media_links": {
        "high_quality": {
          "download_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN"
        },
        "original": {
          "download_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN",
          "inline_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=inline%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragSDFXDFh&1Key-Pair-Id=KKI497NESTHMN"
        },
        "thumbnail": {
          "download_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN",
          "url": "https://picture2.frame.io/image/s3://frameio-assets-development/image/cd58cb8e-24b3-4498-8d0f-9532fcd04d11/image_full.png?alg=HS256&sig=0_u7w_wz2MwQHOXp000ibbQSMRijujyaUu8V3YYPxu4&exp=1729857600"
        }
      },
      "metadata": [
        {
          "field_type": "select",
          "field_definition_id": "b859ccec-9536-4bf2-bc6f-5e9206e26606",
          "field_definition_name": "Fields definition name",
          "mutable": true,
          "value": [
            {
              "display_name": "Display name",
              "id": "212add59-6527-4fd2-ac30-55ea94a8b5f8"
            }
          ],
          "field_options": [
            {
              "display_name": "Display name",
              "id": "212add59-6527-4fd2-ac30-55ea94a8b5f8"
            },
            {
              "display_name": "Display name 2",
              "id": "c6eb873f-125b-4317-b857-1a22eb3dbf22"
            }
          ]
        }
      ],
      "project": {
        "created_at": "2024-01-25T19:18:29.614189Z",
        "description": "Project Description",
        "id": "e0e30b1d-c3aa-44ee-926e-c6c326fb10dc",
        "name": "My Project",
        "root_folder_id": "be733511-6f15-4d97-8ee7-bc23b2fb0bd7",
        "status": "active",
        "storage": 15000,
        "updated_at": "2024-02-07T16:44:41.986478Z",
        "view_url": "https://next.frame.io/project/d5e6011c-2bc9-4596-be05-77d562627112/",
        "workspace_id": "91b10e83-5874-44de-9b57-41c937b87256",
        "owner": {
          "active": true,
          "avatar_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN",
          "email": "user_email@example.com",
          "id": "196C1A5666BF4EB00A49411B@176719f5667c82b4494214.e",
          "name": "Jon Doe"
        },
        "restricted": false
      }
    }
  ],
  "links": {
    "next": "/v4/accounts/123/folders/123/folders"
  },
  "total_count": 10
}

Testing the `after` Parameter

If you are testing paginated results, locate the links object in your response:

From the next property URL, copy only the string value following after=
Set this as the value of your after query param in your next request.
Watch out for double encoding! If the URL contains encoded characters (ie: %3D%3D) replace them with the raw version (==). Postman interprets your input literally and may double encode these, leading to a 422 error

Creating a File - Local Upload

The POST create file - local upload request calls /v4/accounts/:account_id/folders/:folder_id/files/local_upload to upload a local file in a specified folder.

Local uploads require two or more requests depending on file size. For your first test, use a small file (less than 10 MB) to limit the process to a single upload URL.

Create Placeholder File Resource

In the request editor, select the Body tab to set the name and file size (specified in bytes) within the data object. A successful request will return a 201 Created status and a response body similar to the example below.

Example Response

{
  "data": {
    "created_at": "2023-09-25T19:18:29.614189Z",
    "file_size": 1137444,
    "media_type": "image/png",
    "parent_id": "2559e2c4-9bb9-4284-b616-a97700a579a4",
    "project_id": "955c0511-656a-4859-b824-ebdbfdcb615b",
    "status": "created",
    "type": "file",
    "updated_at": "2024-02-07T16:44:41.986478Z",
    "view_url": "https://next.frame.io/project/d5e6011c-2bc9-4596-be05-77d562627112/view/5a89a9fb-0900-4b23-826b-127b90e4db4c",
    "id": "cba3b1c5-c644-4592-91c5-0d0b91f4895d",
    "name": "asset.png",
    "upload_urls": [
      {
        "size": 20000000,
        "url": "https://my.fileupload.url.dev"
      }
    ]
  }
}

This call has created a placeholder file resource in the specified folder. Use the pre-signed upload URL in the upload_urls array in the response to complete the upload in the next step.

Upload File Content

Click the URL in the upload_urls array in your response to open a new request tab in Postman. Change the request method to PUT. In the request editor, select the Headers tab to add the following headers to your request:

x-amz-acl:private
Content-Type: This must exactly match the extension type specified in the filename (ie: a file named IMG.png must use image/png)

alt image In the request editor select the Body tab and click the binary option to select your file. Once selected click Send to complete your request. A successful request will return a 200 OK status, confirming your file has been uploaded.

Once your file has been uploaded, the Frame.io media pipeline automatically handles transcoding and thumbnail generation. For larger files, it may take a few moments for the file to move from created to a ready state.

Creating a File - Remote Upload

The POST create file - remote upload request calls /v4/accounts/:account_id/folders/:folder_id/files/remote_upload to pull an external file into a specified folder using a provided source URL.

In the request editor, select the Body tab to set the name and source URL of your file within the data object.

A successful request will return a 202 Accepted status and a response body similar to the example below.

Example Response

{
  "data": {
    "created_at": "2023-09-25T19:18:29.614189Z",
    "file_size": 1137444,
    "media_type": "image/png",
    "parent_id": "2559e2c4-9bb9-4284-b616-a97700a579a4",
    "project_id": "955c0511-656a-4859-b824-ebdbfdcb615b",
    "status": "created",
    "type": "file",
    "updated_at": "2024-02-07T16:44:41.986478Z",
    "view_url": "https://next.frame.io/project/d5e6011c-2bc9-4596-be05-77d562627112/view/5a89a9fb-0900-4b23-826b-127b90e4db4c",
    "id": "cba3b1c5-c644-4592-91c5-0d0b91f4895d",
    "name": "asset.png"
  },
  "links": {
    "status": "/v4/accounts/fb4dd62f-8a89-4e98-8fa1-ad4b29a0094f/files/eab70952-966c-4d99-949b-f0a947ca5754/status"
  }
}

Getting Started with Postman

Create a Postman Account + Choose Your Setup

Import the Frame.io Developer API Postman Collection

Setting Up Your Environment

Setting Up Authorization

Obtaining Your Account ID

Workspace and Project Operations

Listing Workspaces

Creating a Workspace

Updating a Workspace

Creating a Project

Folder and File Operations

Listing Folder Children

Testing the after Parameter

Creating a File - Local Upload

Create Placeholder File Resource

Upload File Content

Creating a File - Remote Upload

Testing the `after` Parameter