Retrieve Multiple Stories

Returns an array of all stories (as story objects). The API response can be filtered using the query parameters, including specific filter queries.

https://api.storyblok.com/v2/cdn/stories

Query parameters

token required string

A preview or public access token
version draft | published

Default: published
cv number

Cached version Unix timestamp (see Cache Invalidation)
starts_with string

Filter by full_slug to only return stories starting with the given value, for example: starts_with=blog/posts
from_release string

Access a story version in a specific release by providing the release ID
search_term string

Search stories by full-text.
per_page number

Default: 25, Max: 100 (see Pagination)
page number

Default: 1 (see Pagination)
resolve_links story | url | link
Resolve link fields. Resolved links are included in the links property of the response.
- link: Provides access to additional information, such as a linked story’s path, parent_id, is_folder, published, is_startpage, position, alternates, real_path, and more.
- url: If only the path of a linked story is required, this value provides the minimum amount of information.
- story: Resolves and returns the complete story object of a linked story.
resolve_links_level 1 | 2

Default: 1. Resolve up to two levels of links.
resolve_relations string

Used to resolve referenced stories. Resolved stories are included in the rels property of the response. A maximum of 50 stories can be resolved. If this limit is exceeded, the story UUIDs are included in the rel_uuids property of the response and can be resolved in subsequent API requests. Entries can be resolved two levels deep. To resolve the stories selected in one field, provide the technical name of the immediate parent component of the field, followed by a . and the field name. To resolve the stories selected in multiple fields, provide a comma-separated list. Example: resolve_relations=page.author,page.categories
resolve_level 2

Used to force resolve second-level relations when the first level reaches a limit of 100 relations. While resolving relations, if the first level exceeds 100 relations, the API, by default, stops looking for the second level. Using resolve_level=2, second-level relations can be resolved even when the limit of first-level relations is reached.
resolve_assets number

Used to resolve asset metadata, including custom metadata. Resolved assets is included in the assets property of the response. Only available in higher-tier plans. Refer to Pricing for further information.
fallback_lang string

Define a custom fallback language to handle untranslated fields. Accepts any language code that is configured in the Storyblok space. Note that the language code needs to be provided with underscores, even if it is defined with hyphens. For example, es_co instead of es-co.
language string

Retrieve translated story version. Accepts any language code that is configured in the Storyblok space.
content_type string

Retrieve stories of a specific content type. Example: content_type=page
by_slugs string
Retrieve stories by comma-separated full_slug. Use wildcards by using *. Examples:
- by_slugs=posts/my-third-post,posts/my-second-post
- by_slugs=posts/*
excluding_slugs string
Exclude stories by comma-separated full_slug. Use wildcards by using *. Examples:
- excluding_slugs=posts/my-third-post,posts/my-second-post
- excluding_slugs=posts*
by_uuids string

Retrieve specific stories by providing their UUIDs as a comma-separated string. Example: by_uuids=a78b2116-c26d-4d23-9cbe-fec477847b0e,9683820e-fc17-429e-ba23-eb41f26c0776
by_uuids_ordered string

Retrieve specific stories by providing their UUIDs as a comma-separated string. The order of the stories in the response matches the order in which the UUIDs are listed. Example: by_uuids_ordered=a78b2116-c26d-4d23-9cbe-fec477847b0e,9683820e-fc17-429e-ba23-eb41f26c0776
excluding_ids string

Exclude specific stories by providing their IDs as a comma-separated string. Example: excluding_ids=335015953,335015954
with_tag string
Filter by specific tag(s) by providing their slug(s). Multiple tags can be provided as a comma-separated string (treated like an OR operator). Examples:
- with_tag=featured
- with_tag=featured,editors_choice
sort_by string
Sort stories in ascending or descending order by a specific property. Possible properties are all default story properties and any custom fields defined in the schema of the story type.
Default story properties can be sorted like this:
- sort_by=created_at:desc
- sort_by=slug:asc
Custom fields can be sorted like this:
- sort_by=content.meta_description:asc
- sort_by=content.event_title:desc
By default, all custom fields are sorted as strings. To sort custom fields with numeric values, specify whether they should be treated as float or integer. Examples:
- sort_by=content.price:asc:float
- sort_by=content.event_number:asc:int
Different sorts can be chained using commas: sort_by=name:desc,slug:asc
It is also possible to sort values keeping the null (or empty) ones first or last:
- sort_by=path:desc:nulls_first
- sort_by=path:desc:nulls_last.
nulls_last is the default behavior.
in_workflow_stages string

Retrieve stories that are in a particular workflow stage by providing a comma-separated list of workflow stage IDs. Example: in_workflow_stages=325604,325605
filter_query string

See Filter Queries.
level number
Retrieve stories located in the specified folder level. Examples:
- level=1 retrieves stories from the root folder
- level=2 retrieves stories from top-level folders
- level=3 retrieves stories from second-level folders
Only the immediate child stories are included in the response. Stories defined as root for the folder are excluded.
is_startpage 0 | 1

Filter by stories defined as root for the folder.
first_published_at_gt string

Retrieve stories first published after the specified date (Format: yyyy-MM-dd HH:mm)
first_published_at_lt string

Retrieve stories first published before the specified date (Format: yyyy-MM-dd HH:mm)
published_at_gt string

Retrieve stories published after the specified date (Format: yyyy-MM-dd HH:mm)
published_at_lt string

Retrieve stories published before the specified date (Format: yyyy-MM-dd HH:mm)
updated_at_gt string

Retrieve stories updated after the specified date (Format: yyyy-MM-dd HH:mm)
updated_at_lt string

Retrieve stories updated before the specified date (Format: yyyy-MM-dd HH:mm)
excluding_fields string

Exclude specific fields of a content type by providing the field names as a comma-separated string. Example: excluding_fields=body,meta_description
Note that excluding the component field from the response, the content of the story will be returned in the default language instead of a requested language.

Response properties

stories

An array of story objects.
rels

Array of resolved stories
links

An array of resolved links
rel_uuids

An array of all UUIDS of referenced stories (if the limit of resolvable relations is exceeded)
link_uuids

An array of all UUIDS of linked stories (if the limit of resolvable links is exceeded)

Examples

curl "https://api.storyblok.com/v2/cdn/stories?token=ask9soUkv02QqbZgmZdeDAtt&version=published&starts_with=articles"

// Using the Universal JavaScript Client:
// https://github.com/storyblok/storyblok-js-client
Storyblok.get('cdn/stories', {
  "version": "published",
  "starts_with": "articles"
})
  .then(response => {
    console.log(response)
  }).catch(error => {
    console.log(error)
  })

$client = new \Storyblok\Client('YOUR_STORYBLOK_SPACE_ACCESS_TOKEN');

$client->getStories([
  "version" => "published",
  "starts_with" => "articles"
])->getBody();

HttpResponse<String> response = Unirest.get("https://api.storyblok.com/v2/cdn/stories?token=ask9soUkv02QqbZgmZdeDAtt&version=published&starts_with=articles")
  .asString();

var client = new RestClient("https://api.storyblok.com/v2/cdn/stories?token=ask9soUkv02QqbZgmZdeDAtt&version=published&starts_with=articles");
var request = new RestRequest(Method.GET);

IRestResponse response = client.Execute(request);

import requests

url = "https://api.storyblok.com/v2/cdn/stories"

querystring = {"token":"ask9soUkv02QqbZgmZdeDAtt","version":"published","starts_with":"articles"}

payload = ""
headers = {}

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

require 'storyblok'
client = Storyblok::Client.new(token: 'YOUR_TOKEN')

client.stories({:params => {
  "version" => "published",
  "starts_with" => "articles"
}})

import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.storyblok.com/v2/cdn/stories?token=ask9soUkv02QqbZgmZdeDAtt&version=published&starts_with=articles")! 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()

{
  "stories": [
    {
      "name": "Mars Unveiled: Exploring the Mysteries and Marvels of the Red Frontier",
      "created_at": "2024-02-16T14:30:19.768Z",
      "published_at": "2024-03-13T17:20:40.220Z",
      "id": 445002665,
      "uuid": "a2c57c06-2c5c-4819-acb7-0d9c047d16e9",
      "content": {
        "_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": "e7307a9e-a3c5-47ad-8f6c-a1a36fe528e2",
        "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
    },
    {
      "name": "Earth's Symphony: Navigating the Wonders and Challenges of Our Blue Oasis",
      "created_at": "2024-02-16T14:22:09.108Z",
      "published_at": "2024-03-13T17:20:40.506Z",
      "id": 444996765,
      "uuid": "660452d2-1a68-4493-b5b6-2f03b6fa722b",
      "content": {
        "_uid": "6bdf037c-f713-415c-a26a-8a9cfc926c85",
        "image": {
          "id": 14114772,
          "alt": "",
          "name": "",
          "focus": "",
          "title": "",
          "source": "",
          "filename": "https://a.storyblok.com/f/276232/2560x1946/ee938cf736/earth.jpg",
          "copyright": "",
          "fieldtype": "asset",
          "meta_data": {},
          "is_private": "",
          "is_external_url": false
        },
        "author": "51eed33d-855f-415c-ac0d-4404e03b89e1",
        "topics": ["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. 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": "Earth's Symphony: Navigating the Wonders and Challenges of Our Blue Oasis",
        "component": "article",
        "scheduled": "2023-10-01 15:00",
        "categories": ["45d968b6-5790-4fbb-aa41-5781b8edde51", "d8e48716-0ecf-4059-b568-343bf54e4128"],
        "highlighted": false
      },
      "slug": "earths-symphony-navigating-wonders-challenges-blue-oasis",
      "full_slug": "articles/earths-symphony-navigating-wonders-challenges-blue-oasis",
      "sort_by_date": null,
      "position": 0,
      "tag_list": [],
      "is_startpage": false,
      "parent_id": 444991588,
      "meta_data": null,
      "group_id": "8d99d18d-5c97-42cd-a646-51e0c553f26a",
      "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": 1710350440,
  "rels": [],
  "links": []
}

Get in touch with the Storyblok community

Cookie notice

Retrieve Multiple Stories

Query parameters

Response properties

Examples