Filters

The API provides methods for listing resources. For example, you can list apps, list users, and list contracts. Where filters are supported, these API list methods share a common structure for filters.

Why use Filters?

By combining multiple filters (in an AND relation) and utilizing the different operations, you can execute a wide variety of calls to help you achieve the exact response you're looking for.

For simpler use cases, use basic key=value filters.

While both types of filters can be used in conjunction, we recommend using only one.


The filters property accepts an array of filters following the schema below:

High-level schema

{
  "key": "the field to filter",
  "op": "see list of available operations below",
  "value": "the value to match"
}

Available operations

  • equals
  • notEquals
  • contains
  • notContains
  • anyOf
  • noneOf
  • allOf
  • isExactly
  • isSet
  • isNotSet
  • gt (greater than)
  • gte (greater than or equal)
  • lt (less than)
  • lte (less than or equal)
  • dayAfter
  • dayOnOrAfter
  • dayBefore
  • dayOnOrBefore
  • nested
  • relativeDateToday
  • relativeDateOn
  • relativeDateLess
  • relativeDateMore
  • exists
  • notExists
  • or
  • and

Example

find all apps whose primary owner is user ID 1 AND discovered after August 3rd, 2024

[
  {
    "key": "primaryOwner",
    "op": "equals",
    "value": 1
  },
  {
    "key": "creationTime",
    "op": "gt",
    "value": "2024-08-03T09:40:20.000Z"
  }
]
curl 'https://api.toriihq.com/v1.0/apps?filters=[{%22key%22%3A%22primaryOwner%22%2C%22op%22%3A%22equals%22%2C%22value%22%3A1}%2C{%22key%22%3A%22creationTime%22%2C%22op%22%3A%22gt%22%2C%22value%22%3A%222024-08-03T09%3A40%3A20.000Z%22}]' \
--header 'X-API-VERSION: 1.1' \
--header 'Authorization: Bearer <API_KEY>'
const myHeaders = new Headers();
myHeaders.append("X-API-VERSION", "1.1");
myHeaders.append("Authorization", "Bearer <API_KEY>");

const requestOptions = {
  method: "GET",
  headers: myHeaders
};

const filters = JSON.stringify([
  { key: "primaryOwner", op: "equals", value: 1 },
  { key: "creationTime", op: "gt", value: "2024-08-03T09:40:20.000Z" }
])

const response = await fetch(`https://api.toriihq.com/v1.0/apps?filters=${encodeURIComponent(filters)}`, requestOptions)
const data = await response.json()