Skip to content
API ruby client for LocomotiveCMS
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
MIT-LICENSE upgrade gems + bump version to 1.5.0 Mar 8, 2018


Code Climate Dependency Status Build Status Coverage Status

The Ruby API Client for LocomotiveCMS V3.

Table of Contents


gem install locomotivecms_coal


First, load the gem:

require 'locomotive/coal'


client ='', { email: <EMAIL>, api_key: <API KEY> })

You can get the version of the remote running Engine by calling the following method:


Note: Coal supports Engine version ~> 3.0.x. However, if you do need to request an Engine running a 2.5.x version, use following code instead:

client ='', { email: <EMAIL>, api_key: <API KEY> })

We do not garantee that all the API resources will work with the V2 Client but PRs are accepted of course.



Get the name of the logged in account

my_account = client.my_account.get
puts + " / " +

If not logged in, then it's possible to create your account

client ='')
client.my_account.create(name: 'John Doe', email: '', password: 'easyone', password_confirmation: 'easyone')

Update my account

client.my_account.update(name: 'Jane Doe')


Get all my sites

my_sites = client.sites.all
puts "I've got #{my_sites.size}"

Create a new site

my_site = client.sites.create(name: 'Acme', handle: 'acme', locales: ['en'], timezone: 'UTC')

Destroy a site

my_site = client.sites.destroy(my_site._id)


Note: We first need to log in to the site. It can be done by calling the scope_by method of the client instance.

site = client.sites.by_handle('acme')
site_client = client.scope_by(site)

Or, in a shorter way:

site_client = client.scope_by('acme')

For the V2 Client, that would be this instead:

site = client.sites.by_subdomain('acme')

Get the list of pages in English

pages = site_client.pages.all(:en)

Get only the id/fullpath attributes

pages = site_client.pages.fullpaths(:en)

It is required when we need the id of an existing page according to its fullpath.

Create a page

page = site_client.pages.create(title: 'About us', slug: 'about-us', parent: 'index', template: 'Locomotive rocks!')

Update a page in French

site_client.pages.update(page._id, { template: 'Locomotive est trop fort!!!' }, :fr)

Destroy a page


Content Types

Get a content type by its slug

Note: We first need to log in to the site the content type belongs to. It can be done by calling the scope_by method of the client instance.

site = client.sites.by_subdomain('acme')
site_client = client.scope_by(site)

content_type = site_client.contents.projects

Content Entries

Get the first 10 entries filtered by a property (published)

articles = site_client.contents.articles.all({ published: true })

Loop over all the content entries

page = 1
while page do
  articles = site_client.contents.articles.all({ published: true }, page: page)
  articles.each { |article| puts article.title }
  page = articles._next_page

Note: You can also use the following syntax

content_type = site_client.contents.by_slug('projects')
articles = site_client.content_entries(content_type).all

Create a content entry

first_article = site_client.contents.articles.create(title: 'Hello world')

Update a content entry

article = site_client.contents.articles.all.first
site_client.contents.articles.update(article._id, { title: 'Hello world'})

Update a content entry in a different locale

# create the article in the default locale
article = site_client.contents.articles.create(title: 'Hello world')

# then update the title in another locale
site_client.contents.articles.update(article._id, { title: 'Bonjour le monde'}, :fr)

Destroy a content entry



Get the list of snippets

snippets = site_client.snippets.all

To get the snippets in the FR locale:

snippets_in_french = site_client.snippets.all('fr')

Create a snippet

snippet = site_client.snippets.create(name: 'Header', slug: 'header', template: 'Locomotive rocks!')

# create a snippet in different locales

snippet = site_client.snippets.create(name: 'Header', slug: 'header', template: { en: 'Locomotive rocks!', fr: 'Locomotive déchire !' })

Update a snippet

site_client.snippets.update('header', template: 'Locomotive rocks!!!')

Destroy a snippet



Get the list of sections

sections = site_client.sections.all

Create a section

snippet = site_client.sections.create(name: 'Header', slug: 'header', template: 'Locomotive rocks!', settings: [{ id: 'title', type: 'string' }])

Update a section

site_client.sections.update('header', template: 'Locomotive rocks!!!')

Destroy a section


Theme assets

Get the list of theme assets

assets = site_client.theme_assets.all

Create a theme asset

asset = site_client.theme_assets.create(source:'<local path of my image>'), folder: 'images/header')

Update a theme asset

site_client.theme_assets.update(asset._id, source:'<local path of my new image>'))

Destroy a theme asset


Content assets

Get the list of content assets

assets = site_client.content_assets.all

Create a content asset

asset = site_client.content_assets.create(source:'<local path of my image>'))

Update a content asset

site_client.content_assets.update(asset._id, source:'<local path of my new image>'))

Destroy a content asset



Get the list of translations

translations = site_client.translations.all

Create a translation

translation = site_client.translations.create(key: 'hello_world', values: { en: 'Hello world!', fr: 'Bonjour monde' })

Update a translation

site_client.translations.update(translation._id, values: { en: 'Hello world!!!', fr: 'Bonjour monde !!!'} ))

Destroy a translation



Get the list of memberships

memberships = site_client.memberships.all

Create a membership

membership = site_client.memberships.create(role: 'author', account_email: '')

Update a membership

site_client.memberships.update(account_email: '', role: 'admin')

Destroy a membership


What is missing?

We only implemented a few resources (my_account, sites, content types, memberships and content entries) and for some of them, not all the actions have been implemented.

Check the issues section of the repository to see what is missing.


  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

How to write specs

Engine configuration:

  1. You need to run the last version (master branch) of the Locomotive engine.
  2. Pick a different database name to run your Coal specs against.
  3. Run bundle exec rake development:bootstrap
  4. Run the Locomotive server bundle exec rails server

System configuration:

  • edit your /etc/hosts file (*NIX systems) and add 2 lines


Christian, Greg and Ben from the Cogip/Insert International LTD who brainstormed with me (a very long time) to find this awesome name.


Copyright (c) 2018 NoCoffee. MIT Licensed, see LICENSE for details.

You can’t perform that action at this time.