> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://next.developer.frame.io/platform/v4/docs/guides/postman-collection/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server. # Postman Collection 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 > **Tip** > > This guide assumes you have generated credentials for the API. If you haven't, start [here](/platform/docs/quick-start) first #### Create a Postman Account + Choose Your Setup Create your Postman account at [postman.com](http://auth.postman.com/__redirect/login), and choose your setup. You can download the Postman app [here](https://www.postman.com/downloads/) or use Postman on the web. #### Import the Frame.io Developer API Postman Collection #### [Frame.io Developer API Collection](https://www.postman.com/adobe/workspace/frame-io-v4-public-api/collection/33150877-924315f2-cc62-45f5-8153-77ff2aaa9067?action=share\&creator=33150877\&active-environment=33150877-cffd66a8-23bd-4c50-8891-29157ead1185) 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. ![alt image](/_fern-img/0780e30f05ff2cee570d698b9adc209f24326281b60e23968e5d78e66c5c9b43.webp) ![alt image](/_fern-img/663c863cbbec947567616faf433d79e3900e70ace3d8d9d26299ee20e204c064.webp) 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](https://developer.adobe.com/developer-console/)** | Stage | | `IMS_CLIENT_SECRET` | Your Frame.io App Client Secret | Credential page in **[Adobe Developer Console](https://developer.adobe.com/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 > **Tip** > > 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](/platform/docs/guides/authentication/overview). 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](https://developer.adobe.com/console). ![alt image](/_fern-img/8f77af2f98d46f52b5d9da85adb48ee8f383f326edc8103f291f192deb4d9dba.webp) 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](/_fern-img/518e800fde27188c25a4f8438a552fca3cb37a27af7a810f9a93ab959b786615.webp) 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](/platform/docs/getting-started#errors)** 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](/platform/api-reference/accounts/index)** **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" } } ``` > **Tip** > > 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](/platform/docs/getting-started#resource-hierarchy)**. ### Listing Workspaces The **`GET list workspaces`** request in the **Workspaces** folder calls **[`/v4/accounts/:account_id/workspaces`](/platform/api-reference/workspaces/index)** 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`](/platform/api-reference/workspaces/create)** 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`](/platform/api-reference/workspaces/update)** 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`](/platform/api-reference/projects/create)** 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. > **Tip** > > 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](/platform/docs/guides/postman-collection)**) --- ## Folder and File Operations ### Listing Folder Children The **`GET list folder children`** request calls **[`/v4/accounts/:account_id/folders/:folder_id/children`](/platform/api-reference/folders/index)** 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](/platform/api-reference/folders/index#request.query.include)** | 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`](/platform/v4/api-reference/files/create-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](/_fern-img/86ddb4aebecaffdee01cf07be3c2e7af0b616285721ec8ef412575114a916b21.webp) 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`](/platform/v4/api-reference/files/create-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" } } ```