Ruby SDK

The ButterCMS Ruby SDK provides a production-ready idiomatic Ruby interface with Rails support and a resilient fallback data store.

Installation

Bundler (Gemfile)

Add to your Gemfile:

gem 'buttercms-ruby'

Then run:

bundle install

gem install

gem install buttercms-ruby

Initialization

Configure the SDK with your Read API token from the ButterCMS Settings.

require 'buttercms-ruby'

ButterCMS::api_token = "your_api_token"

Configuration options

# Enable test/preview mode for draft content
ButterCMS::test_mode = true

# Customize timeout settings (in seconds)
ButterCMS::read_timeout = 5.0   # Default: 5.0
ButterCMS::open_timeout = 2.0   # Default: 2.0

Option	Type	Default	Description
api_token	String	-	Your ButterCMS Read API token (required)
test_mode	Boolean	false	Enable preview mode for draft content
read_timeout	Float	5.0	Read timeout in seconds
open_timeout	Float	2.0	Connection open timeout in seconds

API methods

Pages

Retrieve and search pages created in the ButterCMS dashboard.

# List all pages of a type
pages = ButterCMS::Page.list("landing_page", {
  page: 1,
  page_size: 10,
  locale: "en",
  preview: 1,    # Include draft content
  levels: 2      # Depth of nested references
})

# Access page data
pages.each do |page|
  puts page.fields[:headline]
end

# Retrieve a single page
page = ButterCMS::Page.get("landing_page", "home-page", {
  locale: "en"
})
puts page.fields[:headline]
puts page.fields[:body]

# Search pages
results = ButterCMS::Page.search("search query", {
  page: 1,
  page_size: 10
})

Collections

Fetch content from Collections (structured data tables).

# List collection items with pagination metadata
params = { page: 1, page_size: 10, locale: "en" }
collection = ButterCMS::Content.list("faq", params)

collection.items.each do |item|
  puts item[:question]
  puts item[:answer]
end

# Fetch multiple collections at once (without pagination)
content = ButterCMS::Content.fetch(["faq", "navigation"], {
  locale: "en"
})

Blog Posts

Access the built-in Blog Engine for posts, categories, tags, and authors.

# List blog posts
posts = ButterCMS::Post.all({
  page: 1,
  page_size: 10
})

posts.each do |post|
  puts post.title
end

# Access pagination metadata
puts posts.meta.next_page
puts posts.meta.previous_page

# Retrieve a single post
post = ButterCMS::Post.find("my-post-slug")
puts post.title
puts post.body

# Search posts
results = ButterCMS::Post.search("search query", {
  page: 1,
  page_size: 10
})

Authors

# List all authors
authors = ButterCMS::Author.all

# Retrieve a single author
author = ButterCMS::Author.find("jennifer-smith")
puts author.first_name
puts author.last_name

Categories

# List all categories
categories = ButterCMS::Category.all

# Retrieve a single category
category = ButterCMS::Category.find("news")
puts category.name
puts category.slug

Tags

# List all tags
tags = ButterCMS::Tag.all

# Each tag has name and slug
tags.each do |tag|
  puts tag.name
end

Feeds

Retrieve RSS, Atom, and Sitemap feeds.

# Get RSS feed
rss = ButterCMS::Feed.find(:rss)
puts rss.data

# Get Atom feed
atom = ButterCMS::Feed.find(:atom)

# Get Sitemap
sitemap = ButterCMS::Feed.find(:sitemap)

Query parameters reference

Parameter	Applies To	Description
page	Posts, Pages	Page number for pagination
page_size	Posts, Pages	Number of items per page
exclude_body	Posts	Exclude post body for faster response
author_slug	Posts	Filter posts by author
category_slug	Posts	Filter posts by category
tag_slug	Posts	Filter posts by tag
include	Authors, Categories, Tags	Include recent_posts with response
locale	Pages, Collections	Locale code for localized content
preview	Pages	Set to 1 to include draft content
levels	Pages	Depth of nested references (1–3)

Complete example

require 'buttercms-ruby'

ButterCMS::api_token = ENV["BUTTERCMS_API_TOKEN"]

def fetch_homepage_data
  # Fetch the home page
  page = ButterCMS::Page.get("landing_page", "home", {
    locale: "en"
  })

  # Fetch navigation from collection
  navigation = ButterCMS::Content.fetch(["main_navigation"])

  # Fetch recent blog posts
  posts = ButterCMS::Post.all({
    page: 1,
    page_size: 3
  })

  {
    page: page,
    navigation: navigation["main_navigation"],
    recent_posts: posts
  }
rescue => e
  puts "Error fetching content: #{e.message}"
  nil
end

# Usage
data = fetch_homepage_data
if data
  puts "Page headline: #{data[:page].fields[:headline]}"
  puts "Navigation items: #{data[:navigation].length}"
  puts "Recent posts: #{data[:recent_posts].length}"
end

Resources

GitHub Repository

View source code, report issues, and contribute

RubyGems

Package details and version history