Filtering

Filter records by field values using bracket notation in query parameters. Filters work with pagination, sorting, relationship expansion, and field selection.

Syntax

?filter[field]=value              # Equality (default)
?filter[field.operator]=value     # With operator

Multiple filters are combined with AND logic:

?filter[status]=active&filter[age.gte]=18

Operators

Operator	Syntax	Description	Example
eq	filter[field]=value	Equal to (default)	filter[status]=active
neq	filter[field.neq]=value	Not equal to	filter[status.neq]=inactive
gt	filter[field.gt]=value	Greater than	filter[age.gt]=18
gte	filter[field.gte]=value	Greater than or equal	filter[age.gte]=18
lt	filter[field.lt]=value	Less than	filter[price.lt]=100
lte	filter[field.lte]=value	Less than or equal	filter[price.lte]=100
like	filter[field.like]=value	Contains substring (case-sensitive)	filter[name.like]=Ali
in	filter[field.in]=a,b,c	In list (comma-separated)	filter[status.in]=active,pending
isNull	filter[field.isNull]=	Is null	filter[email.isNull]=
isNotNull	filter[field.isNotNull]=	Is not null	filter[email.isNotNull]=

Examples

Basic Equality Filter

curl ".../api/v1/acme-corp/sales/customers?filter[name]=Alice" \
  -H "Authorization: Bearer sk_live_abc123..."

Numeric Range

# Customers aged 18-65
curl ".../api/v1/acme-corp/sales/customers?filter[age.gte]=18&filter[age.lte]=65" \
  -H "Authorization: Bearer sk_live_abc123..."

Substring Search

# Customers with "smith" in their name
curl ".../api/v1/acme-corp/sales/customers?filter[name.like]=smith" \
  -H "Authorization: Bearer sk_live_abc123..."

Multiple Values (IN)

# Orders with status "pending" or "processing"
curl ".../api/v1/acme-corp/sales/orders?filter[status.in]=pending,processing" \
  -H "Authorization: Bearer sk_live_abc123..."

Null Checks

# Customers without an email address
curl ".../api/v1/acme-corp/sales/customers?filter[email.isNull]=" \
  -H "Authorization: Bearer sk_live_abc123..."

Combining with Other Features

Filters work seamlessly with pagination, sorting, expansion, and field selection:

# Active customers, sorted by name, page 2, with order count
curl ".../api/v1/acme-corp/sales/customers\
  ?filter[status]=active\
  &sort=name,asc\
  &page=1&size=10\
  &expand=orders\
  &fields=id,name,email,orders" \
  -H "Authorization: Bearer sk_live_abc123..."

Type Conversion

Filter values are automatically converted to match the column type:

Column Type	Filter Value	Converted To
INTEGER, BIGINT	"42"	42 (Long/Integer)
DECIMAL, NUMERIC	"19.99"	19.99 (BigDecimal)
BOOLEAN	"true"	true (Boolean)
VARCHAR, TEXT	"hello"	"hello" (String)

Type mismatches return a 400 BAD_REQUEST:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid value 'abc' for field 'age' (expected INTEGER)"
  }
}

Unknown Fields

Filtering by a field that doesn't exist on the entity returns 400 BAD_REQUEST:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Unknown filter field: 'nonexistent'"
  }
}

Filterable Fields Whitelist

Workspace admins can restrict which fields are filterable per entity via the API configuration. When a whitelist is set, only the listed fields accept filter queries. Attempting to filter on a non-whitelisted field returns 400 BAD_REQUEST.