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, a sample API Key will be used in the sample code, which you should replace with your own butter API key. If you don't yet have an account, create one free.
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.
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");
import 'package:buttercms_dart/buttercms_dart.dart';
Butter butter = Butter('your_api_token');
OR
var butter = Butter('your_api_token');
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY")
// In Swift, you can also override the default false setting
// for preview mode at the client level.
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY", previewMode: true)
// For custom sessions:
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY", urlSession: yourURLSession)
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.
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. |
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:
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.
Quickly launch a new marketing site or add pages to your existing one using our Pages end points.
| Attribute | Description |
|---|---|
| slug string | Unique identifier |
| name string | Name of the Page |
| published timestamp | Timestamp of when the page was first published |
| updated timestamp | Timestamp of when the page was most recently published |
| page_type string | API slug identifier of the page_type for the Page |
| fields string | fields contains all of the actual content for the Page |
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"
}]
}
}'
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"
}]
}
}'
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"
}]
}
}'
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse('https://api.buttercms.com/v2/pages/')
header = {
"Content-type": "application/json",
"Authorization": "Token your_write_api_token"
}
payload = {
"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"
}]
}
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
let payload = {
"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"
}]
}
}
fetch('https://api.buttercms.com/v2/pages/', {
method: 'POST',
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err));
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"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"
}]
}
}
`)
req, err := http.NewRequest("POST", "https://api.buttercms.com/v2/pages/", payload)
req.Header.Add("Authorization", "Token your_write_api_token")
req.Header.Add("Content-type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
<?php
$url = "http://api.buttercms.com/v2/pages/";
$payload = array(
"title" => "Frequently Asked Questions",
"slug" => "faq34",
"page-type" => "questions",
"fields" => array(
"headline" => "Frequently Asked Questions",
"hero_image" => "",
"body" => "<p class=\"content\">We love questions</p>",
"questions" => [array(
"question" => "Are dogs allowed?",
"answer" => "Leashed dogs are allowed.",
"picture" => "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
), array(
"question" => "Are wallabies allowed?",
"answer" => "Yes, leashed wallabies are allowed",
"picture" => "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
)]
)
);
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
import requests
payload = {
"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"
}]
}
}
response = requests.post("https://api.buttercms.com/v2/pages/", json=payload, headers={"Authorization": "Token your_write_api_token" })
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async{
Map payload = {
"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"
}]
}
};
String body = convert.jsonEncode(payload);
http.Response response = await http.post(
url: 'https://api.buttercms.com/v2/pages/',
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
},
body: body,
);
print(convert.jsonDecode(response.body));
}
var payload = {
"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"
}]
}
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/pages/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
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"
}]
}
}
}'
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"
}]
}
}
}'
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"
}]
}
}
}'
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse('https://api.buttercms.com/v2/pages/')
header = {
"Content-type": "application/json",
"Authorization": "Token your_write_api_token"
}
payload = {
"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"
}]
}
}
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
let payload = {
"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"
}]
}
}
}
fetch('https://api.buttercms.com/v2/pages/', {
method: 'POST',
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err));
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"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"
}]
}
}
}
`)
req, err := http.NewRequest("POST", "https://api.buttercms.com/v2/pages/", payload)
req.Header.Add("Authorization", "Token your_write_api_token")
req.Header.Add("Content-type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
<?php
$url = "http://api.buttercms.com/v2/pages/";
$payload = array(
"title" => "Frequently Asked Questions",
"slug" => "faq34",
"page-type" => "questions",
"fields" => array(
"en" => array(
"headline" => "Frequently Asked Questions",
"body" => "<p class=\"content\">We love questions</p>",
"questions" => [array(
"question" => "Are dogs allowed?",
"answer" => "Leashed dogs are allowed.",
"picture" => "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
)],
),
"es" => array(
"headline" => "Preguntas frecuentes",
"body" => "<p class=\"content\">Nos encantan las preguntas</p>",
"questions" => [array(
"question" => "Se admiten perros?",
"answer" => "Se permiten perros con correa.",
"picture" => "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
)]
)
)
);
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
>
import requests
payload = {
"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"
}]
}
}
}
response = requests.post("https://api.buttercms.com/v2/pages/", json=payload, headers={"Authorization": "Token your_write_api_token" })
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async{
Map payload = {
"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"
}]
}
}
};
String body = convert.jsonEncode(payload);
http.Response response = await http.post(
url: 'https://api.buttercms.com/v2/pages/',
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
},
body: body,
);
print(convert.jsonDecode(response.body));
}
var payload = payload = {
"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"
}]
}
}
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/pages/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
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).
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.
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.
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.
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.
| Attribute | Description |
|---|---|
| title | Required. The title of the page. |
| slug | Required. The slug of the page. |
| status | Optional. Status of the update. Can be draft or published. Defaults to draft. |
| page-type | Required. The key of the page type. |
| locale | Optional. Set to the api slug of a pre-configured locale (e.g. en or fr). When omitted, this query parameter 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.
hero_image in the example).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.
Update Page WITHOUT Locales
curl -X PATCH \
https://api.buttercms.com/v2/pages/*/faq/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "draft",
"fields": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}'
curl -X PATCH \
https://api.buttercms.com/v2/pages/*/faq/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "draft",
"fields": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}'
curl -X PATCH \
https://api.buttercms.com/v2/pages/*/faq/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "draft",
"fields": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}'
import requests
payload = {
"status": "draft",
"fields": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}
response = requests.patch("https://api.buttercms.com/v2/pages/*/faq/", json=payload, headers={"Authorization": "Token your_write_api_token" })
print(response.content)
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse('https://api.buttercms.com/v2/pages/*/faq/')
header = {
"Content-type": "application/json",
"Authorization": "Token your_write_api_token"
}
payload = {
"status": "draft",
"fields": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Patch.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
let payload = {
"status": "draft",
"fields": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}
fetch('https://api.buttercms.com/v2/pages/*/faq/', {
method: 'PATCH',
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err));
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"status": "draft",
"fields": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}
`)
req, err := http.NewRequest("PATCH", "https://api.buttercms.com/v2/pages/*/faq/", payload)
req.Header.Add("Authorization", "Token your_write_api_token")
req.Header.Add("Content-type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async {
Map payload = {
"status": "draft",
"fields": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
};
String body = convert.jsonEncode(payload);
http.Response response = await http.patch(
url: 'https://api.buttercms.com/v2/pages/*/faq/',
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
},
body: body,
);
print(convert.jsonDecode(response.body));
}
<?php
$url = "https://api.buttercms.com/v2/pages/*/faq/";
$payload = array(
"status" => "draft",
"fields" => array(
"headline" => "Frequently Asked Questions Updated",
"questions" => [array(
"question" => "Are dogs allowed?",
"answer" => "Leashed dogs are allowed.",
"picture" => "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
),
array(
"question" => "Another dog question",
"answer" => "Another dog answer",
"picture" => "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
)]
);
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($curl, CURLOPT_POSTFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
var payload = {
"status": "draft",
"fields": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/pages/*/faq/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "PATCH"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
Update Page WITH Locales
curl -X PATCH \
https://api.buttercms.com/v2/pages/*/faq/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "draft",
"fields": {
"en": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}
}'
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async {
Map payload = {
"status": "draft",
"fields": {
"en": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}
};
String body = convert.jsonEncode(payload);
http.Response response = await http.patch(
url: 'https://api.buttercms.com/v2/pages/*/faq/',
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
},
body: body,
);
print(convert.jsonDecode(response.body));
}
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"status": "draft",
"fields": {
"en": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}
}
`)
req, err := http.NewRequest("PATCH", "https://api.buttercms.com/v2/pages/*/faq/", payload)
req.Header.Add("Authorization", "Token your_write_api_token")
req.Header.Add("Content-type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
curl -X PATCH \
'https://api.buttercms.com/v2/pages/*/faq/' \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "draft",
"fields": {
"en": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}
}'
let payload = {
"status": "draft",
"fields": {
"en": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}
}
fetch('https://api.buttercms.com/v2/pages/*/faq/', {
method: 'PATCH',
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err));
<?php
$url = "https://api.buttercms.com/v2/pages/*/faq/";
$payload = array(
"status" => "draft",
"fields" => array(
"en" => array(
"headline" => "Frequently Asked Questions Updated",
"questions" => [array(
"question" => "Are dogs allowed?",
"answer" => "Leashed dogs are allowed.",
"picture" => "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
),
array(
"question" => "Another dog question",
"answer" => "Another dog answer",
"picture" => "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
)]
)
)
);
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($curl, CURLOPT_POSTFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
import requests
payload = {
"status": "draft",
"fields": {
"en": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}
}
response = requests.patch("https://api.buttercms.com/v2/pages/*/faq/", json=payload, headers={"Authorization": "Token your_write_api_token" })
print(response.content)
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse('https://api.buttercms.com/v2/pages/*/faq/')
header = {
"Content-type": "application/json",
"Authorization": "Token your_write_api_token"
}
payload = {
"status": "draft",
"fields": {
"en": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Patch.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
var payload = {
"status": "draft",
"fields": {
"en": {
"headline": "Frequently Asked Questions Updated",
"questions": [{
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
},
{
"question": "Another dog question",
"answer": "Another dog answer",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/pages/*/faq/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "PATCH"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
You can update existing Pages by using a PATCH request to /v2/pages/*/your-page-slug/ endpoint. In the body of the request you can specify one or more fields you'd like to update.
You can also specify status of the update, which is by default "draft", to be "published" which will cause your update to go live immediately.
It's not currently possible to update the page title or slug via PATCH.
The pages write API supports adding components as well. Components, like the hero component in this example, map component field value to their respective field keys within a JSON object which is mapped to the component key in the field list.
Adding Components via Write API
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",
"hero": {
"image": "https://live.staticflickr.com/6005/5908020758_bcd2bdcec9_c_d.jpg",
"alt_text": "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>",
"hero": {
"image": "https://live.staticflickr.com/6005/5908020758_bcd2bdcec9_c_d.jpg",
"alt_text": "Preguntas frecuentes"
},
"questions": [{
"question": "Se admiten perros?",
"answer": "Se permiten perros con correa.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}
}'
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",
"hero": {
"image": "https://live.staticflickr.com/6005/5908020758_bcd2bdcec9_c_d.jpg",
"alt_text": "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>",
"hero": {
"image": "https://live.staticflickr.com/6005/5908020758_bcd2bdcec9_c_d.jpg",
"alt_text": "Preguntas frecuentes"
},
"questions": [{
"question": "Se admiten perros?",
"answer": "Se permiten perros con correa.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}
}'
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",
"hero": {
"image": "https://live.staticflickr.com/6005/5908020758_bcd2bdcec9_c_d.jpg",
"alt_text": "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>",
"hero": {
"image": "https://live.staticflickr.com/6005/5908020758_bcd2bdcec9_c_d.jpg",
"alt_text": "Preguntas frecuentes"
},
"questions": [{
"question": "Se admiten perros?",
"answer": "Se permiten perros con correa.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}]
}
}
}'
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async {
Map payload = {
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"body": "<p class=\"content\">We love questions</p>",
"sections": [
{
"question": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}
},
{
"question": {
"question": "Are wallabies allowed?",
"answer": "Yes, leashed wallabies are allowed",
"picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
}
},
{
"trivia": {
"title": "Pocket creatures",
"body": "Wallabies are marsupials. The keep their babies in their pouches"
}
}
]
}
}
}
String body = convert.jsonEncode(payload);
http.Response response = await http.post(
url: 'https://api.buttercms.com/v2/pages/',
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
},
body: body,
);
print(convert.jsonDecode(response.body));
}
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"body": "<p class=\"content\">We love questions</p>",
"sections": [
{
"question": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}
},
{
"question": {
"question": "Are wallabies allowed?",
"answer": "Yes, leashed wallabies are allowed",
"picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
}
},
{
"trivia": {
"title": "Pocket creatures",
"body": "Wallabies are marsupials. The keep their babies in their pouches"
}
}
]
}
}
}
`)
req, err := http.NewRequest("POST", "https://api.buttercms.com/v2/pages/", payload)
req.Header.Add("Authorization", "Token your_write_api_token")
req.Header.Add("Content-type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
let payload = {
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"body": "<p class=\"content\">We love questions</p>",
"sections": [
{
"question": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}
},
{
"question": {
"question": "Are wallabies allowed?",
"answer": "Yes, leashed wallabies are allowed",
"picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
}
},
{
"trivia": {
"title": "Pocket creatures",
"body": "Wallabies are marsupials. The keep their babies in their pouches"
}
}
]
}
}
}
fetch('https://api.buttercms.com/v2/pages/', {
method: 'POST',
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err));
<?php
$url = "https://api.buttercms.com/v2/pages/";
$payload = array(
"title" => "Frequently Asked Questions",
"slug" => "faq",
"page-type" => "questions",
"fields" => array(
"en" => array(
"headline" => "Frequently Asked Questions",
"body" => "<p class=\"content\">We love questions</p>",
"sections" => [
array(
"question" => array(
"question" => "Are dogs allowed?",
"answer" => "Leashed dogs are allowed.",
"picture" => "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
)
),
array(
"question" => array(
"question" => "Are wallabies allowed?",
"answer" => "Yes, leashed wallabies are allowed",
"picture" => "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
)
),
array(
"trivia" => array(
"title" => "Pocket creatures",
"body" => "Wallabies are marsupials. The keep their babies in their pouches"
)
)
]
)
)
);
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
import requests
payload = {
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"body": "<p class=\"content\">We love questions</p>",
"sections": [
{
"question": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}
},
{
"question": {
"question": "Are wallabies allowed?",
"answer": "Yes, leashed wallabies are allowed",
"picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
}
},
{
"trivia": {
"title": "Pocket creatures",
"body": "Wallabies are marsupials. The keep their babies in their pouches"
}
}
]
}
}
}
response = requests.post("https://api.buttercms.com/v2/pages/", json=payload, headers={"Authorization": "Token your_write_api_token" })
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse('https://api.buttercms.com/v2/pages/')
header = {
"Content-type": "application/json",
"Authorization": "Token your_write_api_token"
}
payload = {
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"body": "<p class=\"content\">We love questions</p>",
"sections": [
{
"question": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}
},
{
"question": {
"question": "Are wallabies allowed?",
"answer": "Yes, leashed wallabies are allowed",
"picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
}
},
{
"trivia": {
"title": "Pocket creatures",
"body": "Wallabies are marsupials. The keep their babies in their pouches"
}
}
]
}
}
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
var payload = {
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"body": "<p class=\"content\">We love questions</p>",
"sections": [
{
"question": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}
},
{
"question": {
"question": "Are wallabies allowed?",
"answer": "Yes, leashed wallabies are allowed",
"picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
}
},
{
"trivia": {
"title": "Pocket creatures",
"body": "Wallabies are marsupials. The keep their babies in their pouches"
}
}
]
}
}
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/pages/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
The update API supports both creating and updating components, and updating individual component fields works the same way as updating individual page fields.
Updating Components via Write API
curl -X PATCH \
https://api.buttercms.com/v2/pages/*/faq/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "draft",
"fields": {
"en": {
"hero": {
"alt_text": "Questions and answers"
}
},
"es": {
"hero": {
"image": "https://live.staticflickr.com/6005/5908020758_bcd2bdcec9_c_d.jpg"
}
}
}
}'
curl -X PATCH \
https://api.buttercms.com/v2/pages/*/faq/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "draft",
"fields": {
"en": {
"hero": {
"alt_text": "Questions and answers"
}
},
"es": {
"hero": {
"image": "https://live.staticflickr.com/6005/5908020758_bcd2bdcec9_c_d.jpg"
}
}
}
}'
curl -X PATCH \
https://api.buttercms.com/v2/pages/*/faq/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "draft",
"fields": {
"en": {
"hero": {
"alt_text": "Questions and answers"
}
},
"es": {
"hero": {
"image": "https://live.staticflickr.com/6005/5908020758_bcd2bdcec9_c_d.jpg"
}
}
}
}'
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async {
Map payload = {
"status": "draft",
"fields": {
"en": {
"hero": {
"alt_text": "Questions and answers"
}
},
"es": {
"hero": {
"image": "https://live.staticflickr.com/6005/5908020758_bcd2bdcec9_c_d.jpg"
}
}
}
}
String body = convert.jsonEncode(payload);
http.Response response = await http.patch(
url: 'https://api.buttercms.com/v2/pages/*/faq/',
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
},
body: body,
);
print(convert.jsonDecode(response.body));
}
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"status": "draft",
"fields": {
"en": {
"hero": {
"alt_text": "Questions and answers"
}
},
"es": {
"hero": {
"image": "https://live.staticflickr.com/6005/5908020758_bcd2bdcec9_c_d.jpg"
}
}
}
}
`)
req, err := http.NewRequest("PATCH", "https://api.buttercms.com/v2/pages/*/faq/", payload)
req.Header.Add("Authorization", "Token your_write_api_token")
req.Header.Add("Content-type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
let payload = {
"status": "draft",
"fields": {
"en": {
"hero": {
"alt_text": "Questions and answers"
}
},
"es": {
"hero": {
"image": "https://live.staticflickr.com/6005/5908020758_bcd2bdcec9_c_d.jpg"
}
}
}
}
fetch('https://api.buttercms.com/v2/pages/', {
method: 'PATCH',
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err));
<?php
$url = "https://api.buttercms.com/v2/pages/*/faq/";
$payload = array(
"status" => "draft",
"fields" => array(
"en" => array(
"hero" => array(
"alt_text" => "Questions and answers"
)
),
"es" => array(
"hero" => array(
"image" => "https://live.staticflickr.com/6005/5908020758_bcd2bdcec9_c_d.jpg"
)
)
)
);
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($curl, CURLOPT_POSTFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
import requests
payload = {
"status": "draft",
"fields": {
"en": {
"hero": {
"alt_text": "Questions and answers"
}
},
"es": {
"hero": {
"image": "https://live.staticflickr.com/6005/5908020758_bcd2bdcec9_c_d.jpg"
}
}
}
}
response = requests.patch("https://api.buttercms.com/v2/pages/*/faq/", json=payload, headers={"Authorization": "Token your_write_api_token" })
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse('https://api.buttercms.com/v2/pages/*/faq/')
header = {
"Content-type": "application/json",
"Authorization": "Token your_write_api_token"
}
payload = {
"status": "draft",
"fields": {
"en": {
"hero": {
"alt_text": "Questions and answers"
}
},
"es": {
"hero": {
"image": "https://live.staticflickr.com/6005/5908020758_bcd2bdcec9_c_d.jpg"
}
}
}
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Patch.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
var payload = {
"status": "draft",
"fields": {
"en": {
"hero": {
"alt_text": "Questions and answers"
}
},
"es": {
"hero": {
"image": "https://live.staticflickr.com/6005/5908020758_bcd2bdcec9_c_d.jpg"
}
}
}
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/pages/*/faq/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "PATCH"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
Component picker fields combine one or more pre-defined components in an ordered field. These can be added by including an array of component objects. In this example the questions repeater has been replaced with a component picker field with key of sections.
{
"type": "component_key",
"fields": {
"field_one": "field value",
...
}
}
{
"type": question",
"fields": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "dog.jpg"
}
}
{
"question": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "dog.jpg"
}
}
Combining one or more predefined components
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>",
"sections": [
{
"question": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}
},
{
"question": {
"question": "Are wallabies allowed?",
"answer": "Yes, leashed wallabies are allowed",
"picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
}
},
{
"trivia": {
"title": "Pocket creatures",
"body": "Wallabies are marsupials. The keep their babies in their pouches"
}
}
]
}
}
}
'
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>",
"sections": [
{
"question": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}
},
{
"question": {
"question": "Are wallabies allowed?",
"answer": "Yes, leashed wallabies are allowed",
"picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
}
},
{
"trivia": {
"title": "Pocket creatures",
"body": "Wallabies are marsupials. The keep their babies in their pouches"
}
}
]
}
}
}
'
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>",
"sections": [
{
"question": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}
},
{
"question": {
"question": "Are wallabies allowed?",
"answer": "Yes, leashed wallabies are allowed",
"picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
}
},
{
"trivia": {
"title": "Pocket creatures",
"body": "Wallabies are marsupials. The keep their babies in their pouches"
}
}
]
}
}
}
'
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async {
Map payload = {
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"body": "<p class=\"content\">We love questions</p>",
"sections": [
{
"question": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}
},
{
"question": {
"question": "Are wallabies allowed?",
"answer": "Yes, leashed wallabies are allowed",
"picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
}
},
{
"trivia": {
"title": "Pocket creatures",
"body": "Wallabies are marsupials. The keep their babies in their pouches"
}
}
]
}
}
}
String body = convert.jsonEncode(payload);
http.Response response = await http.post(
url: 'https://api.buttercms.com/v2/pages/',
headers: {
"Content-Type":"application/json",
"Authorization": "Token your_write_api_token"
},
body: body
);
print(convert.jsonDecode(response.body));
}
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"body": "<p class=\"content\">We love questions</p>",
"sections": [
{
"question": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}
},
{
"question": {
"question": "Are wallabies allowed?",
"answer": "Yes, leashed wallabies are allowed",
"picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
}
},
{
"trivia": {
"title": "Pocket creatures",
"body": "Wallabies are marsupials. The keep their babies in their pouches"
}
}
]
}
}
}
`)
req, err := http.NewRequest("POST", "https://api.buttercms.com/v2/pages/",, payload)
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Token your_write_api_token")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
let payload = {
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"body": "<p class=\"content\">We love questions</p>",
"sections": [
{
"question": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}
},
{
"question": {
"question": "Are wallabies allowed?",
"answer": "Yes, leashed wallabies are allowed",
"picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
}
},
{
"trivia": {
"title": "Pocket creatures",
"body": "Wallabies are marsupials. The keep their babies in their pouches"
}
}
]
}
}
}
fetch("https://api.buttercms.com/v2/pages/", {
method: 'POST',
header: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err))
<?
$url = "https://api.buttercms.com/v2/pages/"
$payload = array(
"title" => "Frequently Asked Questions",
"slug" => "faq",
"page-type" => "questions",
"fields" => array(
"en" => array(
"headline" => "Frequently Asked Questions",
"body" => "<p class=\"content\">We love questions</p>",
"sections" => [
array(
"question" => array(
"question" => "Are dogs allowed?",
"answer" => "Leashed dogs are allowed.",
"picture" => "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
)
),
array(
"question" => array(
"question" => "Are wallabies allowed?",
"answer" => "Yes, leashed wallabies are allowed",
"picture" => "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
)
),
array(
"trivia" => array(
"title" => "Pocket creatures",
"body" => "Wallabies are marsupials. The keep their babies in their pouches"
)
)
]
)
)
)
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
import requests
payload = {
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"body": "<p class=\"content\">We love questions</p>",
"sections": [
{
"question": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}
},
{
"question": {
"question": "Are wallabies allowed?",
"answer": "Yes, leashed wallabies are allowed",
"picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
}
},
{
"trivia": {
"title": "Pocket creatures",
"body": "Wallabies are marsupials. The keep their babies in their pouches"
}
}
]
}
}
}
response = requests.post('https://api.buttercms.com/v2/pages/', json=payload, headers={"Authorization": "Token your_write_api_token" })
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse('https://api.buttercms.com/v2/pages/')
header = {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
}
payload = {
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"body": "<p class=\"content\">We love questions</p>",
"sections": [
{
"question": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}
},
{
"question": {
"question": "Are wallabies allowed?",
"answer": "Yes, leashed wallabies are allowed",
"picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
}
},
{
"trivia": {
"title": "Pocket creatures",
"body": "Wallabies are marsupials. The keep their babies in their pouches"
}
}
]
}
}
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
var payload = {
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"body": "<p class=\"content\">We love questions</p>",
"sections": [
{
"question": {
"question": "Are dogs allowed?",
"answer": "Leashed dogs are allowed.",
"picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
}
},
{
"question": {
"question": "Are wallabies allowed?",
"answer": "Yes, leashed wallabies are allowed",
"picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
}
},
{
"trivia": {
"title": "Pocket creatures",
"body": "Wallabies are marsupials. The keep their babies in their pouches"
}
}
]
}
}
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/pages/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
Component picker fields can be updated as well however, as with repeaters, they cannot be partially updated. If a component picker field is included in an update request the included contents will be used to overwrite the previous contents.
Reference fields for Page Types and Collections can both be edited via the Pages Write API.
To edit a reference field pointing to a specific Page Type, provide a Page slug for a one-to-one relationship, e.g., "related_page": "example-page-slug", or a list of slugs for a one-to-many relationship, e.g., "related_pages: ["example-page-1-slug", "example-page-2-slug"].
To edit a reference field pointing to a Collection, provide the Collection Item ID for a one-to-one relationship, e.g., "tag": 123, and a list of Collection Item IDs for a one-to-many relationship, e.g., "tags: [1, 2].
For both Page Type and Collection reference fields, it is possible to remove the references by setting the field to "" (for one-to-one relationships), [] (for one-to-many relationships), or null (for either relationship type). However, if the field key is omitted in the request, which is only possible when updating a Page, the references will not change from their current values.
Updating References via Write API
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",
"related_page": "example-page-slug",
"tags": [1, 2, 3]
},
"es": {
"headline": "Preguntas frecuentes",
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}
}'
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",
"related_page": "example-page-slug",
"tags": [1, 2, 3]
},
"es": {
"headline": "Preguntas frecuentes",
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}
}'
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",
"related_page": "example-page-slug",
"tags": [1, 2, 3]
},
"es": {
"headline": "Preguntas frecuentes",
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}
}'
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async {
Map payload = {
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}
}
String body = convert.jsonEncode(payload);
http.Response response = await http.post(
url: 'https://api.buttercms.com/v2/pages/',
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
},
body: body,
);
print(convert.jsonDecode(response.body));
}
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}
}
`)
req, err := http.NewRequest("POST", "https://api.buttercms.com/v2/pages/", payload)
req.Header.Add("Authorization", "Token your_write_api_token")
req.Header.Add("Content-type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
let payload = {
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}
}
fetch('https://api.buttercms.com/v2/pages/', {
method: 'POST',
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err));
<?php
$url = "https://api.buttercms.com/v2/pages/";
$payload = array(
"title" => "Frequently Asked Questions",
"slug" => "faq",
"page-type" => "questions",
"fields" => array(
"en" => array(
"headline" => "Frequently Asked Questions",
"related_page" => "example-page-slug",
"tags" => [1, 2, 3]
)
)
);
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
import requests
payload = {
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}
}
response = requests.post("https://api.buttercms.com/v2/pages/", json=payload, headers={"Authorization": "Token your_write_api_token" })
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse('https://api.buttercms.com/v2/pages/')
header = {
"Content-type": "application/json",
"Authorization": "Token your_write_api_token"
}
payload = {
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
var payload = {
"title": "Frequently Asked Questions",
"slug": "faq",
"page-type": "questions",
"fields": {
"en": {
"headline": "Frequently Asked Questions",
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/pages/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
To give your marketers the ability to preview pages you will want to first configure the preview URL of your Page Type.
When your marketer clicks "Preview", they will get taken to that preview URL such as https://yoursite.com/the-page/?preview=1 with a preview=1 parameter appended.
Your application will then look for that preview=1 parameter and when detected, call the ButterCMS API with the same preview parameter. You can see this defined in our API docs when querying Pages.
Passing preview=1 to ButterCMS will cause the draft version of the Page content to be returned and thus displayed within your application, allowing your marketing team to see a full in-context preview of their draft changes.
Example request
curl -X GET 'https://api.buttercms.com/v2/pages/<page_type_slug>/<page_slug>/?locale=en&preview=1&auth_token=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"
params = {"locale": 'en', "preview": 1}
ButterCMS::Page.get('*', 'example-news-page', params)
var butter = require('buttercms')("your_api_token");
butter.page.retrieve('*',
'example-news-page',
{
"locale": "en",
"preview": 1
}
).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{
"locale": "en",
"preview":"1"
}
ButterCMS.GetPage("*", "example-news-page", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->fetchPage('*', 'example-news-page', [
'locale' => 'en',
'preview' => 1
]);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
client.pages.get('*', 'example-news-page', {
'locale': 'en',
'preview': 1
})
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"},
};
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; }
}
PageReponse<NewsPage> newsPage = butterClient.RetrievePage<NewsPage>("*", "example-news-page", paramterDict);
// Async
PageReponse<NewsPage> newsPage = await butterClient.RetrievePageAsync<NewsPage>("*",
"example-news-page",
paramterDict);
import 'package:buttercms_dart/buttercms_dart.dart';
Butter butter = Butter('your_api_token');
butter.page.retrieve('news', 'example-news-page', {
'locale': 'en',
'preview': 1
}).then((response) {
print(response);
});
// https://github.com/ButterCMS/buttercms-java#retrieve-a-single-page
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
Map<String, String> queryParams = new HashMap<String, String>() {{
put("preview", "1")
}}
PageResponse<NewsPage> response = butterClient.getPage(
"*",
"example-news-page",
queryParams,
NewsPage.class
)
// Note: The swift SDK requires you to model the Page
// schema as a Codable Struct and pass it to getPages API.
// This allows the SDK to deserialize the page data for you.
private struct PageFields: Codable {
var name: String
var slug: String
// ... continue building struct based on expected datatypes.
// To see the expected data as a json, you can make a query using
// the API endpoint to the left.
// See https://developer.apple.com/documentation/foundation/archives_and_serialization/encoding_and_decoding_custom_types for more details
}
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY")
butter.getPage(
slug:"example-news-page",
parameters: [
.preview(value: 1),
.locale(value: "en"),
.levels(value: 2),
],
pageTypeSlug:"*",
type: PageFields.self
) // {Do something with result}
Example response
{
"data": {
"slug": "example-news-page",
"name": "Example News Page",
"page_type": "news",
"published": "2019-11-12T17:23:53.109696Z",
"updated": "2020-10-22T20:07:52.965850Z",
"fields": {
"seo": {
"title": "Example News Page",
"description": "SEO Description",
"keywords": "SEO, Keywords"
},
"headline": "This is an example news page",
"sections": [
{
"fields": {
"headline": "...",
"subheadline": "...",
"call_to_action": "..."
},
"type": "hero"
},
{
"fields": {
"video_headline": "...",
"video_link": "..."
},
"type": "product_video"
}
]
}
}
}
Get a single Page using its slug.
https://api.buttercms.com/v2/pages/<page_type>/?auth_token=your_api_token
| 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. 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 (e.g. en or fr). When omitted, this query parameter will default to your organization's default locale. |
| levels | Optional. Defaults to 2. Defines the levels of relationships to serialize. See below. |
A hash with a data property that contains the page matching the page slug.
Example request
curl -X GET 'https://api.buttercms.com/v2/pages/*/?preview=1&page=1&page_size=10&locale=en&levels=2&auth_token=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"
params = {
"preview": 1,
"page": 1,
"page_size": 10,
"locale": 'en',
"levels": 2
} # optional
ButterCMS::Page.list('*', params)
var butter = require('buttercms')("your_api_token");
var params = {
"preview": 1,
"page": 1,
"page_size": 10,
"locale": 'en',
"levels": 2
};
butter.page.list('*', 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")
params := map[string]string{
"preview":"1",
"page": "1",
"page_size": "10",
locale": "en",
"levels": "2"
}
ButterCMS.GetPages("*", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->fetchPages('*', [
'preview' => '1',
'page' => '1',
'page_size' => '10',
'locale' => 'en',
'levels' => '2'
]);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
params = {
'preview': '1',
'page': '1',
'page_size': '10',
'locale': 'en',
'levels': '2'
}
client.pages.all('*', params)
// Takes a generic PageType which is a class you define
// to match your ButterCMS config
using ButterCMS;
public class BasePage
{
...
}
var paramterDict = new Dictionary<string, string>()
{
{"preview", "1"},
{"page", "1"},
{"page_size", "10"}
{"locale", "en"},
{"levels", "2"},
};
PagesResponse<BasePage> newsPages = butterClient.ListPages<BasePage>("*",
paramterDict
);
// Async
PagesResponse<BasePage> newsPages = await butterClient.ListPagesAsync<BasePage>("*",
paramterDict
);
import 'package:buttercms_dart/buttercms_dart.dart';
Butter butter = Butter('your_api_token');
butter.page.list('*', {
'preview': '1',
'page': '1',
'page_size': '10',
'locale': 'en',
'levels': '2'
}).then((response) {
print(response);
});
// https://github.com/ButterCMS/buttercms-java#list-pages
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
Map<String, String> queryParams = new HashMap<String, String>() {{
put("preview", "1");
put("page", "1");
put("page_size", "10");
put("locale", "en");
put("levels", "2");
}};
PagesResponse<BasePage> response = butterClient.getPages(
"*",
queryParams,
BasePage.class
)
// Note: The swift SDK requires you to model the Page Type
// schema as a Codable Struct and pass it to getPages
// API. This allows the SDK to deserialize the page data
// for you.
// As such, although you can fetch all single pages from
// the API via a getPages call, the data returned would
// likely not match any codable struct configuration.
// There is no similar limitation for multiple pages of
// a defined page type (see the entry, "Get multiple Pages
// (Page Type) below" or blog posts, which have a defined
// schema.)
Example response
{
"meta": {
"previous_page": null,
"next_page": null,
"count": 2
},
"data": [
{
"slug": "single-page-1",
"page_type": null,
"published": "2019-11-12T17:23:53.109696Z",
"updated": "2020-10-22T20:07:52.965850Z",
"fields": {
"title": "This is a single page",
"body": "<p>Single PAGE!</p>"
}
},
{
"slug": "single-page-2",
"page_type": null,
"published": "2019-11-12T17:23:53.109696Z",
"updated": "2020-10-22T20:07:52.965850Z",
"fields": {
"title": "Amazing Single Page",
"body": "<p>Another single page!</p>",
"tag": "example",
"genre": "api"
}
}
]
}
Single Pages (those without a Page Type) are used to represent unique pages on your site. For example your Homepage. To get a list of all of your Single Pages, for instance when creating your sitemap.xml, simply use '*' as the PageType slug.
https://api.buttercms.com/v2/pages/*/?auth_token=your_api_token
| Argument | Description |
|---|---|
| page_type | Required. '*'. |
| preview | Optional. Set to 1 to return the latest draft version of a page. Useful for previewing changes before publishing live. i.e. &preview=1 |
| page¹ | Optional. Used for Paginating through result set. |
| page_size¹ | Optional. Used for Paginating. Defines the number of results returned. |
| locale | Optional. Set to the api slug of your configured locale (e.g. en or fr). When omitted, this query parameter will default to your organization's default locale. |
| levels | Optional. Defaults to 2. Defines the levels of relationships to serialize. See below. |
| limit¹ | Optional. Used for Paginating. Defines the number of results returned. |
| offset¹ | Optional. Used for Paginating through result set. |
¹ We support two types of pagination. You have to choose if you want to use page + page_size or limit + offset for getting entries. If you provide limit or offset we will ignore page and page_size.
A hash with a data property that contains an array with all single pages, and a meta property that contains pagination information.
Example request
curl -X GET 'https://api.buttercms.com/v2/pages/<page_type>/?preview=1&fields.tag=example&fields.genre=api&order=title&page=1&page_size=10&locale=en&levels=2&auth_token=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"
params = {
"preview": 1,
"fields.tag": 'example',
"fields.genre": 'api',
"order": 'title',
"page": 1,
"page_size": 10,
"locale": 'en',
"levels": 2
} # optional
ButterCMS::Page.list('news', params)
var butter = require('buttercms')("your_api_token");
var params = {
"preview": 1,
"fields.tag": "example",
"fields.genre": "api",
"order": 'title',
"page": 1,
"page_size": 10,
"locale": 'en',
"levels": 2
};
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")
params := map[string]string{
"preview":"1",
"fields.tag": "example",
"fields.genre": "api",
"order": "title",
"page": "1",
"page_size": "10",
locale": "en",
"levels": "2"
}
ButterCMS.GetPages("news", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->fetchPages('news', [
'preview' => '1',
'fields.tag' => 'example',
'fields.genre' => 'api',
'order' => 'title',
'page' => '1',
'page_size' => '10',
'locale' => 'en',
'levels' => '2'
]);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
params = {
'preview': '1',
'fields.tag': 'example',
'fields.genre': 'api',
'order': 'title',
'page': '1',
'page_size': '10',
'locale': 'en',
'levels': '2'
}
client.pages.all('news', params)
// 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; }
public string tag { get; set; }
public string genre { get; set; }
}
var paramterDict = new Dictionary<string, string>()
{
{"preview", "1"},
{"fields.tag", "example"},
{"fields.genre", "api"},
{"order", "title"},
{"page", "1"},
{"page_size", "10"}
{"locale", "en"},
{"levels", "2"}
};
PagesResponse<NewsPage> newsPages = butterClient.ListPages<NewsPage>("news",
paramterDict
);
// Async
PagesResponse<NewsPage> newsPages = await butterClient.ListPagesAsync<NewsPage>("news",
paramterDict
);
import 'package:buttercms_dart/buttercms_dart.dart';
Butter butter = Butter('your_api_token');
butter.page.list('news', {
'preview': '1',
'fields.tag': 'example',
'fields.genre': 'api',
'order': 'title',
'page': '1',
'page_size': '10',
'locale': 'en',
'levels': '2'
}).then((response) {
print(response);
});
// https://github.com/ButterCMS/buttercms-java#list-pages
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
Map<String, String> queryParams = new HashMap<String, String>(){{
put("preview", "1");
put("page", "1");
put("page_size", "10");
put("locale", "en");
put("levels", "2");
}}
PagesResponse<NewsPage> response = butterClient.getPages(
"news",
queryParams,
NewsPage.class
)
import ButterCMSSDK
// Note: The swift SDK requires you to model the Page
// schema as a Codable Struct and pass it to getPages API.
// This allows the SDK to deserialize the page data for you.
private struct NewsPageFields: Codable {
var name: String
var slug: String
// ... continue building struct based on expected datatypes.
// To see the expected data as a json, you can make a query using
// the API endpoint to the left.
// See https://developer.apple.com/documentation/foundation/archives_and_serialization/encoding_and_decoding_custom_types for more details
}
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY")
butter.getPages(
parameters: [
.preview(value: 1),
.page(value: 1)
.fields(key: "tag", value: "example")
.fields(value: "genre", value: "api")
.order(value: "title")
.locale(value: "en"),
.pageSize(value: 10),
.levels(value: 2)
],
pageTypeSlug:"news",
type: NewsPageFields.self,
) // {do something with result ....}
Example response
{
"meta": {
"previous_page": null,
"next_page": null,
"count": 2
},
"data": [
{
"slug": "example-news-page",
"name": "Example News Page",
"page_type": "news",
"published": "2019-11-12T17:23:53.109696Z",
"updated": "2020-10-22T20:07:52.965850Z",
"fields": {
"seo": {
"title": "Example News Page",
"description": "SEO Description",
"keywords": "SEO, Keywords"
},
"headline": "This is an example news page",
"tag": "example",
"genre": "api",
"sections": [
{
"fields": {
"headline": "...",
"subheadline": "...",
"call_to_action": "..."
},
"type": "hero"
}
]
}
},
{
"slug": "example-news-page-2",
"name": "Example News Page 2",
"page_type": "news",
"published": "2019-11-12T17:23:53.109696Z",
"updated": "2020-10-22T20:07:52.965850Z",
"fields": {
"seo": {
"title": "Example News Page",
"description": "SEO Description",
"keywords": "SEO, Keywords"
},
"headline": "This is another news page",
"tag": "example",
"genre": "api",
"sections": [
{
"fields": {
"video_headline": "...",
"video_link": "..."
},
"type": "product_video"
}
]
}
}
]
}
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.
https://api.buttercms.com/v2/pages/<page_type>/?auth_token=your_api_token
| Argument | Description |
|---|---|
| page_type | Required. The slug of the type of pages you want to retrieve. |
| preview | Optional. 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. 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 . To filter on Reference or Component fields use dot notation. i.e. fields.hero.title= or fields.hero.reference.title= |
| order | Optional. Can order by page level published, updated, or a content field of the Page Type. Defaults to ascending, preprend '-' to sort descending. |
| page¹ | Optional. Used for Paginating through result set. |
| page_size¹ | Optional. Used for Paginating. Defines the number of results returned. |
| locale | Optional. Set to the api slug of your configured locale (e.g. en or fr). When omitted, this query parameter will default to your organization's default locale. |
| levels | Optional. Defaults to 2. Defines the levels of relationships to serialize. See below. |
| limit¹ | Optional. Used for Paginating. Defines the number of results returned. |
| offset¹ | Optional. Used for Paginating through result set. |
¹ We support two types of pagination. You have to choose if you want to use page + page_size or limit + offset for getting entries. If you provide limit or offset we will ignore page and page_size.
A hash with a data property that contains an array of pages matching the query, and a meta property that contains pagination information.
Example Request
curl -X GET 'https://api.buttercms.com/v2/pages/search/?query=buttercmsapi&auth_token=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"
pages = ButterCMS::Page.search("buttercmsapi", {
"page_type": "news",
"page": 1,
"page_size": 10
})
var butter = require('buttercms')("your_api_token");
butter.page.search("buttercmsapi", {
"page_type": "news",
"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_type": "news",
"page": "1",
"page_size": "10"
}
ButterCMS.SearchPages("buttercmsapi", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->searchPages('buttercmsapi', [
'page_type' => 'news',
'page' => 1,
'page_size' => 10
]);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
client.pages.search('buttercmsapi', {
'page_type': 'news',
'page': 1,
'page_size': 10
})
using ButterCMS;
PagesResponse pages =
butterClient.SearchPages("buttercmsapi",
page_type: "news",
page: 1,
pageSize: 10
);
// We also support Async requests for all C# calls
PagesResponse caffeinePages =
await butterClient.SearchPagesAsync(query: "buttercmsapi",
page_type: "news",
page: 3,
pageSize: 5
);
import 'package:buttercms_dart/buttercms_dart.dart';
Butter butter = Butter('your_api_token');
butter.page.search("buttercmsapi", {
'page_type'; 'news',
'page': '1',
'page_size': '10'
}).then((response) {
print(response);
});
// https://github.com/ButterCMS/buttercms-java#pages
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
Map<String,String> queryParams = new HashMap<String,String>(){{
put("query","search term");
}}
PagesResponse pages = butterClient.getPageSearch(queryParams);
import ButterCMSSDK
// Note: The swift SDK requires you to model the Page
// schema as a Codable Struct and pass it to searchPages API.
// This allows the SDK to deserialize the page data for you. As such,
// the swift SDK pageSearch function is likely most useful when
// narrowing your search by Page Type, so that the data returned
// has a consistent structure.
// Note that for Swift, you'll want to pass page_type and
// query inside of your parameters dictionary.
private struct SearchPageFields: Codable {
var name: String
var slug: String
// ... continue building struct based on expected datatypes.
// To see the expected data as a json, you can make a query using
// the API endpoint to the left.
// See https://developer.apple.com/documentation/foundation/archives_and_serialization/encoding_and_decoding_custom_types for more details
}
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY")
butter.searchPages(
parameters: [
.preview(value: 1),
.page(value: 1),
.pageSize(value: 10),
.pageType(value: "news"),
.query(value: "buttercmsapi")
],
type: SearchPageFields.self,
) // {do something with result ....}
Example response
{
"meta": {
"previous_page": null,
"next_page": null,
"count": 2
},
"data": [
{
"slug": "example-news-page",
"name": "Example News Page",
"page_type": "news",
"published": "2019-11-12T17:23:53.109696Z",
"updated": "2020-10-22T20:07:52.965850Z",
"fields": {
"seo": {
"title": "Example News Page",
"description": "SEO Description",
"keywords": "SEO, Keywords"
},
"headline": "This is an example news page",
"sections": [
{
"fields": {
"headline": "...",
"subheadline": "...",
"call_to_action": "..."
},
"type": "hero"
}
]
}
},
{
"slug": "example-news-page-2",
"name": "Example News Page 2",
"page_type": "news",
"published": "2019-11-12T17:23:53.109696Z",
"updated": "2020-10-22T20:07:52.965850Z",
"fields": {
"seo": {
"title": "Example News Page",
"description": "SEO Description",
"keywords": "SEO, Keywords"
},
"headline": "This is another news page",
"sections": [
{
"fields": {
"video_headline": "...",
"video_link": "..."
},
"type": "product_video"
}
]
}
}
]
}
Returns a list of pages that match the search query. The pages are returned sorted by relevancy.
https://api.buttercms.com/v2/pages/search/?query=&auth_token=your_api_token
| Argument | Description |
|---|---|
| query | Required. Search query |
| page_type | Optional. The slug of the type of pages you want to limit your search to. Use * if you want to search only Single Pages (without a Page Type). If left empty, searching will not be limited to a specific Page Type. |
| locale | Optional. Set to the api slug of your configured locale (e.g. en or fr). When omitted, this query parameter will default to your organization's default locale. |
| levels | Optional. Defaults to 2. Defines the levels of relationships to serialize. See below. |
| page¹ | Optional. Used for Paginating through result set. |
| page_size¹ | Optional. Used for Paginating. Defines the number of results returned. |
| limit¹ | Optional. Used for Paginating. Defines the number of results returned. |
| offset¹ | Optional. Used for Paginating through result set. |
¹ We support two types of pagination. You have to choose if you want to use page + page_size or limit + offset for getting entries. If you provide limit or offset we will ignore page and page_size.
A hash with a data property that contains an array of pages matching the query, and a meta property that contains pagination information.
If no results are found, the API returns an empty array: "data": []
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=artists[_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.
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 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.
You can create Collection items by using POST requests to the Butter /v2/content/ API endpoint.
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"
},
...
]
}'
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"
},
...
]
}'
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"
},
...
]
}'
import requests
payload = {
"key": "collection_api_slug",
"status": "published",
"fields": [
{
"field1_key": "Field value",
"field2_key": "Field value"
},
]
}
response = requests.post("https://api.buttercms.com/v2/content/", json=payload, headers={"Authorization": "Token your_write_api_token"})
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async {
Map payload = {
"key": "collection_api_slug",
"status": "published",
"fields": [
{
"field1_key": "Field value",
"field2_key": "Field value"
},
]
};
String body = convert.jsonEncode(payload);
http.Response response = await http.post(
url: "https://api.buttercms.com/v2/content/",
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
},
body: body,
);
print(convert.jsonDecode(response.body));
}
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"key": "collection_api_slug",
"status": "published",
"fields": [
{
"field1_key": "Field value",
"field2_key": "Field value"
},
]
}
`)
req, err := http.NewRequest("POST", "https://api.buttercms.com/v2/content/", payload)
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Token your_write_api_token")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
let payload = {
"key": "collection_api_slug",
"status": "published",
"fields": [
{
"field1_key": "Field value",
"field2_key": "Field value"
},
]
}
fetch("https://api.buttercms.com/v2/content/", {
method: "POST",
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err))
<?php
$url = "https://api.buttercms.com/v2/content/";
$payload = array(
"key" => "collection_api_slug",
"status" => "published",
"fields" => [
array(
"field1_key" => "Field value",
"field2_key" => "Field value"
),
]
);
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://api.buttercms.com/v2/content/")
payload = {
"key": "collection_api_slug",
"status": "published",
"fields": [
{
"field1_key": "Field value",
"field2_key": "Field value"
},
]
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
var payload = {
"key": "collection_api_slug",
"status": "published",
"fields": [
{
"field1_key": "Field value",
"field2_key": "Field value"
}
]
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/content/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
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"
}
},
...
]
}'
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"
}
},
...
]
}'
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"
}
},
...
]
}'
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async {
Map payload = {
"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"
}
},
]
};
String body = convert.jsonEncode(payload);
http.Response response = await http.post(
url: "https://api.buttercms.com/v2/content/",
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
},
body: body
);
print(convert.jsonDecode(response.body));
}
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"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"
}
},
]
}
`)
req, err := http.NewRequest("POST", "https://api.buttercms.com/v2/content/", payload)
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Token your_write_api_token")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
let payload = {
"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"
}
},
]
}
fetch("https://api.buttercms.com/v2/content/", {
method: "POST",
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err))
<?php
$url = "https://api.buttercms.com/v2/content/";
$payload = array(
"key" => "collection_api_slug",
"status" => "published",
"fields" => [
array(
"en" => array(
"field1_key" => "Field value",
"field2_key" => "Field value"
),
"es" => array(
"field1_key" => "Field value",
"field2_key" => "Field value"
)
),
]
);
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
import requests
payload = {
"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"
}
},
]
}
response = requests.post("https://api.buttercms.com/v2/content/", json=payload, headers={"Authorization": "Token your_write_api_token"})
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://api.buttercms.com/v2/content/")
payload = {
"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"
}
},
]
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
var payload = {
"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"
}
}
]
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/content/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
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).
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.
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.
| Attribute | Description |
|---|---|
| key | Required. The unique name for the Collection. |
| 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. |
A validated POST request will return a response with HTTP status code 202. Full Collection item creation occurs asynchronously, meaning a successfully created Collection item may not show immediately. Items are validated prior to returning the API response, but it is also possible that item 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 is not a valid URL. Error explanations will be returned in a single JSON array.
You can update Collection items by using PUT and PATCH requests to the Butter /v2/content/<collection_key>/<item_id>/ API endpoint.
Update the whole Item WITHOUT Locales
curl -X PUT \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}'
curl -X PUT \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}'
curl -X PUT \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}'
import requests
payload = {
"status": "published",
"fields": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}
response = requests.put("https://api.buttercms.com/v2/content/collection_api_slug/123/", json=payload, headers={"Authorization": "Token your_write_api_token"})
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async {
Map payload = {
"status": "published",
"fields": {
"field1_key": "Field value",
"field2_key": "Field value"
}
};
String body = convert.jsonEncode(payload);
http.Response response = await http.put(
url: "https://api.buttercms.com/v2/content/collection_api_slug/123/",
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
},
body: body,
);
print(convert.jsonDecode(response.body));
}
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"status": "published",
"fields": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}
`)
req, err := http.NewRequest("PUT", "https://api.buttercms.com/v2/content/collection_api_slug/123/", payload)
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Token your_write_api_token")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
let payload = {
"status": "published",
"fields": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}
fetch("https://api.buttercms.com/v2/content/collection_api_slug/123/", {
method: "PUT",
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err))
<?php
$url = "https://api.buttercms.com/v2/content/collection_api_slug/123/";
$payload = array(
"status" => "published",
"fields" => array(
"field1_key" => "Field value",
"field2_key" => "Field value"
)
);
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_PUT, true);
curl_setopt($curl, CURLOPT_PUTFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://api.buttercms.com/v2/content/collection_api_slug/123/")
payload = {
"status": "published",
"fields": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Put.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
var payload = {
"status": "published",
"fields": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/content/collection_api_slug/123/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "PUT"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
Partial update WITHOUT Locales
curl -X PATCH \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"field2_key": "Field value"
}
}'
curl -X PATCH \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"field2_key": "Field value"
}
}'
curl -X PATCH \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"field2_key": "Field value"
}
}'
import requests
payload = {
"status": "published",
"fields": {
"field2_key": "Field value"
}
}
response = requests.patch("https://api.buttercms.com/v2/content/collection_api_slug/123/", json=payload, headers={"Authorization": "Token your_write_api_token"})
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async {
Map payload = {
"status": "published",
"fields": {
"field2_key": "Field value"
}
};
String body = convert.jsonEncode(payload);
http.Response response = await http.patch(
url: "https://api.buttercms.com/v2/content/collection_api_slug/123/",
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
},
body: body,
);
print(convert.jsonDecode(response.body));
}
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"status": "published",
"fields": {
"field2_key": "Field value"
}
}
`)
req, err := http.NewRequest("PATCH", "https://api.buttercms.com/v2/content/collection_api_slug/123/", payload)
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Token your_write_api_token")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
let payload = {
"status": "published",
"fields": {
"field2_key": "Field value"
}
}
fetch("https://api.buttercms.com/v2/content/collection_api_slug/123/", {
method: "PATCH",
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err))
<?php
$url = "https://api.buttercms.com/v2/content/collection_api_slug/123/";
$payload = array(
"status" => "published",
"fields" => array(
"field2_key" => "Field value"
)
);
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_PATCH, true);
curl_setopt($curl, CURLOPT_PATCHFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://api.buttercms.com/v2/content/collection_api_slug/123/")
payload = {
"status": "published",
"fields": {
"field2_key": "Field value"
}
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Patch.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
var payload = {
"status": "published",
"fields": {
"field2_key": "Field value"
}
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/content/collection_api_slug/123/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "PATCH"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
Update the whole Item WITH Locales
curl -X PUT \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"en": {
"field1_key": "Field value",
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}
}'
curl -X PUT \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"en": {
"field1_key": "Field value",
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}
}'
curl -X PUT \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"en": {
"field1_key": "Field value",
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}
}'
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async {
Map payload = {
"status": "published",
"fields": {
"en": {
"field1_key": "Field value",
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}
};
String body = convert.jsonEncode(payload);
http.Response response = await http.put(
url: "https://api.buttercms.com/v2/content/collection_api_slug/123/",
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
},
body: body
);
print(convert.jsonDecode(response.body));
}
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"status": "published",
"fields": {
"en": {
"field1_key": "Field value",
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}
}
`)
req, err := http.NewRequest("PUT", "https://api.buttercms.com/v2/content/collection_api_slug/123/", payload)
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Token your_write_api_token")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
let payload = {
"status": "published",
"fields": {
"en": {
"field1_key": "Field value",
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}
}
fetch("https://api.buttercms.com/v2/content/collection_api_slug/123/", {
method: "PUT",
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err))
<?php
$url = "https://api.buttercms.com/v2/content/collection_api_slug/123/";
$payload = array(
"status" => "published",
"fields" => array(
"en" => array(
"field1_key" => "Field value",
"field2_key" => "Field value"
),
"es" => array(
"field1_key" => "Field value",
"field2_key" => "Field value"
)
)
);
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_PUT, true);
curl_setopt($curl, CURLOPT_PUTFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
import requests
payload = {
"status": "published",
"fields": {
"en": {
"field1_key": "Field value",
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}
}
response = requests.put("https://api.buttercms.com/v2/content/collection_api_slug/123/", json=payload, headers={"Authorization": "Token your_write_api_token"})
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://api.buttercms.com/v2/content/collection_api_slug/123/")
payload = {
"status": "published",
"fields": {
"en": {
"field1_key": "Field value",
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Put.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
var payload = {
"status": "published",
"fields": {
"en": {
"field1_key": "Field value",
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value",
"field2_key": "Field value"
}
}
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/content/collection_api_slug/123/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "PUT"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
Partial update WITH Locales
curl -X PATCH \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"en": {
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value"
}
}
}'
curl -X PATCH \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"en": {
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value"
}
}
}'
curl -X PATCH \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"en": {
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value"
}
}
}'
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async {
Map payload = {
"status": "published",
"fields": {
"en": {
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value"
}
}
};
String body = convert.jsonEncode(payload);
http.Response response = await http.patch(
url: "https://api.buttercms.com/v2/content/collection_api_slug/123/",
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
},
body: body
);
print(convert.jsonDecode(response.body));
}
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"status": "published",
"fields": {
"en": {
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value"
}
}
}
`)
req, err := http.NewRequest("PATCH", "https://api.buttercms.com/v2/content/collection_api_slug/123/", payload)
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Token your_write_api_token")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
let payload = {
"status": "published",
"fields": {
"en": {
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value"
}
}
}
fetch("https://api.buttercms.com/v2/content/collection_api_slug/123/", {
method: "PATCH",
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err))
<?php
$url = "https://api.buttercms.com/v2/content/collection_api_slug/123/";
$payload = array(
"status" => "published",
"fields" => array(
"en" => array(
"field2_key" => "Field value"
),
"es" => array(
"field1_key" => "Field value"
)
)
);
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_PATCH, true);
curl_setopt($curl, CURLOPT_PATCHFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
import requests
payload = {
"status": "published",
"fields": {
"en": {
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value"
}
}
}
response = requests.patch("https://api.buttercms.com/v2/content/collection_api_slug/123/", json=payload, headers={"Authorization": "Token your_write_api_token"})
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://api.buttercms.com/v2/content/collection_api_slug/123/")
payload = {
"status": "published",
"fields": {
"en": {
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value"
}
}
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Patch.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
var payload = {
"status": "published",
"fields": {
"en": {
"field2_key": "Field value"
},
"es": {
"field1_key": "Field value"
}
}
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/content/collection_api_slug/123/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "PATCH"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
<item_id>?The ID used to compose the Item's URL can be found in the meta field on each individual item returned by /v2/content/ and /v2/content/<collection_key>/ API endpoints.
Requests should be HTTP PUT (to update all fields) or PATCH (to update only a subset of fields) requests made to https://api.buttercms.com/v2/content/<collection_key>/<item_id>/, 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).
If you don't have locales, your request body should be a JSON object like the example to the right. fields is an object representing a content list object with each of its fields updated by key and value.
If you do have locales configured, the object has 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.
| Attribute | Description |
|---|---|
| status | Required. Should be 'published' or 'draft'. |
| fields | Required. An object representing a collection item with each of its fields created by key and value. |
A validated PUT or PATCH request will return a response with HTTP status code 202. Full collection item update occurs asynchronously, meaning a successfully updated content may not show immediately. Content item fields are validated prior to returning the API response, but it is also possible that the update 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 if the remote URL for a media field is not a valid URL. Error explanations will be returned in a single JSON array.
Reference fields for Collections items that point to Page Types or Collections can be edited via the Collection item Write API.
To edit a reference field pointing to a specific Page Type, provide a Page slug for a one-to-one relationship, e.g., "related_page": "example-page-slug", or a list of slugs for a one-to-many relationship, e.g., "related_pages: ["example-page-1-slug", "example-page-2-slug"].
To edit a reference field pointing to a Collection, provide the Collection Item ID for a one-to-one relationship, e.g., "tag": 123, and a list of Collection Item IDs for a one-to-many relationship, e.g., "tags: [1, 2].
For both Page Type and Collection reference fields, it is possible to remove the references by setting the field to "" (for one-to-one relationships), [] (for one-to-many relationships), or null (for either relationship type). However, if the field key is omitted in the request, which is only possible when updating a Collection Item using PATCH, the references will not change from their current values.
Updating References via Write API
curl -X PATCH \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}'
curl -X PATCH \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}'
curl -X PATCH \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}'
import requests
payload = {
"status": "published",
"fields": {
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}
response = requests.patch("https://api.buttercms.com/v2/content/collection_api_slug/123/", json=payload, headers={"Authorization": "Token your_write_api_token"})
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async {
Map payload = {
"status": "published",
"fields": {
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
};
String body = convert.jsonEncode(payload);
http.Response response = await http.patch(
url: "https://api.buttercms.com/v2/content/collection_api_slug/123/",
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
},
body: body,
);
print(convert.jsonDecode(response.body));
}
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"status": "published",
"fields": {
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}
`)
req, err := http.NewRequest("PATCH", "https://api.buttercms.com/v2/content/collection_api_slug/123/", payload)
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Token your_write_api_token")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
let payload = {
"status": "published",
"fields": {
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}
fetch("https://api.buttercms.com/v2/content/collection_api_slug/123/", {
method: "PATCH",
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err))
<?php
$url = "https://api.buttercms.com/v2/content/collection_api_slug/123/";
$payload = array(
"status" => "published",
"fields" => array(
"related_page" => "example-page-slug",
"tags" => [1, 2, 3]
)
);
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_PATCH, true);
curl_setopt($curl, CURLOPT_PATCHFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://api.buttercms.com/v2/content/collection_api_slug/123/")
payload = {
"status": "published",
"fields": {
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Patch.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
var payload = {
"status": "published",
"fields": {
"related_page": "example-page-slug",
"tags": [1, 2, 3]
}
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/content/collection_api_slug/123/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "PATCH"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
You can delete a single Collection item by using DELETE request to the Butter /v2/content/<collection_key>/<item_id>/ API endpoint.
Delete a Collection Item
curl -X DELETE \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json'
curl -X DELETE \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json'
curl -X DELETE \
https://api.buttercms.com/v2/content/collection_api_slug/123/ \
-H 'Authorization: Token your_write_api_token' \
-H 'Content-Type: application/json'
import requests
response = requests.delete("https://api.buttercms.com/v2/content/collection_api_slug/123/", headers={"Authorization": "Token your_write_api_token"})
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async {
http.Response response = await http.delete(
url: "https://api.buttercms.com/v2/content/collection_api_slug/123/",
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
}
);
}
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
req, err := http.NewRequest("DELETE", "https://api.buttercms.com/v2/content/collection_api_slug/123/")
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Token your_write_api_token")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
}
fetch("https://api.buttercms.com/v2/content/collection_api_slug/123/", {
method: "DELETE",
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json"
}
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err))
<?php
$url = "https://api.buttercms.com/v2/content/collection_api_slug/123/";
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_DELETE, true);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://api.buttercms.com/v2/content/collection_api_slug/123/")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Delete.new(uri.request_uri, header)
response = http.request(request)
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/content/collection_api_slug/123/")
var request = URLRequest(url: requestUrl)
request.httpMethod = "DELETE"
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
Example request
curl -X GET 'https://api.buttercms.com/v2/content/artists/?preview=1&fields.genre=Rock&order=name&page=1&page_size=10&locale=en&levels=2&auth_token=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"
params = {
"preview": 1,
"fields.genre": "Rock",
"order": "name",
"page": 1,
"page_size": 10,
"locale": "en",
"levels": 2
} # optional
content = ButterCMS::Content.list('artists', params)
var butter = require('buttercms')("your_api_token");
var params = {
"preview": 1,
"fields.genre": "Rock",
"page": 1,
"page_size": 10,
"locale": "en",
"levels": 2
};
butter.content.retrieve(['artists'], 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")
params := map[string]string{
"preview":"1",
"fields.genre": "Rock",
"order": "name",
"page": "1",
"page_size": "10",
"locale": "en",
"levels": "2"
}
ButterCMS.GetContentFields([]string{"artists"},)
<?
use ButterCMS\ButterCMS;
$butter = new ButterCMS('your_api_token');
$butter->fetchContentFields(['artists'], [
'preview' => '1',
'fields.genre' => 'Rock',
'order' => 'name',
'page' => '1',
'page_size' => '10',
'locale' => 'en',
'levels' => '2'
]);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
params = {
'preview': '1',
'fields.genre': 'Rock',
'order': 'name',
'page': '1',
'page_size': '10',
'locale': 'en',
'levels': '2'
}
client.content_fields.get(['artists'], params)
using ButterCMS;
// You can pass one or more keys at a time
var keys = new string[2] { "artists" };
var paramterDict = new Dictionary<string, string>()
{
{"preview", "1"},
{"fields.genre", "Rock"},
{"order", "name"},
{"page", "1"},
{"page_size", "10"}
{"locale", "en"},
{"levels", "2"},
};
var contentFields = await butterClient.RetrieveContentFieldsJSONAsync(keys,
parameterDict
);
import 'package:buttercms_dart/buttercms_dart.dart';
Butter butter = Butter('your_api_token');
butter.content.retrieve(['artists'], {
'preview': '1',
'fields.genre': 'Rock',
'order': 'name',
'page': '1',
'page_size': '10',
'locale': 'en',
'levels': '2'
}).then((response) {
print(response);
});
// https://github.com/ButterCMS/buttercms-java#list-collection-items
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
Map<String, String> queryParams = new HashMap<String, String>(){{
put("preview", "1");
put("page", "1");
put("page_size", "10");
put("locale", "en");
put("levels", "2");
put("fields.genre", "Rock");
put("order", "name");
}}
CollectionResponse response = butterClient.getCollection(
"artists",
queryParams,
ArtistCollection.class
);
// Note: The swift SDK requires you to model the Collection
// schema as a Codable Struct and pass it to getPages API.
// This allows the SDK to deserialize the page data for you.
private struct CollectionFields: Codable {
var name: String
var description: String
// ... continue building struct based on expected datatypes.
// To see the expected data as a json, you can make a query using
// the API endpoint to the left.
// See https://developer.apple.com/documentation/foundation/archives_and_serialization/encoding_and_decoding_custom_types for more details
}
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY")
butter.getCollection(
slug:"artists",
parameters: [
// Collections API for Swift does not have preview at this time
.page(value: 1)
.fields(value: "genre", value: "Rock")
// Note - currently takes two keys, "by", and "direction"
.order(by: "name", direction:"")
.locale(value: "en"),
.pageSize(value: 10),
.levels(value: 2),
],
type: CollectionFields.self
) // {Do something with result}
Example response
{
"data": {
"artists": [
{
"meta": {
"id": 123
},
"name": "The Beatles",
"genre": "Rock"
},
{
"meta": {
"id": 123
},
"name": "The Rolling Stones",
"genre": "Rock"
}
]
}
}
Returns values for the supplied Collection keys.
https://api.buttercms.com/v2/content/<collection_slug>/?auth_token=your_api_token
| Argument | Description |
|---|---|
| keys | Comma delimited list of Collection keys. |
| preview | Optional. Set to 1 to enable Preview mode for viewing draft content. |
fields.key |
Optional. Filter the result set by the field and value. |
| order | Optional. Order the result set by this field. Defaults to Ascending. Preprend '-' to sort Descending. i.e. &order=-your_field |
| page | Optional. Used for Paginating through result set. |
| page_size | Optional. Used for Paginating. Defines the number of results returned. |
| locale | Optional. Set to the api slug of your configured locale (e.g. en or fr). When omitted, this query parameter will default to your organization's default locale. |
| levels | Optional. Defaults to 2. Defines the levels of relationships to serialize. See below. |
An object with a data property that contains a list of objects with Collection item keys and values.
Each returned Collection item object contains a special meta key. This key contains an object with data about the Collection item. Currently, it only contains the item's ID, which can be used to update or delete the item. In the future this object could contain other information.
| Meta property | Description |
|---|---|
| id | An identifier for the Collection item. |
Sometimes you want to filter a Collection to return only a subset of items. Use fields.key to do this. i.e. ?fields.field_name=value
For example, if you have a Collection of musical artists:
/v2/content/artists/
You can filter on any Collection property:
/v2/content/artists?fields.name=The Beatles
Example Request
curl -X GET 'https://api.buttercms.com/v2/content/artists/?&preview=1&auth_token=your_api_token'
To setup a staging website for previewing content you'll need to fetch the draft version of a Collection item. To do this, simply add ?preview=1 as a parameter to the normal API call.
You'll often want to set this ?preview=1 flag in your local, development, and staging environments to enable previewing of content.
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=artists[_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 serialize 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.
Example Request
curl -X GET 'https://api.buttercms.com/v2/content/artists/?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/artists/?locale=en
The API slugs values for each locale are configured by you in your account.
<item_id>?The ID used to compose the Item's URL can be found in the meta field on each individual item returned by /v2/content/ and /v2/content/<collection_key>/ API endpoints.
Requests should be HTTP DELETE made to https://api.buttercms.com/v2/content/<collection_key>/<item_id>/, with the Content-Type header set to application/json and Authorization header set to Token your_write_api_token.
The request should have no body data.
A successful DELETE request will return a response with HTTP status code 204 (No content).
Full collection update occurs asynchronously, meaning a successfully deleted content may still show up for a short time.
The API will return HTTP status code 404 if the Collection item doesn't exist.
The ButterCMS Blog Engine provides you with a set of pre-built API's to quickly add a fully customized blog to your website.
| 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 | Timestamp of when the post was created |
| updated timestamp | Timestamp of when the post was last updated |
| 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 |
| featured_image_alt string |
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",
"featured_image_alt": "Featured image alt text example.",
"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"
}'
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",
"featured_image_alt": "Featured image alt text example.",
"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"
}'
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",
"featured_image_alt": "Featured image alt text example.",
"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"
}'
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async{
Map payload = {
"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",
"featured_image_alt": "Featured image alt text example.",
"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"
};
String body = convert.jsonEncode(payload);
http.Response response = await http.post(
url: 'https://api.buttercms.com/v2/posts/',
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
},
body: body,
);
print(convert.jsonDecode(response.body));
}
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"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",
"featured_image_alt": "Featured image alt text example.",
"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"
}
`)
req, err := http.NewRequest("POST", "https://api.buttercms.com/v2/posts/", payload)
req.Header.Add("Authorization", "Token your_write_api_token")
req.Header.Add("Content-type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
let payload = {
"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",
"featured_image_alt": "Featured image alt text example.",
"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"
}
fetch('https://api.buttercms.com/v2/posts/', {
method: 'POST',
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err));
import requests
payload = {
"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",
"featured_image_alt": "Featured image alt text example.",
"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"
}
response = requests.post("https://api.buttercms.com/v2/posts/", json=payload, headers={"Authorization": "Token your_write_api_token" })
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse('https://api.buttercms.com/v2/posts/')
header = {
"Content-type": "application/json",
"Authorization": "Token your_write_api_token"
}
payload = {
"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",
"featured_image_alt": "Featured image alt text example.",
"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"
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
<?php
$url = "https://api.buttercms.com/v2/posts/";
$payload = array(
"author" => array(
"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",
"featured_image_alt" => "Featured image alt text example.",
"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"
);
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
var payload = {
"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",
"featured_image_alt": "Featured image alt text example.",
"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"
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/posts/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
You can create posts by using POST requests to the Butter /v2/posts/ API endpoint.
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.
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.
| 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. The image will always be uploaded to the media library (the value of |
| featured_image_alt | Optional. |
| body | Optional. Should be an string of escaped HTML. In case it contains any remote URLs to images, the |
| summary | Optional. |
| seo_title | Optional. |
| meta_description | Optional. |
| upload_images_to_media_library | Optional. Defaults to If set to If set to |
body property, image content from provided URLs will be uploaded to Butter if upload_images_to_media_library is true.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.
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>"
}'
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>"
}'
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>"
}'
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async {
Map payload = {
"slug": "the-new-post-slug",
"body": "<h1>Updated</h1><p>This is a blog post was updated via API</p>"
};
String body = convert.jsonEncode(payload);
http.Response response = await http.patch(
url: 'https://api.buttercms.com/v2/posts/this-is-a-blog-post/',
headers: {
"Content-Type": "application/json",
"Authorization": "Token your_write_api_token"
},
body: body,
);
print(convert.jsonDecode(response.body));
}
import (
"net/http"
"io/ioutil"
"strings"
"log"
)
func main() {
payload := strings.NewReader(`
{
"slug": "the-new-post-slug",
"body": "<h1>Updated</h1><p>This is a blog post was updated via API</p>"
}
`)
req, err := http.NewRequest("PATCH", "https://api.buttercms.com/v2/posts/this-is-a-blog-post/", payload)
req.Header.Add("Authorization", "Token your_write_api_token")
req.Header.Add("Content-type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
let payload = {
"slug": "the-new-post-slug",
"body": "<h1>Updated</h1><p>This is a blog post was updated via API</p>"
}
fetch('https://api.buttercms.com/v2/posts/this-is-a-blog-post/', {
method: 'PATCH',
headers: {
"Authorization": "Token your_write_api_token",
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err));
import requests
payload = {
"slug": "the-new-post-slug",
"body": "<h1>Updated</h1><p>This is a blog post was updated via API</p>"
}
response = requests.patch("https://api.buttercms.com/v2/posts/this-is-a-blog-post/", json=payload, headers={"Authorization": "Token your_write_api_token" })
print(response.content)
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse('https://api.buttercms.com/v2/posts/this-is-a-blog-post/')
header = {
"Content-type": "application/json",
"Authorization": "Token your_write_api_token"
}
payload = {
"slug": "the-new-post-slug",
"body": "<h1>Updated</h1><p>This is a blog post was updated via API</p>"
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Patch.new(uri.request_uri, header)
request.body = payload.to_json
response = http.request(request)
<?php
$url = "https://api.buttercms.com/v2/posts/this-is-a-blog-post/";
$payload = array(
"slug" => "the-new-post-slug",
"body" => "<h1>Updated</h1><p>This is a blog post was updated via API</p>"
);
$content = json_encode($payload);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-type: application/json", "Authorization: Token your_write_api_token" ));
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($curl, CURLOPT_POSTFIELDS, $content);
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
var payload = {
"slug": "the-new-post-slug",
"body": "<h1>Updated</h1><p>This is a blog post was updated via API</p>"
}
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/posts/this-is-a-blog-post/")
var request = URLRequest(url: requestUrl)
let bodyData = try? JSONSerialization.data(
withJSONObject: payload,
options: []
)
request.httpMethod = "PATCH"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
request.httpBody = bodyData
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
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.
You can provide the optional upload_images_to_media_library attribute with a value of true if you'd like any image URLs in the body property to be uploaded to the Butter Media Library. See the same flag's description in Create Blog Post via Write API for more details.
Example DELETE Request
curl -X DELETE \
https://api.buttercms.com/v2/posts/this-is-a-blog-post/ \
-H 'Authorization: Token your_write_api_token'
curl -X DELETE \
https://api.buttercms.com/v2/posts/this-is-a-blog-post/ \
-H 'Authorization: Token your_write_api_token'
curl -X DELETE \
https://api.buttercms.com/v2/posts/this-is-a-blog-post/ \
-H 'Authorization: Token your_write_api_token'
import 'dart:convert' as convert;
import 'package:http/http.dart' as http;
void main() async {
http.Response response = await http.delete(
url: 'https://api.buttercms.com/v2/posts/this-is-a-blog-post/',
headers: {
"Authorization": "Token your_write_api_token"
},
);
print(convert.jsonDecode(response.body));
}
import (
"net/http"
"io/ioutil"
"log"
)
func main() {
req, err := http.NewRequest("DELETE", "https://api.buttercms.com/v2/posts/this-is-a-blog-post/", nil)
req.Header.Add("Authorization", "Token your_write_api_token")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalln(err)
}
body, _ := ioutil.ReadAll(resp.Body)
log.Println(string([]byte(body)))
}
fetch('https://api.buttercms.com/v2/posts/this-is-a-blog-post/', {
method: 'DELETE',
headers: {
"Authorization": "Token your_write_api_token",
},
})
.then(json => console.log(json))
.catch(err => console.log("Request Failed", err));
import requests
response = requests.delete("https://api.buttercms.com/v2/posts/this-is-a-blog-post/", headers={"Authorization": "Token your_write_api_token" })
print(response.content)
require 'net/http'
require 'uri'
uri = URI.parse('https://api.buttercms.com/v2/posts/this-is-a-blog-post/')
header = {
"Authorization": "Token your_write_api_token"
}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Delete.new(uri.request_uri, header)
response = http.request(request)
<?php
$url = "https://api.buttercms.com/v2/posts/this-is-a-blog-post/";
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Authorization: Token your_write_api_token"));
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'DELETE');
$json_response = curl_exec($curl);
curl_close($curl);
$response = json_decode($json_response, true);
print_r($response);
?>
// Prepare URL Request Object
let requestUrl = URL(string: "https://api.buttercms.com/v2/posts/this-is-a-blog-post/")
var request = URLRequest(url: requestUrl)
request.httpMethod = "DELETE"
request.setValue("your_api_token_here", forHTTPHeaderField: "Authorization")
// Perform HTTP Request
let session = URLSession.shared
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("Error took place \(error)")
} else if let data = data {
// Do something with returned data
} else {
// Handle unexpected error
}
}
// Start request
task.resume()
You can delete an existing blog post by making a DELETE request to the /v2/posts/your-post-slug/ endpoint.
Example request
curl -X GET 'https://api.buttercms.com/v2/posts/?page=1&page_size=10&exclude_body=false&author_slug=api-test&category_slug=test-category&tag_slug=test-tag&auth_token=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"
posts = ButterCMS::Post.all({
"page": 1,
"page_size": 10,
"exclude_body": false,
"author_slug": 'test-api',
"category_slug": 'test-category',
"tag_slug": 'test-tag'
})
var butter = require('buttercms')("your_api_token");
butter.post.list({
"page": 1,
"page_size": 10,
"exclude_body": false,
"author_slug": 'test-api',
"category_slug": 'test-category',
"tag_slug": 'test-tag'
})
.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",
"page_size": "10",
"exclude_body": "false",
"author_slug": "test-api",
"category_slug": "test-category",
"tag_slug": "test-tag"
}
ButterCMS.GetPosts(params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->fetchPosts([
'page' => '1',
'page_size' => '10',
'exclude_body' => 'false',
'author_slug' => 'test-api',
'category_slug' => 'test-category',
'tag_slug' => 'test-tag'
]);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
client.posts.all({
"page": "1",
"page_size": "10",
"exclude_body": "false",
"author_slug": "test-api",
"category_slug": "test-category",
"tag_slug": "test-tag"
})
using ButterCMS;
PostsResponse posts = butterClient.ListPosts(
page: 1,
pageSize: 10,
excludeBody: false,
authorSlug: "test-api",
categorySlug: "test-category",
tagSlug: "test-tag"
);
// We also support Async requests for all C# calls
PostsResponse filteredPosts = await butterClient.ListPostsAsync();
import 'package:buttercms_dart/buttercms_dart.dart';
Butter butter = Butter('your_api_token');
butter.posts.list({
'page': '1',
'page_size': '10',
'exclude_body': 'false',
'author_slug': 'test-api',
'category_slug': 'test-category',
'tag_slug': 'test-tag'
}).then((response) {
print(response);
});
// https://github.com/ButterCMS/buttercms-java#posts
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
Map<String,String> queryParams = new HashMap<String, String>() {{
put("page", "1");
put("page_size", "10");
put("exclude_body", "false");
put("author_slug", "test-api");
put("category_slug", "test-category");
put("tag_slug", "test-tag");
}}
PostsResponse posts = butterClient.getPosts(queryParams);
// Unlike with fetching pages, it is not necessary
// to construct and pass a struct for blog posts for
// the Swift SDK to consume, as their schema doesn't change.
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY")
butter.getPosts(parameters: [ .preview(value:1)]) { result in
switch result {
case .sucess(let posts):
posts.data.compactMap { print (*Post: \($0) \n*)}
case .failure(let error):
print (error)
}
}
Example response
{
"meta": {
"count": 1,
"next_page": null,
"previous_page": null
},
"data": [
{
"url": "http://www.example.com/blog/this-is-a-blog-post",
"created": "2020-10-08T18:29:19.987936Z",
"updated": "2020-10-09T15:49:54.580309Z",
"published": "2020-10-08T18:08: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,
"featured_image_alt": "",
"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,
"featured_image_alt": "",
"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": "2020-10-08T18:29:19.987936Z",
"updated": "2020-10-09T15:49:54.580309Z",
"published": "2020-10-08T18:08: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,
"featured_image_alt": "",
"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,
"featured_image_alt": "",
"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,
"featured_image_alt": "",
"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,
"featured_image_alt": "",
"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,
"featured_image_alt": "",
"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,
"featured_image_alt": "",
"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,
"featured_image_alt": "",
"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"
}
]
}
Post: Post(
status: Optional(ButterCMSSDK.Status.PUBLISHED),
created: Optional(2021-07-19 12:24:21 +0000),
published: Optional(2021-07-19 12:24:00 +0000),
title: "An Example blog post",
slug: "example-post-1",
body: Optional("<p>I am a post"),
summary: Optional("This is a blog post."),
seoTitle: Optional("TEST"),
metaDescription: Optional("This is a blog post to test the API."),
featuredImage: nil,
featuredImageAlt: Optional(""),
url: Optional("test"),
author: Optional(ButterCMSSDK.Author(
slug: "sample-name",
firstName: Optional("First"),
lastName: Optional("last"),
email: Optional("sample.email@sample.com"),
bio: Optional("my bio"),
title: Optional("title"),
linkedinUrl: Optional(""),
facebookUrl: Optional(""),
pinterestUrl: Optional(""),
instagramUrl: Optional(""),
twitterHandle: Optional(""),
profileImage: Optional(""),
recentPosts: nil
)),
tags: Optional([ButterCSMSDK.Tag(
slug: "example-tag",
name: "Example Tag",
recentPosts: nil,
)]),
categories: Optional([ButterCMSSDK.Category(
slug: "example-category",
name: "Example Category",
recentPosts: nil,
)])
)
Post: Post(
status: Optional(ButterCMSSDK.Status.PUBLISHED),
created: Optional(2021-07-19 12:24:21 +0000),
published: Optional(2021-07-19 12:24:00 +0000),
title: "An Example blog post",
slug: "example-post-2",
body: Optional("<p>I am a post"),
summary: Optional("This is a blog post."),
seoTitle: Optional("TEST"),
metaDescription: Optional("This is a blog post to test the API."),
featuredImage: nil,
featuredImageAlt: Optional(""),
url: Optional("test"),
author: Optional(ButterCMSSDK.Author(
slug: "sample-name",
firstName: Optional("First"),
lastName: Optional("last"),
email: Optional("sample.email@sample.com"),
bio: Optional("my bio"),
title: Optional("title"),
linkedinUrl: Optional(""),
facebookUrl: Optional(""),
pinterestUrl: Optional(""),
instagramUrl: Optional(""),
twitterHandle: Optional(""),
profileImage: Optional(""),
recentPosts: nil
)),
tags: Optional([ButterCSMSDK.Tag(
slug: "example-tag",
name: "Example Tag",
recentPosts: nil,
)]),
categories: Optional([ButterCMSSDK.Category(
slug: "example-category",
name: "Example Category",
recentPosts: nil,
)])
)
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.
| 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. |
| preview | 1 | Optional. Set to 1 to return all published and draft posts. i.e. &preview=1 |
| 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. | |
| limit¹ | 10 | Used for Paginating. Defines the number of results returned. |
| offset¹ | 0 | Used for Paginating through result set. |
¹ We support two types of pagination. You have to choose if you want to use page + page_size or limit + offset for getting entries. If you provide limit or offset we will ignore page and page_size.
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.
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("hello-world");
// We also support Async requests for all C# calls
PostResponse safePost =
await butterClient.RetrievePostAsync("hello-world");
import 'package:buttercms_dart/buttercms_dart.dart';
Butter butter = Butter('your_api_token');
butter.posts.retrieve("hello-world").then((response) {
print(response);
});
// https://github.com/ButterCMS/buttercms-java#posts
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
PostResponse post = butterClient.getPost("hello-world");
// Unlike with fetching pages, it is not necessary
// to construct and pass a struct for blog posts for
// the Swift SDK to consume, as their schema doesn't change.
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY")
}
butter.getPost(
slug: "hello-world"
) // {Print the result}
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,
"featured_image_alt": "",
"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.
| Argument | Description |
|---|---|
| slug | The slug of the post to be retrieved. |
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.
Example Request
curl -X GET 'https://api.buttercms.com/v2/posts/search/?query=buttercmsapi&page=1&page_size=10&auth_token=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"
posts = ButterCMS::Post.search("buttercmsapi", {
"page": 1,
"page_size": 10
})
var butter = require('buttercms')("your_api_token");
butter.post.search("buttercmsapi", {
"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",
"page_size": "10"
}
ButterCMS.SearchPosts("buttercmsapi", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->searchPosts('buttercmsapi', [
'page' => 1,
'page_size' => 10
]);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
client.posts.search('buttercmsapi', {
'page': 1,
'page_size': 10
})
using ButterCMS;
PostsResponse posts =
butterClient.SearchPosts("buttercmsapi",
page: 1,
pageSize: 10
);
// We also support Async requests for all C# calls
PostsResponse caffeinePosts =
await butterClient.SearchPostsAsync(query: "buttercmsapi",
page: 3,
pageSize: 5
);
import 'package:buttercms_dart/buttercms_dart.dart';
Butter butter = Butter('your_api_token');
butter.posts.search("buttercmsapi", {
'page': '1',
'page_size': '10'
}).then((response) {
print(response);
});
// https://github.com/ButterCMS/buttercms-java#posts
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
Map<String,String> queryParams = new HashMap<String,String>(){{
put("query","search term");
}}
PostsResponse posts = butterClient.getPostSearch(queryParams);
// Unlike with fetching pages, it is not necessary
// to construct and pass a struct for blog posts for
// the Swift SDK to consume, as their schema doesn't change.
// Note that the swift SDK is unique, in that the query
// terms is passed as a string inside params.
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY")
butter.searchPosts(
parameters: [
.page(value: 1),
.page_size(value: 10),
.query(value: "buttercmsapi")
]
) // {Do something with result}
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,
"featured_image_alt": "",
"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.
| Argument | Default | Description |
|---|---|---|
| query | Search query | |
| page | 1 | |
| page_size | 10 |
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": []
| 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. |
Example request
curl -X GET 'https://api.buttercms.com/v2/authors/?include=recent_posts&auth_token=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"
authors = ButterCMS::Author.all({
"include": "recent_posts"
})
var butter = require('buttercms')("your_api_token");
butter.author.list({"include": "recent_posts"})
.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(includeRecentPosts: true);
// Async
IEnumerable<Author> authorsWithPosts =
await butterClient.ListAuthorsAsync(includeRecentPosts: true);
import 'package:buttercms_dart/buttercms_dart.dart';
Butter butter = Butter('your_api_token');
butter.authors.list({
'include': 'recent_posts'
}).then((response) {
print(response);
});
// https://github.com/ButterCMS/buttercms-java#authors
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
Map<String,String> queryParams = new HashMap<String,String>(){{
put("include","recent_posts");
}}
AuthorsResponse authors = butterClient.getAuthors(queryParams);
// Unlike with fetching pages, it is not necessary
// to construct and pass a struct for authors for
// the Swift SDK to consume, as their schema doesn't change.
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY")
butter.getAuthors(
parameters: [.include(value: "recent_posts")]
) // {Do something with result}
Example response
// Note that `data` is an array/list composed of a
// number of author objects/dictionaries.
{
"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.
| Argument | Description |
|---|---|
| include | Use include=recent_posts to include the author's recent posts in the response. |
A hash with a data property that contains an array of authors.
Example request
curl -X GET 'https://api.buttercms.com/v2/authors/jennifer-smith/?include=recent_posts&auth_token=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"
author = ButterCMS::Author.find("jennifer-smith", {
"include": "recent_posts"
})
// https://github.com/ButterCMS/buttercms-java#authors
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
Map<String,String> queryParams = new HashMap<String,String>(){{
put("include","recent_posts");
}}
AuthorResponse author = butterClient.getAuthor("jennifer-smith", queryParams);
var butter = require('buttercms')("your_api_token");
butter.author.retrieve("jennifer-smith", {
"include": "recent_posts"
}).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.GetAuthor("jennifer-smith", params)
<?
use ButterCMS\ButterCMS;
$butterCms = new ButterCMS('your_api_token');
$butterCms->fetchAuthor('jennifer-smith', [
'include' => 'recent_posts'
]);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
client.authors.get('jennifer-smith',{
'include': 'recent_posts'
})
Author sally = butterClient.RetrieveAuthor(
"jennifer-smith",
includeRecentPosts: true
);
// Async
Author tylerAndPosts =
await butterClient.RetrieveAuthorAsync(
authorSlug: "jennifer-smith",
includeRecentPosts: true
);
import 'package:buttercms_dart/buttercms_dart.dart';
Butter butter = Butter('your_api_token');
butter.authors.retrieve("jennifer-smith", {
'include': 'recent_posts'
}).then((response) {
print(response);
});
// Unlike with fetching pages, it is not necessary
// to construct and pass a struct for authors for
// the Swift SDK to consume, as their schema doesn't change.
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY")
butter.getAuthor(
slug: "jennifer-smith",
parameters: [.include(value: "recent_posts")]
) // {Do something with result}
Example response
// Note that in contrast to above, `data` is a single
// object/dictionary.
{
"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.
| 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. |
A hash with a data property that contains an author object.
| Attribute | Description |
|---|---|
| slug string | Unique identifer |
| name string |
Example request
curl -X GET 'https://api.buttercms.com/v2/categories/?include=recent_posts&auth_token=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"
categories = ButterCMS::Category.all({
"include": "recent_posts"
})
var butter = require('buttercms')("your_api_token");
butter.category.list({
"include": "recent_posts"
})
.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);
import 'package:buttercms_dart/buttercms_dart.dart';
Butter butter = Butter('your_api_token');
butter.categories.list({
'include': "recent_posts"
}).then((response) {
print(response);
});
// https://github.com/ButterCMS/buttercms-java#categories
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
Map<String,String> queryParams = new HashMap<String,String>(){{
put("include","recent_posts");
...
}}
CategoriesResponse getCategories = butterClient.getCategories(queryParams);
// Unlike with fetching pages, it is not necessary
// to construct and pass a struct for categories for
// the Swift SDK to consume, as their schema doesn't change.
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY")
butter.getCategories(
parameters: [.include(value: "recent_posts")]
) // {Do something with result}
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.
| Argument | Description |
|---|---|
| include | Use include=recent_posts to return a category's recent posts. |
A hash with a data property that contains an array of categories.
Example request
curl -X GET 'https://api.buttercms.com/v2/categories/product-updates/?include=recent_posts&auth_token=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"
category = ButterCMS::Category.find("product-updates", {
"include": "recent_posts"
})
var butter = require('buttercms')("your_api_token");
butter.category.retrieve('product-updates', {
"include": "recent_posts"
}).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', [
'include' => 'recent_posts'
]);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
client.categories.get('product-updates', {
'include': 'recent_posts'
})
Category dotnetCategory = butterClient.RetrieveCategory("product-updates",
includeRecentPosts: true
);
//Async
Category fsharpCategoryWithPosts =
await butterClient.RetrieveCategoryAsync(categorySlug: "product-updates",
includeRecentPosts: true
);
import 'package:buttercms_dart/buttercms_dart.dart';
Butter butter = Butter('your_api_token');
butter.categories.retrieve("product-updates", {
'include': 'recent_posts'
}).then((response) {
print(response);
});
// https://github.com/ButterCMS/buttercms-java#categories
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
Map<String,String> queryParams = new HashMap<String,String>(){{
put("include","recent_posts");
}}
CategoryResponse getCategory = butterClient.getCategory("product-updates", queryParams);
// Unlike with fetching pages, it is not necessary
// to construct and pass a struct for categories for
// the Swift SDK to consume, as their schema doesn't change.
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY")
butter.getCategory(
slug: "test-category",
parameters: [.include(value: "recent_posts")]
) // {Do something with result}
Example response
{
"data": {
"name": "Product Updates",
"slug": "product-updates"
}
}
Retrieves the details of a category. Supply the unique slug of the category.
| Argument | Description |
|---|---|
| slug | The slug of the category to be retrieved. |
| include | Use include=recent_posts to return a category's recent posts. |
A hash with a data property that contains a catgory object.
| Attribute | Description |
|---|---|
| slug string | Unique identifer |
| name string |
Example request
curl -X GET 'https://api.buttercms.com/v2/tags/?include=recent_posts&auth_token=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"
tags = ButterCMS::Tag.all({"include": "recent_posts"})
var butter = require('buttercms')("your_api_token");
butter.tag.list({"include": "recent_posts"})
.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)
// https://github.com/ButterCMS/buttercms-java#categories
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
Map<String,String> queryParams = new HashMap<String,String>(){{
put("include","recent_posts");
...
}}
TagsResponse getTags = butterClient.getTags(queryParams);
<?
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(includeRecentPosts: true);
//Async
IEnumerable<Tag> tagsWithPosts =
await butterClient.ListTagsAsync(includeRecentPosts: true);
import 'package:buttercms_dart/buttercms_dart.dart';
Butter butter = Butter('your_api_token');
butter.tags.list({
'include': 'recent_posts'
}).then((response) {
print(response);
});
// Unlike with fetching pages, it is not necessary
// to construct and pass a struct for tags for
// the Swift SDK to consume, as their schema doesn't change.
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY")
butter.getTags(
parameters: [.include(value: "recent_posts")]
) // {Do something with result}
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.
| Argument | Description |
|---|---|
| include | Use include=recent_posts to return a tags's recent posts. |
A hash with a data property that contains an array of tags.
Example request
curl -X GET 'https://api.buttercms.com/v2/tags/product-updates/?include=recent_posts&auth_token=your_api_token'
require "buttercms-ruby"
ButterCMS::api_token = "your_api_token"
category = ButterCMS::Tag.find("product-updates", {
"include": "recent_posts"
})
// https://github.com/ButterCMS/buttercms-java#categories
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
Map<String,String> queryParams = new HashMap<String,String>(){{
put("include","recent_posts");
}}
TagResponse getTag = butterClient.getTag("product-updates",queryParams);
var butter = require('buttercms')("your_api_token");
butter.tag.retrieve('product-updates', {
"include": "recent_posts"
}).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', [
'include' => 'recent_posts'
]);
?>
from butter_cms import ButterCMS
client = ButterCMS('your_api_token')
client.tags.get('product-updates', {
'include': 'recent_posts'
})
Tag dotnetTag = butterClient.RetrieveTag(
"product-updates",
includeRecentPosts: true
);
//Async
Tag fsharpTagWithPosts =
await butterClient.RetrieveTagAsync(
tagSlug: "product-updates",
includeRecentPosts: true
);
import 'package:buttercms_dart/buttercms_dart.dart';
Butter butter = Butter('your_api_token');
butter.tags.retrieve("product-updates", {
"include": "recent_posts"
}).then((response) {
print(response);
});
// Unlike with fetching pages, it is not necessary
// to construct and pass a struct for categories for
// the Swift SDK to consume, as their schema doesn't change.
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "YOUR_API_KEY")
butter.getTag(
slug: "product-updates",
parameters: [.include(value: "recent_posts")]
) // {Do something with result}
Example response
{
"data": {
"name": "Product Updates",
"slug": "product-updates"
}
}
Retrieves the details of a tag. Supply the unique slug of the tag.
| Argument | Description |
|---|---|
| slug | The slug of the tag to be retrieved. |
| include | Use include=recent_posts to return a tag's recent posts. |
A hash with a data property that contains a tag object.
| Argument | Default | Description |
|---|---|---|
| category_slug | Filter posts by a category's slug. | |
| tag_slug | Filter posts by a tag's slug. |
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();
import 'package:buttercms_dart/buttercms_dart.dart';
Butter butter = Butter('your_api_token');
butter.feed.retrieve("jennifer-smith",
'include': "recent_posts"
}).then((response) {
print(response);
});
// https://github.com/ButterCMS/buttercms-java#categories
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
Document rssFeed = butterClient.getRSS();
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "Your_API_KEY")
butter.getFeeds(
name:"rss",
)
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.
A hash with a data property that contains an RSS feed.
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)
// https://github.com/ButterCMS/buttercms-java#categories
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
Document atomFeed = butterClient.getAtom();
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();
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "Your_API_KEY")
butter.getFeeds(
name:"atom",
)
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.
A hash with a data property that contains an Atom feed.
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)
// https://github.com/ButterCMS/buttercms-java#categories
import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
IButterCMSClient butterClient = new ButterCMSClient("your_api_token");
XmlDocument siteMap = butterClient.getSiteMap();
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();
import ButterCMSSDK
var butter = ButterCMSClient(apiKey: "Your_API_KEY")
butter.getFeeds(
name:"sitemap",
)
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.
A hash with a data property that contains an XML sitemap.
Page Webhook Body
POST http://yoururl.com/process_webbook
{
"data": {
"id": "example-page-slug",
"buttercms_id": 1234,
"page_type": "news",
"editor": "John Doe",
"name": "Example page",
"timestamp": "2022-02-14T18:11:09",
"locale": "en",
"status": "draft",
"updated": "2022-02-14T18:11:09.791061Z",
"published": null
},
"webhook": {
"event": "page.all",
"target": "http://yoururl.com/process_webbook"
}
}
Collection Item Webhook Body
POST http://yoururl.com/process_webbook
{
"data": {
"id": "your_collection",
"itemid": '/v2/content/?keys=your_collection[_id=1234]',
"label": "Your Collection Item",
"editor": "John Doe",
"name": "Example page",
"timestamp": "2022-02-14T18:11:09",
"locale": "en",
"status": "published"
},
"webhook": {
"event": "collectionitem.all",
"target": "http://yoururl.com/process_webbook"
}
}
Blog Post Webhook Body
POST http://yoururl.com/process_webbook
{
"data": {
"id": "example-blog-post-slug",
"_id": 1234
},
"webhook": {
"event": "post.all",
"target": "http://yoururl.com/process_webbook"
}
}
Get notified when content changes. Configure webhooks in your account settings to POST change notifications to your application.
When account has localization, webhook payload will have locale if event happened only for one locale i.e. page.published.
Note the data section will always contain id but may differ in other attributes based on the object.
| Event | Triggered when a... |
|---|---|
| post.all | blog post has any activity on it |
| post.published | blog post is published |
| post.draft | draft blog post is saved |
| post.delete | published blog post is unpublished or deleted |
| page.all | page has any activity on it |
| page.published | page is published |
| page.draft | draft page version is saved |
| page.delete | published page is deleted |
| page.unpublished | published page is unpublished |
| collectionitem.all | item has any activity on it |
| collectionitem.published | item is published |
| collectionitem.draft | draft item is saved |
| collectionitem.delete | published item is deleted |
| collectionitem.unpublish | published item is unpublished |
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: