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.
As of March, 2022, there is known a bug affecting the search API’s paging function. Until this bug is addressed, we do not recommend using the search API to iterate over multiple pages of results (i.e. more than 100 assets), because the requested page size may not correspend with actual returned asset count.
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:
This guide walks through the process of building a search query that matches:
"moon"The body for our search will end up looking like this:
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.
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).
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”.
Frame.io supports a number of different sorting options. The syntax for sort order is similar across options:
-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:
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 — equalslt — less thangt — greater thanlte — less than or equal togte — greater than or equal tomatch — exact match, used only for Uploader and Filetype filtersFor example, a filter to match on a known project_id would be constructed as follows:
The following table describes the options and operations associated with each filter type.
Searching for Creator’s that are no longer members in the account will not work as that user is no longer in the User Search index.
To continue building out our query, we can now add a filter for Assets that are:
The search endpoint paginates exactly as any other endpoint, via page_size and page attributes that sit at the outermost layer of the request body. For more details on pagination, please refer to the separate guide here.