Skip to main content

​
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.
TypeDescriptionExample
Single PageA one-off page with a unique schemaHomepage, Contact Us
Page TypeA template shared across multiple pagesLanding 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:
StateDescriptionAPI Access
DraftContent accessible only via preview mode?preview=1
PublishedLive content served through global CDNStandard endpoints
ScheduledAutomatically published at a specified timePreview 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:
RelationshipEmpty 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.
ValueBehavior
1Reference fields return API URIs only (minimal data transfer)
2 (default)Reference fields return complete objects
3–5Deeper 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