Filters

Learn how to use filters to query specific resources.

Some API resources expose a /filter endpoint which you can use to filter and order resources based on given query selectors. It allows you to narrow down specific items using a standard API.

It consists of the two URL encoded fields:

where	JSON query selectors
order	Comma seperated list of fields

Filter endpoints accept a where parameter which includes JSON holding the query selectors. For example:

{"status": "in_progress"}

You can also build more complex queries with query operators:

{"status": {"$in": ["in_progress", "completed"]}}

For example, the following query scopes projects with in_progress status with most recently created projects being first.

curl -G \
  --data-urlencode 'where={"status": "in_progress"}' \
  --data-urlencode 'order=-created_at' \
  https://api.textmaster.com/v1/clients/projects/filter

Warning: Unsupported query selectors will result in a 422 HTTP response.

Query Operators

$gt

Selects resources where the value of the field is greater than the given value.

{"word_count": {"$gt": 100}}
{"created_at": {"$gt": "1970-01-01T00:00:00Z"}}

$gte

Selects resources where the value of the field is greater than or equal to the given value.

{"word_count": {"$gte": 100}}
{"created_at": {"$gte": "1970-01-01T00:00:00Z"}}

$lt

Selects resources where the value of the field is less than the given value.

{"word_count": {"$lt": 100}}
{"created_at": {"$lt": "1970-01-01T00:00:00Z"}}

$lte

Selects resources where the value of the field is less than or equal to the given value.

{"word_count": {"$lte": 100}}
{"created_at": {"$lte": "1970-01-01T00:00:00Z"}}

$in

Selects resources where the value of the field is included in the given list of values.

{"status": {"$in": ["in_progress", "completed"]}}

$nin

Selects resources where the value of the field is not included in the given list of values.

{"status": {"$nin": ["in_progress", "completed"]}}

$ne

Selects resources where the value of the field is not equal to the given value.

{"status": {"$ne": "in_progress"}}

$or

Performs a logical OR operation on a list of two or more expressions and selects resources that satisfy at least one of the expressions.

{
  "$or": [
    {"status": "in_progress"},
    {"word_count": {"$gt": 100}}
  ]
}

$regex

Selects resources where the value of the field matches the given regular expression. It must be a string representation of a PCRE compatible regular expression.

Supported regular expression flags are:

• i toggles case insensitivity

• m toggles multi-line support

• x toggles an "extended" capability. When set, $regex ignores all white space characters unless escaped or included in a character class.

Selects all resources where their name field starts with "Some", ignoring the case:

{"name": {"$regex": "/^Some/i"}}

Order

order is a string parameter containing comma separated list of fields to sort by. If a field is prefixed with a - the sort order will be descending. For example, the following order specification will sort resources by status ascending and created_at descending order:

status,-created_at