> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Filtering

> Reference for filtering Kodexa list API endpoints, including the two filter formats and how to combine criteria when querying platform resources.

API endpoints that allow you to list typically provide two ways of filtering the results.

## Query

You can use the query parameter to filter the results by a search term. The search term is matched against the name of the resource. For example, to list all the projects that contain the word "test" in their name, you can use the following query:

```bash theme={null}
GET /api/projects?query=test
```

## Filter

Filters allow for more precise queries on specific fields. The platform uses a SpringFilter-style DSL in the `filter` query parameter. For example, to list all projects named `test`:

```bash theme={null}
GET /api/projects?filter=name=='test'
```

### Fields

Field names are used directly. Dotted paths traverse related objects or structured fields. For example: `category.updatedAt`, `project.organization.id`, `features.slug`

### Inputs

Numbers and booleans are unquoted. Strings, enums, UUIDs, and dates should be single-quoted. For example: `status=='ACTIVE'`

### Operators

| Syntax       | Description                 | Example                                                            |
| ------------ | --------------------------- | ------------------------------------------------------------------ |
| `and` or `;` | Both expressions must match | `status=='ACTIVE' and createdAt>'2026-01-01'`                      |
| `or` or `,`  | Either expression may match | `status=='FAILED' or status=='PENDING'`                            |
| `(` `)`      | Group expressions           | `(status=='FAILED' or status=='PENDING') and project.id=='abc123'` |

<Note>
  Use parentheses when you want to override the default precedence of `and` before `or`.
</Note>

### Comparators

| Syntax        | Description           | Example                          |
| ------------- | --------------------- | -------------------------------- |
| `==`          | Equals                | `id==5`                          |
| `!=`          | Not equal             | `status!='ARCHIVED'`             |
| `>`           | Greater than          | `createdAt>'2026-01-01'`         |
| `>=`          | Greater than or equal | `priority>=5`                    |
| `<`           | Less than             | `pageCount<100`                  |
| `<=`          | Less than or equal    | `pageCount<=100`                 |
| `=like=`      | Wildcard string match | `path=like='*invoice*'`          |
| `=in=`        | Value is in a list    | `status=in=('FAILED','PENDING')` |
| `is null`     | Field is null         | `completedAt is null`            |
| `is not null` | Field is not null     | `project.id is not null`         |

<Note>
  Use `*` as the wildcard character with `=like=`. For example, `name=like='*invoice*'`.
</Note>

## Common Examples

```bash theme={null}
# Failed executions for a specific assistant
GET /api/executions?filter=status=='FAILED' and assistantId=='abc123'
```

```bash theme={null}
# Document families whose path contains "invoice"
GET /api/document-families?filter=path=like='*invoice*'
```

```bash theme={null}
# Pending document families
GET /api/document-families?filter=pendingProcessing==true
```

```bash theme={null}
# Document families linked to a specific knowledge feature
GET /api/document-families?filter=features.id=='550e8400-e29b-41d4-a716-446655440000'
```

## Sort

The `sort` query parameter uses semicolon-separated `field:direction` pairs:

```bash theme={null}
GET /api/executions?sort=createdOn:desc
GET /api/projects?sort=name:asc;createdOn:desc
```

The direction defaults to `asc`. If you omit `sort`, the platform falls back to its resource-specific default order.