1. Nestable Bloks and Fields

Nestable Bloks and Fields

It is possible to use filter queries with nestable bloks and fields that return objects. The following syntax applies:

stories/?filter_query[field.property][operation]=value

Examples Use Cases

  • filter_query[body.0.name][in]=This is a nested blok

    Returns all stories which meet the following criteria:

    • a top-level bloks field named body
    • the first nested blok in this field (represented by the 0) has a name field with the value "This is a nested blok"
  • filter_query[seo.description][is]=not_empty

    Returns all stories configured with an seo field (using the SEO App) with the property description that is not empty

  • Example Request and Response

    The following example demonstrates how to use the filter_query parameter with nestable bloks.

    Request
    curl "https://api.storyblok.com/v2/cdn/stories/?filter_query[body.0.name][in]=This is a nested blok&token=ask9soUkv02QqbZgmZdeDAtt" \
      -X GET \
      -H "Accept: application/json" \
      -H "Content-Type: application/json"
    Request
    // Using the Universal JavaScript Client:
    // https://github.com/storyblok/storyblok-js-client
    Storyblok.get('cdn/stories/', {
      "filter_query": {
        "body.0.name": {
          "in": "This is a nested blok"
        }
      }
    })
      .then(response => {
        console.log(response)
      }).catch(error => { 
        console.log(error)
      })
    Request
    $client = new \Storyblok\Client('YOUR_STORYBLOK_SPACE_ACCESS_TOKEN');
    
    $client->getStories([
      "filter_query" =>  [
        "body.0.name" =>  [
          "in" =>  "This is a nested blok"
        ]
      ]
    ])->getBody();
    Request
    require 'storyblok'
    client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')
    
    client.stories({:params => {
      "filter_query" =>  {
        "body.0.name" =>  {
          "in" =>  "This is a nested blok"
        }
      }
    }})
    Request
    HttpResponse<String> response = Unirest.get("https://api.storyblok.com/v2/cdn/stories/?filter_query[body.0.name][in]=This is a nested blok&token=ask9soUkv02QqbZgmZdeDAtt")
      .asString();
    Request
    var client = new RestClient("https://api.storyblok.com/v2/cdn/stories/?filter_query[body.0.name][in]=This is a nested blok&token=ask9soUkv02QqbZgmZdeDAtt");
    var request = new RestRequest(Method.GET);
    
    IRestResponse response = client.Execute(request);
    Request
    import Foundation
    
    let request = NSMutableURLRequest(url: NSURL(string: "https://api.storyblok.com/v2/cdn/stories/?filter_query[body.0.name][in]=This is a nested blok&token=ask9soUkv02QqbZgmZdeDAtt")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
    request.method = "GET"
    
    let session = URLSession.shared
    let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
      if (error != nil) {
        print(error)
      } else {
        let httpResponse = response as? HTTPURLResponse
        print(httpResponse)
      }
    })
    
    dataTask.resume()
    Request
    import requests
    
    url = "https://api.storyblok.com/v2/cdn/stories/"
    
    querystring = {"filter_query":{"body.0.name":{"in":"This is a nested blok"}},"token":"ask9soUkv02QqbZgmZdeDAtt"}
    
    payload = ""
    headers = {}
    
    response = requests.request("GET", url, data=payload, headers=headers, params=querystring)
    
    print(response.text)
    Response
    {
      "stories": [
        {
          "name": "Nestable bloks",
          "created_at": "2024-03-07T18:22:10.389Z",
          "published_at": "2024-03-07T18:32:44.919Z",
          "id": 457784924,
          "uuid": "387914f2-0d36-4172-93c6-0f5535be2d27",
          "content": {
            "seo": {
              "_uid": "d3797349-49c9-4155-8d31-acdd15d47b05",
              "title": "SEO title",
              "plugin": "seo_metatags",
              "og_image": "",
              "og_title": "",
              "description": "Just a test",
              "twitter_image": "",
              "twitter_title": "",
              "og_description": "",
              "twitter_description": ""
            },
            "_uid": "a925a690-464c-4a88-b99f-35234e4bf49c",
            "body": [
              {
                "_uid": "73997a89-085a-44df-87d5-4f1b4f053b24",
                "name": "This is a nested blok",
                "component": "feature"
              }
            ],
            "component": "page"
          },
          "slug": "nested-fields",
          "full_slug": "nested-fields",
          "sort_by_date": null,
          "position": -40,
          "tag_list": [],
          "is_startpage": false,
          "parent_id": null,
          "meta_data": null,
          "group_id": "bb4c871c-fac7-47c0-8dc9-2bd58024647f",
          "first_published_at": "2024-03-07T18:23:14.717Z",
          "release_id": null,
          "lang": "default",
          "path": null,
          "alternates": [],
          "default_full_slug": null,
          "translated_slugs": null
        }
      ],
      "cv": 1709836364,
      "rels": [],
      "links": []
    }