Skip to main content
PATCH
/
pages
/
{page_type}
/
{page_slug}
curl --request PATCH \
  --url https://api.buttercms.com/v2/pages/{page_type}/{page_slug}/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
      }
    ]
  }
}
'
{
  "status": "pending"
}
Update existing pages using PATCH requests with support for partial updates and multi-locale content. This endpoint provides flexible page modification capabilities while preserving unchanged content. PUT Support: PUT requests are supported for backwards compatibility. PATCH is the recommended method going forward. Both methods perform partial updates — only the fields you include in the request body will be modified. Page Type Flexibility: Use * to update pages across all page types when you know the slug but not the specific type, or specify the particular page type slug for optimized queries. Partial Update Behavior: Include only the fields you want to modify in your request body. All other fields will retain their current values, making this ideal for targeted content updates without affecting the entire page structure. Note: PUT behaves like PATCH (partial update) for Pages. Use either method to perform partial updates. Locale Handling: For single-locale updates, use the direct field format. For multi-locale organizations, nest your field changes under the appropriate locale codes. You can update specific locales without affecting others. Status Control: Control page visibility by setting status to “draft” (keeps the page unpublished) or “published” (makes changes live immediately). Draft status is useful for staging content changes. Immutable Fields: Page title and slug cannot be modified via PATCH requests to maintain URL consistency and prevent broken links. These core identifiers must remain stable after page creation. Repeater Field Behavior: When updating repeater fields, you must include the complete array contents in your request. Partial repeater updates are not supported - the entire repeater will be replaced with your provided data. Scheduling Limitation: Page scheduling is not available through the Write API. Any scheduled parameters in your request will be ignored, allowing you to safely update pages that are currently scheduled without affecting their publication timing.

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.

Path Parameters

​
page_type
string
required

The type of page to update.

  • Use * to search across all page types
  • Use a specific page type slug to limit search to that type
​
page_slug
string
required

The slug of the page to update.

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 update only a single locale's version of a page, you can 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, updates the organization's default locale.

Example:

"en"

Body

application/json

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

Partial Updates: Unlike creating pages, you only need to specify the fields you want to update. You don't need to include all fields.

Format Flexibility: The API accepts data wrapped in a top-level "data" key (Read API format). For example: {"data": {"status": "draft", "fields": {...}}} will be automatically unwrapped. You can use either title or name - both are accepted and name will be automatically converted to title.

Request Body Formats:

  • WITHOUT Locales or Single Locale: One format mirrors the read API response and can be used for pages without locales or updating a single, specified locale.
  • WITH Locales (Multi-Locale): The second format can be used for updating multiple locales at once. In this format, the fields object has an extra level and must be first mapped to the locale code to use.

Flexible request schema for updating 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)

Partial Updates: You only need to specify the fields you want to update. Note: Pages accept both PATCH and PUT; PUT behaves like PATCH (partial update).

Immutable Fields: Cannot update title or slug via PATCH.

Field Name Flexibility: You can use either title or name in the request - both are accepted and name will be automatically converted to title.

​
title
string

The title of the page. Note: This field cannot be updated via PATCH - it's included here for documentation completeness only.

Alternative: You can also use name which will be automatically converted to title.

​
status
enum<string>

Status of the update. Can be 'draft' or 'published'. Defaults to 'draft'. Setting to 'published' will make your update live immediately.

Note: If scheduled timestamp or status is passed, these fields will be ignored to allow updating already scheduled pages.

Available options:
draft,
published
Example:

"draft"

​
fields
object

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.

  • Partial update behavior

    • Only specify the fields you want to update; omitted fields remain unchanged.
    • Repeater fields must be replaced in full; delta changes are not supported. If you need to clear a repeater, provide an empty array ([]).
    • Images and media can be updated by providing remote URLs.

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

Response

Accepted - Page update started successfully

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

Warning Messages: If you include fields that cannot be updated (like scheduled timestamp or scheduled status), the API will return warning messages explaining which fields were ignored.

​
status
enum<string>

Indicates that the collection item update request has been accepted and is being processed asynchronously

Available options:
pending
Example:

"pending"