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.

Run in Postman

Postman is a great tool for experiementing with our API. We wrote a post about it here. Once you’ve installed Postman, click this button to quickly add our end point Collection to your Postman.

Run in Postman

Authentication

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

Authentication to the API is performed by passing your api token via the auth_token parameter on every request: ?auth_token=your_api_token. 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.

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.

Write API

We have a Write / POST API that allows you to programmatically create content. This can enable many powerful use cases and allow you to scale your content faster than ever.

Refer to these sections to see how to format your API requests when creating content:

Write Authentication

The API token you use for reading from the ButterCMS API will not allow you to create content in the API. For this you will need to use a different write-enabled token. Write-enabled tokens are provided on request. Just chat or email support@buttercms.com to get yours.

Set the Authorization header to Token your_write_api_token rather than using a query string parameter.

Your write-enabled token should never be used anywhere it would be exposed, e.g. in client-side JavaScript.

Pages

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

Create page via Write API

Create Page WITHOUT Locales

curl -X POST \
  https://api.buttercms.com/v2/pages/ \
  -H 'Authorization: Token your_write_api_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Frequently Asked Questions",
  "slug": "faq",
  "page-type": "questions",
  "fields": {
    "headline": "Frequently Asked Questions",
    "hero_image": "",
    "body": "<p class=\"content\">We love questions</p>",
    "questions": [{
        "question": "Are dogs allowed?",
        "answer": "Leashed dogs are allowed.",
        "picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
    }, {
        "question": "Are wallabies allowed?",
        "answer": "Yes, leashed wallabies are allowed",
        "picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
    }]
  }
}'

Create Page WITH Locales

curl -X POST \
  https://api.buttercms.com/v2/pages/ \
  -H 'Authorization: Token your_write_api_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Frequently Asked Questions",
  "slug": "faq",
  "page-type": "questions",
  "fields": {
    "en": {
      "headline": "Frequently Asked Questions",
      "body": "<p class=\"content\">We love questions</p>",
      "questions": [{
          "question": "Are dogs allowed?",
          "answer": "Leashed dogs are allowed.",
          "picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
      }]
    },
    "es": {
      "headline": "Preguntas frecuentes",
      "body": "<p class=\"content\">Nos encantan las preguntas</p>",
      "questions": [{
          "question": "Se admiten perros?",
          "answer": "Se permiten perros con correa.",
          "picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
      }]
    }
  }
}'

Making requests

Requests should be HTTP POST requests made to https://api.buttercms.com/v2/pages/, with the Content-Type header set to application/json.

The structure of your request body is conditional on whether you have any configured locales (English, Spanish, etc).

WITHOUT Locales

If you don’t have locales, your request body should be a JSON object like the example to the right. fields is an array of objects, where each object represents a content list object with each of its fields created by key and value.

WITH Locales

If you do have locales configured, the objects in each array have an extra level and must be first mapped to the locale code to use. See the example to the right. Locale codes must already be configured in your account, however it is not necessary that they are all used.

Authentication

The API token you use for reading from the ButterCMS API will not allow you to create content in the API. For this you will need to use a different write-enabled token. Write-enabled tokens are provided on request. Just chat or email support@buttercms.com to get yours.

Set the Authorization header to Token your_write_api_token rather than using a query string parameter.

Your write-enabled token should never be used anywhere it would be exposed, e.g. in client-side JavaScript.

Making requests

Requests should be HTTP POST requests made to https://api.buttercms.com/v2/pages/, with the Content-Type header set to application/json.

The body of your request should be a JSON object like the example to the right. Note this is the same structure as when you GET a page.

Body Fields

Attribute Description
title Required. The title of the page.
slug Required. The slug of the page.
page-type Required. The key of the page type.
locale Optional. Set to the api slug of a pre-configured locale (i.e. en). When omitted this will default to your organization’s default locale.
fields Required. A dictionary object of your page fields and their values.

The fields attribute describes the page content itself.

Responses

A validated POST request will return a response with HTTP status code 202. Full page creation occurs asynchronously, meaning a successfully created page may not show immediately. Pages are validated prior to returning the API response but it is also possible that page creation may fail after returning a 202 response. If this happens please contact support.

The API will return HTTP status code 400 if your data does not pass the initial validation stage. This may happen if you are missing a field, missing a required field, or the remote URL for a media field returns a 404. Error explanations will be returned in a single JSON array.

Get a single page

Example request

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

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

butter.page.retrieve('*', 'example-news-page', { 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("your_api_token")
ButterCMS.GetPage("*", "example-news-page", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->fetchPage('*', 'example-news-page', params);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
client.pages.get('*', 'example-news-page', {'foo': 'bar'})
using ButterCMS;
// Takes a generic PageType which is a class you define
// to match your ButterCMS config
var paramterDict = new Dictionary<string, string>() 
{
    {"preview", "1"},
    {"locale", "en"},
    {"page_size", "10"}
};

public class NewsPage
{
    public string seo_title { get; set; }
    public string seo_description { get; set; }
    public string seo_keywords { get; set; }
    public string title { get; set; }
    public string body { get; set; }
}

Page<NewsPage> newsPage = butterClient.RetrievePage<NewsPage>("*", "example-news-page", paramterDict);
// Async
Page<NewsPage> newsPage = await butterClient.RetrievePageAsync<NewsPage>("*", "example-news-page", paramterDict);

Example response

{
  "data": {
    "slug": "example-news-page",
    "page_type": "news",
    "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>"
    }
  }
}

Get a single page using its slug.

Arguments

Argument Description
page_type Required. Use '*'. If limiting to a Page Type, use the Page Type slug (see below).
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
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 the page matching the page slug.

Get multiple pages (Page Type)

Example request

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

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

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("your_api_token")
ButterCMS.GetPages("news", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->fetchPages('news', params);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
client.pages.all('news', {'foo': 'bar'})
// Takes a generic PageType which is a class you define
// to match your ButterCMS config
using ButterCMS;

public class NewsPage
{
    public string seo_title { get; set; }
    public string title { get; set; }
    public string body { get; set; }
}

var paramterDict = new Dictionary<string, string>() 
{
    {"preview", "1"},
    {"locale", "en"},
    {"page_size", "10"}
};

PagesResponse<NewsPage> newsPages = butterClient.ListPages<NewsPage>("news");

// Async
PagesResponse<NewsPage> newsPages = await butterClient.ListPagesAsync<NewsPage>("news");

Example response

{
  "meta": {
    "previous_page": null,
    "next_page": null,
    "count": 2
  },
  "data": [
    {
      "slug": "example-news-page-1",
      "page_type": "news",
      "fields": {
        "seo_title": "Example News Page #1",
        "title": "This is an example news page",
        "body": "<p>Breaking news!</p>"
      }
    },
    {
      "slug": "example-news-page-2",
      "page_type": "news",
      "fields": {
        "seo_title": "Example News Page #2",
        "title": "This is another news page",
        "body": "<p>Wow wow wow!</p>"
      }
    }
  ]
}

Page Types allow you to create many pages with the same structure. Get a list of all pages for a given Page Type using its 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 results returned.
locale Optional. Set to the api slug of your configured locale (i.e. en or fr)
levels Optional. Defaults to 2. Defines the levels of relationships to serialize. See below.

Returns

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

Reference Levels

Example Reference Response

# related_pages and tags are Reference fields
"fields": {
  "title": "...",
  "body": "...",
  "related_pages": [
    "/v2/pages/example-page-type/example-page-slug"
  ],
  "tags": [
    "/v2/content/?keys=example_collaction[_id=1234]"
  ]

Using Reference fields, you can create relationships between a Page Type and another type of content (Page Type or Collection). These relationships can create heirarchies of content many levels deep and sometimes circular in nature (A references B which references A).

The most common case is for one Reference to exist (A references B) which means two levels of content, which is what we serailize by default. If you need more levels, specify that parameter. If you only need one level, you can specify levels=1 which also makes the response payload smaller.

When the level limit is reached, we return unique URIs for any unserialized objects.

Localization

Example Request

curl -X GET 'https://api.buttercms.com/v2/pages/news/locale=en&auth_token=your_api_token'

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

v2/pages/news/locale=en

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

Collections

Collections are tables of data to be referenced by Pages, extending the use cases that you can achieve with ButterCMS. Collections can also be queried from the API directly using its API key. You can also query multiple Collections at once.

Create Collection Item via Write API

You can create Collection items by using POST requests to the Butter /v2/content/ API endpoint.

Authentication

The API token you use for reading from the ButterCMS API will not allow you to create content in the API. For this you will need to use a different write-enabled token. Write-enabled tokens are provided on request. Just chat or email support@buttercms.com to get yours.

Set the Authorization header to Token your_write_api_token rather than using a query string parameter.

Your write-enabled token should never be used anywhere it would be exposed, e.g. in client-side JavaScript.

Create Item WITHOUT Locales

curl -X POST \
  https://api.buttercms.com/v2/content/ \
  -H 'Authorization: Token your_write_api_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "collection_api_slug",
    "status": "published",
    "fields": [
        {
          "field1_key": "Field value",
          "field2_key": "Field value"
        },
        ...
    ]
}'

Create Item WITH Locales

curl -X POST \
  https://api.buttercms.com/v2/content/ \
  -H 'Authorization: Token your_write_api_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "collection_api_slug",
    "status": "published",
    "fields": [
      {
      "en": {
          "field1_key": "Field value",
          "field2_key": "Field value"
        },
      "es": {
          "field1_key": "Field value",
          "field2_key": "Field value"
        }
      },
      ...
    ]
}'

Making requests

Requests should be HTTP POST requests made to https://api.buttercms.com/v2/content/, with the Content-Type header set to application/json.

The structure of your request body is conditional on whether you have any configured locales (English, Spanish, etc).

WITHOUT Locales

If you don’t have locales, your request body should be a JSON object like the example to the right. fields is an array of objects, where each object represents a content list object with each of its fields created by key and value.

WITH Locales

If you do have locales configured, the objects in each array have an extra level and must be first mapped to the locale code to use. See the example to the right. Locale codes must already be configured in your account, however it is not necessary that they are all used.

Body Fields

Attribute Description
key Required. The title of the post.
status Optional. Should be ‘published’ or 'draft’. Defaults to 'published’
fields Required. An array of objects, where each object represents a collection item with each of its fields created by key and value.

Responses

A validated POST request will return a response with HTTP status code 202. Full post creation occurs asynchronously, meaning a successfully created post may not show immediately. Posts are validated prior to returning the API response but it is also possible that post creation may fail after returning a 202 response. If this happens please contact support.

The API will return HTTP status code 400 if your data does not pass the initial validation stage. This may happen if you are missing a field, missing a required field, or the remote URL for a media field returns a 404. Error explanations will be returned in a single JSON array.

Retrieve a Collection

Example request

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

content = ButterCMS::Content.fetch([
  :artists
])
var butter = require('buttercms')("your_api_token");

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

Example response

{
  "data": {
    "artists": [
      {
        "name": "The Beatles",
        "genre": "Rock"
      },
      {
        "name": "Jay Z",
        "genre": "Rap"
      }
    ]
  }
}

Returns values for the supplied Collection keys.

Arguments

Argument Description
keys Comma delimited list of Collection keys.
test Optional. Set to 1 to enable Draft 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 Collection keys and values.

Filtering a Collection

Sometimes you want to filter a Collection to return only a subset of items. To do this you simply add the filter to the API key. i.e. collection_api_key[property=value]

For example, if you have a Collection of musical artists:

/v2/content/?keys=artists

You can filter on any Collection property:

/v2/content/?keys=artists[name=The Beatles]

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]

Draft Mode

Example Request

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

Draft 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.

Reference Levels

Example Reference Response

# related_pages and tags are Reference fields
"title": "...",
"body": "...",
"related_pages": [
  "/v2/pages/example-page-type/example-page-slug"
],
"tags": [
  "/v2/content/?keys=example_collaction[_id=1234]"
]

Using Reference fields, you can create relationships between a Page Type and another type of content (Page Type or Collection). These relationships can create heirarchies of content many levels deep and sometimes circular in nature (A references B which references A).

The most common case is for one Reference to exist (A references B) which means two levels of content, which is what we serailize by default. If you need more levels, specify that parameter. If you only need one level, you can specify levels=1 which also makes the response payload smaller.

When the level limit is reached, we return unique URIs for any unserialized objects.

Localization

Example Request

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

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.

Create blog post via Write API

Example POST Request

curl -X POST \
  https://api.buttercms.com/v2/posts/ \
  -H 'Authorization: Token your_write_api_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "author": {
    "email": "your@author.com" // You can also lookup by author "slug"
  },
  "categories": ["Recipes", "Meals"],
  "tags": ["Butter", "Sushi", "Really Good Recipes"],
  "featured_image": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg",
  "slug": "this-is-a-blog-post",
  "title": "This is a blog post",
  "body": "<h1>Butter</h1><p>I am so hungry!</p>",
  "summary": "This is a blog post summary.",
  "seo_title": "This is a blog post",
  "meta_description": "This is a blog post to test the API.",
  "status": "published"
}'

You can create posts by using POST requests to the Butter /v2/posts/ API endpoint.

Authentication

The API token you use for reading from the ButterCMS API will not allow you to create content in the API. For this you will need to use a different write-enabled token. Write-enabled tokens are provided on request. Just chat or email support@buttercms.com to get yours.

Set the Authorization header to Token your_write_api_token rather than using a query string parameter.

Your write-enabled token should never be used anywhere it would be exposed, e.g. in client-side JavaScript.

Making requests

Requests should be HTTP POST requests made to https://api.buttercms.com/v2/posts/, with the Content-Type header set to application/json.

The body of your request should be a JSON object like the example to the right. Note this is the same structure as when you GET a post.

Body Fields

Attribute Description
title Required. The title of the post.
slug Required. The slug of the post.
status Optional. The status of the post. Defaults to draft.
author Optonal. Author must exist in your account prior to POST. Should either be { "email" : "your@author.com" } or { “slug” : “firstname-lastname” }. Defaults to the organization owner.
categories Optional. Array of strings.
tags Optional. Array of strings.
featured_image Optional. Can be a remote URL to an image.
body Optional. Should be an string of escaped HTML.
summary Optional.
seo_title Optional.
meta_description Optional.

Responses

A validated POST request will return a response with HTTP status code 202. Full post creation occurs asynchronously, meaning a successfully created post may not show immediately. Posts are validated prior to returning the API response but it is also possible that post creation may fail after returning a 202 response. If this happens please contact support.

The API will return HTTP status code 400 if your data does not pass the initial validation stage. This may happen if you are missing a field, missing a required field, or the remote URL for a media field returns a 404. Error explanations will be returned in a single JSON array.

Update blog post via Write API

Example PATCH Request

curl -X PATCH \
  https://api.buttercms.com/v2/posts/this-is-a-blog-post/ \
  -H 'Authorization: Token your_write_api_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "slug": "the-new-post-slug",
  "body": "<h1>Updated</h1><p>This is a blog post was updated via API</p>"
}'

You can update existing blog posts by using a PATCH request to /v2/posts/your-post-slug endpoint. In the body of the request you can specify one or more fields you’d like to update.

Get your 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=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"

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

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("your_api_token")
params := map[string]string{"page_size": "10"}
ButterCMS.GetPosts(params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->fetchPosts(['page_size' => 10]);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
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=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"

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

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("your_api_token")
ButterCMS.GetPost("hello-world")
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->fetchPost('hello-world');
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
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=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"

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

butter.post.search("my favorite post", {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("your_api_token")
params := map[string]string{"page": "1"}
ButterCMS.SearchPosts("query", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->searchPosts('query', ['page' => 1]);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
client.posts.search('query', {'page': 1, 'page_size': 10})
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=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"

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

butter.author.list()
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("your_api_token")
params = map[string]string{"include": "recent_posts"}
ButterCMS.GetAuthors(params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->fetchAuthors(['include' => 'recent_posts']);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
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=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"

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

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("your_api_token")
ButterCMS.GetAuthor("jennifer-smith", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->fetchAuthor('jennifer-smith');
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
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=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"

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

butter.category.list()
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("your_api_token")
params = map[string]string{"include": "recent_posts"}
ButterCMS.GetCategories(params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->fetchCategories(['include' => 'recent_posts']);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
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=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"

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

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("your_api_token")
params = map[string]string{"include": "recent_posts"}
ButterCMS.GetCategory("product-updates", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->fetchCategory('product-updates');
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
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=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"

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

butter.tag.list()
  .then(function(resp) {
    console.log(resp.data)
  }).catch(function(resp) {
    console.log(resp)
  });
import (
    "github.com/buttercms/buttercms-go"
)
ButterCMS.SetAuthToken("your_api_token")
params = map[string]string{"include": "recent_posts"}
ButterCMS.GetTags(params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->fetchTags(['include' => 'recent_posts']);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
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=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"

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

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("your_api_token")
params = map[string]string{"include": "recent_posts"}
ButterCMS.GetTag("product-updates", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->fetchTag('product-updates');
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
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=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"

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

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("your_api_token")
ButterCMS.GetFeed("rss")
<?
use ButterCMS\ButterCMS;
$butter = new ButterCMS('your_api_token');
// Returns a SimpleXMLElement object
$feed = $butter->fetchFeed('rss');
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
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=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"

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

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("your_api_token")
ButterCMS.GetFeed("atom")
<?
use ButterCMS\ButterCMS;
$butter = new ButterCMS('your_api_token');
// Returns a SimpleXMLElement object
$feed = $butter->fetchFeed('atom');
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
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=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"

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

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("your_api_token")
ButterCMS.GetFeed("sitemap")
<?
use ButterCMS\ButterCMS;
$butter = new ButterCMS('your_api_token');
// Returns a SimpleXMLElement object
$feed = $butter->fetchFeed('sitemap');
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
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. Note the data section will always contain id but may differ in other attributes based on the object.

POST http://yoururl.com/process_webbook

{
  "data": {
    "id": "example-page-slug"
    "page_type": "news"
  }, 
  "webhook": {
    "event": "page.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.published Triggered when a blog post goes from draft -> published.
post.create Triggered when a blog post is created.
post.update Triggered when a published blog post is updated.
post.delete Triggered when a published blog post is deleted.
page.all Triggered when a page has any activity on it.
page.create Triggered when a page is published live.
page.update Triggered when a published page is updated.
page.delete Triggered when a published page is deleted.
collection.update Triggered when a published Collection 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: