Request/response format

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 typically return only the data property. The single Blog Post detail endpoint is an exception and also returns a meta object with next/previous post navigation (see Blog Posts response below). List response:

{
  "meta": {
    "count": 25,
    "next_page": 3,
    "previous_page": 1
  },
  "data": [
    // Your content here
  ]
}

Detail response:

{
  "data": {
    // Your content here
  }
}

The `meta` object

Included in list responses and blog post detail responses. Contains metadata about the response such as pagination information or navigation links:

Field	Type	Description
`count`	integer	Total number of items available
`next_page`	integer/null	Next page number (null if last page)
`previous_page`	integer/null	Previous page number (null if first page)

For offset-based pagination:

Field	Type	Description
`count`	integer	Total number of items available
`next_offset`	integer/null	Next offset value
`previous_offset`	integer/null	Previous offset value

The `data` object

Contains the actual content. Structure varies by endpoint type:

List endpoints: Array of items or keyed object
Detail endpoints: Single item object
Write 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 field formats

Media fields can return data in two formats based on the alt_media_text parameter:

Default format (URL string)

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..."
    }
  }
}

Request formats

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)

{
  "status": "pending"
}

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)

{
  "status": "pending"
}

Successful deletion (204 No Content)

No response body is returned for successful deletions.

Pagination patterns

Page-based pagination

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
  }
}

Offset-based pagination

Pages and Blog Posts list endpoints also accept limit and offset (Collections only support page and page_size):

GET /v2/pages/products/?limit=10&offset=20

Response includes:

{
  "meta": {
    "count": 100,
    "next_offset": 30,
    "previous_offset": 10
  }
}

Content-type headers

Request headers

Content-Type: application/json
Authorization: Token your_api_token

Content-Type only applies to POST/PUT/PATCH requests that send a JSON body; GET requests don’t need it.

Response headers

Content-Type: application/json
X-Robots-Tag: noindex, nofollow
Surrogate-Key: ...
Surrogate-Control: stale-if-error=86400

Surrogate-Key and Surrogate-Control are Fastly cache-control headers used for purge-based invalidation; X-Robots-Tag keeps API responses out of search engine indexes.

Next steps

HTTP Status Codes

Understand error responses

Rate Limits

Learn about API limits

REST Endpoints

View all available endpoints

Overview

Read API

Write API

Webhooks API

Image API

Response structure

The `meta` object

The `data` object

Content type responses

Pages response

Collections response

Blog Posts response

Reference field responses

Level 1 (URIs only)

Level 2+ (complete objects)

Media field formats

Default format (URL string)

Object format with alt text

Localized responses

Request formats

GET requests

POST/PUT/PATCH requests

Write operation responses

Successful creation (202 Accepted)

Successful update (202 Accepted)

Successful deletion (204 No Content)

Content-type headers

Request headers

Response headers

Next steps

HTTP Status Codes

Rate Limits

REST Endpoints

​Response structure

​The meta object

​The data object

​Content type responses

​Pages response

​Collections response

​Blog Posts response

​Reference field responses

​Level 1 (URIs only)

​Level 2+ (complete objects)

​Media field formats

​Default format (URL string)

​Object format with alt text

​Localized responses

​Request formats

​GET requests

​POST/PUT/PATCH requests

​Write operation responses

​Successful creation (202 Accepted)

​Successful update (202 Accepted)

​Successful deletion (204 No Content)

​Pagination patterns

​Page-based pagination

​Offset-based pagination

​Content-type headers

​Request headers

​Response headers

​Next steps

HTTP Status Codes

Rate Limits

REST Endpoints

Response structure

The `meta` object

The `data` object

Content type responses

Pages response

Collections response

Blog Posts response

Reference field responses

Level 1 (URIs only)

Level 2+ (complete objects)

Media field formats

Default format (URL string)

Object format with alt text

Localized responses

Request formats

GET requests

POST/PUT/PATCH requests

Write operation responses

Successful creation (202 Accepted)

Successful update (202 Accepted)

Successful deletion (204 No Content)

Pagination patterns

Page-based pagination

Offset-based pagination

Content-type headers

Request headers

Response headers

Next steps