Response structure All successful API responses return JSON with a data property containing the requested content. List endpoints also include a meta property with pagination information. Detail endpoints for single items return only the data property.
List response: { "meta" : { "count" : 25 , "next_page" : 3 , "previous_page" : 1 }, "data" : [ // Your content here ] }
Detail response: { "data" : { // Your content here } }
Included in list responses and blog post detail responses. Contains metadata about the response such as pagination information or navigation links:
Field Type Description countinteger Total number of items available next_pageinteger/null Next page number (null if last page) previous_pageinteger/null Previous page number (null if first page)
For offset-based pagination:
Field Type Description countinteger Total number of items available next_offsetinteger/null Next offset value previous_offsetinteger/null Previous offset value
The data object Contains the actual content. Structure varies by endpoint type:
List endpoints : Array of items or keyed objectDetail endpoints : Single item objectWrite operations : Success confirmation or created item
Content type responses Pages response Single Page Detail: { "data" : { "slug" : "homepage" , "name" : "Homepage" , "published" : "2024-01-15T10:30:00Z" , "updated" : "2024-01-20T14:45:00Z" , "scheduled" : null , "status" : "published" , "page_type" : null , "fields" : { "hero_title" : "Welcome to Our Site" , "hero_image" : "https://cdn.buttercms.com/abc123" , "body_content" : "<p>Welcome to our homepage...</p>" , "cta_button_text" : "Get Started" } } }
Page Type List: { "meta" : { "count" : 15 , "next_page" : 2 , "previous_page" : null }, "data" : [ { "slug" : "summer-sale" , "name" : "Summer Sale" , "published" : "2024-01-15T10:30:00Z" , "updated" : "2024-01-16T09:00:00Z" , "scheduled" : null , "status" : "published" , "page_type" : "landing-pages" , "fields" : { "title" : "Summer Sale 2024" , "description" : "..." } }, { "slug" : "winter-promo" , "name" : "Winter Promo" , "published" : "2024-01-10T08:00:00Z" , "updated" : "2024-01-11T11:00:00Z" , "scheduled" : null , "status" : "published" , "page_type" : "landing-pages" , "fields" : { "title" : "Winter Promotion" , "description" : "..." } } ] }
Collections response Collection List: { "meta" : { "count" : 25 , "next_page" : 3 , "previous_page" : 1 }, "data" : { "artists" : [ { "meta" : { "id" : 123 }, "name" : "The Beatles" , "genre" : "Rock" , "formed_year" : 1960 , "description" : "Legendary British rock band" }, { "meta" : { "id" : 124 }, "name" : "The Rolling Stones" , "genre" : "Rock" , "formed_year" : 1962 , "description" : "Iconic rock and roll band" } ] } }
Collection items include a nested meta object with the item’s numeric id, which is required for update and delete operations.
Blog Posts response Post List: { "meta" : { "count" : 50 , "next_page" : 2 , "previous_page" : null }, "data" : [ { "status" : "published" , "created" : "2024-01-15T10:30:00Z" , "updated" : "2024-01-20T14:45:00Z" , "published" : "2024-01-15T12:00:00Z" , "scheduled" : null , "title" : "Getting Started with ButterCMS" , "slug" : "getting-started-buttercms" , "body" : "<p>Welcome to ButterCMS...</p>" , "summary" : "Learn how to get started with ButterCMS" , "seo_title" : "Getting Started with ButterCMS | Tutorial" , "meta_description" : "A complete guide to getting started..." , "featured_image" : "https://cdn.buttercms.com/xyz789" , "featured_image_alt" : "ButterCMS dashboard screenshot" , "url" : "https://www.example.com/blog/getting-started-buttercms" , "author" : { "first_name" : "John" , "last_name" : "Doe" , "email" : "john@example.com" , "slug" : "john-doe" , "bio" : "Technical writer and CMS enthusiast." , "title" : "Developer Advocate" , "linkedin_url" : "https://www.linkedin.com/in/johndoe" , "facebook_url" : "https://www.facebook.com/johndoe" , "instagram_url" : "https://www.instagram.com/johndoe" , "pinterest_url" : "https://www.pinterest.com/johndoe" , "twitter_handle" : "johndoe" , "profile_image" : "https://cdn.buttercms.com/author123.jpg" }, "categories" : [ { "name" : "Tutorials" , "slug" : "tutorials" } ], "tags" : [ { "name" : "Getting Started" , "slug" : "getting-started" } ] } ] }
Single Post Detail: { "meta" : { "next_post" : { "slug" : "advanced-features" , "title" : "Advanced ButterCMS Features" , "featured_image" : "https://cdn.buttercms.com/next123.jpg" }, "previous_post" : { "slug" : "introduction" , "title" : "Introduction to Headless CMS" , "featured_image" : null } }, "data" : { "status" : "published" , "created" : "2024-01-15T10:30:00Z" , "updated" : "2024-01-20T14:45:00Z" , "published" : "2024-01-15T12:00:00Z" , "scheduled" : null , "slug" : "getting-started-buttercms" , "title" : "Getting Started with ButterCMS" , "body" : "<p>Full post content here...</p>" , // ... additional fields (same as list response) } }
Reference field responses Reference fields return different data based on the levels parameter:
Level 1 (URIs only) { "data" : { "meta" : { "id" : 123 }, "name" : "Technology" , "related_items" : [ "/v2/content/?keys=categories[_id=456]" ], "featured_page" : [ "/v2/pages/product-guides/tech-overview/" ] } }
Level 2+ (complete objects) { "data" : { "meta" : { "id" : 123 }, "name" : "Technology" , "related_items" : [ { "meta" : { "id" : 456 }, "name" : "Software" , "description" : "..." } ], "featured_page" : [ { "slug" : "tech-overview" , "fields" : { "title" : "Technology Guide" , "summary" : "..." }} ] } }
Media fields can return data in two formats based on the alt_media_text parameter:
When alt_media_text=0 (default):
{ "data" : { "title" : "Product Image" , "media" : "https://cdn.buttercms.com/abc123.jpg" } }
Object format with alt text When alt_media_text=1:
{ "data" : { "title" : "Product Image" , "media" : { "url" : "https://cdn.buttercms.com/abc123.jpg" , "alt" : "Product showcase image" } } }
Localized responses When requesting content in a specific locale using the locale query parameter (e.g., ?locale=de), the response returns the localized content for that locale. The response structure is the same as a standard response — there is no additional locale field in the response body:
{ "data" : { "slug" : "about-us" , "name" : "About Us" , "published" : "2024-01-15T10:30:00Z" , "updated" : "2024-01-20T14:45:00Z" , "scheduled" : null , "status" : "published" , "page_type" : null , "fields" : { "title" : "Über uns" , "description" : "Willkommen bei unserem Unternehmen..." } } }
GET requests Query parameters are passed in the URL:
GET /v2/posts/?auth_token=TOKEN & page = 1 & page_size = 10 & locale = en
POST/PUT/PATCH requests Data is sent as JSON in the request body:
POST /v2/pages/ Content-Type: application/json Authorization: Token YOUR_WRITE_TOKEN { "title" : "New Landing Page", "slug" : "new-landing-page", "page_type" : "landing-pages", "status" : "draft", "fields" : { "en" : { "hero_title" : "Welcome", "hero_subtitle" : "Get started today" } } }
Write operation responses Successful creation (202 Accepted) Write operations are processed asynchronously. The pending status indicates the request has been accepted and is being processed in the background.
Successful update (202 Accepted) Successful deletion (204 No Content) No response body is returned for successful deletions.
Use page and page_size parameters:
GET /v2/posts/?page= 2 & page_size = 10
Response includes:
{ "meta" : { "count" : 100 , "next_page" : 3 , "previous_page" : 1 } }
Use limit and offset parameters:
GET /v2/content/products/?limit= 10 & offset = 20
Response includes:
{ "meta" : { "count" : 100 , "next_offset" : 30 , "previous_offset" : 10 } }
Content-Type: application/json Authorization: Token your_api_token
Content-Type: application/json
Next steps
HTTP Status Codes Understand error responses
Rate Limits Learn about API limits
REST Endpoints View all available endpoints
