# Filters

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:

```json
{"status": "in_progress"}
```

You can also build more complex queries with query operators:

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

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

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

{% hint style="warning" %}
**Warning:** Unsupported query selectors will result in a `422` HTTP response.
{% endhint %}

## Query Operators

### $gt

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

```json
{"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.

```json
{"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.

```json
{"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.

```json
{"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.

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

### $nin

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

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

### $ne

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

```json
{"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.

```json
{
  "$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](https://pcre.org/pcre.txt) 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:

```json
{"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
```