Filtering

Filter results using the filter query parameter with bracket notation.

Syntax

?filter[fieldName]=value

Each endpoint documents its available filters in the OpenAPI spec below.

Filter Types

Exact Match

Most filters perform exact matching. Comma-separated values are treated as an IN clause:

?filter[id]=5            # Single value
?filter[id]=1,2,5        # Multiple values (WHERE id IN (1, 2, 5))
?filter[active]=1        # Boolean filter
?filter[vendorId]=3      # Foreign key filter

Partial Match (LIKE)

String/text filters typically use partial matching:

?filter[name]=Widget     # Matches "Widget", "Blue Widget", "Widget Pro", etc.

Translation Filters

For multi-language fields, append the locale code:

?filter[name.el]=...
?filter[name.en]=...
?filter[slug.en]=my-product

Between (Range)

Some numeric/date filters support range queries with comma-separated min,max:

?filter[inDates]=2026-01-01,2026-06-30   # WHERE blog_date >= '2026-01-01' AND blog_date <= '2026-06-30'

A range filter compiles to two separate predicates rather than a single BETWEEN clause. Both bounds are inclusive, and each is handed to the query builder as a bound, driver-escaped value.

Not Empty

Some filters check for non-empty values:

?filter[hasImage]=1      # Only entities where image is not empty

Combining Filters

Multiple filters are combined with AND logic:

?filter[active]=1&filter[vendorId]=3&filter[categoryId]=12

Discovering Filters from the OpenAPI Spec

Each resource's OpenAPI tag includes a vendor extension x-filters that lists all valid filters with their type:

Filter type	Operator	Description
exact	= / IN	Exact match; comma-separated values become an IN clause
partial	LIKE	Substring match; wraps the value in %...%
between	>= / <=	Range query; expects two comma-separated values (min, max). Compiles to two bound predicates, field >= min AND field <= max — inclusive at both ends
not_empty	IS NOT NULL / != ''	Existence check; pass 1 to filter for non-empty values

Example x-filters excerpt from a tag definition:

x-filters:
  id:
    type: exact
  name:
    type: partial
  inDates:
    type: between
  hasImage:
    type: not_empty
  active:
    type: exact

Range Filter Example

For between-type filters, pass a comma-separated min and max value:

?filter[inDates]=2026-01-01,2026-06-30

This translates to two bound predicates, WHERE blog_date >= '2026-01-01' AND blog_date <= '2026-06-30', returning only articles dated within that range — inclusive at both ends. Both bounds are passed as bound parameters, so neither can alter the shape of the query.

Use the x-filters vendor extensions to programmatically discover which filters each resource supports and what type of matching they perform.