Introduction

Filter by (a) specific field(s) of your story 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

It is possible to use multiple filter queries per request. By default, the applied filters are connected by the AND operator, but it is also possible to apply filters by the OR operator using the following syntax:

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

Filtering by default story properties is not supported.

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

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)
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

Lower than date (Format: (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

Example Request

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.

Example Story Object

{
  "story": {
    // default story properties
    "name": "Mars Unveiled: Exploring the Mysteries and Marvels of the Red Frontier",
    "created_at": "2024-02-16T14:30:19.768Z",
    "published_at": "2024-03-07T16:13:01.143Z",
    "id": 445002665,
    "uuid": "a2c57c06-2c5c-4819-acb7-0d9c047d16e9",
    "content": {
      // properties that are specific to the story type
      "_uid": "6bdf037c-f713-415c-a26a-8a9cfc926c85",
      "image": {
        "id": 14114865,
        "alt": "",
        "name": "",
        "focus": "",
        "title": "",
        "source": "",
        "filename": "https://a.storyblok.com/f/276232/3500x2000/cd4947ece2/mars.jpg",
        "copyright": "",
        "fieldtype": "asset",
        "meta_data": {},
        "is_private": "",
        "is_external_url": false
      },
      "author": "51eed33d-855f-415c-ac0d-4404e03b89e1",
      "topics": ["space-exploration", "solar-system"],
      "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.",
      "headline": "Mars Unveiled: Exploring the Mysteries and Marvels of the Red Frontier",
      "component": "article",
      "scheduled": "2024-02-29 17:00",
      "categories": [
        "45d968b6-5790-4fbb-aa41-5781b8edde51",
        "a6af7728-eadf-4428-8cf5-343304857374",
        "d8e48716-0ecf-4059-b568-343bf54e4128"
      ],
      "highlighted": false
    },
    "slug": "mars-unveiled-exploring-mysteries-marvels-red-frontier",
    "full_slug": "articles/mars-unveiled-exploring-mysteries-marvels-red-frontier",
    "sort_by_date": null,
    "position": 0,
    "tag_list": [],
    "is_startpage": false,
    "parent_id": 444991588,
    "meta_data": null,
    "group_id": "2e0c427d-63ed-420e-830f-bf1889da0792",
    "first_published_at": "2024-02-16T14:30:11.990Z",
    "release_id": null,
    "lang": "default",
    "path": null,
    "alternates": [],
    "default_full_slug": null,
    "translated_slugs": null
  },
  "cv": 1709828038,
  "rels": [],
  "links": []
}

Prev Examples

Next Nestable Bloks and Fields