# Pages - Write

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.


## Create Page via Write API

 - [POST /pages/](https://api.docs.buttercms.com/pages-write/createpage.md): 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.

## Update Page via Write API

 - [PATCH /pages/{page_type}/{page_slug}/](https://api.docs.buttercms.com/pages-write/updatepage.md): 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.

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.

## Update Page via Write API (Full Update)

 - [PUT /pages/{page_type}/{page_slug}/](https://api.docs.buttercms.com/pages-write/updatepageput.md): Update existing pages using PUT requests. PUT behaves identically to PATCH (partial update), allowing you to update only the fields you specify while preserving unchanged content.

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.

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 PUT 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.