# 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.textmaster.com/overview/filters.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.