> ## Documentation Index > Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Update Page via Write API > Update an existing page via PATCH request with support for locale handling and status control. 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. ## OpenAPI ````yaml /api/openapi/write_api.yaml patch /pages/{page_type}/{page_slug}/ openapi: 3.1.0 info: title: ButterCMS Write API version: 2.0.0 description: > Write endpoints for the ButterCMS API — create, update, and delete Pages, Collections, and Blog Posts. contact: email: support@buttercms.com license: name: ButterCMS Terms of Service url: https://buttercms.com/terms/ servers: - url: https://api.buttercms.com/v2 description: ButterCMS API v2 security: - writeTokenAuth: [] tags: - name: Pages description: > Create new pages using ButterCMS Write API. Programmatically create content to enable powerful use cases and scale your content faster. Note: For Pages, PUT behaves like PATCH (partial update). Use either method to perform partial updates. - name: Collections description: > Create, update, and delete Collection items using ButterCMS Write API. Collections are user-defined content structures with completely customizable field schemas. - name: Blog posts description: > Create, update, and delete blog posts using ButterCMS Write API. Blog posts support rich content including HTML body, categories, tags, featured images, and SEO metadata. paths: /pages/{page_type}/{page_slug}/: patch: tags: - Pages summary: Update Page via Write API description: > 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. operationId: updatePage parameters: - name: page_type in: path description: | 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 required: true schema: type: string examples: wildcard: value: '*' description: Update page across all page types specific_type: value: news description: Update page within news page type only - name: page_slug in: path description: | The slug of the page to update. required: true schema: type: string example: faq - name: locale in: query description: > 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. required: false schema: type: string example: en examples: english: value: en description: English locale spanish: value: es description: Spanish locale french: value: fr description: French locale requestBody: required: true description: > 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. content: application/json: schema: $ref: '#/components/schemas/UpdatePageRequest' examples: without_locales: summary: Update Page WITHOUT Locales or with a Single Locale description: > Example of updating a page without locale support or for a single locale. Note: You only need to specify the fields you want to update, not all fields. value: 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 with_locales: summary: Update Page WITH Locales description: > Example of updating a page with multiple locales at the same time. Note: You only need to specify the fields you want to update for each locale. value: status: draft fields: en: 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 responses: '202': description: > **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. content: application/json: schema: $ref: '#/components/schemas/UpdateSuccessResponse' examples: basic_success: summary: Standard successful update value: status: pending success_with_warnings: summary: Successful update with ignored fields value: status: pending 'warning: scheduled field': >- Scheduled timestamps cannot be created or altered via write API. This field will be ignored. 'warning: status field': >- A page's status cannot be set as `scheduled` via write API at this time. This field will be ignored. '400': description: > **Bad Request - Validation Error** Your data did not pass the initial validation stage. This may happen if you are: - Missing a required field for the specific page type - Providing a remote URL for a media field that returns a 404 - Trying to update immutable fields (title, slug) - Providing invalid field values Error explanations will be returned in a JSON array. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' examples: missing_required_field: summary: Missing required field value: headline: - This field is required for this page type. invalid_status: summary: Invalid status value: status: - Valid status values are 'draft' and 'published' immutable_field_attempt: summary: Attempted to update immutable field value: title: - Page title cannot be updated via PATCH. locale_validation_error: summary: Locale validation error value: fields: - You must specify one or more locales from your account. '401': $ref: '#/components/responses/UnauthorizedWriteResponse' '403': description: | **Forbidden - Permission Denied** You don't have permission to update this page. This could be due to: - Page update limits exceeded - Insufficient permissions for the page type - Organization-level restrictions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Permission denied '404': description: > **Not Found - Page Does Not Exist** The requested page doesn't exist, or you don't have access to it. This could be because: - The page slug doesn't exist - The page type doesn't exist - The page exists but not in the specified page type content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: page_not_found: summary: Page not found value: detail: Page not found. page_type_not_found: summary: Page type not found value: detail: Page type not found. security: - writeTokenAuth: [] components: schemas: UpdatePageRequest: type: object description: > **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`. properties: title: type: string description: > 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: type: string enum: - draft - published description: > 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. example: draft fields: type: object description: > **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. UpdateSuccessResponse: type: object properties: status: type: string enum: - pending description: >- Indicates that the collection item update request has been accepted and is being processed asynchronously example: pending example: status: pending ValidationErrorResponse: type: object description: >- Response for validation errors (400 Bad Request) - supports both field-specific errors and general error messages oneOf: - type: object description: >- Field-specific validation errors (used by Pages, Blog Posts, and Collections) additionalProperties: type: array items: type: string example: title: - You must specify a page title. slug: - You must specify a page slug. - type: object description: General error message (used for organization limits, etc.) properties: error: type: string description: Error message example: error: >- Cannot create a new Collection Item. Collection Item Limit Reached. ErrorResponse: type: object properties: detail: type: string description: Error message describing what went wrong example: Authentication credentials were not provided responses: UnauthorizedWriteResponse: description: > **Unauthorized - Invalid or Missing Write API Token** No valid write API key provided. The API token you use for reading from the ButterCMS API will not allow you to create content. You need a different write-enabled token. Contact support@buttercms.com to get yours. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Authentication credentials were not provided securitySchemes: writeTokenAuth: type: apiKey in: header name: Authorization description: > 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. ````