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
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'
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

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_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

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'.
resolve_links Automatically resolve internal links of the multilink field type. The limit of resolved links per Story is 50.
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-04-10T11:10:39.503Z",
    "published_at": "2018-04-10T11:10:39.511Z",
    "alternates": [

    ],
    "id": 260,
    "uuid": "b67e4ea0-9302-464f-948b-2fd9f78a8d5a",
    "content": {
      "_uid": "dde401ac-e123-490e-b435-00fa562ff330",
      "body": [

      ],
      "component": "page"
    },
    "slug": "de",
    "full_slug": "de/",
    "sort_by_date": null,
    "position": 0,
    "tag_list": [
      "spicy",
      "red"
    ],
    "is_startpage": true,
    "parent_id": 259,
    "meta_data": null,
    "group_id": "18853943-2824-4f70-aa2d-07d00e463b32"
  }
}

Documentation