Stories

This endpoint is probably the most used one and it is trimmed for low latency and highest 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 need 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
starts_with Filter by slug. Can be used to retrieve all entries form a specific folder. Examples: starts_with=de, starts_with=en/news
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'
filter_by Filter by specific attribute(s) of your content type. It's also possible to filter by multiple values with filter_by[YOUR_ATTRIBUTE][]=red,filter_by[YOUR_ATTRIBUTE][]=blue. Examples: filter_by[component]=news (filters by content type news), filter_by[your_bool_attribute]=1
per_page Define numbers of items per page
page Get 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_by[component]=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_by[component]=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

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 by id if numeric and by full_slug if a string (or by uuid if find_by=uuid).
find_by If provided and the value is 'uuid' the story_id is the uuid instead of the id. Example: find_by=uuid
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.

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": "Home",
    "created_at": "2018-01-02T20:47:20.129Z",
    "published_at": "2018-01-02T20:47:20.136Z",
    "alternates": [

    ],
    "id": 1926,
    "uuid": "e07717da-51ec-4bd4-bbd9-bb785e70ed5a",
    "content": {
      "_uid": "5d4fe669-948d-4486-9a08-01ef8be04030",
      "body": [

      ],
      "component": "page"
    },
    "slug": "de",
    "full_slug": "de",
    "sort_by_date": null,
    "tag_list": [
      "spicy",
      "red"
    ],
    "is_startpage": false,
    "parent_id": 0,
    "meta_data": null,
    "group_id": "8c8bf14b-37a5-4f39-9580-9379aa0b07ce"
  }
}

Documentation