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

# Pages: key concepts

> Essential concepts for working with ButterCMS Pages, including unique features, publication states, and architectural patterns.

## Overview

Pages serve as your primary content structure for individual web pages, articles, landing pages, or any content with a URL. Pages provide advanced functionality that distinguishes them from Collections and Blog Posts.

**Unique Page capabilities**

* **Components**: Structured content blocks including individual components and component picker fields for dynamic layouts
* **Repeaters**: Fields that allow multiple instances of the same field structure
* **Form integrations**: Direct integration with third-party form services
* **Slug-based retrieval**: Human-readable URL identification system
* **True versioning**: Draft versions can be created over existing published content

## Page types

Pages can be structured as **Single Pages** (unique pages like Homepage) or **Page Types** (templated pages that share the same field structure). Page Types enable you to create multiple pages with consistent schemas while maintaining individual content.

| Type            | Description                             | Example                      |
| --------------- | --------------------------------------- | ---------------------------- |
| **Single Page** | A one-off page with a unique schema     | Homepage, Contact Us         |
| **Page Type**   | A template shared across multiple pages | Landing pages, Product pages |

Pages excel at complex content scenarios requiring flexible layouts, dynamic components, and sophisticated reference relationships.

## Publication states

Pages support a three-state lifecycle:

| State         | Description                                 | API Access                |
| ------------- | ------------------------------------------- | ------------------------- |
| **Draft**     | Content accessible only via preview mode    | `?preview=1`              |
| **Published** | Live content served through global CDN      | Standard endpoints        |
| **Scheduled** | Automatically published at a specified time | Preview until publication |

**Versioning capability**: Pages uniquely support creating new draft versions over existing published content, allowing continuous iteration without taking existing pages offline.

## Preview

Preview lets content teams review draft pages in full website context before publishing.

**Workflow**:

1. Configure preview URLs for Page Types in your ButterCMS dashboard
2. Content creators click **Preview** and are redirected to your preview URL with `preview=1`
3. Your application detects the parameter and includes it in API calls
4. Draft page content is returned and displayed in complete website context

```bash theme={null}
GET /v2/pages/landing-pages/summer-sale/?auth_token=TOKEN&preview=1
```

Consider implementing environment-based configuration that automatically includes `preview=1` in development and staging environments.

## Reference architecture

Pages participate in ButterCMS's reference system, enabling content relationships and reusable data patterns.

### Page-to-page references

Reference fields pointing to other pages use **slugs** as identifiers:

```json theme={null}
{
  "related_page": "example-page-slug",
  "related_pages": ["page-1-slug", "page-2-slug"]
}
```

### Page-to-collection references

Pages can reference Collection items using numeric **IDs**:

```json theme={null}
{
  "category": 123,
  "authors": [456, 789],
  "featured_products": [101, 102, 103]
}
```

### Managing references

**Adding references**: Provide the appropriate identifier (slug for pages, ID for collections) in Write API requests.

**Removing references** — use the appropriate empty value:

| Relationship | Empty value                   |
| ------------ | ----------------------------- |
| One-to-one   | `""` (empty string) or `null` |
| One-to-many  | `[]` (empty array) or `null`  |

**PATCH vs PUT behavior**:

* **PATCH**: Omitted reference fields remain unchanged
* **PUT**: For Pages, PUT behaves like PATCH (partial update)

## Reference levels

The `levels` parameter controls how deeply reference fields are resolved in API responses.

| Value         | Behavior                                                         |
| ------------- | ---------------------------------------------------------------- |
| `1`           | Reference fields return API URIs only (minimal data transfer)    |
| `2` (default) | Reference fields return complete objects                         |
| `3–5`         | Deeper resolution for nested reference chains                    |
| `5` (max)     | Returns URIs for any remaining references beyond specified depth |

**Performance guidelines**:

* Use `levels=1` for page listings or navigation menus
* Use `levels=2` (default) for standard page display
* Use `levels=3–5` for pages with complex nested references
* Note: responses are capped at 10MB — reduce `levels` if approaching this limit

**Level 1 response** (URIs only):

```json theme={null}
{
  "data": {
    "fields": {
      "related_pages": ["/v2/pages/example-page-type/example-page-slug/"],
      "category": ["/v2/content/?keys=categories[_id=1234]"]
    }
  }
}
```

**Level 2+ response** (complete objects):

```json theme={null}
{
  "data": {
    "fields": {
      "related_pages": [
        {
          "slug": "example-page-slug",
          "fields": { "title": "Example Page", "summary": "..." }
        }
      ],
      "category": [
        { "meta": { "id": 1234 }, "name": "Technology", "description": "..." }
      ]
    }
  }
}
```

## Localization

Pages can maintain separate content versions for each configured locale.

**Account configuration**: Locale support must be configured in your ButterCMS account settings before creating multi-language pages.

<Warning>
  Once locales are added to an account, they cannot be removed. Plan your internationalization strategy carefully before configuration.
</Warning>

**API integration**:

```bash theme={null}
# Retrieve a page in Spanish
GET /v2/pages/landing-pages/summer-sale/?auth_token=TOKEN&locale=es

# Omit locale to use your organization's default
GET /v2/pages/landing-pages/summer-sale/?auth_token=TOKEN
```

**Field formats**:

* **Single-language**: Direct `fields` object (no localization configured)
* **Multi-language**: Fields nested under locale codes (e.g., `"en"`, `"es"`)

Reference fields work seamlessly with localization, allowing different reference relationships per language version.

## Next steps

<CardGroup cols={2}>
  <Card title="Pages — components" icon="layer-group" href="./pages-components">
    How to work with individual components and component picker fields
  </Card>

  <Card title="Read API — Pages" icon="book-open" href="../../api-reference/pages/get-multiple-pages">
    Fetch pages via the Read API
  </Card>

  <Card title="Write API — Pages" icon="pen" href="../../api-reference/pages/create-page-via-write-api">
    Create and update pages via the Write API
  </Card>

  <Card title="Collections — key concepts" icon="table" href="./collections-key-concepts">
    Learn how Collections work
  </Card>
</CardGroup>