Request/response format

A summary of all ButterCMS API responses, including formats and status codes.

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

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": "[e-mail]",
        "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

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 headers

Request headers

Content-Type: application/json
Authorization: Token your_api_token

Response headers

Content-Type: application/json

Next steps

HTTP Status Codes

Understand error responses

Rate Limits

Learn about API limits

REST Endpoints

View all available endpoints