> ## 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. # Create Page via Write API > Create a new page via the Write API with support for multiple locales, media uploads, and draft status. 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. ## OpenAPI ````yaml /api/openapi/write_api.yaml post /pages/ 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/: post: tags: - Pages summary: Create Page via Write API description: > 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. operationId: createPage parameters: - 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 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. 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 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. content: application/json: schema: $ref: '#/components/schemas/CreatePageRequest' examples: without_locales: summary: Create Page WITHOUT Locales or with a Single Locale description: > Example of creating a page without locale support or for a single locale. If you don't have locales, or if you are only creating a single locale's version of a page, you can format your request body into a JSON object where `fields` is an object in which each property represents a content field with its key and value. Note: If you are using this format to create only a single locale's version of a page, you must specify the locale via query param, e.g., `?locale=en`. value: title: Frequently Asked Questions slug: faq page_type: questions status: draft fields: headline: Frequently Asked Questions hero_image: '' body:

We love questions

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 with_locales: summary: Create Page WITH Locales description: > Example of creating a page with multiple locales at the same time. This is our multi-locale format, which 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 to use. The locale codes must already be configured in your account; however, you can pick and choose which locales to create. value: title: Frequently Asked Questions slug: faq page_type: questions status: draft fields: en: headline: Frequently Asked Questions body:

We love questions

questions: - question: Are dogs allowed? answer: Leashed dogs are allowed. picture: >- https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg es: headline: Preguntas frecuentes body:

Nos encantan las preguntas

questions: - question: Se admiten perros? answer: Se permiten perros con correa. picture: >- https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg responses: '202': description: > **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. content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' example: status: pending '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 - Missing a field that's required in your page type - Providing a remote URL for a media field that returns a 404 Error explanations will be returned in a JSON array. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' examples: missing_page_type: summary: Missing page type value: page_type: - You must specify a page type. invalid_page_type: summary: Invalid page type value: page_type: - The write API cannot be used to create single pages. missing_title: summary: Missing title value: title: - You must specify a page title. missing_slug: summary: Missing slug value: slug: - You must specify a page slug. slug_already_exists: summary: Slug already exists value: slug: - A page with slug 'faq' already exists. invalid_status: summary: Invalid status value: status: - Valid status values are 'draft' and 'published' scheduling_not_supported: summary: Scheduling not supported value: scheduled: - >- Scheduling a page during page creation is not supported by the write API at this time. 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 - Page Creation Limit Exceeded** The organization has exceeded its page creation limit. This can happen when you've reached the maximum number of pages allowed for your plan. content: application/json: schema: $ref: '#/components/schemas/LimitErrorResponse' example: error: Page creation limit is over security: - writeTokenAuth: [] components: schemas: CreatePageRequest: type: object required: - title - slug - page_type - fields description: > **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. properties: title: type: string description: The title of the page. example: Frequently Asked Questions slug: type: string description: The slug of the page. example: faq status: type: string enum: - draft - published default: draft description: > 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. example: draft page_type: type: string description: >- The key of the page type. The page type must already exist in your Butter account. example: questions 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. - **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. SuccessResponse: type: object properties: status: type: string enum: - pending description: >- Indicates that the page creation request has been accepted and is being processed asynchronously example: 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. LimitErrorResponse: type: object properties: error: type: string description: Error message when subscription plan limits are exceeded example: Page creation limit is over 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. ````