Overview

Frame.io’s API supports deep, faceted search for Assets across an entire Account, mirroring the functionality in the web application. While the most commonly useful filters are Team, Project, and Status, filters and sorting can be combined in unique ways to produce extremely specific, API-driven sets. In general, all filters aside from the account_id, q (query), and sort follow the same structure, and all are explained below.

Defaults

The API request to trigger a search is always the same:

It’s always the same request

POST to https://api.frame.io/v2/search/library

If not supplied explicitly, default values for search tuning are as follows:

About this guide

This guide walks through the process of building a search query that matches:

• Assets within an Account
• That matches the query "moon"
• Is in a specific Project
• Was uploaded between April 1st and 30th, 2020
• And has been “Approved”

The body for our search will end up looking like this:

1
{
2
    "account_id": "<account_id>",
3
    "q": "moon",
4
    "sort": "name",
5
    "filter": {
6
        "inserted_at": [
7
            {
8
                "op": "gte",
9
                "value": "2020-04-01T04:00:00.000Z"
10
            },
11
            {
12
                "op": "lte",
13
                "value": "2020-04-30T03:59:59.999Z"
14
            }
15
        ],
16
        "project_id": {
17
            "op": "eq",
18
            "value": "<project_id>"
19
        },
20
        "label": {
21
            "op": "eq",
22
            "value": "approved"
23
        }
24
    },
25
    "page_size": 10,
26
    "page": 1
27
}

Account, query and sort

The Account (account_id), query (q), and sort are the three most basic building blocks that sit outside of any filter attributes in a search query.

Account context

Technically, the only attribute you need to perform a search is an account_id. Doing so will simply pull every Asset (including folders) on the Account, with default pagination values (10 Assets per page, starting on page 1).

1
{
2
    "account_id": "<account_id>"
3
}

Search query

The next most common (and helpful) attribute to include is the query itself. Note: because Frame.io’s API search accepts a null query, there is no need for a wildcard (*) query. You’re either searching for something, or you’re requesting a (potentially filtered) sort of all Assets in an Account.

In our case, we’ll be searching for the term “moon”.

1
{
2
    "account_id": "<account_id>",
3
    "q": "moon"
4
}

Sorting

Frame.io supports a number of different sorting options. The syntax for sort order is similar across options:

• There is a default sort direction
• To reverse that direction, prefix the sort value with a negative -

For example, to sort in reverse alphabetical order (Z to A), you would declare "sort": "-name".

The default sort operation is “Relevance.” Accordingly, it does not need to be declared, and will be assumed if no sort attribute is provided.

Accordingly, as we build out our query, we can now add in our sort for name, A to Z:

1
{
2
    "account_id": "<account_id>",
3
    "q": "moon",
4
    "sort": "name"
5
}

Filters and pagination

Filters are both the trickiest, and most powerful feature of Frame.io’s Asset search. Filters are written within a single filter object, and all follow the same pattern of an operation (op), and a value. Filters will use the following common abbreviations, with equivalency options other than “equals” reserved for date and size queries:

• eq — equals
• lt — less than
• gt — greater than
• lte — less than or equal to
• gte — greater than or equal to
• match — exact match, used only for Uploader and Filetype filters

For example, a filter to match on a known project_id would be constructed as follows:

1
{
2
    "filter": {
3
        "project_id": {
4
            "op": "eq",
5
            "value": "<project_id>"
6
        }
7
    }
8
}

Options and operations

The following table describes the options and operations associated with each filter type.

To continue building out our query, we can now add a filter for Assets that are:

• Is in a specific Project
• Uploaded between April 1st and 30th, 2020
• Marked as “Approved”

1
{
2
    "account_id": "<account_id>",
3
    "q": "moon",
4
    "sort": "name",
5
    "filter": {
6
        "inserted_at": [
7
            {
8
                "op": "gte",
9
                "value": "2020-04-01T04:00:00.000Z"
10
            },
11
            {
12
                "op": "lte",
13
                "value": "2020-04-28T03:59:59.999Z"
14
            }
15
        ],
16
        "project_id": {
17
            "op": "eq",
18
            "value": "<project_id>"
19
        },
20
        "label": {
21
            "op": "eq",
22
            "value": "approved"
23
        }
24
    }
25
}