> ## 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 (PUT) > Update an existing page via the Write API using PUT. Behaves exactly like PATCH: a partial update of the fields you send. 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` keys in the request body are ignored: the update serializer does not declare either field, so no error is raised and the page's existing title/slug are left unchanged. **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 put /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. **Authentication**: pass your write-enabled token via the `Authorization: Token ` header. A `?auth_token=` query parameter also works (the same mechanism as the Read API), but avoid it for write requests: a write token is higher-privilege and a URL is more likely to be logged or leaked than a header. 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}/: put: tags: - Pages summary: Update Page via Write API (PUT) 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` keys in the request body are ignored: the update serializer does not declare either field, so no error is raised and the page's existing title/slug are left unchanged. **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: updatePagePut 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: url: >- https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg alt: A leashed dog on a park trail - 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 - Providing invalid field values Error explanations are returned in a JSON object keyed by field name. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' examples: missing_required_field: summary: Missing required field value: headline: - This field is required. invalid_status: summary: Invalid status value: status: - Valid status values are 'draft' and 'published' 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** Either the token used is read-only (write access is a paid add-on), or the `*` wildcard page type matched more than one page with the same slug. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: write_permission: summary: Token does not allow writes value: detail: Your API token does not allow writes. duplicate_slug: summary: Multiple pages matched the wildcard page type value: detail: >- Multiple pages found with slug "faq". Either pass in page_type or ensure only one page has this slug. '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 or page type not found value: detail: 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, or objects `{"url": "https://...", "alt": "Descriptive alt text"}` to also set alt text. A plain URL string replaces any existing alt text. - **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: description: >- Response for validation errors (400 Bad Request). The shape varies by endpoint and check: a field-keyed object whose values are arrays of messages or single message strings, a bare array of messages, or a general `error` message. anyOf: - type: object description: >- Field-specific validation errors (used by Pages, Blog Posts, and Collections). Values are usually arrays of messages; some checks return a single string. additionalProperties: oneOf: - type: array items: type: string - type: string example: title: - This field is required. slug: You must specify a page slug. - type: array description: >- Bare array of messages (used by some Collection item validation errors) items: type: string example: - '''field1_key'' is required' - 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 - Missing or Invalid API Token** No token was sent, or the token isn't valid. A valid Read API token on a write request returns `403` with `Your API token does not allow writes.` instead. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_token: summary: Missing API token value: detail: Authentication credentials were not provided. invalid_token: summary: Invalid API token value: detail: Invalid token. 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. Write API access is a paid add-on for Advanced and Professional plans, enabled from the Billing page of your account. It isn't offered on Basic plans. Set the `Authorization` header to `Token your_write_api_token`. The `?auth_token=` query parameter also works for write requests, but a header is safer because URLs are more likely to be logged. Example: `Authorization: Token abc123def456` Your write-enabled token should never be used anywhere it would be exposed, e.g. in client-side JavaScript. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.