filter query parameter using SFS-1 (Soluts Filter Syntax v1) — a lightweight, predictable filter language. This page covers the mental model and common patterns; the Filtering reference is the full normative contract.
The mental model
A filter is a list of comparisons joined byAND (or ; as shorthand):
field, an operator, and a literal. The server validates everything against the endpoint’s schema before executing the query.
That is the whole language. There is no OR, no parentheses, no functions, no wildcards — and that is deliberate. SFS-1 prioritizes predictability over expressiveness.
Operators
For strings, booleans, and enums, you can only check equality. This keeps query performance bounded and prevents accidental full-text scans.
Common patterns
Equality
Range
>= start, < end) is the canonical way to express “all items in January” without overlap.
Multiple criteria
; is shorthand for AND — both are equivalent. Whitespace is optional but improves readability.
Enum filtering
direction=in will fail with INVALID_FILTER.
What you cannot do (and why)
The design rationale: filters should be cheap to plan, fast to execute, predictable to non-technical users. Complex boolean algebra defeats those goals.
Which fields can you filter on?
Filterable fields are explicitly allowlisted by each endpoint. Each endpoint’s reference page lists its filterable fields.
Trying to filter on a field not in the allowlist returns
INVALID_FILTER.
Literal forms
For values that contain spaces, dots, dashes that look like operators, or any non-identifier characters, quote them.
URL encoding
Thefilter value lives in the URL. Spaces, >, <, = must be encoded per RFC 3986:
Filtering and pagination interact
When you paginate (page_token), the filter you used on the first call must stay identical for every subsequent page. Changing it returns INVALID_PAGE_TOKEN. This is intentional — pagination tokens are bound to the filter context.
Reference
Filtering (SFS-1) — full reference contract
Operators, literals, validation, formal grammar.