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

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:

{
  "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:

{
  "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):

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

Level 2+ response (complete objects):

{
  "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.

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

API integration:

# 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

Pages — components

How to work with individual components and component picker fields

Read API — Pages

Fetch pages via the Read API

Write API — Pages

Create and update pages via the Write API

Collections — key concepts

Learn how Collections work