Skip to main content
POST
/
pages
curl --request POST \
  --url https://api.buttercms.com/v2/pages/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Frequently Asked Questions",
  "slug": "faq",
  "page_type": "questions",
  "status": "draft",
  "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"
      }
    ]
  }
}
'
{
  "status": "pending"
}
Create a new page using the ButterCMS Write API with support for multiple locales and automatic media uploads. This endpoint allows you to programmatically generate content that follows your predefined page type structure. Page Type Requirement: The page type schema must already exist in your ButterCMS account before creating pages. Page types define the structure and field requirements for your content. You cannot create new Page Types through the API - they must be configured through the dashboard first. Field Requirements: When creating a page, all field keys defined in your page type schema must be included in the request, even if they’re marked as optional in your schema. For optional fields that you don’t want to populate, provide empty strings (e.g., "hero_image": ""). This ensures your content structure remains consistent. Locale Formats: Define all page content inside of a single fields object for accounts that do not have localization set up. For accounts with localization, all page content for each individual language should be defined inside of an object whose key is the locale slug. Nest these objects inside of the fields object. The locale codes must match those configured in your account. Media Upload: If Media is the field_type for a chosen field, any URL can be provided as the field’s value. The media corresponding to this URL will be automatically downloaded and uploaded to your ButterCMS media library. This ensures your media is hosted reliably and integrates with ButterCMS’s CDN for optimal performance. Publication & Scheduling: Pages are created as draft by default. You can set status=published to publish immediately. Scheduling future publication is not supported via the Write API.

Authorizations

​
Authorization
string
header
required

Write-enabled API token required for 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. Chat or email support@buttercms.com to get yours.

Set the Authorization header to Token your_write_api_token.

Example: Authorization: Token abc123def456

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

Query Parameters

​
locale
string

Set to the API slug of a pre-configured locale (e.g., 'en' or 'fr').

Usage: Only applicable when using the single-locale request format (WITHOUT Locales format). If you are using the single-locale format to create only a single locale's version of a page, you must specify the locale via this query param, e.g., ?locale=en.

Not applicable when using the multi-locale format (WITH Locales format), as locale codes are specified within the request body under the fields object.

When omitted and using single-locale format, defaults to your organization's default locale.

Example:

"en"

Body

application/json

Page data in either single-locale or multi-locale format.

Request Body Formats:

  • WITHOUT Locales or Single Locale: If you don't have locales, or if you are only creating a single locale's version of a page, format your request body as a JSON object where fields is an object with each property representing a content field. Note: if creating only a single locale's version, you must specify the locale via query param, e.g., ?locale=en.
  • WITH Locales (Multi-Locale): The multi-locale format can be used to create one or more locales of a page at the same time. In this format, the fields object has an extra level and must be first mapped to the locale code. The locale codes must already be configured in your account; however, you can pick and choose which locales to create.

Flexible request schema for creating pages - supports both single-locale and multi-locale formats.

System automatically detects the format based on the structure of the fields object:

Single-Locale Format: fields contains field names as keys (e.g., headline, questions) Multi-Locale Format: fields contains locale codes as keys (e.g., en, es, fr)

Request Body Formats:

  • WITHOUT Locales or Single Locale: Use when you don't have locales, or when creating a single locale's version of a page. Format fields as a direct object with field names as keys. Note: if creating only a single locale's version, you must specify the locale via query param, e.g., ?locale=en.
  • WITH Locales (Multi-Locale): Use to create one or more locales of a page at the same time. Format fields with locale codes as top-level keys. The locale codes must already be configured in your account.
​
title
string
required

The title of the page.

Example:

"Frequently Asked Questions"

​
slug
string
required

The slug of the page.

Example:

"faq"

​
page_type
string
required

The key of the page type. The page type must already exist in your Butter account.

Example:

"questions"

​
fields
object
required

Flexible Fields Object - Two Supported Formats

  • Format 1: Single-locale/direct fields

    • fields contains field names as keys (e.g., headline, questions).

  • Format 2: Multi-locale

    • fields contains locale codes as keys (e.g., en, es, fr).

  • Detection: The system automatically detects the format based on whether the top-level keys are locale codes or field names.

  • Field requirements

    • All field keys are required for each locale/format you include. If a field is not required in your page type, set it to an empty string.
    • Repeater fields must be JSON arrays of the repeater groups. For optional repeater fields, use an empty array ([]).
    • Providing a remote URL in any Media field triggers automatic download and upload to your ButterCMS media library.

  • Examples: See the Examples section for sample request bodies.

​
status
enum<string>
default:draft

Status of the page. Can be 'draft' or 'published'. Defaults to 'draft'. Note that you cannot create a page with a status of 'scheduled' via the write API.

Available options:
draft,
published
Example:

"draft"

Response

Accepted - Page creation started successfully

The request has been accepted for processing. Full page creation occurs asynchronously, meaning the successfully created page may not show immediately. Pages are validated prior to returning this response, but it is possible that page creation may fail after returning a 202 response. If this happens, please contact support.

​
status
enum<string>

Indicates that the page creation request has been accepted and is being processed asynchronously

Available options:
pending
Example:

"pending"