Introduction to Filter Queries

Filter by (a) specific field(s) of a content type. The filter_query parameter accepts a field and an operation key. Separate the values by a comma to filter by multiple values. The following syntax applies:

stories/?filter_query[field][operation]=value1,value2

You can use multiple filter queries per request. By default, the AND operator connects the applied filters, so a story must match every filter to appear in the results. For example, the following request returns only stories whose category is news and whose author is jane:

stories/?filter_query[category][in]=news&filter_query[author][in]=jane

To return stories that match any of the filters instead, connect them with the OR operator (Content Delivery API only) using the __or syntax:

stories/?filter_query[__or][][field][operation]=value&filter_query[__or][][field][operation]=value

For example, the following request returns stories whose category is news, plus stories whose author is jane, even when they don’t match both:

stories/?filter_query[__or][][category][in]=news&filter_query[__or][][author][in]=jane

Note

Filtering by default story properties is not supported.

Tip

Filter queries can be combined with other parameters applicable to the Stories endpoint.

Note

These operations apply to the Content Delivery API. The Management API stories endpoint supports the same operations with two exceptions. It doesn’t support any_in_array (use in_array instead), and it doesn’t support OR grouping, so its filters are always combined with AND.

https://api.storyblok.com/v2/cdn/stories?filter_query[field][operation]=value&token=ask9soUkv02QqbZgmZdeDAtt

The filter_query use cases throughout this section are based on the example story type for a simple blog article represented by the story object below.

The usage of filter_query is not limited to the fields of this example. Every custom field defined for a story type is included in the content object of a story object and can, therefore, be used as the field key in a filter_query.

Operations

• is
  Matches a value type (empty, not_empty, empty_array, not_empty_array, true, false, null, not_null)
• in
  Matches all with the exact specified value
• not_in
  Matches all without the exact specified value
• like
  Matches all with the specified value (wildcard allowed)
• not_like
  Matches all without the specified value (wildcard allowed)
• any_in_array

  Matches if any of the specified values is contained in the field value (array). Content Delivery API only; for the Management API, use in_array.

• in_array

  Management API equivalent of any_in_array: matches if any of the specified values is contained in the field value (array). Deprecated for the Content Delivery API in favor of any_in_array.

• all_in_array
  Matches if all specified values are contained in the field value (array)
• gt_date
  Greater than date (Format: YYYY-mm-dd HH:MM)
• lt_date
  Earlier than date (Format: YYYY-MM-DD HH:MM)
• gt_int
  Greater than integer value
• lt_int
  Lower than integer value
• gt_float
  Greater than float value
• lt_float
  Lower than float value