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

Rate limits

Storyblok's GraphQL API limit is different from the REST API limit.

Why are the API rate limits different? With GraphQL, one GraphQL call can replace multiple REST calls. A single complex GraphQL call could be the equivalent of thousands of REST requests.

To accurately represent the server cost of a query, the Storyblok's GraphQL API calculates a call's rate limit score based on a normalized scale of points. A query's score factors in first and last arguments on a parent connection and its children.

The formula uses the first and last arguments on a parent connection and its children to pre-calculate the potential load on Storyblok's systems.

Each new connection has its own point value. Points are combined with other points from the call into an overall rate limit score.

Storyblok's GraphQL API rate limit is 100 points per second. Note that 100 points per second is not the same as 100 calls per second: the GraphQL API and REST API use different rate limits.

If the GraphQL API reaches 100 points per second it will return the status code 429 which means you can retry your call with a delay later.

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