Skip to navigation

Filtering and sorting

Narrow and order a listing
View as MarkdownOpen in Claude

Listings accept five query parameters: page, filter, sort, include and fields. Any other query parameter answers 422.

Each endpoint documents the filters, sorts and includes it accepts.

Filtering

Filters go under filter:

filter[connected]=1
filter[team][]=12&filter[team][]=15
filter[s]=shop
  • A list filter takes several values with []. A row matches when it matches any of them.
  • Several filters combine: a row must match all of them.
  • Boolean filters take 1 or 0 (true and false also work).
  • An empty value is ignored: filter[team]= does not filter.

Sorting

sort takes a comma-separated list of fields. A leading - sorts that field in descending order:

sort=-created_at,name

Without sort, each listing uses the default order its endpoint documents.

Mistakes: 400 or 422

MistakeAnswer
A filter, sort or include the endpoint does not offer400 Invalid Query Parameter; source.parameter is filter, sort or include, and detail lists the allowed values
A value that is not valid for a filter, such as text where a number is expected422 Validation Error; source.parameter names the filter, for example filter[core_version]
A query parameter other than page, filter, sort, include and fields422 Validation Error

The allowed values are listed in full in the real answer:

{
  "errors": [
    {
      "status": "400",
      "title": "Invalid Query Parameter",
      "detail": "Requested filter(s) `colour` are not allowed. Allowed filter(s) are `...`.",
      "source": { "parameter": "filter" }
    }
  ],
  "jsonapi": { "version": "1.1" }
}