Accessing your data

Storyblok offers a comprehensive API (application programming interface) that follows common patterns you see across the web. We offer a Content Delivery API, a Management API and a GraphQL API.

We will only discuss Content Delivery API in this part of the guide. The Content Delivery API is designed around the REST architecture principals and supports the four basic HTTP verbs GET, POST, PUT and DELETE. Responses will be in JSON (Javascript Object Notation) format.

Section titled Interacting with the Content Delivery API Interacting with the Content Delivery API

To interact with the Content Delivery API, you must ensure you have the access token associated with your Storyblok space. The access token serves as authentication credentials to interact with the Content Delivery API.

Section titled Retrieving your Access Token Retrieving your Access Token

Learn how to retrieve and generate access tokens by visiting our Access Token FAQ. It's important to note that making a request without a valid access token will result in an unauthorized error.

Your First API Request

To make a valid API request it is necessary to send a HTTP request to api.storyblok.com. If you want to try out a request to the Content Delivery API you can send a GET request from your web browser.

GET api.storyblok.com

The response will contain a simple JSON object indicating that the request was processed successfully.

{ "success" : true }

This response doesn’t contain a lot of valuable information, but it shows how a basic API request works. The next step is to fetch meaningful data from the Storyblok API.

Access Data

When a space is created, a new page is added automatically. To show how to access data using the API we will use this story and open the visual editor.

list view of the private assets in the assets library

To demonstrate what the API is going to return in different states, take a look at the data returned when pressing the "Published JSON" button {1}.

GET https://api.storyblok.com/v2/cdn/stories/home?version=published&token=<token>&cv=<timestamp>

{
  "stories":[
    "This record could not be found"
  ]
}

Since we didn’t publish the content yet there is nothing for the API to return. The error message indicates that the record can’t be found and that the HTTP status code will be 404. This result isn’t surprising because the content was not published yet. It is still possible to view the content in draft mode. To request the draft version of the content press the "Draft json" button {2}.

GET https://api.storyblok.com/v2/cdn/stories/home?version=draft&token=<token>&cv=<timestamp>

{
    "story": {
        "name": "Home",
        "slug": "home",
        "full_slug": "home",
        "id": 10718480,
        "uuid": "74a92c75-dbb6-4cb6-8c2f-b4582017c087",
        "content": {
            "_uid": "c0c5fd8d-6913-4ebf-bbed-a60d5e83dc1f",
            "component": "page",
            "body": [
                ...
            ],
            ...
        },
        ...
    }
}

After a successful request you should see a JSON object that contains the story still in draft mode. Every story has the same basic structure where id, uuid and slug that can be used to access the story directly. This example uses the slug of the story in the URL to identify the content but the uuid would have worked as well.

learn:

If you wonder about the difference between id, uuid or _uid there is an FAQ entry you can check out.

Values commonly used when working with the content are:

name user readable name of the story
content fields defined by a content type

learn:

A comprehensive description of the available properties can be found in the Content Delivery API documentation.

Let’s take a look at what the API returns once the content is published. To do that, press the "Publish" button {3} which changes the status of the story to be published. Now press the "Published json" button {1} again. The browser will open the now published content which should look very similar to what we were previously looking at in draft mode.

Private assets management

With Storyblok, you can create and manage private assets. Private assets are assets that are not available to the public and can only be accessed via an access token.

You can choose the visibility in the upload dialog and change it in the info dialog of already uploaded assets.

You can add upload a private asset using the management API by adding the parameter is_private=1 to the payload.

You can see filter the list view to see all private assets.

To access a private asset, create an asset access token and use the new assets API to get a signed URL. You can learn how to get a signed URL in this faq entry at storyblok.com/faq/how-to-create-a-protected-download-area.

SDKs

We have prepared some helpers and SDKs to get your new project started. The best place to find out about new SDKs is our GitHub page (https://github.com/storyblok).

Some of our most popular projects:

If this doesn’t cover the programming language you are using for your project there is always the option to use the HTTP client of the respective language directly. We have assembled how to use different HTTP clients on this reference page.

learn:

It’s also always worth taking a look at our awesome list where we collect valuable resources for Storyblok. It features a section of community contributions where you can find more SDKs and connectors.

Explaining the API URL Structure

The structure of the API URLs follows a common pattern which is in line with the REST principles. Each entry is represented by its own URL. The URL for the Content Delivery API consists of four parts. Looking at the URL from the previous example, these can be split into the following parts:

https://api.storyblok.com/v2/cdn/stories/home?version=draft&token=...&cv=...
       │-----------------│------│-------------│------------│---------│-----
       └── Base URL      │      └─ Resource   │            └─ token  │
                         └─ Path              └─ version             └─ cache

Base URL: https://api.storyblok.com/
Path: /v2/cdn
Resource: /{stories|spaces|datasources|datasource_entries|links|tags}, resource - see: tbd
Resource identifier: /{id|uuid|slug}, unique identifier of the resource - see: tbd
Parameters:
- version: {draft|published}, published or draft version - see: tbd
- token: {preview token|public token}, access token - see: tbd
- cv: {timestamp}, cache version - see: Content Delivery API Reference

Using the API

Content Delivery API: Stories One of the most fundamental elements in Storyblok is a Story. A Story can be fetched directly using its slug, id or uuid.

GET /v2/cdn/stories/(:full_slug|:id|:uuid)

Further details and all parameters are described in the Content Delivery API Reference.

Content Delivery API: Links

Links are an alternative representation of your content. Think of it as an alternative format for your stories. Each story is represented by an uuid. The link format then uses the uuid as a key to hold an object that contains basic information to identify, load or display a link to the resource.

GET /v2/cdn/links/

Further details and all parameters are described in the Content Delivery API Reference.

Filter Queries

The Content Delivery API offers a wide range of operators and allows to filter the result.

GET /v2/cdn/stories/?filter_query\[ATTRIBUTE\]\[OPERATION\]=VALUE,…

If you are interested in learning more about the capabilities of these filters or if you have a concrete use case in mind we suggest taking a look at the Content Delivery API Reference) and specifically at the examples we prepared for you.

Hint:

Please note that the _editable property is only included in the draft version of the story.

Content Versions

To make the API suitable for different use cases, accounts can have different API tokens for draft and published versions of the content.

To switch between these versions you can append the query parameter version={draft | published} and use the appropriate token to perform a call for the draft or published version of your content.

The preview token allows access to the draft and the published version of the content. This is useful during development, or for reviewing, before new content is deployed to production environments.

GET https://api.storyblok.com/v2/cdn/stories/home?version=draft&token=<preview-token>&cv=<timestamp>

Once the published content is used in a public environment it is highly recommended to use a different (public) token. The public token gives access only to published content and prevents accidental publishing of draft content.

GET https://api.storyblok.com/v2/cdn/stories/home?version=published&token=<public-token>&cv=<timestamp>