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.

GET

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

Note

This endpoint is paginated by default, including a maximum of 100 stories in the response. See Pagination for further information.

Tip

An empty array rather than a 404 error is returned if no stories are found with the filters applied.

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 for any string in stories. The response contains all stories where the string appears anywhere in the name, slug/full slug, or content object (including UIDs, field values, asset file names, and rich text nodes and attributes, such as “bold”). Combine this parameter with the version parameter to filter by draft or published stories.

• 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 full_slug, 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. Entries can be resolved two levels deep.

  A maximum of 50 stories can be resolved in a single request. If this limit is exceeded, all story UUIDs are included in the rel_uuids property of the response and need to be resolved in subsequent API requests.

  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. When resolve_assets=1, an array of all assets associated with stories appear in the assets property of the response.

• 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 (Formats: yyyy-MM-dd HH:mm or ISO 8601 date format)

• first_published_at_lt string

  Retrieve stories first published before the specified date (Formats: yyyy-MM-dd HH:mm or ISO 8601 date format)

• published_at_gt string

  Retrieve stories published after the specified date (Formats: yyyy-MM-dd HH:mm or ISO 8601 date format)

• published_at_lt string

  Retrieve stories published before the specified date (Formats: yyyy-MM-dd HH:mm or ISO 8601 date format)

• published_at_gte string

  Retrieve stories published on or after the specified date (Formats: yyyy-MM-dd HH:mm or ISO 8601 date format)

• published_at_lte string

  Retrieve stories published on or before the specified date (Formats: yyyy-MM-dd HH:mm or ISO 8601 date format)

• updated_at_gt string

  Retrieve stories updated after the specified date (Formats: yyyy-MM-dd HH:mm or ISO 8601 date format)

• updated_at_lt string

  Retrieve stories updated before the specified date (Formats: yyyy-MM-dd HH:mm or ISO 8601 date format)

• 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

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

JS

// storyblok-js-client@>=7, node@>=18
import Storyblok from "storyblok-js-client";

const storyblok = new Storyblok({
  accessToken: "krcV6QGxWORpYLUWt12xKQtt",
});

try {
  const response = await storyblok.get('cdn/stories', {
    "version": "published",
    "starts_with": "articles"
  })
  console.log({ response })
} catch (error) {
  console.log(error)
}

PHP

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

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

Java

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

C#

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

Python

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)

Ruby

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

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

Swift

let storyblok = URLSession(storyblok: .cdn(accessToken: "ask9soUkv02QqbZgmZdeDAtt"))
var request = URLRequest(storyblok: storyblok, path: "stories")
request.url!.append(queryItems: [
    URLQueryItem(name: "version", value: "published"),
    URLQueryItem(name: "starts_with", value: "articles")
])
let (data, _) = try await storyblok.data(for: request)
print(try JSONSerialization.jsonObject(with: data))

Kotlin

val client = HttpClient {
    install(Storyblok(CDN)) {
        accessToken = "ask9soUkv02QqbZgmZdeDAtt"
    }
}

val response = client.get("stories") {
    url {
        parameters.append("version", "published")
        parameters.append("starts_with", "articles")
    }
}

println(response.body<JsonElement>())

Response

{
  "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": []
}