Pagination, Sorting, and Filtering

In addition to dealing with resources by ID (eg. "/v3/myresource/[SOME_ID]") the SHIFT API also supports querying for multiple resources by way of query parameters. You can specify criteria, pagination, and sorting. Querying support is available for most of our resource endpoints.

Pagination

To specify the number of results that are returned, you can use the "_page" and "_pageSize" query parameters to specify the page index and total results per page that you'd like returned.

/v3/assets?_page=2&_pageSize=25

Your results will include the total number of results in the response header "total-results". It will also include links to the first, next, and last pages in the "Link" header.

Sorting

You can order the results that are returned to you by passing the "_sort" and "_sortBy" parameters, which specify the directional order and field to sort by.

/v3/assets?_sort=asc&_sortBy=title
OR
/v3/assets?_sort=desc&_sortBy=title

Query Operators

Equality

To search for resources where a field in the resource equals an exact value, you can use:

/v3/assets?type=video

Inequality

To search for resources where a field in the resource does not equal some value, the following can be used:

/v3/assets?type={"neq":"video"}

Contains

To search for resources where a field in the resource contains some value, the following can be used:

/v3/assets?title={"ct":"oscar"}

Range

To search for resources with a field that exists between two values, the following can be used:

/v3/assets?duration={"bt":"10000..60000"}

Greater Than

To search for assets with a field that is greater than some value, the following can be used

/v3/assets?duration={"gt":"10000"}

Less Than

To search for assets with a field that is less than some value, the following can be used

/v3/assets?duration={"lt":"10000"}

In

To search for a resource with a field where the value can be any value in a list, the following can be used

/v3/assets?uploadedBy={"in":"susan,jim"}

Not In

To search for a resource with a field where the value cannot be any value in a list, the following can be used

/v3/assets?tags={"nin":"susan,jim"}

πŸ“˜

A couple important things to consider...

  • Query parameters are supported for root level fields on a resource. If you have a resource that has child objects, the child object and the fields contained within it are not queryable.

  • Querying is limited to your scope. No matter what you ask for, it will be limited by what you have access to. For example, if you query for all video assets in a project that you are not a part of, you will not receive any results.


What’s Next
Did this page help you?