NAV
curl Ruby Python Javascript PHP Go C#

Introduction

This document is a detailed reference for our REST API. See our full documentation for tutorials on using Butter with your framework.

The ButterCMS API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

As you read these docs, if you’re logged in, your actual API Key will be used in the sample code. If you don’t yet have an account, create one free.

Authentication

curl -X GET 'https://api.buttercms.com/v2/posts/?auth_token=api_token_b60a008a'
require "buttercms-ruby"
ButterCMS::api_token = "api_token_b60a008a"
var butter = require('buttercms')("api_token_b60a008a");
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("api_token_b60a008a")
<?
use ButterCMS\ButterCMS;
$butter = new ButterCMS('api_token_b60a008a');
?>
from butter_cms import ButterCMS
client = ButterCMS('api_token_b60a008a')
using ButterCMS;
var butterClient = new ButterCMSClient("api_token_b60a008a");

Authentication to the API is performed by passing your api token via the auth_token parameter on every request: ?auth_token=api_token_b60a008a. You can access your API token from your settings page.

Requests made with a missing or invalid token will get a 401 Unauthorized response. All requests must be made over HTTPS. Tokens provide complete access to your account, so keep them secure. Don’t put them in source code, use an environment variable instead.

Errors

Butter CMS uses conventional HTTP response codes. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided and codes in the 5xx range indicate an error with Butter’s servers (these are rare).

Code Description
200 Success.
400 Bad request, often due to missing a required parameter.
401 No valid API key provided.
404 The requested resource doesn’t exist.

Pages

Quickly launch a new marketing site or add pages to your existing one using our Pages end points.

List pages for a Page Type

Example request

curl -X GET 'https://api.buttercms.com/v2/pages/<page_type>/?auth_token=api_token_b60a008a'
require "buttercms-ruby"
ButterCMS::api_token = "api_token_b60a008a"

ButterCMS::Page.list('news', params)
var butter = require('buttercms')("api_token_b60a008a");

butter.page.list('news', params)
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("api_token_b60a008a")
ButterCMS.GetPages("news", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('api_token_b60a008a');
$butterCms->fetchPages('news', params);
?>
from butter_cms import ButterCMS
client = ButterCMS('api_token_b60a008a')
client.pages.all('news', params)
using ButterCMS;
butterClient.ListPages("news");
// We also support Async requests for all C# calls
butterClient.ListPagesAsync("news");

Example response

{
  "meta": {
    "previous_page": null,
    "next_page": null,
    "count": 1
  },
  "data": [
    {
      "slug": "example-news-page",
      "fields": {
          "seo_title": "Example News Page",
          "seo_description": "SEO Description",
          "seo_keywords": "SEO Keywords",
          "title": "This is an example news page",
          "body": "<p>Breaking news!</p>"
        }
      }
  ]
}

Retrieves a list of pages for a given Page Type. Supply the Page Type API slug.

Arguments

Argument Description
page_type Required. The slug of the type of pages you want to retrieve.
preview Optional param. Set to 1 to return the latest draft version of a page. Useful for previewing changes before publishing live. i.e. &preview=1
fields.key Optional param. Filter the result set by the field and value. You can pass in multiple filters at once. i.e. &fields.category=news&fields.genre=finance
order Optional param. Order the result set by this field. Defaults to Ascending. Preprend ’-’ to sort Descending. i.e. &order=-date_published
page Optional param. Used for Paginating through result set.
page_size Optional param. Used for Paginating. Defines the number of pages returned.

Returns

A hash with a data property that contains an array of pages matching the query, and a meta property that contains pagination information.

Retrieve a specific page

Example request

curl -X GET 'https://api.buttercms.com/v2/pages/<page_type>/<page_slug>/?auth_token=api_token_b60a008a'
require "buttercms-ruby"
ButterCMS::api_token = "api_token_b60a008a"

ButterCMS::Page.get('news', 'example-news-page', params)
var butter = require('buttercms')("api_token_b60a008a");

butter.page.retrieve('news', 'example-news-page', params)
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("api_token_b60a008a")
ButterCMS.GetPage("news", "example-news-page", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('api_token_b60a008a');
$butterCms->fetchPage('news', 'example-news-page', params);
?>
from butter_cms import ButterCMS
client = ButterCMS('api_token_b60a008a')
client.pages.get('news', 'example-news-page', params)
using ButterCMS;
butterClient.ListPage("news", "example-news-page");
// We also support Async requests for all C# calls
butterClient.ListPageAsync("news", "example-news-page");

Example response

{
  "data": {
    "slug": "example-news-page",
    "fields": {
      "seo_title": "Example News Page",
      "seo_description": "SEO Description",
      "seo_keywords": "SEO Keywords",
      "title": "This is an example news page",
      "body": "<p>Breaking news!</p>"
    }
  }
}

Retrieves a given page based on it’s slug and page type.

Arguments

Argument Description
page_type Required. The slug of the type of pages you want query.
page_slug Required. The slug of the page.
preview Optional param. Set to 1 to return the latest draft version of a page. Useful for previewing changes before publishing live. i.e. &preview=1

Returns

A hash with a data property that contains the page matching the page slug.

Content Fields

Content Fields are global pieces of content that can be managed by your team. They can be used for content that spans multiple pages (header, footer) or platforms (desktop, mobile). Each content field has unique key slug for querying via our API. Simply pass in as many keys as you’d like and we’ll return the content for them all at once.

Retrieve content

Example request

curl -X GET 'https://api.buttercms.com/v2/content/?keys=homepage_headline,homepage_title&auth_token=api_token_b60a008a'
require "buttercms-ruby"
ButterCMS::api_token = "api_token_b60a008a"

content = ButterCMS::Content.fetch([
  :homepage_title,
  :homepage_headline
])
var butter = require('buttercms')("api_token_b60a008a");

butter.content.retrieve(['homepage_title', 'homepage_headline'])
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("api_token_b60a008a")
ButterCMS.GetContentFields([]string{"homepage_headline", "homepage_title"})
<?
use ButterCMS\ButterCMS;
$butter = new ButterCMS('api_token_b60a008a');
$butter->fetchContentFields(['homepage_headline', 'homepage_title']);
?>
from butter_cms import ButterCMS
client = ButterCMS('api_token_b60a008a')
client.content_fields.get(['homepage_headline', 'homepage_title'])
// You can pass one or more keys at a time
var keys = new string[2] { "homepage_headline", "homepage_title" };
var contentFields = await butterClient.RetrieveContentFieldsJSONAsync(keys);

Example response

{
  "data": {
    "homepage_title": "ButterCMS",
    "homepage_headline": "API-first CMS and blogging platform built for developers"
  }
}

Returns values for the supplied content field keys.

Arguments

Argument Description
keys Comma delimited list of content field keys.
test Optional. Set to 1 to enable test mode for viewing draft content.
locale Optional. Set to the api slug of your configured locale (i.e. en or fr)

Returns

A hash with a data property that contains a hash of content field keys and values.

Filtering Collections

Sometimes you want to filter a collection to return only a subset of items, or in the case of landing pages, just one specific page. To do this you simply add the filter to the API key. i.e. collection_api_key[property=value]

For example, if you have several landing pages defined in a Collection:

/v2/content/?keys=landing_pages

You can filter on any collection property, allowing you to retrieve one specific page based on a slug property:

/v2/content/?keys=landing_pages[slug=my-landing-page-url-slug]

You can also perform multiple filter operations to get multiple entries from the same collection.

/v2/content/?keys=team[name=Elon Musk],team[name=Steve Jobs]

Test Mode

Example Request

curl -X GET 'https://api.buttercms.com/v2/content/?keys=headline&test=1&auth_token=api_token_b60a008a'

Test mode can be used to setup a staging website for previewing content. Set add test=1 as a parameter to the API call to retrieve the preview version of content.

You’ll often want to set this flag to true in your local and development environments.

Localization

Example Request

curl -X GET 'https://api.buttercms.com/v2/content/?keys=headline&locale=en&auth_token=api_token_b60a008a'

When Localization is enabled in your account, your content has a version for each locale specified. To query content based on locale, simply add locale= as a parameter. For example:

/v2/content/?keys=headline&locale=en

The API slugs values for each locale are configured by you in your account.

Blog Engine

The ButterCMS Blog Engine provides you with a set of pre-built API’s to quickly add a fully customized blog to your website.

Blog Posts

The post object

Attribute Description
slug string Unique identifier
url string Full url of post based on base URL in settings
published timestamp Timestamp of when the post was published
created string
status string draft or published
title string
body string Full HTML body
summary string Plain-text summary
seo_title string Use in HTML title tag
meta_description string Use in meta and og description tags
author hash, author object
categories array, category objects
tags array, tag objects
featured_image CDN URL of featured image

List all posts

Example request

curl -X GET 'https://api.buttercms.com/v2/posts/?page=1&page_size=10&auth_token=api_token_b60a008a'
require "buttercms-ruby"
ButterCMS::api_token = "api_token_b60a008a"

posts = ButterCMS::Post.all({:page => 1, :page_size => 10})
var butter = require('buttercms')("api_token_b60a008a");

butter.post.list({page: 1, page_size: 10})
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("api_token_b60a008a")
params := map[string]string{"page_size": "10"}
ButterCMS.GetPosts(params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('api_token_b60a008a');
$butterCms->fetchPosts(['page_size' => 10]);
?>
from butter_cms import ButterCMS
client = ButterCMS('api_token_b60a008a')
client.posts.all({'page_size': 10})
using ButterCMS;
PostsResponse posts = butterClient.ListPosts(page: 2, 
  pageSize: 5, 
  excludeBody: true, 
  authorSlug: "alice", 
  categorySlug: "dot-net",
  tagSlug: "wonderland"
);

// We also support Async requests for all C# calls
PostsResponse filteredPosts = await butterClient.ListPostsAsync();

Example response

{
  "meta": {
    "count": 1,
    "next_page": null,
    "previous_page": null
  },
  "data": [
    {
      "url": "http://www.example.com/blog/this-is-a-blog-post",
      "created": "2015-06-12T13:59:32.441289Z",
      "published": "2015-06-12T00:00:00Z",
      "author": {
        "first_name": "API",
        "last_name": "Test",
        "email": "apitest@buttercms.com",
        "slug": "api-test",
        "bio": "This is my bio.",
        "title": "API",
        "linkedin_url": "https://www.linkedin.com/in/API",
        "facebook_url": "https://www.facebook.com/API",
        "twitter_handle": "buttercmsapi",
        "profile_image": "https://buttercms.com/api.png"
      },
      "categories": [
        {
          "name": "test category",
          "slug": "test-category"
        }
      ],
      "tags": [
        {
          "name": "test tag",
          "slug": "test-tag"
        }
      ],
      "featured_image": null,
      "slug": "this-is-a-blog-post",
      "title": "This is a blog post",
      "body": "<p class=\"\">This is a blog post to test the API.</p>",
      "summary": "This is a blog post to test the API.",
      "seo_title": "This is a blog post",
      "meta_description": "This is a blog post to test the API.",
      "status": "published"
    }
  ]
}
<ButterCMS::ButterCollection:0x007fd86c96de70 @meta=#<OpenStruct count=1, next_page=nil, previous_page=nil>, @items=[#<ButterCMS::Post:0x3fec364b6bc8> JSON: {
  "data": {
    "url": "http://www.example.com/blog/this-is-a-blog-post",
    "created": "2015-06-12T13:59:32.441289Z",
    "published": "2015-06-12T00:00:00Z",
    "author": {
      "first_name": "API",
      "last_name": "Test",
      "email": "apitest@buttercms.com",
      "slug": "api-test",
      "bio": "This is my bio.",
      "title": "API",
      "linkedin_url": "https://www.linkedin.com/in/API",
      "facebook_url": "https://www.facebook.com/API",
      "twitter_handle": "buttercmsapi",
      "profile_image": "https://buttercms.com/api.png"
    },
    "categories": [
      {
        "name": "test category",
        "slug": "test-category"
      }
    ],
    "tags": [
      {
        "name": "test tag",
        "slug": "test-tag"
      }
    ],
    "featured_image": null,
    "slug": "this-is-a-blog-post",
    "title": "This is a blog post",
    "body": "<p class=\"\">This is a blog post to test the API.</p>",
    "summary": "This is a blog post to test the API.",
    "seo_title": "This is a blog post",
    "meta_description": "This is a blog post to test the API.",
    "status": "published"
  }
}]>
{
  "meta": {
    "count": 1,
    "next_page": null,
    "previous_page": null
  },
  "data": [
    {
      "url": "http://www.example.com/blog/this-is-a-blog-post",
      "created": "2015-06-12T13:59:32.441289Z",
      "published": "2015-06-12T00:00:00Z",
      "author": {
        "first_name": "API",
        "last_name": "Test",
        "email": "apitest@buttercms.com",
        "slug": "api-test",
        "bio": "This is my bio.",
        "title": "API",
        "linkedin_url": "https://www.linkedin.com/in/API",
        "facebook_url": "https://www.facebook.com/API",
        "pinterest_url": "https://www.pinterest.com/API",
        "instagram_url": "https://www.instagram.com/API",
        "twitter_handle": "buttercmsapi",
        "profile_image": "https://buttercms.com/api.png"
      },
      "categories": [
        {
          "name": "test category",
          "slug": "test-category"
        }
      ],
      "tags": [
        {
          "name": "test tag",
          "slug": "test-tag"
        }
      ],
      "featured_image": null,
      "slug": "this-is-a-blog-post",
      "title": "This is a blog post",
      "body": "<p class=\"\">This is a blog post to test the API.</p>",
      "summary": "This is a blog post to test the API.",
      "seo_title": "This is a blog post",
      "meta_description": "This is a blog post to test the API.",
      "status": "published"
    }
  ]
}
JSON: {
{
  "meta": {
    "count": 1,
    "next_page": null,
    "previous_page": null
  },
  "data": [
    {
      "url": "http://www.example.com/blog/this-is-a-blog-post",
      "created": "2015-06-12T13:59:32.441289Z",
      "published": "2015-06-12T00:00:00Z",
      "author": {
        "first_name": "API",
        "last_name": "Test",
        "email": "apitest@buttercms.com",
        "slug": "api-test",
        "bio": "This is my bio.",
        "title": "API",
        "linkedin_url": "https://www.linkedin.com/in/API",
        "facebook_url": "https://www.facebook.com/API",
        "twitter_handle": "buttercmsapi",
        "profile_image": "https://buttercms.com/api.png"
      },
      "categories": [
        {
          "name": "test category",
          "slug": "test-category"
        }
      ],
      "tags": [
        {
          "name": "test tag",
          "slug": "test-tag"
        }
      ],
      "featured_image": null,
      "slug": "this-is-a-blog-post",
      "title": "This is a blog post",
      "body": "<p class=\"\">This is a blog post to test the API.</p>",
      "summary": "This is a blog post to test the API.",
      "seo_title": "This is a blog post",
      "meta_description": "This is a blog post to test the API.",
      "status": "published"
    }
  ]
}
JSON: {
{
  "meta": {
    "count": 1,
    "next_page": null,
    "previous_page": null
  },
  "data": [
    {
      "url": "http://www.example.com/blog/this-is-a-blog-post",
      "created": "2015-06-12T13:59:32.441289Z",
      "published": "2015-06-12T00:00:00Z",
      "author": {
        "first_name": "API",
        "last_name": "Test",
        "email": "apitest@buttercms.com",
        "slug": "api-test",
        "bio": "This is my bio.",
        "title": "API",
        "linkedin_url": "https://www.linkedin.com/in/API",
        "facebook_url": "https://www.facebook.com/API",
        "twitter_handle": "buttercmsapi",
        "profile_image": "https://buttercms.com/api.png"
      },
      "categories": [
        {
          "name": "test category",
          "slug": "test-category"
        }
      ],
      "tags": [
        {
          "name": "test tag",
          "slug": "test-tag"
        }
      ],
      "featured_image": null,
      "slug": "this-is-a-blog-post",
      "title": "This is a blog post",
      "body": "<p class=\"\">This is a blog post to test the API.</p>",
      "summary": "This is a blog post to test the API.",
      "seo_title": "This is a blog post",
      "meta_description": "This is a blog post to test the API.",
      "status": "published"
    }
  ]
}
{
  "meta": {
    "count": 1,
    "next_page": null,
    "previous_page": null
  },
  "data": [
    {
      "url": "http://www.example.com/blog/this-is-a-blog-post",
      "created": "2015-06-12T13:59:32.441289Z",
      "published": "2015-06-12T00:00:00Z",
      "author": {
        "first_name": "API",
        "last_name": "Test",
        "email": "apitest@buttercms.com",
        "slug": "api-test",
        "bio": "This is my bio.",
        "title": "API",
        "linkedin_url": "https://www.linkedin.com/in/API",
        "facebook_url": "https://www.facebook.com/API",
        "twitter_handle": "buttercmsapi",
        "profile_image": "https://buttercms.com/api.png"
      },
      "categories": [
        {
          "name": "test category",
          "slug": "test-category"
        }
      ],
      "tags": [
        {
          "name": "test tag",
          "slug": "test-tag"
        }
      ],
      "featured_image": null,
      "slug": "this-is-a-blog-post",
      "title": "This is a blog post",
      "body": "<p class=\"\">This is a blog post to test the API.</p>",
      "summary": "This is a blog post to test the API.",
      "seo_title": "This is a blog post",
      "meta_description": "This is a blog post to test the API.",
      "status": "published"
    }
  ]
}
{
  "meta": {
    "count": 1,
    "next_page": null,
    "previous_page": null
  },
  "data": [
    {
      "url": "http://www.example.com/blog/this-is-a-blog-post",
      "created": "2015-06-12T13:59:32.441289Z",
      "published": "2015-06-12T00:00:00Z",
      "author": {
        "first_name": "API",
        "last_name": "Test",
        "email": "apitest@buttercms.com",
        "slug": "api-test",
        "bio": "This is my bio.",
        "title": "API",
        "linkedin_url": "https://www.linkedin.com/in/API",
        "facebook_url": "https://www.facebook.com/API",
        "twitter_handle": "buttercmsapi",
        "profile_image": "https://buttercms.com/api.png"
      },
      "categories": [
        {
          "name": "test category",
          "slug": "test-category"
        }
      ],
      "tags": [
        {
          "name": "test tag",
          "slug": "test-tag"
        }
      ],
      "featured_image": null,
      "slug": "this-is-a-blog-post",
      "title": "This is a blog post",
      "body": "<p class=\"\">This is a blog post to test the API.</p>",
      "summary": "This is a blog post to test the API.",
      "seo_title": "This is a blog post",
      "meta_description": "This is a blog post to test the API.",
      "status": "published"
    }
  ]
}

Returns a list of published posts. The posts are returned sorted by publish date, with the most recent posts appearing first. The endpoint supports pagination and filtering.

Arguments

Argument Default Description
page 1 Used to paginate through older posts.
page_size 10 Used to set the number of blog posts shown per page.
exclude_body false When true, does not return the full post body. Useful for keeping response size down when showing list of blog posts.
author_slug Filter posts by an author’s slug.
category_slug Filter posts by a category’s slug.
tag_slug Filter posts by a tag’s slug.

Returns

A hash with a data property that contains an array of posts, and a meta property that contains the total number of posts and the next and previous page number if they exist.

Retrieve a post

Example request

curl -X GET 'https://api.buttercms.com/v2/posts/<slug>/?auth_token=api_token_b60a008a'
require "buttercms-ruby"
ButterCMS::api_token = "api_token_b60a008a"

post = ButterCMS::Post.find("hello-world")
var butter = require('buttercms')("api_token_b60a008a");

butter.post.retrieve("hello-world")
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("api_token_b60a008a")
ButterCMS.GetPost("hello-world")
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('api_token_b60a008a');
$butterCms->fetchPost('hello-world');
?>
from butter_cms import ButterCMS
client = ButterCMS('api_token_b60a008a')
client.posts.get('hello-world')
using ButterCMS;
PostResponse controversialPost = 
  butterClient.RetrievePost("tabs-vs-spaces-throwdown");
// We also support Async requests for all C# calls
PostResponse safePost = 
  await butterClient.RetrievePostAsync("puppies-and-kittens");

Example response

{
  "meta": {
    "next_post": null,
    "previous_post": {
      "slug": "google-analytics-is-now-integrated-with-your-butter-blog",
      "title": "Google Analytics is now integrated with your Butter blog",
      "featured_image": "https://d2devwt40at1e2.cloudfront.net/api/file/etSDYJUIFDADGEEAQ/"
    }
  },
  "data": {
    "url": "http://www.example.com/blog/this-is-a-blog-post",
    "created": "2015-06-12T13:59:32.441289Z",
    "published": "2015-06-12T00:00:00Z",
    "author": {
      "first_name": "API",
      "last_name": "Test",
      "email": "apitest@buttercms.com",
      "slug": "api-test",
      "bio": "This is my bio.",
      "title": "API",
      "linkedin_url": "https://www.linkedin.com/in/API",
      "facebook_url": "https://www.facebook.com/API",
      "pinterest_url": "https://www.pinterest.com/API",
      "instagram_url": "https://www.instagram.com/API",
      "twitter_handle": "buttercmsapi",
      "profile_image": "https://buttercms.com/api.png"
    },
    "categories": [
      {
        "name": "test category",
        "slug": "test-category"
      }
    ],
    "tags": [
        {
          "name": "test tag",
          "slug": "test-tag"
        }
      ],
    "featured_image": null,
    "slug": "hello-world",
    "title": "This is a blog post",
    "body": "<p class=\"\">This is a blog post to test the API.</p>",
    "summary": "This is a blog post to test the API.",
    "seo_title": "This is a blog post",
    "meta_description": "This is a blog post to test the API.",
    "status": "published"
  }
}

Retrieves the details of a post. Supply the unique slug of the post.

Arguments

Argument Description
slug The slug of the post to be retrieved.

Returns

A hash with a data property that contains a post object, and a meta property that contains properties of the next and previous post if they exist.

Search Posts

Example Request

curl -X GET 'https://api.buttercms.com/v2/search/?query=my+favorite+post&auth_token=api_token_b60a008a'
require "buttercms-ruby"
ButterCMS::api_token = "api_token_b60a008a"

posts = ButterCMS::Post.search("my favorite post", {page: 1, page_size: 10})
var butter = require('buttercms')("api_token_b60a008a");

butter.post.search("my favorite post")
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("api_token_b60a008a")
params := map[string]string{"page": "1"}
ButterCMS.SearchPosts("query", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('api_token_b60a008a');
$butterCms->searchPosts('query', ['page' => 1]);
?>
from butter_cms import ButterCMS
client = ButterCMS('api_token_b60a008a')
client.posts.search('query', page=1)
using ButterCMS;
PostsResponse posts = 
  butterClient.SearchPosts("spaceships");
// We also support Async requests for all C# calls
PostsResponse caffeinePosts = 
  await butterClient.SearchPostsAsync(query: "coffee", 
    page: 3, 
    pageSize: 5
  );

Example response

{
  "meta": {
    "count": 1,
    "next_page": null,
    "previous_page": null
  },
  "data": [
    {
      "url": "http://www.example.com/blog/this-is-a-blog-post",
      "created": "2015-06-12T13:59:32.441289Z",
      "published": "2015-06-12T00:00:00Z",
      "author": {
        "first_name": "API",
        "last_name": "Test",
        "email": "apitest@buttercms.com",
        "slug": "api-test",
        "bio": "This is my bio.",
        "title": "API",
        "linkedin_url": "https://www.linkedin.com/in/API",
        "facebook_url": "https://www.facebook.com/API",
        "twitter_handle": "buttercmsapi",
        "profile_image": "https://buttercms.com/api.png"
      },
      "categories": [
        {
          "name": "test category",
          "slug": "test-category"
        }
      ],
      "tags": [
        {
          "name": "test tag",
          "slug": "test-tag"
        }
      ],
      "featured_image": null,
      "slug": "this-is-a-blog-post",
      "title": "This is a blog post",
      "body": "<p class=\"\">This is a blog post to test the API.</p>",
      "summary": "This is a blog post to test the API.",
      "seo_title": "This is a blog post",
      "meta_description": "This is a blog post to test the API.",
      "status": "published",
      "rank": 0.5
    }
  ]
}

Returns a list of posts that match the search query. The posts are returned sorted by relevancy and include their absolute rank value based on looking at the post title and body fields.

Arguments

Argument Default Description
query Search query
page 1
page_size 10

Returns

A hash with a data property that contains an array of posts, and a meta property that contains the total number of posts and the next and previous page number if they exist.

If no results are found, the API returns an empty array: "data": []

Authors

The author object

Attribute Description
slug string Unique identifier
first_name string
last_name string
email string
bio string
title string
linkedin_url string
facebook_url string
pinterest_url string
instagram_url string
twitter_handle string
profile_image string CDN URL of author’s image.

List all authors

Example request

curl -X GET 'https://api.buttercms.com/v2/authors/?auth_token=api_token_b60a008a'
require "buttercms-ruby"
ButterCMS::api_token = "api_token_b60a008a"

authors = ButterCMS::Author.all()
var butter = require('buttercms')("api_token_b60a008a");

butter.author.list()
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("api_token_b60a008a")
params = map[string]string{"include": "recent_posts"}
ButterCMS.GetAuthors(params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('api_token_b60a008a');
$butterCms->fetchAuthors(['include' => 'recent_posts']);
?>
from butter_cms import ButterCMS
client = ButterCMS('api_token_b60a008a')
client.authors.all({'include':'recent_posts'})
IEnumerable<Author> authors = butterClient.ListAuthors();
// Async
IEnumerable<Author> authorsWithPosts = 
  await butterClient.ListAuthorsAsync(includeRecentPosts: true);

Example response

{
  "data": [
    {
      "first_name": "API",
      "last_name": "Test",
      "email": "apitest@buttercms.com",
      "slug": "api-test",
      "bio": "This is my bio.",
      "title": "API",
      "linkedin_url": "https://www.linkedin.com/in/API",
      "facebook_url": "https://www.facebook.com/API",
      "pinterest_url": "https://www.pinterest.com/API",
      "instagram_url": "https://www.instagram.com/API",
      "twitter_handle": "buttercmsapi",
      "profile_image": "https://buttercms.com/api.png"
    }
  ]
}

Returns a list of authors.

Arguments

Argument Description
include Use include=recent_posts to include the author’s recent posts in the response.

Returns

A hash with a data property that contains an array of authors.

Retrieve an author

Example request

curl -X GET 'https://api.buttercms.com/v2/authors/jennifer-smith/?auth_token=api_token_b60a008a'
require "buttercms-ruby"
ButterCMS::api_token = "api_token_b60a008a"

author = ButterCMS::Author.find("jennifer-smith")
var butter = require('buttercms')("api_token_b60a008a");

butter.author.retrieve("jennifer-smith")
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("api_token_b60a008a")
ButterCMS.GetAuthor("jennifer-smith", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('api_token_b60a008a');
$butterCms->fetchAuthor('jennifer-smith');
?>
from butter_cms import ButterCMS
client = ButterCMS('api_token_b60a008a')
client.authors.get('jennifer-smith')
Author sally = butterClient.RetrieveAuthor("jennifer-smith");
// Async
Author tylerAndPosts = 
  await butterClient.RetrieveAuthorAsync(authorSlug: "jennifer-smith", 
    includeRecentPosts: true
  );

Example response

{
  "data": {
    "first_name": "Jennifer",
    "last_name": "Smith",
    "email": "jennifersmith@buttercms.com",
    "slug": "jennifer-smith",
    "bio": "I love coffee!",
    "title": "President",
    "linkedin_url": "https://www.linkedin.com/in/jennifersmith",
    "facebook_url": "https://www.facebook.com/jennifersmith",
    "pinterest_url": "https://www.pinterest.com/jennifersmith",
    "instagram_url": "https://www.instagram.com/jennifersmith",
    "twitter_handle": "jennifersmith",
    "profile_image": "https://d2devwt40at1e2.cloudfront.net/api/file/etSDYJUIFDADGEEAQ.png"
  }
}

Retrieves an author’s information. Supply the unique slug of the author.

Arguments

Argument Description
slug The slug of the author to be retrieved.
include Use include=recent_posts to include the author’s recent posts in the response.

Returns

A hash with a data property that contains an author object.

Categories

The category object

Attribute Description
slug string Unique identifer
name string

List all categories

Example request

curl -X GET 'https://api.buttercms.com/v2/categories/?auth_token=api_token_b60a008a'
require "buttercms-ruby"
ButterCMS::api_token = "api_token_b60a008a"

categories = ButterCMS::Category.all()
var butter = require('buttercms')("api_token_b60a008a");

butter.category.list()
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("api_token_b60a008a")
params = map[string]string{"include": "recent_posts"}
ButterCMS.GetCategories(params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('api_token_b60a008a');
$butterCms->fetchCategories(['include' => 'recent_posts']);
?>
from butter_cms import ButterCMS
client = ButterCMS('api_token_b60a008a')
client.categories.all({'include':'recent_posts'})
IEnumerable<Category> categories = butterClient.ListCategories();
//Async
IEnumerable<Category> categoriesWithPosts = 
  await butterClient.ListCategoriesAsync(includeRecentPosts: true);

Example response

{
  "data": [
    {
      "name": "test category",
      "slug": "test-category"
    }
  ]
}

Returns a list of blog categories. You can incude each category’s posts using the include=recent_posts parameter.

Arguments

Argument Description
include Use include=recent_posts to return a category’s recent posts.

Returns

A hash with a data property that contains an array of categories.

Retrieve a category

Example request

curl -X GET 'https://api.buttercms.com/v2/categories/product-updates/?auth_token=api_token_b60a008a'
require "buttercms-ruby"
ButterCMS::api_token = "api_token_b60a008a"

category = ButterCMS::Category.find("product-updates")
var butter = require('buttercms')("api_token_b60a008a");

butter.category.retrieve('product-updates')
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("api_token_b60a008a")
params = map[string]string{"include": "recent_posts"}
ButterCMS.GetCategory("product-updates", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('api_token_b60a008a');
$butterCms->fetchCategory('product-updates');
?>
from butter_cms import ButterCMS
client = ButterCMS('api_token_b60a008a')
client.categories.get('product-updates')
Category dotnetCategory = butterClient.RetrieveCategory("dotnet");
//Async
Category fsharpCategoryWithPosts = 
  await butterClient.RetrieveCategoryAsync(categorySlug: "fsharp", 
    includeRecentPosts: true
  );

Example response

{
  "data": {
    "name": "Product Updates",
    "slug": "product-updates"
  }
}

Retrieves the details of a category. Supply the unique slug of the category.

Arguments

Argument Description
slug The slug of the category to be retrieved.
include Use include=recent_posts to return a category’s recent posts.

Returns

A hash with a data property that contains a catgory object.

Tags

The tag object

Attribute Description
slug string Unique identifer
name string

List all tags

Example request

curl -X GET 'https://api.buttercms.com/v2/tags/?auth_token=api_token_b60a008a'
require "buttercms-ruby"
ButterCMS::api_token = "api_token_b60a008a"

tags = ButterCMS::Tag.all()
var butter = require('buttercms')("api_token_b60a008a");

butter.tag.list()
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("api_token_b60a008a")
params = map[string]string{"include": "recent_posts"}
ButterCMS.GetTags(params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('api_token_b60a008a');
$butterCms->fetchTags(['include' => 'recent_posts']);
?>
from butter_cms import ButterCMS
client = ButterCMS('api_token_b60a008a')
client.tags.all({'include':'recent_posts'})
IEnumerable<Tag> tags = butterClient.ListTags();
//Async
IEnumerable<Tag> tagsWithPosts = 
  await butterClient.ListTagsAsync(includeRecentPosts: true);

Example response

{
  "data": [
    {
      "name": "test tag",
      "slug": "test-tag"
    }
  ]
}

Returns a list of blog tags. You can incude each tags’s posts using the include=recent_posts parameter.

Arguments

Argument Description
include Use include=recent_posts to return a tags’s recent posts.

Returns

A hash with a data property that contains an array of tags.

Retrieve a tag

Example request

curl -X GET 'https://api.buttercms.com/v2/tags/product-updates/?auth_token=api_token_b60a008a'
require "buttercms-ruby"
ButterCMS::api_token = "api_token_b60a008a"

category = ButterCMS::Tag.find("product-updates")
var butter = require('buttercms')("api_token_b60a008a");

butter.tag.retrieve('product-updates')
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("api_token_b60a008a")
params = map[string]string{"include": "recent_posts"}
ButterCMS.GetTag("product-updates", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('api_token_b60a008a');
$butterCms->fetchTag('product-updates');
?>
from butter_cms import ButterCMS
client = ButterCMS('api_token_b60a008a')
client.tags.get('product-updates')
Tag dotnetTag = butterClient.RetrieveTag("dotnet");
//Async
Tag fsharpTagWithPosts = 
  await butterClient.RetrieveTagAsync(tagSlug: "fsharp", 
    includeRecentPosts: true
  );

Example response

{
  "data": {
    "name": "Product Updates",
    "slug": "product-updates"
  }
}

Retrieves the details of a tag. Supply the unique slug of the tag.

Arguments

Argument Description
slug The slug of the tag to be retrieved.
include Use include=recent_posts to return a tag’s recent posts.

Returns

A hash with a data property that contains a tag object.

Feeds

RSS

Example request

curl -X GET 'https://api.buttercms.com/v2/feeds/rss/?auth_token=api_token_b60a008a'
require "buttercms-ruby"
ButterCMS::api_token = "api_token_b60a008a"

feed = ButterCMS::Feed.find(:rss)
var butter = require('buttercms')("api_token_b60a008a");

butter.feed.retrieve('rss')
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("api_token_b60a008a")
ButterCMS.GetFeed("rss")
<?
use ButterCMS\ButterCMS;
$butter = new ButterCMS('api_token_b60a008a');
// Returns a SimpleXMLElement object
$feed = $butter->fetchFeed('rss');
?>
from butter_cms import ButterCMS
client = ButterCMS('api_token_b60a008a')
client.feeds.get('rss')
XmlDocument rssFeed = butterClient.GetRSSFeed();
//Async
XmlDocument rssFeed = await butterClient.GetRSSFeedAsync();

Example response

{
  "data": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd\">\n \n  <url><loc>http://www.example.com/blog/this-is-a-blog-post</loc></url>\n \n</urlset>"
}

Retrieve a fully generated RSS feed for your blog.

Returns

A hash with a data property that contains an RSS feed.

Atom

Example request

curl -X GET 'https://api.buttercms.com/v2/feeds/atom/?auth_token=api_token_b60a008a'
require "buttercms-ruby"
ButterCMS::api_token = "api_token_b60a008a"

feed = ButterCMS::Feed.find(:atom)
var butter = require('buttercms')("api_token_b60a008a");

butter.feed.retrieve('atom')
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("api_token_b60a008a")
ButterCMS.GetFeed("atom")
<?
use ButterCMS\ButterCMS;
$butter = new ButterCMS('api_token_b60a008a');
// Returns a SimpleXMLElement object
$feed = $butter->fetchFeed('atom');
?>
from butter_cms import ButterCMS
client = ButterCMS('api_token_b60a008a')
client.feeds.get('atom')
XmlDocument atomFeed = butterClient.GetAtomFeed();
//Async
XmlDocument atomFeed = await butterClient.GetAtomFeedAsync();

Example response

{
  "data": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd\">\n \n  <url><loc>http://www.example.com/blog/this-is-a-blog-post</loc></url>\n \n</urlset>"
}

Retrieve a fully generated Atom feed for your blog.

Returns

A hash with a data property that contains an Atom feed.

Sitemap

Example request

curl -X GET 'https://api.buttercms.com/v2/feeds/sitemap/?auth_token=api_token_b60a008a'
require "buttercms-ruby"
ButterCMS::api_token = "api_token_b60a008a"

feed = ButterCMS::Feed.find(:sitemap)
var butter = require('buttercms')("api_token_b60a008a");

butter.feed.retrieve('sitemap')
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("api_token_b60a008a")
ButterCMS.GetFeed("sitemap")
<?
use ButterCMS\ButterCMS;
$butter = new ButterCMS('api_token_b60a008a');
// Returns a SimpleXMLElement object
$feed = $butter->fetchFeed('sitemap');
?>
from butter_cms import ButterCMS
client = ButterCMS('api_token_b60a008a')
client.feeds.get('sitemap')
XmlDocument siteMap = butterClient.GetSitemap();
//Async
XmlDocument siteMap = await butterClient.GetSitemapAsync();

Example response

{
  "data": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd\">\n \n  <url><loc>http://www.example.com/blog/this-is-a-blog-post</loc></url>\n \n</urlset>"
}

Retrieve a fully generated sitemap for your blog.

Returns

A hash with a data property that contains an XML sitemap.

Webhooks

Example Webhook POST

POST http://yoururl.com/process_webbook

{
  "data": {
    "id": "example-blog-post"
  }, 
  "webhook": {
    "event": "post.update", 
    "target": "http://yoururl.com/process_webbook"
  }
}

Get notified when content changes. Configure webhooks in your account settings to POST change notifications to your application.

Event types

Event Type Description
post.all Triggered when a blog post has any activity on it.
post.create Triggered when a blog post is published live.
post.update Triggered when a published blog post is updated.
post.delete Triggered when a published blog post is deleted.
contentfield.update Triggered when a published Content Field is updated.

Image API

We have an integration with Filestack. You can leverage their robust set of Image transformation capabilities. Full docs are here.

After you upload an image, to create a thumbnail, here’s an example: