# Create Page via Write API

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.

Endpoint: POST /pages/
Version: 2.0.0
Security: writeTokenAuth

## 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 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.
    Example: "en"

## Request fields (application/json):

  - `title` (string, required)
    The title of the page.
    Example: "Frequently Asked Questions"

  - `slug` (string, required)
    The slug of the page.
    Example: "faq"

  - `status` (string)
    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.
    Enum: "draft", "published"

  - `page_type` (string, required)
    The key of the page type. The page type must already exist in your Butter account.
    Example: "questions"

  - `fields` (object, required)
    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.

## Response 202 fields (application/json):

  - `status` (string)
    Indicates that the page creation request has been accepted and is being processed asynchronously
    Enum: "pending"

## Response 401 fields (application/json):

  - `detail` (string)
    Error message describing what went wrong
    Example: "Authentication credentials were not provided"

## Response 403 fields (application/json):

  - `error` (string)
    Error message when subscription plan limits are exceeded
    Example: "Page creation limit is over"