GraphQL Content Delivery Api

Beside the traditional REST API you can also use Storyblok with GraphQL, which offers a number of advantages like automated documentation and strongly typed responses. The API is a read-only endpoint and optimized for fast content delivery.

Endpoint

You can use following endpoint to send GraphQL requests:

https://gapi.storyblok.com/v1/api

The GraphQL endpoint is read-only, if you want to write, update or delete your content or migrate from another solution you can use our Management API for those operations.

Authentication

To communicate with the GraphQL endpoint, you will need to send an API token in the request header Token. You can find your read-only API token in the Space Settings area:

Storyblok Token

  • Public: Allows access to your published content entries: version=published results in 403 on version=draft
  • Preview: Allows access to the draft and published content entries: version=draft and version=published

Send your first request

To try out the GraphQL endpoint you can send a basic curl request with your bash console.

$ curl 'https://gapi.storyblok.com/v1/api' \
    -H 'Token: YOUR_PREVIEW_TOKEN' \
    -H 'Version: draft' \
    --data-binary '{ "query": "query { PageItems { items { name } } }" }'

GraphQL Playground

To see which queries are available you can use our GraphQL Browser. Just exchange YOUR_TOKEN with your API token and you can play around with the API:

http://gapi-browser.storyblok.com?token=YOUR_TOKEN

How to fetch content items

Generated fields

Storyblok’s GraphQL engine generates a field for each content type you define by using the pascal case version of the component name. For every content type Storyblok generates two fields.

  • One for receiving a single item: [Pascal-cased Name] Item
  • And one for receiving a multiple items: [Pascal-cased Name] Items

Examples:

  • page gets converted to PageItem and PageItems
  • blog-article gets converted to BlogArticleItem and BlogArticleItems

Query a single record

To query a single content item use the pascal-cased version of your content type name and provide an id as filter attribute which can be the id, uuid or slug of the item.

Following an example which shows how to get the content item with “home” as slug:

query {
  PageItem(id: "home") {
    name
    content {
       _uid
       component
    }
  }
}

Query multiple records

To query multiple content items you can use the pascal-cased version of your content type followed by the keyword Items. There are the same filters available as from the REST api endpoint. Please check the REST API documentation for the filter options you have.

Following an example of how to query the content type product and filter the result to show only items from a specific folder:

query {
  ProductItems(starts_with: "products/") {
    items {
      id
      name
    }
    total
  }
}

Pagination

When querying content items you can supply arguments that allows you to paginate the query response. Pagination allows you to request a certain amount of records at the same time. The default limit is 25 content items and the maximum is 100. With the attribute total you can get the total number of items which is useful to create pagination links.

Use per_page to limit the number of results:

{
  ProductItems(per_page: 5) {
    items {
      name
    }
    total
  }
}

By providing the page argument you can go to a specific offset (page is multiplied by the default per_page value 25):

{
  ProductItems(page: 2) {
    items {
      name
    }
    total
  }
}

Tutorial and Examples

To get started quickly we recommend our tutorial which uses GraphQL, React and Apollo: storyblok.com/tp/storyblok-graphql-react-apollo