Stories

Storyblok’s most used endpoint is trimmed for low latency and optimum availability.

To achieve low latencies all over the world, Storyblok uses a CDN in front of the API. The official Storyblok SDKs already take care of cache invalidation, so you don’t have to. But if you are doing the API calls on your own, you will need to append the cv parameter to the story API in order to get the latest version of the content.

Cache invalidation using the spaces API or a timestamp

  1. First you call /v1/cdn/spaces/me to get the space.version attribute. Alternatively you can also generate timestamp.
  2. After that you append this space.version or the to all your subsequent calls to the endpoint /v1/cdn/stories using the cv parameter.
  3. For server side applications it is recommended to save the space.version to a file and refresh the content of the file listening to the published event. (https://www.storyblok.com/docs/Guides/storyblok-latest-js)

Get a list of stories

Endpoint

GET /v1/cdn/stories

Parameters

Name Description
token required Public token for published or private token for draft version
with_tag Filter by specific tag(s). Use comma to filter by multiple tags. Examples: with_tag=featured,home
is_startpage Filter by folder startpage. Use '1' to only return startpages and '0' to exclude startpages from the result.
starts_with Filter by slug. Can be used to retrieve all entries form a specific folder. Examples: starts_with=de, starts_with=en/news
by_uuids Get stories by comma separated uuids. Example: by_uuids=52323-...,52323-...
excluding_ids Exclude stories by comma separated ids. Example: excluding_ids=5,8
excluding_fields Exclude specific fields of your content type by comma seperated names. Example: excluding_fields=title,body
version Published or draft version. Possible values: 'draft', 'published'
cv Cache version. Important: Required if you want to get the latest published version. Read more at the top of the page.
sort_by Sort entries by specific attribute and order with 'content.YOUR_FIELD:asc' and 'content.YOUR_FIELD:desc'. Possible values are all root attributes of the entry and all fields of your content type inside 'content' with the dot as seperator. Example: 'position:asc', 'content.your_custom_field:asc', 'created_at:desc'
search_term Search content items by full text.
filter_query

Filter by specific attribute(s) of your content type. The filter query parameter needs to contain the query operation key. Separate the values by a comma , to filter by multiple values.

filter_query[YOUR_ATTRIBUTE][OPERATION_KEY]=VALUE,VALUE

Following filter operations (OPERATION_KEY´s) are available:
all - Contains all values of a string value
in - Contains one of the values of a string value
exists - Contains one of the values in an array value
gt-date - Greater than date (Format: 2018-03-03 10:00)
lt-date - Less than date
gt-num - Greater than numeric value
lt-num - Less than numeric value

Examples:
Is page and news content type: filter_query[component][all]=page,news
Is page or news content type: filter_query[component][in]=page,news
Has white style (styles is ['white', 'shiny']): filter_query[styles][exists]=white
Greater than date: filter_query[custom_date][gt-date]=2018-03-03 10:00
Greater than rating: filter_query[rating][gt-num]=4

resolve_links If resolve_links=1 it will automatically resolve internal links of the multilink field type. The limit of resolved links per Story is 50.
resolve_relations Resolve relationships to other Stories of a multi-option or single-option field-type. Provide the field key(s) as comma separated string to resolve specific fields. Example: authors,comments
per_page Define number of items per page.
page Get a specific page.

Try it out

Request

Query Parameters

token=wANpEQEsMYGOwLxwXQ76Ggtt
with_tag=red
starts_with=de/
excluding_ids=5,6
excluding_fields=title
version=published
cv=1514926039
sort_by=name:asc
filter_query[component][all]=page
per_page=10
page=0

cURL

curl "https://api.storyblok.com/v1/cdn/stories?token=wANpEQEsMYGOwLxwXQ76Ggtt&with_tag=red&starts_with=de%2F&excluding_ids=5%2C6&excluding_fields=title&version=published&cv=1514926039&sort_by=name%3Aasc&filter_query[component][all]=page&per_page=10&page=0" -X GET \
	-H "Accept: application/json" \
	-H "Content-Type: application/json"

Response

Body

{
  "stories": [
    {
      "name": "Home2",
      "created_at": "2018-01-02T20:47:18.945Z",
      "published_at": "2018-01-02T20:47:18.953Z",
      "alternates": [

      ],
      "id": 1887,
      "uuid": "45e4cf79-99ea-4771-a50d-58155a9a1d30",
      "content": {
        "_uid": "7b870b36-7512-40ef-bad3-e2cbb7513cba",
        "body": [

        ],
        "component": "page"
      },
      "slug": "de",
      "full_slug": "de/",
      "sort_by_date": null,
      "tag_list": [
        "spicy",
        "red"
      ],
      "is_startpage": true,
      "parent_id": 1886,
      "meta_data": null,
      "group_id": "7e44dd68-ef43-40e1-8814-aae4af7188b1"
    }
  ]
}

Get a story by id

This endpoint is used to get a single Story. It accepts a path (For example: home or article/blog-post-xy) or a uuid in the request url and returns a Story object.

Examples:
/v1/cdn/stories/article/blog-post-xy
/v1/cdn/stories/90b2172-3e61-4a1a-822c-e06d381cce07?find_by=uuid

Endpoint

GET /v1/cdn/stories/:story_id

Parameters

Name Description
token required Public token for published or private token for draft version
story_id Find a single Story by the full_slug if a string is provided and the id if a numeric value is provided (or by uuid if the find_by parameter is 'uuid').
find_by If provided and the value is 'uuid' the story_id is the uuid instead of the id and full_slug. Example: find_by=uuid.
version Published or draft version. Possible values: 'draft', 'published'.
resolve_links If resolve_links=1 it will automatically resolve internal links of the multilink field type. The limit of resolved links per Story is 50.
resolve_relations Resolve relationships to other Stories of a multi-option or single-option field-type. Provide the field key(s) as comma separated string to resolve specific fields. Example: authors,comments
cv Cache version. Important: Required if you want to get the latest published version. Read more at the top of the page.

Try it out

Request

Query Parameters

token=wANpEQEsMYGOwLxwXQ76Ggtt

cURL

curl "https://api.storyblok.com/v1/cdn/stories/de?token=wANpEQEsMYGOwLxwXQ76Ggtt" -X GET \
	-H "Accept: application/json" \
	-H "Content-Type: application/json"

Response

Body

{
  "story": {
    "name": "Home2",
    "created_at": "2018-10-05T08:46:12.471Z",
    "published_at": "2018-10-05T08:46:12.494Z",
    "alternates": [

    ],
    "id": 1565,
    "uuid": "a5ff6d40-25c7-499c-8657-e3ab2e2facdf",
    "content": {
      "_uid": "de65fb94-6a2d-41b1-bae7-1a23321de516",
      "body": [

      ],
      "author": "915ac9b7-fc60-4e2c-89ad-2291493698d7",
      "headline": "tom",
      "component": "page"
    },
    "slug": "de",
    "full_slug": "de/",
    "sort_by_date": null,
    "position": -20,
    "tag_list": [
      "spicy",
      "red"
    ],
    "is_startpage": true,
    "parent_id": 1564,
    "meta_data": null,
    "group_id": "d51bcc27-c8fb-49aa-a218-46fba902ac88"
  }
}

Documentation