Frame.io API

Frame.io API Documentation

Welcome to Frame.io's official documentation portal.In here, you'll find everything you need to:

Get up and running with Frame.io's public API 🤙
Leverage powerful features like Webhooks and Custom Actions 🚀
Build your own OAuth2.0 app 🚢

Get Started    Guides

Custom Actions Overview

Custom actions are a way for you to build integrations directly into Frame.io as programmable UI components. This page explains how they work.

Example Applications

If you'd like to get started building your own Custom Actions application, feel free to grab one of our sample apps and extend it:

Custom actions are a way for you to build integrations directly into Frame.io as programmable UI components. This enables a whole class of workflows that can be triggered by users within the app, leveraging the same underlying events routing as Webhooks. Currently, custom actions are available for Assets, and are displayed in the contextual / right-click dropdown menu available on any Asset, as shown in the image below.

An Asset is a robust representation of a file in S3, and its context in Frame.io, including transcodes, user/team/project context, and metadata. When a user clicks a custom action on an Asset, Frame.io will send a payload to a URL you provide. The receiving application may then respond with an HTTP status code to simply acknowledge receipt, or may respond with a custom callback that can render additional UI in Frame.io.

Setup Your Custom Action

Custom actions can be configured in the Custom Actions area of developer.frame.io. An action requires:

Field Name Description
Name The name you choose for your custom action. It will be shown in the menu of available custom actions in Frame.io.
Description Explain what the action does, for reference (the description appears here, it won't appear in the Frame.io web app).
Event Internal event key to help you differentiate between standard webhook events and yours. Event names are created like so: my.custom.event or my.event. You can retrieve this from the payload using action_id.
URL Where to deliver events. If you need help setting up a test server and public facing URL to send events to, see Setup and Troubleshoot ngrok (Mac).
Team This shows which team the custom action will be associated with.

Click - What's in the Payload You Receive From Frame.io

When the user clicks your custom action, a payload will be sent to the URL you specified in the URL field when you set up your custom action in the Custom Action section of developer.frame.io.

POST /your/url
{
  "action_id": "2444cccc-7777-4a11-8ddd-05aa45bb956b",
  "interaction_id": "aafa3qq2-c1f6-4111-92b2-4aa64277c33f",
  "resource": {
    "type": "asset",
    "id": "9q2e5555-3a22-44dd-888a-abbb72c3333b"
  },
  "type": "my.action"
}

You can use this payload to identify:

  • Which of your custom actions were clicked
  • Which resource was clicked
  • Which User took the action
Field Name Description
action_id This is a unique identifier generated by Frame.io that you can use to identify your action any time a user clicks the custom action this id is associated with.
interaction_id This is a unique identifier generated by Frame.io that you can use to keep track of your transaction. This identifier will be presented throughout the duration of the transaction, encompassing from when the user clicks on the custom action in the web app, to when the back and forth with any web forms you present completes.
type The name of the event you put in the Event field when configuring your custom action in the Custom Actions area of developer.frame.io
resource
NameDescription>
idA unique identifier used to represent the asset that was clicked on to send your custom action from.
typeWhen applied inside the resource section, the type parameter refers to what the ID is for, in this case an asset.

NOTE:

The interaction_id is provided as a unique identifier to help you keep track of the interaction as it evolves over time. If you do not need to respond to the user, simply return a 200 status code, and you're done. While optional, we recommend including some information about the result of the action, like a simple success message or error alert. Custom actions support message callbacks.

Create a Message Callback

In your HTTP response to the webhook event, you can return a JSON object describing a message that will be returned to the initiating User in the Frame.io UI. If you want to try building a message and seeing how it will turn out, you can try our Custom Action Builder, which allows you to set up message callbacks or forms and see how they would appear in the Frame.io web app. Here's an example object:

json
{
  "title": "Success!",
  "description": "The thing worked! Nice."
}

This will show an alert to the user that looks like this:

Messages are a simple way of closing the action lifecycle loop in a way that provides variable context to the acting User, without asking them to switch contexts.

This is enough to satisfy many use cases, but sometimes the initial payload and subsequent calls to the Frame.io API won't provide enough context for the receiving application. For these scenarios, we also support Form Callbacks.

Create a Form Callback

Let's say that you actually need more info before you start your process. For example, you may be uploading content to a system that requires additional details and settings. You can “describe” a Form in your response, which the user will actually see! And fill out! And it'll be sent right back to you!

Here's an example Form:

This will render a Form in the Frame.io UI that the initial acting User can fill out and submit:

json
{
  "title": "Need some more info!",
  "description": "Getting ready to submit this file!",
  "fields": [
    {
      "type": "text",
      "label": "Title",
      "name": "title",
      "value": "MyVideo.mp4"
    },
    {
      "type": "select",
      "label": "Captions",
      "name": "captions",
      "options": [
        {
          "name": "Off",
          "value": "off"
        },
        {
          "name": "On",
          "value": "on"
        }
      ]
    }
  ]
}

NOTE:

If you want to try playing around with the form, you can use the Custom Actions Builder to try building forms too.

When the user submits the form, you'll receive an event on the same URL as the initial POST:

POST /your/url​
{
  "type": "your-specified-event-name",
  "interaction_id": "the-same-id-as-before",
  "action_id": "unique-id-for-this-custom-action",
  "data":{
    "title": "MyVideo.mp4",
    "captions": "off"
  }
}

All the custom fields you added on your form appear in the data section of the JSON payload sent by Frame.io

Use the interaction_id to map the initial request and this new form data. And again, if you'd like, you can respond with a message (or even another form!).

By chaining Actions, Forms, and Messages, you can effectively program entire Asset workflows in Frame.io with business logic from an external system.

Get imaginative! The sky's the limit.

Form Details

Like messages, Forms support title and description attributes that render at the top of the Form. Beyond that, each form field accepts the following base attributes:

  • type -- Tells the Frame.io UI which type of data to expect, and which component and render.
  • label -- Appears on the UI as the header above the field.
  • name -- Key by which the field will be identified on the subsequent payload.
  • value -- Value with which to pre-populate the field.

Supported Field Types

Text field
A simple text field with no additional parameters.

{  
  "type": "text",
  "label": "Title",
  "name": "title",
  "value": "MyVideo.mp4"
}

Text area
A simple text area with no additional parameters.

{  
  "type": "textarea",
  "label": "Description",
  "name": "description",
  "value": "This video is really, really popular."
}
`

Select list
Defines a picklist that the user can choose from. Must include an options list, each member of which should include a human-readable name, and a machine-parseable value.

{
  "type": "select",
  "label": "Captions",
  "name": "captions",
  "value": "off",
  "options": [
       {
         "name": "Off",
         "value": "off"
       },
       {
         "name": "On",
         "value": "on"
      }
   ]
}

As always, if you have any questions, or would like to experiment with Custom Actions, please reach out to our team at [email protected].

Updated 4 months ago

Custom Actions Overview


Custom actions are a way for you to build integrations directly into Frame.io as programmable UI components. This page explains how they work.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.