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 Apps

If you'd like to build your own Custom Actions app, our sample apps will help you get started:

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

πŸ“˜

Check your permissions

Team Manager permissions are required to create Customer Actions for a Team. Ask your admin to modify your permissions if you don't have access.

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

Field NameDescription
NameThe name you choose for your custom action. It will be shown in the menu of available custom actions in Frame.io.
DescriptionExplain what the action does, for reference (the description won't appear in the Frame.io web app).
EventInternal event key to help you differentiate between standard webhook events and your own. Event names are created like so: my.custom.event or my.event. You can retrieve this from the payload using action_id.
URLWhere 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).
TeamThe team that will use the custom action.

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.

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 NameDescription
action_idThis 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_idThis 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.
typeThe 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"
      }
   ]
}

Security

By default, all Custom Actions have a signing key generated during their creation. This is not configurable. This key can be used to verify that the request originates from Frame.io.

Verification

Included in the POST request are the following headers:

Name

Description

X-Frameio-Request-Timestamp

The time your Custom Action was triggered.

X-Frameio-Signature

The computed signature.

The timestamp is the time the request was signed on its way out of Frame.io's network. This can be used to prevent replay attacks. We recommended verifying this time is within 5 minutes of local time.

The signature is a HMAC SHA-256 hash using the signing key provided when the Custom Action is first created.

This is how you can go about verifying the signature:

  1. Extract the signature from the HTTP headers
  2. Create a message to sign by combining the version, delivery time, and request body
  • v0:timestamp:body
  1. Compute the HMAC SHA256 signature using your signing secret.
  • Note: The provided signature is prefixed with v0=. Currently Frame.io only has this one version for signing requests. You will need to add this prefix to your computed signature.
  1. Compare!

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 14 days 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.