Storyblok Logo

Storyblok Ruby Client

This is the official Storyblok ruby client for easy access of the management and content delivery api.

Test Coverage Follow @Storyblok
Follow @Storyblok

🚀 Usage


gem 'storyblok'

Usage for the content delivery api

By default the client loads the "draft" version of the Story. Be sure to set the version to "published" to get the published content only.

# The draft mode is required for the preview 'draft')

# Requests only published stories 'published')

Using the APIs on other regions

You should use the space access token AND api_region: 'us' whenever your space was created under US Server Location.

client = 'YOUR_TOKEN', api_region: 'us')

Load a story

# Without cache
client = 'YOUR_TOKEN')

# Optionally set a cache client
redis = 'redis://localhost:6379')
cache = redis)
client = cache, token: 'YOUR_TOKEN')

# Get a story

Load a list of stories

# Get all Stories that start with news
  :starts_with => 'news'

Load a list of datasource entries

# Get all label datasource entries
  :datasource => 'labels'

Load a list of tags

# Get all Tags that within the folder news
  :starts_with => 'news'


Generate a navigation tree

tree = client.tree

puts '<ul>'
tree.each do |key, item|
  puts '<li>' + item['item']['name']

  if !item['children'].empty?
    puts '<ul>'
    item['children'].each do |key, inner_item|
      puts '<li>' + inner_item['item']['name'] + '</li>'
    puts '</ul>'

  puts '</li>'
puts '</ul>'

Get the space info

How to flush the cache

Following an example of how to flush the client cache:

cache = Redis.current)
client = cache, token: 'YOUR_TOKEN')

# Get a story and cache it

# Flush the cache

Usage for the management api

Initialize the client and load spaces

client = 'YOUR_OAUTH_TOKEN')

# Get your spaces

Create a story"spaces/{space_id}/stories", {story: {name: 'new', slug: "new"}})

Update a story

client.put("spaces/{space_id}/stories/{story_id}", {story: {name: 'new', slug: "new"}})

Delete a story


Rendering of richtext fields

This SDK comes with a rendering service for richtext fields of Storyblok to get html output.

Rendering a richtext field


Define a component renderer

Storyblok's richtext field also let's you insert content blocks. To render these blocks you can define a Lambda.

# Option 1: Define the resolver when initializing
client =
  component_resolver: ->(component, data) {
    case component
    when 'button'
    when 'your_custom_component'
      "<div class='welcome'>#{data['welcome_text']}</div>"

# Option 2: Define the resolver afterwards
client.set_component_resolver(->(component, data) {


How to build a gem file.

gem build storyblok.gemspec
gem push storyblok-2.0.X.gem

Running Tests

We use RSpec for testing.

To run the whole test suite you will need export the environment variables, ATTENTION when running the test suit with the variable REDIS_URL exported, the test suite will remove the keys with this pattern storyblok:* from the redis database defined by REDIS_URL
export REDIS_URL="redis://localhost:6379"

Optionally you can generate the test report coverage by setting the environment variable

export COVERAGE=true

To run the whole test suite use the following command:


To run tests without redis cache tests (for when you don't have redis, or to avoid the test suite to remove the keys with this pattern storyblok:* ):

rspec --tag ~redis_cache:true
  • Storyblok & Ruby on GitHub: Check all of our Ruby open source repos;
  • Storyblok & Ruby 5 minutes tutorial: will show you how you can use the API-based CMS Storyblok in combination with the Framework “Ruby on Rails”;
  • Technology Hub: We prepared technology hubs so that you can find selected beginner tutorials, videos, boilerplates, and even cheatsheets all in one place;
  • Storyblok CLI: A simple CLI for scaffolding Storyblok projects and fieldtypes.

ℹ️ More Resources



Please see our contributing guidelines and our code of conduct. This project use semantic-release for generate new versions by using commit messages and we use the Angular Convention to naming the commits. Check this question about it in semantic-release FAQ.