openapi: 3.1.0
info:
  title: ButterCMS API
  version: 2.0.0
  description: >
    This OpenAPI specification covers the complete ButterCMS API, including read
    and write operations for Pages, Blog Posts, Collections, and more.


    ### New Documentation Version

    This is a new version of our API documentation built with OpenAPI standards.
    If you encounter any issues, inaccuracies, or have suggestions for
    improvement, please report them to
    [support@buttercms.com](mailto:support@buttercms.com).

    ## API Overview

    The ButterCMS API is organized around REST principles with predictable,
    resource-oriented URLs and uses HTTP response codes to indicate API errors.
    JSON is returned by all API responses, including errors.


    Our API provides comprehensive content management capabilities through both
    read and write operations. Content is served through a global CDN with 150+
    edge locations, ensuring fast delivery worldwide.

    ---

    The API supports creating, updating, and deleting items of three main
    content types:


    **Pages**: Fully customizable, reusable schemas that are supercharged with
    features like structured local and global components, form integrations, and
    repeaters. These can be individually fetched via a slug and are ideal for
    complex web content requiring flexible layouts and advanced functionality.


    **Collections**: Lighter-weight, customizable, reusable schemas for tables
    of data that are fetched via ID. Perfect for structured content like
    categories, team members, or product catalogs that primarily serve as
    reference data.


    **Blog Posts**: Built-in content type from our blog engine, which comes
    out-of-the-box with categorization, tagging, predefined SEO, and authors.
    Designed for chronological content with standardized blog functionality.

    ---

    Authentication is handled through token-based access; read operations can
    use a query parameter (`auth_token`) while write operations require
    header-based authentication for enhanced security.
  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
tags:
  - name: Product Architecture & Integration
    description: >
      ButterCMS API architecture and performance characteristics for developers
      integrating headless CMS functionality.


      ## Overview


      **Content Types**


      The ButterCMS API supports creating, updating, and deleting items of three
      main content types:


      **Pages**


      Fully customizable, reusable schemas that are supercharged with features
      like structured local and global components, form integrations, and
      repeaters. These can be individually fetched via a slug and are ideal for
      complex web content requiring flexible layouts and advanced functionality.
      Pages can be either Single Pages (unique pages like Homepage) or Page
      Types (templated pages like blog posts or product pages).


      **Collections**


      Lighter-weight, customizable, reusable schemas for tables of data that are
      fetched via ID. Perfect for structured content like categories, team
      members, or product catalogs that primarily serve as reference data.
      Collections are optimized for simpler data structures and faster querying,
      making them ideal for content that needs to be referenced by Pages or
      queried directly from the API.


      **Blog Posts**


      Built-in content type from our blog engine, which comes out-of-the-box
      with categorization, tagging, predefined SEO, and authors. Designed for
      chronological content with standardized blog functionality and includes
      features like automated RSS feeds and WordPress import capabilities.


      ---


      **API Architecture**


      ButterCMS provides a REST API that serves content through a globally
      distributed infrastructure. Content created through the dashboard or Write
      API is immediately available via read endpoints with automatic global
      distribution for optimized delivery.


      **Content Types**


      The API serves three primary content types: Pages (individual web
      content), Collections (structured data tables), and Blog Posts
      (chronological content with built-in categorization and authoring
      features).


      ```

      ┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐

      │     Pages       │◄────▶│   Collections   │◄────▶│   Blog Posts    │

      │                 │      │                 │      │                 │

      │ • Single Pages  │      │ • Categories    │      │ • Authors       │

      │ • Page Types    │      │ • Products      │      │ • Categories    │

      │                 │      │ • Team Members  │      │ • Tags          │

      └─────────────────┘      └─────────────────┘      └─────────────────┘
               │                         │                         │
               └─────────────────────────┼─────────────────────────┘
                                         │
                          Reference Fields (slugs/IDs)
                          One-to-One or One-to-Many
      ```


      **Publication States**


      Content can exist as draft (accessible via preview), published (live via
      API endpoints), or scheduled (automatic publication). State changes
      trigger system-wide operations including cache invalidation, webhook
      notifications, and reference resolution across related content. Note:
      Pages support true three-state lifecycle with versioned drafts and
      scheduling; Blog posts have simplified state management without
      draft-over-published versioning.


      ```

      ┌─────────────┐    Publish    ┌─────────────┐    Schedule  
      ┌─────────────┐

      │    Draft    │──────────────▶│  Published  │──────────────▶│  Scheduled 
      │

      │             │               │             │               │            
      │

      │ • Preview   │◄──────────────┤ • Live API  │◄──────────────┤ • Auto-pub 
      │

      │ • Editable  │   Unpublish   │ • Cached    │   Update      │ • Queued   
      │

      └─────────────┘               └─────────────┘              
      └─────────────┘

      ```


      All content types follow a unified publication state system where content
      can be **draft** (accessible via preview), **published** (live via
      standard API endpoints), or **scheduled** (automatically published at
      specified times through dashboard configuration). Write API operations
      return immediate `202 Accepted` responses while background systems handle
      media processing, validation, webhook notifications, and cache
      invalidation.


      **Important Differences**


      Pages support true three-state lifecycle with versioned drafts and
      scheduling, allowing new draft versions over existing published content.
      Blog posts have simplified state management without draft-over-published
      versioning capabilities.


      ---


      **Request Flow**


      Read operations query cached content from edge locations, while write
      operations process through the primary API and trigger cache invalidation.
      All write operations return immediate responses (`202 Accepted`) and
      initiate background processes to handle resource-intensive tasks like
      media processing and webhook delivery.


      ```

      ┌─────────────┐    ┌──────────────┐    ┌─────────────┐    ┌──────────────┐

      │   Client    │───▶│ Global CDN   │───▶│ ButterCMS   │───▶│  Background  │

      │ Application │    │ (150+ edges) │    │    API      │    │  Processing  │

      └─────────────┘    └──────────────┘    └─────────────┘    └──────────────┘
                                 │                   │                   │
                         Cache Hit (50-100ms)   Cache Miss        Media Upload
                          ┌──────────────┐      (200-500ms)        Validation
                          │   Cached     │                         Webhooks
                          │   Response   │                         Cache Refresh
                          └──────────────┘
      ```


      **Authentication**


      Read operations use query parameter authentication (`auth_token`), while
      write operations require header-based token authentication. This
      separation allows for secure content management while enabling efficient
      public content delivery.


      ---


      ## Performance and Integration


      **Performance and Caching**


      Content delivery operates through a global CDN with 150+ edge locations.
      Read operations are cached for 20 days at edge locations by default,
      providing sub-100ms response times for cached content worldwide.


      **Cache Behavior**


      Initial requests fetch content from the API and populate edge caches
      (~200-500ms). Subsequent requests serve from the nearest location
      (~50-100ms). Content updates automatically invalidate relevant cache
      entries globally, including all content that references the changed
      content.


      **Reference Serialization Performance**


      When cached content is unavailable, the API serializes both the requested
      content and all content referenced by the requested content at the depth
      specified by the `levels` parameter. For list endpoints, this can create
      substantial serialization work—requesting 100 pages with references may
      require serializing 100+ individual objects plus their references. Use
      `levels=1` for list operations to minimize this overhead.


      ```

      List Request (levels=2):

      ┌─────────────┐

      │ 100 Pages   │ ──────┐

      └─────────────┘       │
                            ▼
                  ┌─────────────────────┐
                  │ Serialization Load  │
                  │                     │
                  │ Page 1 + refs (3)   │ ──┐
                  │ Page 2 + refs (5)   │   │
                  │ Page 3 + refs (2)   │   │ Exponential
                  │ ...                 │   │ Growth
                  │ Page 100 + refs (4) │   │
                  │                     │   │
                  │ Total: 400+ objects │ ◄─┘
                  └─────────────────────┘

      Solution: Use levels=1 for lists

      ```


      **Cache Invalidation**


      Content changes (create, update, delete, and status changes) trigger
      multi-layer cache invalidation including object cache, serialized response
      cache, and global CDN cache. Referenced content invalidation cascades
      automatically—when a referenced object changes, all content that
      references it also gets invalidated to maintain consistency.


      ```

      Content Update:

      ┌─────────────┐

      │   Page A    │ (updated)

      └─────────────┘
             │
             ▼ triggers invalidation
      ┌─────────────────────────────────────┐

      │          Cache Layers               │

      │ ┌─────────────────────────────────┐ │

      │ │ Object Cache        │ ✗ Invalid │ │

      │ ├─────────────────────┼───────────┤ │

      │ │ Response Cache      │ ✗ Invalid │ │

      │ ├─────────────────────┼───────────┤ │

      │ │ Global CDN Cache    │ ✗ Invalid │ │

      │ └─────────────────────────────────┘ │

      └─────────────────────────────────────┘
             │
             ▼ cascades to
      ┌─────────────┐  ┌─────────────┐  ┌─────────────┐

      │   Page B    │  │Collection C │  │   Page D    │

      │(refs Page A)│  │(refs Page A)│  │(refs Page A)│

      └─────────────┘  └─────────────┘  └─────────────┘

      All referencing content also invalidated

      ```


      **Optimization Parameters**


      For Blog list/search endpoints, use `exclude_body=true` to reduce response
      size by 50-70%. Control reference resolution depth with `levels=1` to
      `levels=5` (default `2`) to balance response completeness with
      performance. Implement efficient pagination patterns for large content
      sets to avoid expensive serialization of deeply referenced content.


      **Write Operations**


      Create and update operations return `202 Accepted` for immediate feedback
      while background processing handles tasks like media uploads, validation,
      and webhook notifications. This ensures consistent fast response times
      regardless of operation complexity.


      ---


      **Integration Best Practices**


      For easiest implementation, ButterCMS API integration should follow a
      structured approach of these sequential steps: content architecture
      planning, API endpoint integration, performance optimization, and
      production deployment. Content must be designed in your ButterCMS
      dashboard first to establish schema and reference relationships before
      implementing API calls in your application.


      **Static Site Generation (SSG)** implementations fetch content during
      build processes and utilize webhook-triggered rebuilds for content
      updates. This pattern provides maximum performance through pre-built pages
      and CDN distribution but requires build system integration for content
      synchronization. Build-time fetching typically uses batch API calls to
      retrieve all necessary content, implementing error handling for API
      availability during build processes.


      **Server-Side Rendering (SSR)** applications fetch content on each
      request, implementing application-level caching to optimize performance
      while maintaining real-time content updates. Request-time fetching allows
      for personalized content and immediate content updates but requires
      careful cache management and error handling for API unavailability
      scenarios.


      **Single Page Applications (SPA)** implement client-side content fetching
      with progressive loading patterns, utilizing browser caching and API
      response caching for optimal user experience. Client-side integration
      enables dynamic content updates and interactive experiences but requires
      consideration of API key security and CORS configuration.


      ```

      ┌─────────────────────────────────────────────────────────────────┐

      │                    Integration Patterns                         │

      ├─────────────────────────────────────────────────────────────────┤

      │                                                                 │

      │ SSG (Build Time):                                               │

      │ Content ──▶ Build Process ──▶ Static Files ──▶ CDN ──▶ Users    │

      │              ▲                                                  │

      │ Webhook triggers rebuild                                        │

      │                                                                 │

      │ SSR (Request Time):                                             │

      │ User Request ──▶ Server ──▶ API Call ──▶ Dynamic Page ──▶ User  │

      │                   │                                             │

      │                   ▼ App-level cache                             │

      │                                                                 │

      │ SPA (Client Side):                                              │

      │ User ──▶ App Shell ──▶ API Calls ──▶ Dynamic Updates ──▶ UI     │

      │           │                                                     │

      │           ▼ Browser cache                                       │

      └─────────────────────────────────────────────────────────────────┘

      ```


      **API Efficiency**


      Strategic parameter usage improves performance significantly. The
      `exclude_body=true` parameter reduces response size by 50-70% for content
      listing operations, while the `levels` parameter controls reference depth
      to balance data completeness with response time. Pagination should be
      implemented using appropriate page sizes for large content sets, typically
      10-25 items per request for optimal performance.


      **Error Handling**


      Implement graceful degradation patterns for API unavailability, retry
      logic with exponential backoff for transient failures, and fallback
      content mechanisms for critical application functionality. Applications
      should monitor API response times and implement circuit breaker patterns
      for sustained API issues. Content architecture should minimize reference
      depth requirements and design reference patterns to avoid circular
      dependencies that impact API performance.
  - name: Pages - Key Concepts
    description: >
      Essential concepts for working with ButterCMS Pages, including unique
      features, publication states, and architectural patterns.


      ## Overview and Core Features


      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.


      **Content Architecture**


      Pages excel at complex content scenarios requiring flexible layouts,
      dynamic components, and sophisticated reference relationships. They are
      ideal for marketing pages, product pages, articles, and any content
      requiring rich, structured presentation.


      ---


      **Content Publication States**


      Pages support a comprehensive three-state lifecycle that provides maximum
      flexibility for content management workflows.


      - **Draft State**: Content accessible only via preview mode, enabling
      content teams to review changes before publication. Draft pages can be
      created, edited, and previewed without affecting live content.

      - **Published State**: Content live and accessible via standard API
      endpoints, served through the global CDN with automatic caching and
      optimization.

      - **Scheduled State**: Content automatically published at specified times
      through dashboard configuration, enabling time-based content strategies
      and editorial calendar management.


      **Versioning Capability**: Pages uniquely support creating new draft
      versions over existing published content, allowing continuous content
      iteration without taking existing pages offline. This enables
      sophisticated content workflows where multiple versions can be prepared
      and scheduled.


      ---


      **Previewing**


      Preview functionality enables content teams to review draft pages in full
      website context before publishing, providing confidence in content
      presentation and layout.


      **Pages Preview Workflow**:

      1. Configure preview URLs for Page Types in your ButterCMS dashboard

      2. Content creators click "Preview" button and are redirected to your
      preview URL with `preview=1` parameter

      3. Your application detects the parameter and includes it in ButterCMS API
      calls

      4. Draft page content is returned and displayed in complete website
      context

      5. Content teams can review layout, styling, and content presentation
      before publication


      **Technical Implementation**: Preview mode works by appending `preview=1`
      to API requests, which instructs ButterCMS to return the latest draft
      version rather than published content. This enables seamless integration
      with existing rendering systems.


      **Environment Strategy**: Consider implementing environment-based
      configuration that automatically includes the preview parameter in
      development and staging environments, reducing manual parameter management
      across different deployment contexts.


      ## Reference Architecture


      Pages participate in ButterCMS's reference system, enabling complex
      content relationships and reusable data patterns that scale with your
      content needs.


      **Page-to-Page References**


      Reference fields pointing to other pages use page slugs as identifiers,
      providing human-readable and URL-friendly relationships that support
      navigation and content discovery patterns.


      **Implementation Examples**


      - **One-to-one relationships**: `"related_page": "example-page-slug"` for
      featured content

      - **One-to-many relationships**: `"related_pages": ["page-1-slug",
      "page-2-slug"]` for content series

      - **Navigational references**: Supporting breadcrumbs, previous/next
      navigation, and content recommendations


      **Page-to-Collection References**


      Pages can reference Collection items to incorporate structured data like
      categories, team members, or product information, creating dynamic content
      that leverages centralized data management.


      **Reference Patterns**


      - **Category Assignment**: `"category": 123` using Collection item ID

      - **Author Information**: `"authors": [456, 789]` for multi-author content

      - **Product References**: `"featured_products": [101, 102, 103]` for
      e-commerce integration


      ---


      **Reference Management**


      **Adding References**


      Provide appropriate identifiers (slug for pages, ID for collections) in
      Write API requests. References are validated during processing to ensure
      target content exists.


      **Removing References**


      Clear relationships using appropriate empty values:

      - **Empty string** (`""`): Removes one-to-one relationships

      - **Empty array** (`[]`): Removes one-to-many relationships

      - **Null value** (`null`): Removes either relationship type


      **Update Behavior**


      - **PATCH requests**: Omitted reference fields remain unchanged, enabling
      selective updates

      - **PUT requests**: For Pages, PUT behaves like PATCH (partial update),
      allowing flexible field management


      ---


      **Reference Levels**


      The `levels` parameter controls reference field depth in API responses,
      balancing data completeness with response size and performance for optimal
      page loading.


      **Parameter Configuration**

      - **Default**: `levels=2` covers most page display scenarios

      - **Range**: 1-5 (values outside this range are automatically adjusted)

      - **Level 1**: Reference fields return API URIs only (minimal data
      transfer)

      - **Level 2+**: Reference fields return complete object data

      - **Level 5 (max)**: Returns URIs for any remaining references beyond
      specified depth


      **Performance Guidelines for Pages**

      - **Use `levels=1`** for page listing or navigation menus where you need
      minimal data

      - **Use `levels=2`** (default) for standard page display with basic
      reference information

      - **Use `levels=3-5`** when displaying pages with complex nested reference
      chains

      - **10MB response limit**: Reduce levels if responses approach this size
      limit


      **Response Examples**


      **Level 1 Example** (URIs only for faster loading):

      ```json

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

      ```


      **Level 2+ Example** (Complete objects for rich display):

      ```json

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

      ```


      ## Advanced Features


      **Localization**


      Multi-language support enables Pages to serve international audiences with
      locale-specific content while maintaining consistent schemas and reference
      relationships.


      **Account Configuration**


      Locale support must be configured in your ButterCMS account settings
      before creating multi-language pages. Each locale is identified by an API
      slug (such as `en`, `es`, `fr`) that you define during setup.


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


      **Content Versions**


      Pages can maintain separate content versions for each configured locale,
      allowing the same page structure to serve different language markets while
      preserving field schemas and component layouts.


      **API Integration**:

      - **Specify locale**: Add `locale=en` parameter to retrieve pages in
      specific language

      - **Default locale**: Omit parameter to receive content in your
      organization's default locale

      - **Write API**: Create localized versions by providing locale-specific
      field data in write requests


      **Reference Behavior**


      Reference fields work seamlessly with localization, allowing different
      reference relationships for different language versions. This enables
      locale-specific content recommendations, region-appropriate product
      references, and localized navigation patterns.


      **Use Cases**


      - **Marketing Sites**: Landing pages tailored to regional markets with
      localized messaging

      - **Product Pages**: E-commerce content adapted to local currencies,
      regulations, and preferences

      - **Corporate Content**: Company information, policies, and resources in
      multiple languages

      - **Content Hubs**: Resource centers and knowledge bases serving
      international audiences


      **Field Format Options**


      Pages support two localization formats depending on your organization's
      setup:

      - **Single-language**: Use direct `fields` object for accounts without
      localization

      - **Multi-language**: Nest field data under locale codes within the
      `fields` object (e.g., `"en"`, `"es"`)
  - name: Pages - Components
    description: >
      Complete guide to ButterCMS component system, exclusively available for
      Pages to create dynamic, structured layouts with reusable content blocks.


      **Important**: Components are only available for Pages and are not
      supported by Collections or Blog Posts. This page-exclusive functionality
      enables sophisticated content architecture and flexible layouts that
      distinguish Pages from other content types.


      ## Component System Overview


      Components provide a structured approach to building dynamic page layouts
      with reusable, predefined content blocks. This system enables content
      creators to build complex pages using consistent, developer-defined
      structures while maintaining design integrity and content organization.


      **Component Architecture**


      Components in ButterCMS consist of predefined field schemas that
      developers configure in the dashboard, which content creators then
      populate with data. This separation ensures consistent data structure
      while providing content flexibility.


      **Schema Management**


      Component schemas must be predefined in your ButterCMS dashboard before
      use. Unlike other field types, components cannot be created or modified
      through the Write API—they require dashboard configuration to establish
      field structures, validation rules, and presentation parameters.


      **Content Creation Workflow**:

      1. **Developer Phase**: Define component schemas in ButterCMS dashboard
      with specific field types and structures

      2. **Content Phase**: Content creators populate component fields with data
      using dashboard or Write API

      3. **Delivery Phase**: API responses include structured component data for
      rendering in your application


      ---


      **Individual Components**


      Single, structured content blocks within your page schema that maintain
      consistent field structures while allowing dynamic content updates.
      Individual components are ideal for standardized content sections with
      predictable data requirements.


      **Field Organization**


      Individual component fields are organized as nested JSON objects that
      preserve the component's internal structure while remaining easily
      accessible through API responses.


      ```json

      {
        "hero": {
          "image": "https://example.com/hero-image.jpg",
          "alt_text": "Hero section background image",
          "headline": "Welcome to Our Platform",
          "subtitle": "Powerful content management made simple",
          "cta_button": {
            "text": "Get Started",
            "url": "/signup"
          }
        }
      }

      ```


      **Update Behavior**


      Individual component fields support selective updates using PATCH
      requests, allowing you to modify specific component properties without
      affecting other fields within the same component or other components on
      the page.


      **Example Update Request**:

      ```json

      {
        "fields": {
          "hero": {
            "headline": "Updated Welcome Message"
          }
        }
      }

      ```

      In this example, only the headline field is updated while image, alt_text,
      subtitle, and cta_button retain their existing values.


      **Use Cases**:

      - **Header Sections**: Consistent hero areas with image, headline, and
      call-to-action elements

      - **Contact Information**: Standardized contact blocks with address,
      phone, and email fields

      - **Feature Highlights**: Structured feature presentations with icons,
      titles, and descriptions

      - **Testimonials**: Consistent testimonial formats with quotes,
      attribution, and images


      ---


      **Component Picker Fields**


      Component picker fields combine multiple predefined components in an
      ordered array, enabling dynamic page layouts with mixed content types.
      This functionality is essential for creating flexible, editorial-friendly
      pages where content structure can vary based on specific needs.


      **Dynamic Layout Structure**


      Component picker fields allow content creators to select from available
      component types and arrange them in any order, providing maximum layout
      flexibility while maintaining structured data integrity.


      **Array-Based Organization**


      Each element in a component picker array represents a single component
      instance with its type identifier and associated field data:


      ```json

      {
        "sections": [
          {
            "faq_item": {
              "question": "Are dogs allowed in the facility?",
              "answer": "Leashed dogs are welcome in all common areas and outdoor spaces.",
              "category": "Pets",
              "featured_image": "https://example.com/dog-friendly.jpg"
            }
          },
          {
            "trivia_block": {
              "title": "Did You Know?",
              "facts": [
                "Our facility was built in 1892",
                "We've hosted over 10,000 events"
              ],
              "background_color": "blue"
            }
          },
          {
            "image_gallery": {
              "title": "Recent Photos",
              "images": [
                {
                  "url": "https://example.com/photo1.jpg",
                  "caption": "Summer event 2024"
                },
                {
                  "url": "https://example.com/photo2.jpg",
                  "caption": "Holiday celebration"
                }
              ]
            }
          }
        ]
      }

      ```


      **Component Type Selection**


      Each component in a picker field is identified by its type key
      (`faq_item`, `trivia_block`, `image_gallery` in the example above), which
      corresponds to component schemas configured in your ButterCMS dashboard.


      **Update Limitations**


      Component picker fields require complete array replacement when updating.
      You cannot partially update individual components within a picker
      field—any update must include the entire array contents with all
      components and their complete field data.


      **Complete Update Example**:

      ```json

      {
        "fields": {
          "sections": [
            {
              "faq_item": {
                "question": "Updated question text",
                "answer": "Updated answer with more detail",
                "category": "Updated Category",
                "featured_image": "https://example.com/new-image.jpg"
              }
            },
            {
              "trivia_block": {
                "title": "New Trivia Section",
                "facts": ["New fact one", "New fact two"],
                "background_color": "green"
              }
            }
          ]
        }
      }

      ```


      **Ordering and Management**


      The order of components in the array determines their display sequence,
      giving content creators control over page flow and information hierarchy.
      Components can be reordered by changing their position in the array.


      **Use Cases**:

      - **Landing Pages**: Mixed content sections with headers, features,
      testimonials, and calls-to-action

      - **Resource Pages**: Combination of text blocks, image galleries,
      downloads, and embedded content

      - **Event Pages**: Dynamic sections for schedules, speakers, locations,
      and registration information

      - **Product Pages**: Flexible layouts combining specifications, images,
      reviews, and related products


      ## Advanced Features


      **Media Integration**


      Components seamlessly integrate with ButterCMS media management system,
      enabling automatic media processing and CDN optimization for
      component-based content.


      **Media Field Support**


      When a component field is configured with `Media` field type, any URL
      provided as the field value triggers automatic media processing, including
      download, upload to ButterCMS media library, and CDN integration.


      **Automatic Processing**


      Remote image URLs provided in media fields are automatically downloaded
      and uploaded to your ButterCMS media library, ensuring reliable hosting,
      CDN delivery, and centralized media management.


      **Example Media Integration**:

      ```json

      {
        "hero_section": {
          "background_image": "https://external-site.com/image.jpg",
          "logo": "https://company-assets.com/logo.png"
        }
      }

      ```


      After processing, these external URLs are replaced with ButterCMS CDN
      URLs, providing optimized delivery and eliminating external dependencies.


      **CDN Benefits**


      Media processed through components receives full CDN integration including
      global distribution, automatic optimization, and image transformation
      capabilities through Filestack integration.


      **Media Management**


      All component media becomes part of your centralized ButterCMS media
      library, enabling reuse across multiple pages and providing centralized
      organization and management capabilities.


      ---


      **Component Development Guidelines**


      **Schema Design**


      Design component schemas with reusability and flexibility in mind.
      Consider common use cases and provide appropriate field types that balance
      structure with content creator freedom.


      **Field Validation**


      Leverage ButterCMS field validation options within component schemas to
      ensure data quality and consistency across component instances.


      **Naming Conventions**


      Use clear, descriptive names for component types and fields that help
      content creators understand purpose and expected content without requiring
      extensive documentation.


      **Performance Considerations**


      Design components with appropriate granularity—overly complex components
      can impact API response times, while overly simple components may require
      excessive API calls for complete page rendering.


      **Content Creator Experience**


      Consider the dashboard editing experience when designing components,
      ensuring that field order and grouping create intuitive content creation
      workflows.
  - name: Collections - Key Concepts
    description: >
      Essential concepts for working with ButterCMS Collections, including
      unique characteristics, publication workflows, and architectural patterns
      optimized for structured data management.


      ## Overview and Core Features


      Collections serve as your structured data foundation, providing tables of
      organized content designed for reference by Pages or direct API queries.
      Collections excel at managing reusable data that supports and enhances
      your primary content.


      **Core Collection Characteristics**


      - **ID-based Retrieval**: Numeric ID identification system for precise,
      efficient data access

      - **Optimized Structure**: Streamlined schemas focused on data integrity
      and query performance

      - **Reference-Oriented**: Designed primarily to be referenced by Pages and
      other content types

      - **Simplified Management**: Straightforward field structures without
      component complexity

      - **Flexible Schemas**: Completely customizable field definitions to match
      your data requirements


      **Collections vs. Pages Comparison**


      - **No Components**: Collections do not support individual components,
      component picker fields, or component libraries

      - **No Repeaters**: Collections cannot use repeater field types that allow
      multiple instances of field structures

      - **No Form Integrations**: Direct form service integrations are not
      available for Collections

      - **Simpler Updates**: Streamlined update patterns without
      component-specific update behaviors

      - **Performance Focus**: Optimized for faster querying and smaller
      response sizes


      **Ideal Use Cases**


      - **Categories and Tags**: Organizational taxonomies for content
      classification

      - **Team Members**: Staff directories with contact information, roles, and
      expertise

      - **Product Catalogs**: Basic product information that Pages can reference
      and expand upon

      - **Location Data**: Store and office information for multi-location
      organizations

      - **Reference Lists**: Any structured data that enhances content without
      requiring complex layouts


      ---


      **Content Publication States**


      Collections follow the same unified publication state system as other
      ButterCMS content types, with implementation details optimized for data
      management workflows.


      - **Draft State**: Collection items can be created and edited in draft
      status, allowing data validation and review processes before making
      content live. Draft items are accessible only through preview mode,
      enabling data verification workflows.

      - **Published State**: Published collection items are available through
      standard API endpoints and can be referenced by Pages and other content.
      Published collections benefit from full CDN caching and global
      distribution for optimal performance.

      - **Scheduled State**: Collection items support scheduled publication for
      time-based data release, enabling coordinated content launches and
      editorial calendar integration.


      **Publication Workflow**


      Collection publication states integrate seamlessly with Page and Blog
      publication workflows, allowing coordinated content releases where Pages
      can reference Collections that publish simultaneously.


      **State Management**


      Collection items support standard state transitions (draft to published,
      published to draft, scheduled publication) through both dashboard
      interface and Write API operations.


      ---


      **Previewing**


      Preview functionality enables data validation and quality assurance for
      draft collection items before publication, supporting content review
      processes and data accuracy verification.


      **Collections Preview Strategy**


      Enable preview mode in development, staging, and testing environments by
      adding `preview=1` to Collection API requests. This allows teams to
      validate draft collection items in application context before publication.


      **Data Validation Workflow**


      1. Create or update collection items in draft status

      2. Use preview mode to fetch draft items through API calls

      3. Validate data structure, content accuracy, and integration behavior

      4. Review how draft items appear when referenced by Pages

      5. Publish collection items after validation confirms expected behavior


      **Environment Integration**


      Consider implementing environment-based configuration that automatically
      includes the preview parameter in non-production environments, enabling
      seamless data validation workflows across different deployment contexts.


      **Reference Preview**


      When previewing Pages that reference Collections, use preview mode to
      ensure both the Page draft and any referenced Collection drafts are
      displayed accurately, providing complete content preview scenarios.


      **API Behavior**


      When `preview=1` is included in Collection API requests, ButterCMS returns
      the latest draft version of collection items rather than published
      versions, enabling comprehensive content validation workflows.


      ## Reference Architecture


      Collections serve as both reference targets and reference sources within
      ButterCMS's content relationship system, enabling sophisticated data
      organization and content connections.


      **Collection-to-Page References**


      Collection items can reference Pages using page slugs, creating
      bidirectional content relationships that support navigation, feature
      highlighting, and content discovery patterns.


      **Implementation Patterns**


      - **Featured Content**: `"featured_page": "landing-page-slug"` for
      highlighting specific pages

      - **Related Resources**: `"related_pages": ["guide-1-slug",
      "guide-2-slug"]` for content series

      - **Landing Page Association**: `"product_page": "product-details-slug"`
      for e-commerce integration


      **Collection-to-Collection References**


      Collection items can reference other collection items using numeric IDs,
      enabling hierarchical data structures and complex organizational patterns.


      **Organizational Examples**


      - **Hierarchical Categories**: `"parent_category": 123` for taxonomy
      structures

      - **Related Items**: `"related_products": [456, 789, 101]` for
      cross-selling and recommendations

      - **Team Relationships**: `"department": 234` for organizational structure

      - **Location Hierarchies**: `"region": 345` for geographic organization


      ---


      **Collection Reference Management**


      **Adding References**


      Provide appropriate identifiers in Write API requests—page slugs for Page
      references, numeric IDs for Collection references. The system validates
      reference targets during processing.


      **Removing References**


      Clear relationships using appropriate empty values:

      - **Empty string** (`""`): Removes one-to-one relationships

      - **Empty array** (`[]`): Removes one-to-many relationships

      - **Null value** (`null`): Removes either relationship type


      **Update Behavior**


      - **PATCH requests**: Omitted reference fields remain unchanged, enabling
      selective relationship updates

      - **PUT requests**: Provide all fields including references; full
      replacement semantics apply to Collections


      **Reference Validation**


      Collection reference fields are validated to ensure target content exists
      and is accessible, preventing broken relationships in your content
      architecture.


      ---


      **Reference Levels**


      The `levels` parameter controls reference field depth in Collection API
      responses, optimizing data delivery for different use cases while managing
      response size and performance.


      **Parameter Configuration for Collections**


      - **Default**: `levels=2` provides complete referenced data for most
      collection use cases

      - **Range**: 1-5 (values outside this range are automatically adjusted)

      - **Level 1**: Reference fields return API URIs only (optimal for
      collection listings)

      - **Level 2+**: Reference fields return complete object data (ideal for
      detailed displays)

      - **Level 5 (max)**: Returns URIs for any remaining references beyond
      specified depth


      **Collection-Specific Performance Guidelines**


      - **Use `levels=1`** for collection listings or when building
      dropdown/select options

      - **Use `levels=2`** (default) for individual collection item display with
      reference context

      - **Use `levels=3-5`** when displaying collections with deep reference
      chains

      - **Pagination Considerations**: Use `levels=1` for paginated collection
      lists to minimize serialization overhead


      **Response Format Examples**


      **Level 1 Response** (URIs for minimal data transfer)


      ```json

      {
        "data": [
          {
            "meta": {"id": 123},
            "name": "Technology",
            "related_items": ["/v2/content/?keys=categories[_id=456]"],
            "featured_page": ["/v2/pages/product-guides/tech-overview"]
          }
        ]
      }

      ```


      **Level 2+ Response** (Complete objects for rich data access)


      ```json

      {
        "data": [
          {
            "meta": {"id": 123},
            "name": "Technology",
            "related_items": [
              {"meta": {"id": 456}, "name": "Software", "description": "..."}
            ],
            "featured_page": [
              {"slug": "tech-overview", "fields": {"title": "Technology Guide", "summary": "..."}}
            ]
          }
        ]
      }

      ```


      **Cross-Content Type References**


      The levels parameter works consistently whether references point to Pages
      or other Collections, providing predictable behavior across your entire
      content architecture.


      ## Localization and Best Practices


      **Localization**


      Multi-language support enables Collections to serve international content
      strategies with locale-specific data while maintaining consistent schemas
      and reference relationships.


      **Account Configuration**


      Locale support must be configured in your ButterCMS account settings
      before creating multi-language collections. Each locale uses an API slug
      (such as `en`, `es`, `fr`) defined during account setup.


      **Important Limitation**: Once locales are added to an account, they
      cannot be removed. Plan your internationalization approach carefully
      before configuration to avoid schema constraints.


      **Content Versions**


      Collections can maintain separate content versions for each configured
      locale, allowing the same data structure to serve different language
      markets while preserving field schemas and reference relationships.


      **API Integration Patterns**


      - **Specify locale**: Add `locale=en` parameter to retrieve collection
      items in specific language

      - **Default locale**: Omit parameter to receive content in your
      organization's default locale

      - **Write API**: Create localized versions by providing locale-specific
      field data in write requests


      **Reference Localization**: Reference fields work seamlessly with
      localization, allowing different reference relationships for different
      language versions. This enables locale-specific data associations,
      region-appropriate content relationships, and localized organizational
      structures.


      **Collection Localization Use Cases**


      - **Product Catalogs**: International product information with localized
      descriptions, pricing, and availability

      - **Team Directories**: Multi-regional staff information with localized
      roles and contact details

      - **Category Systems**: Taxonomies adapted to regional content
      organization and cultural preferences

      - **Location Data**: Multi-language address information, operating hours,
      and regional service details


      **Field Data Organization**


      Collections support two localization formats:

      - **Single-language**: Use direct field values for accounts without
      localization enabled

      - **Multi-language**: Nest field data under locale codes for accounts with
      localization (e.g., fields organized by `"en"`, `"es"`, `"fr"` keys)


      ---

      **Best Practices**


      **Localization Best Practices**


      - **Consistent References**: Maintain reference relationships across
      locales where appropriate, or create locale-specific references when
      regional variations are needed

      - **Data Validation**: Validate localized collection data to ensure
      completeness across all configured locales

      - **Reference Planning**: Design reference patterns that work effectively
      across different language and cultural contexts


      **Performance Optimization**


      - **Use appropriate `levels` parameters**: Start with `levels=1` for
      listing operations and increase only when necessary

      - **Implement pagination**: For large collections, use pagination to
      maintain responsive API performance

      - **Cache strategically**: Leverage ButterCMS CDN caching for frequently
      accessed collection data


      **Content Architecture**


      - **Design for scale**: Plan collection schemas that can accommodate
      future data requirements

      - **Reference strategy**: Create logical reference patterns that support
      your content relationships

      - **Validation planning**: Use appropriate field validation to maintain
      data quality across collection items
  - name: Blogs - Key Concepts
    description: >
      Essential concepts for working with ButterCMS Blog Posts, including
      predefined schemas, built-in organizational features, and publication
      characteristics.


      ## Overview and Built-in Features


      **Predefined Blog Schema**


      ButterCMS Blog Posts use a standardized, predefined schema that provides
      out-of-the-box functionality for chronological content with built-in
      organizational and authoring features.


      **Standardized Field Structure**


      Blog Posts come with a predefined set of fields that cannot be modified
      through the dashboard or API. This standardization ensures consistency
      across all blog content and enables built-in features that work reliably
      across all ButterCMS accounts.


      **Core Blog Fields**


      - **Title**: SEO-optimized title field with automatic URL slug generation

      - **Body**: Rich HTML content field supporting full editorial formatting

      - **Summary**: Optional excerpt field for post previews and social sharing

      - **Featured Image**: Dedicated image field with automatic CDN
      optimization

      - **SEO Metadata**: Built-in meta title, meta description, and Open Graph
      fields

      - **Publication Date**: Automatic timestamp management with scheduling
      capabilities

      - **Status**: Draft, published, and scheduled state management


      **Content Richness**


      The body field supports comprehensive HTML content including embedded
      media, formatted text, links, and other rich content elements that enable
      full editorial expression within the standardized structure.


      **SEO Integration**


      Blog Posts include built-in SEO optimization features such as automatic
      XML sitemap generation, RSS feed creation, and structured data markup that
      enhance search engine discoverability without additional configuration.


      ---


      **Built-in Categorization and Tagging**


      Blog Posts provide sophisticated organizational capabilities through
      predefined categorization and tagging systems that enable flexible content
      discovery and filtering.


      **Categories System**


      - **Hierarchical Organization**: Categories support parent-child
      relationships for sophisticated content taxonomy

      - **URL Integration**: Categories automatically generate SEO-friendly URLs
      for category pages

      - **Filtering Capability**: API endpoints support category-based filtering
      for content queries

      - **RSS Integration**: Category-specific RSS feeds are automatically
      generated


      **Tagging System**


      - **Flexible Labeling**: Tags provide flexible, non-hierarchical content
      labeling for cross-cutting themes

      - **Tag-based Discovery**: Readers can discover related content through
      tag-based navigation

      - **API Filtering**: Tags support API filtering for precise content
      queries

      - **Tag Clouds**: Automatic tag frequency calculation for tag cloud
      generation


      **Organizational Benefits**


      The combination of categories and tags enables sophisticated content
      organization that supports both hierarchical browsing (categories) and
      thematic discovery (tags), providing multiple pathways for content access.


      **Content Strategy Integration**


      Use categories for broad content themes and permanent organizational
      structure, while using tags for specific topics, campaigns, or temporal
      content connections that may evolve over time.


      ---


      **Predefined Metadata and Features**


      Blog Posts include comprehensive metadata and built-in features that
      eliminate the need for custom field configuration while providing
      professional blogging capabilities.


      **Author Management**


      - **Author Profiles**: Dedicated author entities with names, biographies,
      profile images, and social links

      - **Multi-author Support**: Blog posts can be attributed to multiple
      authors for collaborative content

      - **Author Archives**: Automatic generation of author-specific content
      archives and RSS feeds

      - **API Access**: Author information is accessible through dedicated API
      endpoints


      **Publication Metadata**


      - **Creation Timestamps**: Automatic tracking of content creation time

      - **Publication Dates**: Separate publication date management for
      editorial calendar control

      - **Update Tracking**: Last modified timestamps for content freshness
      indication

      - **URL Slug Management**: Automatic SEO-friendly URL generation with
      manual override capability


      **Built-in Features**


      - **RSS Feeds**: Automatic RSS 2.0 and Atom feed generation for content
      syndication

      - **XML Sitemaps**: Search engine sitemap integration for improved
      discoverability

      - **Previous/Next Navigation**: Automatic post navigation for
      chronological content browsing

      - **Related Posts**: Built-in content relationship suggestions based on
      categories and tags


      **Social Media Integration**


      Blog Posts include Open Graph and Twitter Card metadata that ensure proper
      social media presentation when content is shared across platforms.


      ---


      **Publication States and Workflow**


      Blog Posts follow a simplified publication state system optimized for
      editorial workflows and content scheduling, with important differences
      from Pages regarding versioning capabilities.


      **Simplified State Management**


      Blog Posts use a streamlined three-state system (draft, published,
      scheduled) without the complex versioning capabilities available to Pages.
      This simplification supports efficient editorial workflows focused on
      chronological content publication.


      **State Characteristics**


      - **Draft State**: Content accessible only through preview mode, enabling
      editorial review and revision

      - **Published State**: Content live and accessible through all blog
      endpoints with full CDN caching

      - **Scheduled State**: Content automatically published at specified times
      through dashboard scheduling


      **Versioning Limitations**


      Unlike Pages, Blog Posts do not support creating draft versions over
      existing published content. Once published, posts can be unpublished
      (returned to draft state) but cannot maintain simultaneous draft and
      published versions.


      **Editorial Workflow**


      The simplified state system supports traditional blog editorial workflows
      where content moves linearly from draft to published, with scheduling
      capabilities for time-based publication strategies.


      **Publication Behavior**


      Blog Posts are created and published immediately when using the Write API
      unless explicitly set to draft status, supporting both automated content
      creation and editorial review workflows.


      ## Limitations and Advanced Topics


      **Localization Limitations and Alternatives**


      **No Native Localization**: Blog Posts do not support the multi-language
      localization features available to Pages and Collections. The predefined
      blog schema is designed for single-language content within each ButterCMS
      account.


      **Alternative Approach for International Content**: Organizations
      requiring multi-language blog functionality should consider using **Page
      Types** instead of Blog Posts. Page Types can be configured to replicate
      blog functionality while providing full localization support.


      **Page Type Blog Implementation**


      - **Custom Schema**: Create Page Types with blog-like fields (title, body,
      date, author references)

      - **Localization Support**: Page Types inherit full localization
      capabilities from the Pages system

      - **Component Integration**: Page Types can include components for rich
      content layouts beyond traditional blog formats

      - **Reference Integration**: Page Types can reference Collections for
      author information, categories, and tags


      **Migration Considerations**


      Organizations planning international blog expansion should evaluate Page
      Types early in their content strategy to avoid complex migration scenarios
      from Blog Posts to Pages.


      **Single-Language Optimization**: For single-language blog content, Blog
      Posts provide optimal performance and built-in features that eliminate the
      need for custom field configuration and development overhead.


      ---


      **Content Import Capabilities**


      **WordPress Import**: ButterCMS provides built-in WordPress import
      functionality that enables migration from WordPress blogs to ButterCMS
      Blog Posts while preserving content structure, metadata, and
      organizational elements.


      **Import Features**


      - **Content Preservation**: Blog post titles, bodies, publication dates,
      and metadata are transferred accurately

      - **Category Migration**: WordPress categories are mapped to ButterCMS
      categories with hierarchy preservation

      - **Tag Transfer**: WordPress tags are converted to ButterCMS tags
      maintaining content relationships

      - **Author Mapping**: WordPress authors are created as ButterCMS author
      entities with profile information

      - **Media Import**: WordPress media attachments are transferred to
      ButterCMS media library with CDN integration


      **Import Planning**: WordPress import is a one-time migration tool that
      requires careful planning for large content volumes and complex category
      structures. Consider content review and cleanup processes as part of
      migration workflows.


      **Post-Import Optimization**: After WordPress import, leverage ButterCMS
      features such as CDN optimization, enhanced SEO metadata, and API access
      to improve content performance and integration capabilities beyond
      original WordPress functionality.


      ---


      **Blog API Characteristics**


      **Optimized Endpoints**: Blog Post APIs are optimized for chronological
      content access patterns with built-in pagination, sorting, and filtering
      capabilities that support common blog functionality requirements.


      **Performance Features**


      - **Body Exclusion**: Use `exclude_body=true` parameter to reduce response
      size by 50-70% for listing operations

      - **Category Filtering**: Native support for category-based content
      filtering without complex query construction

      - **Tag Filtering**: Built-in tag filtering for precise content queries

      - **Date Range Queries**: Support for publication date filtering to build
      archive functionality


      **Integration Patterns**


      Blog Post APIs are designed for traditional blog functionality including
      archive pages, category browsing, tag discovery, author profiles, and RSS
      feed generation, providing comprehensive blog platform capabilities
      through standardized endpoints.
  - name: Webhooks - Key Concepts
    description: >
      Complete Webhooks - Events system for real-time content change
      notifications.


      ButterCMS sends HTTP POST notifications to your configured endpoints
      whenever content changes occur. This enables real-time synchronization,
      cache invalidation, automated workflows, and multi-channel content
      publishing.


      ## Overview and Setup


      **How Webhooks Work**


      1. **Configure Endpoints**: Set up webhook URLs in your ButterCMS account
      settings

      2. **Choose Events**: Select which content events should trigger
      notifications

      3. **Receive Notifications**: ButterCMS sends HTTP POST requests to your
      endpoints

      4. **Process Changes**: Your application processes the webhook payload and
      takes action


      ---


      **Locale Support**


      For organizations with localization enabled, webhooks include a `locale`
      field when events occur for specific locales. The `locale` field is `null`
      for content in the organization's default locale.


      ---


      **Security Best Practices**


      **Authentication**

      - **Custom Headers**: Use custom authentication headers (e.g.,
      `X-API-Key`, `Authorization`) to verify webhook source

      - **IP Allowlisting**: Restrict webhook endpoints to accept requests only
      from ButterCMS IP ranges

      - **HTTPS Only**: Always use HTTPS endpoints to ensure encrypted data
      transmission


      **Payload Validation**

      - **Verify Headers**: Check authentication headers before processing
      webhook payload

      - **Validate Structure**: Ensure payload matches expected webhook event
      schema

      - **Idempotency**: Handle duplicate webhook deliveries gracefully using
      event IDs or timestamps


      **Error Handling**

      - **Return 2xx Status**: Return 200-299 status codes to acknowledge
      successful webhook processing

      - **Fail Fast**: Return error status codes (4xx/5xx) immediately for
      invalid requests

      - **Timeout Compliance**: Respond within 30 seconds to avoid ButterCMS
      timeout and retries


      ## Implementation Details


      **Delivery Guarantees**


      - **At-least-once delivery**: Webhooks may be delivered multiple times

      - **Retry logic**: Failed webhooks are retried with exponential backoff

      - **Timeout**: Webhook endpoints must respond within 30 seconds

      - **Status codes**: Return 2xx status codes to acknowledge successful
      processing


      ---


      **Integration Use Cases**


      - **Real-time Cache Invalidation**: Clear CDN cache when content updates

      - **Multi-channel Publishing**: Sync content to social media, email lists,
      mobile apps

      - **Automated Workflows**: Trigger deployments or notifications on content
      changes
  - name: Pages - Write
    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: Pages - Read
    description: >
      Retrieve pages from your ButterCMS account.


      **Single Pages**: Use `*` as the page_type to get Single Pages (those
      without a Page Type) which represent unique pages on your site like your
      Homepage. Useful for creating your sitemap.xml.


      **Page Type Pages**: Use the actual page type slug to get pages of that
      specific type. Page Types allow you to create many pages with the same
      structure.


      **Note:** The fields of a page are defined by you, they are customizable.
      Sample responses below contain a basic set of fields for illustrative
      purposes.
  - name: Collections - Write
    description: >
      Create, update, and delete Collection items using ButterCMS Write API.
      Collections are user-defined content structures with completely
      customizable field schemas.
  - name: Collections - Read
    description: >
      Retrieve collection items from your ButterCMS account. Collections are
      flexible, user-defined content structures with completely customizable
      field schemas.


      See also: Architecture & Performance for guidance on `levels`, pagination,
      and performance best practices.
  - name: Blog Posts - Write
    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.
  - name: Blog Posts - Read
    description: >
      Retrieve blog posts from your ButterCMS account. List blog posts with
      pagination and filtering options, or retrieve individual posts by slug.
  - name: Blog Metadata
    description: >
      Retrieve blog-related metadata including authors, categories, and tags.
      These endpoints provide access to the organizational structure of your
      blog content.
  - name: Webhooks - Events
    description: >
      Webhook event notifications sent by ButterCMS when content changes occur
      in your account.


      ButterCMS automatically sends webhook notifications for various content
      events including blog posts, pages, and collection items. These events
      enable real-time integration with your applications, triggering immediate
      responses to content changes.


      **Event Types**: Webhooks are triggered for create, update, publish,
      unpublish, and delete operations across all content types. Each event
      includes comprehensive payload data about the content that changed.


      **Delivery Method**: All webhook events are delivered as HTTP POST
      requests to your configured endpoint URLs, with JSON payloads containing
      event metadata and complete content data.


      **Configuration**: Webhook events are configured per content type in your
      ButterCMS account settings. You can select which events to receive and
      configure different endpoint URLs for different event types.
  - name: Feeds & Utilities
    description: >
      Generate XML feeds for content syndication and SEO.


      - **RSS Feed**: Fully generated RSS 2.0 feed for your blog

      - **Atom Feed**: Standards-compliant Atom 1.0 feed

      - **Sitemap**: XML sitemap for search engine discovery


      All feeds can be filtered by category or tag and include only published
      content from your organization.
  - name: Images - Info
    description: >
      ButterCMS has an integration with
      [Filestack](https://www.filestack.com/docs/api/processing/) for image
      transformations. You can leverage their robust set of image transformation
      capabilities.


      After you upload an image, to create a thumbnail, here's an example:


      - **Original URL**: `https://cdn.buttercms.com/3ccPHhYHTNK2zQ14gCOy`

      - **Thumbnail URL**:
      `https://cdn.buttercms.com/resize=width:100,height:100/3ccPHhYHTNK2zQ14gCOy`


      For complete transformation options and parameters, see the [full
      Filestack documentation](https://www.filestack.com/docs/api/processing/).
paths:
  /pages/:
    post:
      tags:
        - Pages - Write
      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
      security:
        - writeTokenAuth: []
      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: <p class="content">We love questions</p>
                    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: <p class="content">We love questions</p>
                      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: <p class="content">Nos encantan las preguntas</p>
                      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
  /pages/{page_type}/:
    get:
      tags:
        - Pages - Read
      summary: Get multiple Pages
      description: >
        Retrieve a paginated list of pages for a given page type, or all Single
        Pages when using the wildcard `*` as the page type. This endpoint
        supports comprehensive filtering and sorting for Page Type collections.


        **Single Pages**: Use `*` to retrieve Single Pages, which are unique
        pages like your Homepage, About page, or Contact page. This is
        particularly useful for generating sitemaps or building navigation
        structures that include your standalone pages.


        **Page Type Collections**: Use the actual page type slug to retrieve all
        pages that follow the same structural template. This allows you to fetch
        collections like all news articles, product pages, or blog posts that
        share the same field schema.


        > **Important**: Advanced filtering and ordering capabilities are only
        available for Page Type endpoints, not when retrieving Single Pages with
        the `*` wildcard. Use dotted notation for field filters (e.g.,
        `fields.title=Home`).

        See also: Architecture & Performance for guidance on `levels`,
        pagination, and performance best practices.
      operationId: getMultiplePages
      security:
        - readTokenAuth: []
      parameters:
        - name: page_type
          in: path
          description: >
            The slug of the type of pages you want to retrieve, or `*` for
            Single Pages.


            - Use `*` to get Single Pages (those without a Page Type)

            - Use the actual page type slug to get pages of that specific type
          required: true
          schema:
            type: string
          examples:
            single_pages:
              value: '*'
              description: Get all Single Pages
            news_pages:
              value: news
              description: Get pages of type 'news'
            faq_pages:
              value: faq
              description: Get pages of type 'faq'
        - $ref: '#/components/parameters/preview'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/locale'
        - $ref: '#/components/parameters/levels'
        - $ref: '#/components/parameters/alt_media_text'
        - $ref: '#/components/parameters/auth_token'
        - $ref: '#/components/parameters/order'
        - name: fields.seo.title
          in: query
          description: >
            Filter the result set by a nested field value. This is an example of
            field filtering — you can filter by any field using the pattern
            `fields.<field_name>=<value>`.


            You can pass in multiple filters at once. For example:
            `&fields.seo.title=Home&fields.headline=Welcome`


            To filter on Reference or Component fields use dot notation. For
            example: `fields.hero.title=value` or
            `fields.hero.reference.title=value`


            **Note**: Field filtering is only available for Page Type endpoints,
            not for Single Pages (`page_type=*`).
          required: false
          schema:
            type: string
          example: Home
        - name: fields.headline
          in: query
          description: >
            Filter the result set by a top-level field value. This is an example
            of field filtering — you can filter by any field using the pattern
            `fields.<field_name>=<value>`.


            **Note**: Field filtering is only available for Page Type endpoints,
            not for Single Pages (`page_type=*`).
          required: false
          schema:
            type: string
          example: Welcome
      responses:
        '200':
          description: >
            **Success**


            Returns a hash with a `data` property that contains an array of
            pages, and a `meta` property that contains pagination information.


            - For Single Pages (`page_type=*`): Returns pages without a page
            type

            - For Page Types: Returns pages of the specified type
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SinglePagesResponse'
                  - $ref: '#/components/schemas/PageBasedPagesResponse'
                  - $ref: '#/components/schemas/OffsetBasedPagesResponse'
              examples:
                single_pages:
                  summary: Single Pages Response (page_type=*)
                  value:
                    meta:
                      previous_page: null
                      next_page: null
                      count: 2
                    data:
                      - slug: single-page-1
                        page_type: null
                        published: '2019-11-12T17:23:53.109696Z'
                        updated: '2020-10-22T20:07:52.965850Z'
                        fields:
                          title: This is a single page
                          body: <p>Single PAGE!</p>
                      - slug: single-page-2
                        page_type: null
                        published: '2019-11-12T17:23:53.109696Z'
                        updated: '2020-10-22T20:07:52.965850Z'
                        fields:
                          title: Amazing Single Page
                          body: <p>Another single page!</p>
                page_type_pages:
                  summary: Page Type Response (page_type=news)
                  value:
                    meta:
                      previous_page: null
                      next_page: null
                      count: 2
                    data:
                      - slug: example-news-page
                        name: Example News Page
                        page_type: news
                        published: '2019-11-12T17:23:53.109696Z'
                        updated: '2020-10-22T20:07:52.965850Z'
                        fields:
                          seo:
                            title: Example News Page
                            description: SEO Description
                            keywords: SEO, Keywords
                          headline: This is an example news page
                media_url_format:
                  summary: Media field as URL string (alt_media_text=0)
                  description: >-
                    When `alt_media_text=0` (default), media fields are returned
                    as URL strings.
                  value:
                    meta:
                      previous_page: null
                      next_page: null
                      count: 1
                    data:
                      - slug: poster-page
                        name: Poster Page
                        page_type: posters
                        published: '2020-01-01T10:00:00Z'
                        updated: '2020-01-02T10:00:00Z'
                        fields:
                          title: Poster Details
                          media: https://cdn.example.com/media/poster.jpg
                media_object_format:
                  summary: Media field as object (alt_media_text=1)
                  description: >
                    When `alt_media_text=1`, media fields are returned as
                    objects. The object always includes `url`, and `alt` is
                    included when available.
                  value:
                    meta:
                      previous_page: null
                      next_page: null
                      count: 1
                    data:
                      - slug: poster-page
                        name: Poster Page
                        page_type: posters
                        published: '2020-01-01T10:00:00Z'
                        updated: '2020-01-02T10:00:00Z'
                        fields:
                          title: Poster Details
                          media:
                            url: https://cdn.example.com/media/poster.jpg
                            alt: Movie poster artwork
                offset_page_type_response:
                  summary: Offset-based pagination for page types
                  description: Using ?limit=10&offset=5 parameters for page type 'news'
                  value:
                    meta:
                      count: 15
                      next_offset: 15
                      previous_offset: null
                    data:
                      - slug: news-page-3
                        name: News Page 3
                        page_type: news
                        published: '2019-11-13T17:23:53.109696Z'
                        updated: '2020-10-23T20:07:52.965850Z'
                        fields:
                          seo:
                            title: Latest News Update
                            description: Breaking news content
                            keywords: News, Updates
                          headline: Breaking news story
                offset_single_pages_response:
                  summary: Offset-based pagination for single pages
                  description: Using ?limit=10&offset=5 parameters for page_type='*'
                  value:
                    meta:
                      count: 8
                      next_offset: null
                      previous_offset: null
                    data:
                      - slug: about-us-page
                        page_type: '*'
                        published: '2019-11-14T17:23:53.109696Z'
                        updated: '2020-10-24T20:07:52.965850Z'
                        fields:
                          title: About Our Company
                          body: <p>Learn about our mission and values</p>
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          description: >
            **Not Found - Page Type Does Not Exist or Invalid Pagination**


            - The requested page type doesn't exist or you don't have access to
            it.

            - Invalid pagination parameters (page number out of range).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                page_type_not_found:
                  summary: Page type not found
                  value:
                    detail: Page type not found.
                missing_page_type:
                  summary: Missing page type key format
                  value:
                    detail: >-
                      Page Type Key missing. Please format request like so
                      /pages/<page_type_key>
                invalid_pagination:
                  summary: Invalid pagination
                  value:
                    detail: Invalid Page.
  /pages/{page_type}/{page_slug}/:
    get:
      tags:
        - Pages - Read
      summary: Get a single Page
      description: >
        Retrieve a specific page by its page type and slug. This endpoint is
        ideal for fetching individual pages for display on your website or
        application.


        **Page Type Flexibility**: You can search across all page types using
        `*` as a wildcard, or optimize your query by providing a specific page
        type slug. Using the wildcard is useful when you know the page slug but
        aren't certain of its type, while specifying the page type can improve
        query performance. Use dotted notation for field filters (e.g.,
        `fields.title=Example`).

        See also: Architecture & Performance for guidance on `levels`,
        pagination, and performance best practices.
      operationId: getSinglePage
      security:
        - readTokenAuth: []
      parameters:
        - name: page_type
          in: path
          description: |
            The type of page to retrieve.

            - Use `*` to search across all page types
            - Use a specific page type slug to limit search to that type
          required: true
          schema:
            type: string
          examples:
            wildcard:
              value: '*'
              description: Search across all page types
            specific_type:
              value: news
              description: Search within news page type only
        - name: page_slug
          in: path
          description: |
            The slug of the page to retrieve.
          required: true
          schema:
            type: string
          example: example-news-page
        - $ref: '#/components/parameters/preview'
        - $ref: '#/components/parameters/locale'
        - $ref: '#/components/parameters/levels'
        - $ref: '#/components/parameters/alt_media_text'
        - $ref: '#/components/parameters/auth_token'
      responses:
        '200':
          description: >
            **Success**


            A hash with a `data` property that contains the page matching the
            page slug.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SinglePageResponse'
              examples:
                basic_page:
                  summary: Basic page response
                  value:
                    data:
                      slug: example-news-page
                      name: Example News Page
                      page_type: news
                      published: '2019-11-12T17:23:53.109696Z'
                      updated: '2020-10-22T20:07:52.965850Z'
                      fields:
                        seo:
                          title: Example News Page
                          description: SEO Description
                          keywords: SEO, Keywords
                        headline: This is an example news page
                        sections:
                          - fields:
                              headline: ...
                              subheadline: ...
                              call_to_action: ...
                            type: hero
                          - fields:
                              video_headline: ...
                              video_link: ...
                            type: product_video
                media_url_format:
                  summary: Media field as URL string (alt_media_text=0)
                  description: >-
                    When `alt_media_text=0` (default), media fields are returned
                    as URL strings.
                  value:
                    data:
                      slug: poster-page
                      name: Poster Page
                      page_type: posters
                      published: '2020-01-01T10:00:00Z'
                      updated: '2020-01-02T10:00:00Z'
                      fields:
                        title: Poster Details
                        media: https://cdn.example.com/media/poster.jpg
                media_object_format:
                  summary: Media field as object (alt_media_text=1)
                  description: >
                    When `alt_media_text=1`, media fields are returned as
                    objects. The object always includes `url`, and `alt` is
                    included when available.
                  value:
                    data:
                      slug: poster-page
                      name: Poster Page
                      page_type: posters
                      published: '2020-01-01T10:00:00Z'
                      updated: '2020-01-02T10:00:00Z'
                      fields:
                        title: Poster Details
                        media:
                          url: https://cdn.example.com/media/poster.jpg
                          alt: Movie poster artwork
        '400':
          description: |
            **Bad Request - Invalid Parameter**

            Invalid parameter value provided. This can happen when:
            - The `levels` parameter is not a valid integer between 1 and 5
            - Invalid locale parameter provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_levels:
                  summary: Invalid levels parameter
                  value:
                    detail: >-
                      levels query parameter should be an integer between 1 and
                      5 (inclusive)
                invalid_locale:
                  summary: Invalid locale parameter
                  value:
                    detail: Invalid locale parameter
        '401':
          description: >
            **Unauthorized - Invalid or Missing API Token**


            Authentication credentials were not provided. Make sure to include
            your read API token as the `auth_token` query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Authentication credentials were not provided
        '403':
          description: >
            **Forbidden - Multiple Pages Found**


            Multiple pages were found with the same slug when using wildcard
            page type. This typically indicates a data integrity issue where the
            same slug exists across different page types.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: >-
                  Multiple pages found with the same slug. Please specify a page
                  type or contact support.
        '404':
          description: >
            **Not Found - Page Does Not Exist**


            The requested page doesn't exist, or you don't have access to it.
            This could be because:

            - The page slug doesn't exist

            - The page type doesn't exist

            - The page exists but not in the specified page type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                page_not_found:
                  summary: Page not found
                  value:
                    detail: Page not found.
                page_type_not_found:
                  summary: Page type not found
                  value:
                    detail: Page type not found.
    patch:
      tags:
        - Pages - Write
      summary: Update Page via Write API
      description: >
        Update existing pages using PATCH requests with support for partial
        updates and multi-locale content. This endpoint provides flexible page
        modification capabilities while preserving unchanged content.


        **Page Type Flexibility**: Use `*` to update pages across all page types
        when you know the slug but not the specific type, or specify the
        particular page type slug for optimized queries.


        **Partial Update Behavior**: Include only the fields you want to modify
        in your request body. All other fields will retain their current values,
        making this ideal for targeted content updates without affecting the
        entire page structure.

        Note: PUT behaves like PATCH (partial update) for Pages. Use either
        method to perform partial updates.


        **Locale Handling**: For single-locale updates, use the direct field
        format. For multi-locale organizations, nest your field changes under
        the appropriate locale codes. You can update specific locales without
        affecting others.


        **Status Control**: Control page visibility by setting `status` to
        "draft" (keeps the page unpublished) or "published" (makes changes live
        immediately). Draft status is useful for staging content changes.


        **Immutable Fields**: Page `title` and `slug` cannot be modified via
        PATCH requests to maintain URL consistency and prevent broken links.
        These core identifiers must remain stable after page creation.


        **Repeater Field Behavior**: When updating repeater fields, you must
        include the complete array contents in your request. Partial repeater
        updates are not supported - the entire repeater will be replaced with
        your provided data.


        **Scheduling Limitation**: Page scheduling is not available through the
        Write API. Any scheduled parameters in your request will be ignored,
        allowing you to safely update pages that are currently scheduled without
        affecting their publication timing.
      operationId: updatePage
      security:
        - writeTokenAuth: []
      parameters:
        - name: page_type
          in: path
          description: |
            The type of page to update.

            - Use `*` to search across all page types
            - Use a specific page type slug to limit search to that type
          required: true
          schema:
            type: string
          examples:
            wildcard:
              value: '*'
              description: Update page across all page types
            specific_type:
              value: news
              description: Update page within news page type only
        - name: page_slug
          in: path
          description: |
            The slug of the page to update.
          required: true
          schema:
            type: string
          example: faq
        - 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 update only a single
            locale's version of a page, you can 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, updates the
            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 update data in either single-locale or multi-locale format.


          **Partial Updates**: Unlike creating pages, you only need to specify
          the fields you want to update. You don't need to include all fields.


          **Format Flexibility**: The API accepts data wrapped in a top-level
          "data" key (Read API format). For example: `{"data": {"status":
          "draft", "fields": {...}}}` will be automatically unwrapped. You can
          use either `title` or `name` - both are accepted and `name` will be
          automatically converted to `title`.


          **Request Body Formats**:

          - **WITHOUT Locales or Single Locale**: One format mirrors the read
          API response and can be used for pages without locales or updating a
          single, specified locale.

          - **WITH Locales (Multi-Locale)**: The second format can be used for
          updating multiple locales at once. In this format, the `fields` object
          has an extra level and must be first mapped to the locale code to use.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePageRequest'
            examples:
              without_locales:
                summary: Update Page WITHOUT Locales or with a Single Locale
                description: >
                  Example of updating a page without locale support or for a
                  single locale.


                  Note: You only need to specify the fields you want to update,
                  not all fields.
                value:
                  status: draft
                  fields:
                    headline: Frequently Asked Questions Updated
                    questions:
                      - question: Are dogs allowed?
                        answer: Leashed dogs are allowed.
                        picture: >-
                          https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg
                      - question: Another dog question
                        answer: Another dog answer
                        picture: >-
                          https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg
              with_locales:
                summary: Update Page WITH Locales
                description: >
                  Example of updating a page with multiple locales at the same
                  time.


                  Note: You only need to specify the fields you want to update
                  for each locale.
                value:
                  status: draft
                  fields:
                    en:
                      headline: Frequently Asked Questions Updated
                      questions:
                        - question: Are dogs allowed?
                          answer: Leashed dogs are allowed.
                          picture: >-
                            https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg
                        - question: Another dog question
                          answer: Another dog answer
                          picture: >-
                            https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg
      responses:
        '202':
          description: >
            **Accepted - Page update started successfully**


            The request has been accepted for processing. Full page update
            occurs asynchronously,

            meaning the successfully updated page may not show changes
            immediately. Page updates are validated

            prior to returning this response, but it is possible that page
            update may fail

            after returning a `202` response. If this happens, please contact
            support.


            **Warning Messages**: If you include fields that cannot be updated
            (like `scheduled` timestamp or `scheduled` status),

            the API will return warning messages explaining which fields were
            ignored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateSuccessResponse'
              examples:
                basic_success:
                  summary: Standard successful update
                  value:
                    status: pending
                success_with_warnings:
                  summary: Successful update with ignored fields
                  value:
                    status: pending
                    'warning: scheduled field': >-
                      Scheduled timestamps cannot be created or altered via
                      write API. This field will be ignored.
                    'warning: status field': >-
                      A page's status cannot be set as `scheduled` via write API
                      at this time. This field will be ignored.
        '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 for the specific page type

            - Providing a remote URL for a media field that returns a 404

            - Trying to update immutable fields (title, slug)

            - Providing invalid field values


            Error explanations will be returned in a JSON array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                missing_required_field:
                  summary: Missing required field
                  value:
                    headline:
                      - This field is required for this page type.
                invalid_status:
                  summary: Invalid status
                  value:
                    status:
                      - Valid status values are 'draft' and 'published'
                immutable_field_attempt:
                  summary: Attempted to update immutable field
                  value:
                    title:
                      - Page title cannot be updated via PATCH.
                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 - Permission Denied**

            You don't have permission to update this page. This could be due to:
            - Page update limits exceeded
            - Insufficient permissions for the page type
            - Organization-level restrictions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Permission denied
        '404':
          description: >
            **Not Found - Page Does Not Exist**


            The requested page doesn't exist, or you don't have access to it.
            This could be because:

            - The page slug doesn't exist

            - The page type doesn't exist

            - The page exists but not in the specified page type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                page_not_found:
                  summary: Page not found
                  value:
                    detail: Page not found.
                page_type_not_found:
                  summary: Page type not found
                  value:
                    detail: Page type not found.
    put:
      tags:
        - Pages - Write
      summary: Update Page via Write API (Full Update)
      description: >
        Update existing pages using PUT requests. **PUT behaves identically to
        PATCH (partial update)**, allowing you to update only the fields you
        specify while preserving unchanged content.


        **Page Type Flexibility**: Use `*` to update pages across all page types
        when you know the slug but not the specific type, or specify the
        particular page type slug for optimized queries.


        **Partial Update Behavior**: Include only the fields you want to modify
        in your request body. All other fields will retain their current values,
        making this ideal for targeted content updates without affecting the
        entire page structure.


        **Locale Handling**: For single-locale updates, use the direct field
        format. For multi-locale organizations, nest your field changes under
        the appropriate locale codes. You can update specific locales without
        affecting others.


        **Status Control**: Control page visibility by setting `status` to
        "draft" (keeps the page unpublished) or "published" (makes changes live
        immediately). Draft status is useful for staging content changes.


        **Immutable Fields**: Page `title` and `slug` cannot be modified via PUT
        requests to maintain URL consistency and prevent broken links. These
        core identifiers must remain stable after page creation.


        **Repeater Field Behavior**: When updating repeater fields, you must
        include the complete array contents in your request. Partial repeater
        updates are not supported - the entire repeater will be replaced with
        your provided data.


        **Scheduling Limitation**: Page scheduling is not available through the
        Write API. Any scheduled parameters in your request will be ignored,
        allowing you to safely update pages that are currently scheduled without
        affecting their publication timing.
      operationId: updatePagePut
      security:
        - writeTokenAuth: []
      parameters:
        - name: page_type
          in: path
          description: |
            The type of page to update.

            - Use `*` to search across all page types
            - Use a specific page type slug to limit search to that type
          required: true
          schema:
            type: string
          examples:
            wildcard:
              value: '*'
              description: Update page across all page types
            specific_type:
              value: news
              description: Update page within news page type only
        - name: page_slug
          in: path
          description: |
            The slug of the page to update.
          required: true
          schema:
            type: string
          example: faq
        - 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 update only a single
            locale's version of a page, you can 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, updates the
            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 update data in either single-locale or multi-locale format.


          **Partial Updates**: You only need to specify the fields you want to
          update. You don't need to include all fields.


          **Format Flexibility**: The API accepts data wrapped in a top-level
          "data" key (Read API format). For example: `{"data": {"status":
          "draft", "fields": {...}}}` will be automatically unwrapped. You can
          use either `title` or `name` - both are accepted and `name` will be
          automatically converted to `title`.


          **Request Body Formats**:

          - **WITHOUT Locales or Single Locale**: One format mirrors the read
          API response and can be used for pages without locales or updating a
          single, specified locale.

          - **WITH Locales (Multi-Locale)**: The second format can be used for
          updating multiple locales at once. In this format, the `fields` object
          has an extra level and must be first mapped to the locale code to use.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePageRequest'
            examples:
              without_locales:
                summary: Update Page WITHOUT Locales or with a Single Locale
                description: >
                  Example of updating a page without locale support or for a
                  single locale.


                  Note: You only need to specify the fields you want to update,
                  not all fields.
                value:
                  status: draft
                  fields:
                    headline: Frequently Asked Questions Updated
                    questions:
                      - question: Are dogs allowed?
                        answer: Leashed dogs are allowed.
                        picture: >-
                          https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg
                      - question: Another dog question
                        answer: Another dog answer
                        picture: >-
                          https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg
              with_locales:
                summary: Update Page WITH Locales
                description: >
                  Example of updating a page with multiple locales at the same
                  time.


                  Note: You only need to specify the fields you want to update
                  for each locale.
                value:
                  status: draft
                  fields:
                    en:
                      headline: Frequently Asked Questions Updated
                      questions:
                        - question: Are dogs allowed?
                          answer: Leashed dogs are allowed.
                          picture: >-
                            https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg
                        - question: Another dog question
                          answer: Another dog answer
                          picture: >-
                            https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg
      responses:
        '202':
          description: >
            **Accepted - Page update started successfully**


            The request has been accepted for processing. Full page update
            occurs asynchronously,

            meaning the successfully updated page may not show changes
            immediately. Page updates are validated

            prior to returning this response, but it is possible that page
            update may fail

            after returning a `202` response. If this happens, please contact
            support.


            **Warning Messages**: If you include fields that cannot be updated
            (like `scheduled` timestamp or `scheduled` status),

            the API will return warning messages explaining which fields were
            ignored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateSuccessResponse'
              examples:
                basic_success:
                  summary: Standard successful update
                  value:
                    status: pending
                success_with_warnings:
                  summary: Successful update with ignored fields
                  value:
                    status: pending
                    'warning: scheduled field': >-
                      Scheduled timestamps cannot be created or altered via
                      write API. This field will be ignored.
                    'warning: status field': >-
                      A page's status cannot be set as `scheduled` via write API
                      at this time. This field will be ignored.
        '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 for the specific page type

            - Providing a remote URL for a media field that returns a 404

            - Trying to update immutable fields (title, slug)

            - Providing invalid field values


            Error explanations will be returned in a JSON array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                missing_required_field:
                  summary: Missing required field
                  value:
                    headline:
                      - This field is required for this page type.
                invalid_status:
                  summary: Invalid status
                  value:
                    status:
                      - Valid status values are 'draft' and 'published'
                immutable_field_attempt:
                  summary: Attempted to update immutable field
                  value:
                    title:
                      - Page title cannot be updated via PUT.
                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 - Permission Denied**

            You don't have permission to update this page. This could be due to:
            - Page update limits exceeded
            - Insufficient permissions for the page type
            - Organization-level restrictions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Permission denied
        '404':
          description: >
            **Not Found - Page Does Not Exist**


            The requested page doesn't exist, or you don't have access to it.
            This could be because:

            - The page slug doesn't exist

            - The page type doesn't exist

            - The page exists but not in the specified page type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                page_not_found:
                  summary: Page not found
                  value:
                    detail: Page not found.
                page_type_not_found:
                  summary: Page type not found
                  value:
                    detail: Page type not found.
  /pages/search/:
    get:
      tags:
        - Pages - Read
      summary: Search Pages
      description: >
        Search for pages using a text query, returning a list of pages that
        match the search query sorted by relevancy. This endpoint provides
        flexible page discovery capabilities across your entire page structure.


        **Search Behavior**: Only the direct content of the Pages is searched.
        Any references that the Page might include are ignored during search,
        but references are still included in the response based on the `levels`
        parameter provided. Pages are returned sorted by relevancy to the search
        query.


        **Page Type Filtering**: You can optionally limit your search to a
        specific page type, or search only Single Pages using `*` as the page
        type parameter.


        **Empty Results**: If no results are found, the API returns an empty
        array: `"data": []`

        See also: Architecture & Performance for guidance on `levels`,
        pagination, and performance best practices.
      operationId: searchPages
      security:
        - readTokenAuth: []
      parameters:
        - name: query
          in: query
          description: >
            The search query string to match against page content.


            Only the direct content of pages will be searched. References are
            excluded from search but will still appear in results.


            **Maximum Length**: 100 characters
          required: true
          schema:
            type: string
            maxLength: 100
          examples:
            simple_search:
              value: buttercmsapi
              description: Simple keyword search
            phrase_search:
              value: frequently asked questions
              description: Multi-word phrase search
        - name: page_type
          in: query
          description: >
            The slug of the type of pages you want to limit your search to.


            - Use `*` if you want to search only Single Pages (without a Page
            Type)

            - Use a specific page type slug to limit search to that type

            - If left empty, searching will not be limited to a specific Page
            Type


            **Maximum Length**: 100 characters
          required: false
          schema:
            type: string
            maxLength: 100
          examples:
            all_types:
              value: ''
              description: Search across all page types (default)
            single_pages:
              value: '*'
              description: Search only Single Pages
            specific_type:
              value: news
              description: Search only pages of type 'news'
        - $ref: '#/components/parameters/locale'
        - $ref: '#/components/parameters/levels'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/auth_token'
      responses:
        '200':
          description: >
            **Success**


            Returns a hash with a `data` property that contains an array of
            pages matching the search query, and a `meta` property that contains
            pagination information.


            **Search Results**: Pages are returned sorted by relevancy. If no
            results are found, returns an empty array: `"data": []`


            **Content Searched**: Only direct page content is searched.
            References are excluded from search but included in response based
            on `levels` parameter.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PageBasedPageSearchResponse'
                  - $ref: '#/components/schemas/OffsetBasedPageSearchResponse'
              examples:
                search_results:
                  summary: Search results found
                  value:
                    meta:
                      previous_page: null
                      next_page: null
                      count: 2
                    data:
                      - slug: example-news-page
                        name: Example News Page
                        page_type: news
                        published: '2019-11-12T17:23:53.109696Z'
                        updated: '2020-10-22T20:07:52.965850Z'
                        fields:
                          seo:
                            title: Example News Page
                            description: SEO Description
                            keywords: SEO, Keywords
                          headline: This is an example news page
                          sections:
                            - fields:
                                headline: ...
                                subheadline: ...
                                call_to_action: ...
                              type: hero
                      - slug: example-news-page-2
                        name: Example News Page 2
                        page_type: news
                        published: '2019-11-12T17:23:53.109696Z'
                        updated: '2020-10-22T20:07:52.965850Z'
                        fields:
                          seo:
                            title: Example News Page
                            description: SEO Description
                            keywords: SEO, Keywords
                          headline: This is another news page
                          sections:
                            - fields:
                                video_headline: ...
                                video_link: ...
                              type: product_video
                offset_search_results:
                  summary: Offset-based pagination search results
                  description: Using ?limit=10&offset=5 parameters
                  value:
                    meta:
                      count: 15
                      next_offset: 15
                      previous_offset: null
                    data:
                      - slug: offset-news-page
                        name: Offset News Page
                        page_type: news
                        published: '2019-11-15T17:23:53.109696Z'
                        updated: '2020-10-25T20:07:52.965850Z'
                        fields:
                          seo:
                            title: Offset News Page
                            description: SEO Description for offset example
                            keywords: SEO, Keywords, Offset
                          headline: This is an offset-based search result
                          sections:
                            - fields:
                                headline: Offset Section
                                subheadline: Demonstrating offset pagination
                                call_to_action: Learn More
                              type: hero
                no_results:
                  summary: No search results found
                  value:
                    meta:
                      previous_page: null
                      next_page: null
                      count: 0
                    data: []
        '400':
          description: |
            **Bad Request - Invalid Parameter**

            Invalid parameter value provided. This can happen when:
            - The `levels` parameter is not a valid integer between 1 and 5
            - Invalid locale parameter provided
            - Missing required `query` parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_query:
                  summary: Missing required query parameter
                  value:
                    detail: Query parameter is required for search.
                invalid_levels:
                  summary: Invalid levels parameter
                  value:
                    detail: >-
                      levels query parameter should be an integer between 1 and
                      5 (inclusive)
                invalid_locale:
                  summary: Invalid locale parameter
                  value:
                    detail: Invalid locale parameter
                invalid_locale_validation:
                  summary: Locale not configured for organization
                  value:
                    detail: fr is not a valid locale
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          description: >
            **Not Found - Page Type Does Not Exist**


            The requested page type doesn't exist or you don't have access to
            it. This only applies when using the `page_type` parameter with a
            specific page type slug.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Not found.
  /content/:
    post:
      tags:
        - Collections - Write
      summary: Create Collection Item
      description: >
        Create new items within a Collection using the Write API. Collections
        support completely dynamic schemas and multi-locale content, making them
        ideal for flexible content types like team members, products, or
        testimonials.


        **Dynamic Schema Flexibility**: Collection fields are entirely
        user-defined through your dashboard configuration. The field structure
        in your request must match the schema you've configured for the specific
        collection, including field types, validation rules, and any required
        fields.


        **Locale Structure**: For organizations without locales configured,
        provide field values directly in a flat structure. For multi-locale
        organizations, nest your field data under the appropriate locale codes
        (e.g., "en", "es") to create content in multiple languages
        simultaneously.


        **Media Integration**: 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, ensuring reliable hosting and CDN integration.


        **Asynchronous Processing**: This endpoint returns `202 Accepted`
        immediately to ensure fast response times for your application. The
        actual item creation, including media uploads, validation, and any
        configured webhooks, happens in the background processing queue.

        See also: Architecture & Performance for guidance on `levels`,
        pagination, and performance best practices.
      operationId: createCollectionItem
      security:
        - writeTokenAuth: []
      requestBody:
        required: true
        description: >-
          Collection item data with dynamic field structure based on collection
          configuration and locale settings.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCollectionItemRequest'
            examples:
              without_locales:
                summary: Create item without locales (single language)
                description: >-
                  Use this format when your organization has no locales
                  configured
                value:
                  key: team_members
                  status: published
                  fields:
                    - name: John Doe
                      position: Software Engineer
                      bio: Experienced developer with expertise in web technologies
                      profile_image: https://example.com/images/john-doe.jpg
                      years_experience: 5
              with_locales:
                summary: Create item with locales (multi-language)
                description: >-
                  Use this format when your organization has locales configured
                  (e.g., English and Spanish)
                value:
                  key: team_members
                  status: published
                  fields:
                    - en:
                        name: John Doe
                        position: Software Engineer
                        bio: >-
                          Experienced developer with expertise in web
                          technologies
                        profile_image: https://example.com/images/john-doe.jpg
                        years_experience: 5
                      es:
                        name: John Doe
                        position: Ingeniero de Software
                        bio: >-
                          Desarrollador experimentado con experiencia en
                          tecnologías web
                        profile_image: https://example.com/images/john-doe.jpg
                        years_experience: 5
              media_upload_example:
                summary: Create item with remote media URLs
                description: Demonstrates automatic media upload from remote URLs
                value:
                  key: products
                  status: draft
                  fields:
                    - name: Premium Widget
                      description: High-quality widget for professional use
                      main_image: https://cdn.example.com/products/widget-main.jpg
                      gallery_images:
                        - https://cdn.example.com/products/widget-1.jpg
                        - https://cdn.example.com/products/widget-2.jpg
                      price: 99.99
      responses:
        '202':
          description: >
            **Accepted - Collection Item Creation Queued**


            The collection item has passed initial validation and creation has
            been queued for asynchronous processing.


            **Important**: The item may not be immediately available in
            collection queries. Background processing includes:


            - Field validation against collection schema

            - Media download and upload to Butter Media Library

            - Reference field resolution

            - Search index updates


            If creation fails during background processing, contact support for
            assistance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCollectionItemResponse'
              example:
                status: pending
        '400':
          description: >
            **Bad Request - Validation Failed**


            The request failed initial validation. Common causes:


            - **Missing Required Fields**: `key` or `fields` not provided

            - **Invalid Status**: Status must be 'published' or 'draft'

            - **Invalid Collection Key**: Collection doesn't exist or access
            denied

            - **Field Validation**: Missing required fields or invalid field
            values

            - **Invalid Media URLs**: Remote URLs are not accessible or return
            404

            - **Locale Errors**: Invalid locale codes or mismatched locale
            format

            - **Organization Limits**: Collection item limit reached for
            subscription plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                missing_fields:
                  summary: Missing required fields
                  value:
                    key:
                      - Missing parameter
                    fields:
                      - Missing parameter
                invalid_status:
                  summary: Invalid status value
                  value:
                    status:
                      - Valid status values are 'draft' and 'published'
                invalid_media_url:
                  summary: Invalid remote media URL
                  value:
                    fields:
                      - Remote URL for media field is not a valid URL
                unsupported_media_type:
                  summary: Unsupported media file type
                  value:
                    fields:
                      - >-
                        We don't support 'text/plain' files, please contact us
                        about possible support.
                video_enterprise_required:
                  summary: Video uploads require enterprise plan
                  value:
                    fields:
                      - >-
                        Video upload is not allowed with your current plan.
                        Please contact support.
                svg_security_error:
                  summary: SVG security validation failed
                  value:
                    fields:
                      - We don't allow <script> tag in the SVG files.
        '401':
          $ref: '#/components/responses/UnauthorizedWriteResponse'
        '403':
          description: >
            **Forbidden - Insufficient Permissions or Subscription Limits**


            This error occurs when the provided token doesn't have write
            permissions or the collection item limit has been reached for your
            subscription plan.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - $ref: '#/components/schemas/LimitErrorResponse'
              examples:
                write_permission:
                  summary: Token lacks write permissions
                  value:
                    detail: Token does not have write permissions
                organization_limit:
                  summary: Collection item limit reached
                  value:
                    error: >-
                      Cannot create a new Collection Item. Collection Item Limit
                      Reached.
  /content/{collection_key}/:
    get:
      tags:
        - Collections - Read
      summary: Retrieve Collection
      operationId: retrieveCollection
      description: >
        Retrieve items from a specific Collection with comprehensive filtering,
        pagination, and relationship serialization capabilities. This endpoint
        provides flexible access to your dynamic content with powerful query
        options.


        **Collection Structure**: Collections contain completely user-defined
        content with customizable field schemas that you configure through the
        dashboard. Each collection can have different field types, validation
        rules, and structural requirements based on your content needs.


        **Response Format**: The response includes a `meta` object containing
        pagination information and result counts, a `data` array with the actual
        collection items, and individual `item.meta` objects containing unique
        IDs that you'll need for update and delete operations.

        See also: Architecture & Performance for guidance on `levels`,
        pagination, and performance best practices.
      parameters:
        - name: collection_key
          in: path
          required: true
          schema:
            type: string
            maxLength: 100
          description: |
            The unique identifier/slug of the Collection to retrieve.

            Must match an existing collection in your organization.
          example: artists
        - $ref: '#/components/parameters/auth_token'
        - name: keys
          in: query
          required: false
          schema:
            type: string
          description: >
            Comma-delimited list of Collection keys for multi-collection
            retrieval.


            **Note**: This is a legacy parameter. For single collection
            retrieval, use the path parameter instead.
          example: artists,albums
        - $ref: '#/components/parameters/preview'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/locale'
        - $ref: '#/components/parameters/levels'
        - $ref: '#/components/parameters/alt_media_text'
        - name: fields
          in: query
          required: false
          style: deepObject
          explode: true
          schema:
            type: object
            additionalProperties:
              type: string
          description: >
            Dynamic field filtering using dot notation.


            Filter collection items by any field using the pattern
            `fields.{field_name}=value`:

            - `fields.genre=Rock` - Filter by genre field

            - `fields.status=published` - Filter by status field

            - `fields.year=2023` - Filter by year field


            Multiple field filters can be combined in a single request.
          examples:
            genre_filter:
              summary: Filter by genre
              value:
                genre: Rock
            status_filter:
              summary: Filter by status
              value:
                status: published
            multi_filter:
              summary: Multiple filters
              value:
                genre: Rock
                year: '2023'
      responses:
        '200':
          description: Collection retrieved successfully
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PageBasedCollectionResponse'
                  - $ref: '#/components/schemas/OffsetBasedCollectionResponse'
              examples:
                artists_collection:
                  summary: Artists collection response
                  value:
                    meta:
                      count: 25
                      next_page: 3
                      previous_page: 1
                    data:
                      artists:
                        - meta:
                            id: 123
                          name: The Beatles
                          genre: Rock
                          formed_year: 1960
                          description: Legendary British rock band
                        - meta:
                            id: 124
                          name: The Rolling Stones
                          genre: Rock
                          formed_year: 1962
                          description: Iconic rock and roll band
                filtered_response:
                  summary: Filtered collection response
                  value:
                    meta:
                      count: 5
                      next_page: null
                      previous_page: null
                    data:
                      products:
                        - meta:
                            id: 456
                          title: Premium Headphones
                          category: Electronics
                          price: 299.99
                          in_stock: true
                localized_response:
                  summary: Localized collection response
                  value:
                    meta:
                      count: 10
                      next_page: 2
                      previous_page: null
                    data:
                      articles:
                        - meta:
                            id: 789
                          title: Bonjour le monde
                          content: Contenu en français...
                          locale: fr
                offset_collection_response:
                  summary: Offset-based pagination collection response
                  description: Using ?limit=10&offset=5 parameters
                  value:
                    meta:
                      count: 25
                      next_offset: 15
                      previous_offset: null
                    data:
                      artists:
                        - meta:
                            id: 125
                          name: Pink Floyd
                          genre: Progressive Rock
                          formed_year: 1965
                          description: English rock band known for philosophical lyrics
                        - meta:
                            id: 126
                          name: Led Zeppelin
                          genre: Hard Rock
                          formed_year: 1968
                          description: Influential English rock band
                media_url_format:
                  summary: Media field as URL string (alt_media_text=0)
                  description: >
                    When `alt_media_text=0` (default), media fields are returned
                    as URL strings.
                  value:
                    meta:
                      count: 1
                      next_page: null
                      previous_page: null
                    data:
                      products:
                        - meta:
                            id: 900
                          title: Poster
                          media: https://cdn.example.com/media/poster.jpg
                media_object_format:
                  summary: Media field as object (alt_media_text=1)
                  description: >
                    When `alt_media_text=1`, media fields are returned as
                    objects. The object always includes `url`, and `alt` is
                    included when available.
                  value:
                    meta:
                      count: 1
                      next_page: null
                      previous_page: null
                    data:
                      products:
                        - meta:
                            id: 901
                          title: Poster
                          media:
                            url: https://cdn.example.com/media/poster.jpg
                            alt: Movie poster artwork
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_locale:
                  summary: Invalid locale
                  value:
                    detail: Invalid locale 'xyz' specified
                invalid_levels:
                  summary: Invalid levels parameter
                  value:
                    detail: >-
                      levels query parameter should be an integer between 1 and
                      5 (inclusive)
                invalid_filter:
                  summary: Invalid filter key
                  value:
                    detail: Invalid filter key 'nonexistent_field'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          description: Not Found - Collection not found or Invalid Pagination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                collection_not_found:
                  summary: Collection not found
                  value:
                    detail: Not found.
                invalid_pagination:
                  summary: Invalid pagination
                  value:
                    detail: Invalid Page.
      security:
        - readTokenAuth: []
  /content/{collection_key}/{item_id}/:
    put:
      tags:
        - Collections - Write
      summary: Update Collection Item (Full)
      operationId: updateCollectionItem
      description: >
        Perform a full update (PUT) of an existing Collection item, completely
        replacing the item with the provided data. This operation is ideal when
        you need to ensure all fields are synchronized with your source data or
        when making comprehensive changes.


        **Update Method**: PUT replaces the entire item with your request data,
        similar to recreating the item from scratch. This differs from PATCH
        operations, which only update specific fields. Use PUT when you want to
        ensure complete data consistency or when your workflow involves
        regenerating entire items.


        > **Important**: The URL must include a trailing slash after the item ID
        (e.g., `/v2/content/my-collection/123/`). This is required for the
        endpoint to function correctly.


        **Item Identification**: The unique item ID can be found in the `meta`
        field of any collection item when retrieved through GET requests. This
        identifier remains constant throughout the item's life cycle and is
        required for all update and delete operations.


        **Reference Field Updates**: When updating reference fields, use page
        slugs for Page references and item IDs for Collection references. To
        remove existing references, provide empty strings (`""`), empty arrays
        (`[]`), or `null` values depending on the field type and whether it's a
        single or multi-reference field.


        **Asynchronous Processing**: This endpoint returns `202 Accepted`
        immediately to ensure fast response times. The actual update processing,
        including media uploads, reference resolution, validation, and webhook
        triggers, happens in the background processing queue.
      parameters:
        - name: collection_key
          in: path
          required: true
          schema:
            type: string
            maxLength: 100
          description: >
            The unique identifier/slug of the Collection containing the item to
            update.


            Must match an existing collection in your organization.
          example: team_members
        - name: item_id
          in: path
          required: true
          schema:
            type: string
            maxLength: 50
          description: >
            The unique identifier of the collection item to update.


            **Important**: The URL must end with a trailing slash after this
            parameter.


            This ID can be found in the `meta` field of collection items
            returned by GET operations.
          example: '123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCollectionItemRequest'
            examples:
              without_locales_full_update:
                summary: Full update without locales
                description: Complete replacement of collection item fields
                value:
                  status: published
                  fields:
                    field1_key: Updated field value
                    field2_key: Another updated value
                    contact_email: updated@example.com
              with_locales_full_update:
                summary: Full update with locales
                description: Complete replacement with multi-locale support
                value:
                  status: published
                  fields:
                    en:
                      field1_key: Updated English value
                      field2_key: Another English value
                    es:
                      field1_key: Valor actualizado en español
                      field2_key: Otro valor en español
              reference_fields_update:
                summary: Reference field updates
                description: Updating relationships to pages and other collections
                value:
                  status: published
                  fields:
                    related_page: updated-page-slug
                    tags:
                      - 4
                      - 5
                      - 6
                    category: null
      responses:
        '202':
          $ref: '#/components/responses/CollectionItemAcceptedResponse'
        '400':
          description: Bad Request - Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                validation_errors:
                  summary: Field validation errors
                  value:
                    field1_key:
                      - This field is required.
                    status:
                      - Valid status values are 'draft' and 'published'
                invalid_references:
                  summary: Reference field errors
                  value:
                    related_page:
                      - Page with slug 'nonexistent-page' not found.
                    tags:
                      - Collection item with ID 999 not found.
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                write_permission:
                  summary: Token lacks write permissions
                  value:
                    detail: Token does not have write permissions
        '404':
          description: Not Found - Collection or item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                collection_not_found:
                  summary: Collection not found
                  value:
                    detail: Collection not found
                item_not_found:
                  summary: Collection item not found
                  value:
                    detail: Collection item not found
      security:
        - writeTokenAuth: []
    patch:
      tags:
        - Collections - Write
      summary: Update Collection Item (Partial)
      operationId: patchCollectionItem
      description: >
        Perform a partial update (PATCH) of an existing Collection item,
        updating only the fields you specify while preserving all other content.
        This method is ideal for targeted updates without affecting the entire
        item structure.


        **Update Method**: PATCH updates only the fields included in your
        request body, leaving all other fields unchanged. This differs from PUT
        operations, which replace the entire item. Use PATCH when you want to
        modify specific fields while preserving existing content, relationships,
        and metadata.


        **Partial Update Intelligence**: Reference fields, status, timestamps,
        and any omitted content fields automatically retain their current
        values. This allows you to safely update specific content without
        worrying about accidentally clearing other important data.


        > **Important**: The URL must include a trailing slash after the item ID
        (e.g., `/v2/content/my-collection/123/`). This is required for the
        endpoint to function correctly.


        **Item Identification**: The unique item ID can be found in the `meta`
        field of any collection item when retrieved through GET requests. This
        identifier remains constant throughout the item's life cycle.


        **Reference Field Handling**: When updating reference fields, use page
        slugs for Page references and item IDs for Collection references. If you
        omit reference fields from your request, existing references remain
        completely unchanged, making it safe to update other content without
        affecting relationships.


        **Asynchronous Processing**: This endpoint returns `202 Accepted`
        immediately to ensure fast response times. The actual update processing,
        including media uploads, reference validation, and webhook triggers,
        happens in the background processing queue.
      parameters:
        - name: collection_key
          in: path
          required: true
          schema:
            type: string
            maxLength: 100
          description: >
            The unique identifier/slug of the Collection containing the item to
            update.


            Must match an existing collection in your organization.
          example: team_members
        - name: item_id
          in: path
          required: true
          schema:
            type: string
            maxLength: 50
          description: >
            The unique identifier of the collection item to update.


            **Important**: The URL must end with a trailing slash after this
            parameter.


            This ID can be found in the `meta` field of collection items
            returned by GET operations.
          example: '123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCollectionItemRequest'
            examples:
              without_locales_partial:
                summary: Partial update without locales
                description: Update only specific fields, others remain unchanged
                value:
                  status: published
                  fields:
                    field2_key: Only this field gets updated
              with_locales_partial:
                summary: Partial update with locales
                description: Update only specific locales and fields
                value:
                  status: published
                  fields:
                    en:
                      field2_key: Updated English field
                    es:
                      field1_key: Campo actualizado en español
              reference_partial_update:
                summary: Partial reference field update
                description: Update only reference relationships, preserve other fields
                value:
                  fields:
                    related_page: new-page-slug
                    tags:
                      - 7
                      - 8
              status_only_update:
                summary: Status change only
                description: Change only the publication status
                value:
                  status: draft
      responses:
        '202':
          $ref: '#/components/responses/CollectionItemAcceptedResponse'
        '400':
          description: Bad Request - Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                validation_errors:
                  summary: Field validation errors
                  value:
                    field1_key:
                      - This field is required.
                    status:
                      - Valid status values are 'draft' and 'published'
                invalid_references:
                  summary: Reference field errors
                  value:
                    related_page:
                      - Page with slug 'nonexistent-page' not found.
                    tags:
                      - Collection item with ID 999 not found.
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                write_permission:
                  summary: Token lacks write permissions
                  value:
                    detail: Token does not have write permissions
        '404':
          description: Not Found - Collection or item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                collection_not_found:
                  summary: Collection not found
                  value:
                    detail: Collection not found
                item_not_found:
                  summary: Collection item not found
                  value:
                    detail: Collection item not found
      security:
        - writeTokenAuth: []
    delete:
      tags:
        - Collections - Write
      summary: Delete Collection Item
      operationId: deleteCollectionItem
      description: >
        Delete an existing Collection item using a soft delete operation, which
        marks the item as deleted while preserving the data for potential
        recovery. This approach ensures data safety while removing items from
        public API responses.


        **Soft Delete Behavior**: The item is marked as deleted in the system
        and will no longer appear in collection listings, search results, or
        standard API responses. However, the actual data is preserved in the
        database, allowing for potential recovery through support channels if
        needed.


        > **Important**: The URL must include a trailing slash after the item ID
        (e.g., `/v2/content/my-collection/123/`). This is required for the
        endpoint to function correctly.


        **Item Identification**: The unique item ID can be found in the `meta`
        field of any collection item when retrieved through GET requests. This
        identifier is required to specify which item to delete.


        **Request Body**: DELETE requests should not include any request body
        data - send an empty body or omit the body entirely. The item ID in the
        URL path is sufficient to identify the target item.


        **Asynchronous Processing**: This endpoint returns `204 No Content`
        immediately upon successful request validation. The actual deletion
        processing, including webhook notifications and reference cleanup,
        happens in the background processing queue.
      parameters:
        - name: collection_key
          in: path
          required: true
          schema:
            type: string
            maxLength: 100
          description: >
            The unique identifier/slug of the Collection containing the item to
            delete.


            Must match an existing collection in your organization.
          example: team_members
        - name: item_id
          in: path
          required: true
          schema:
            type: string
            maxLength: 50
          description: >
            The unique identifier of the collection item to delete.


            **Important**: The URL must end with a trailing slash after this
            parameter.


            This ID can be found in the `meta` field of collection items
            returned by GET operations.
          example: '123'
      responses:
        '204':
          $ref: '#/components/responses/NoContentResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                write_permission:
                  summary: Token lacks write permissions
                  value:
                    detail: Token does not have write permissions
        '404':
          description: Not Found - Collection or item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                collection_not_found:
                  summary: Collection not found
                  value:
                    detail: Collection not found
                item_not_found:
                  summary: Collection item not found
                  value:
                    detail: Collection item not found
      security:
        - writeTokenAuth: []
  /posts/:
    get:
      tags:
        - Blog Posts - Read
      summary: List All Posts
      description: >
        Retrieve a paginated list of all published blog posts, automatically
        sorted

        by publication date with the newest posts appearing first. This endpoint
        is

        ideal for building blog listing pages, RSS feeds, or content archives.


        **Performance Optimization**: Use the `exclude_body=true` parameter when

        building post listing pages to significantly reduce response size by

        excluding the full post content. This improves loading performance while

        still providing titles, summaries, metadata, and author information
        needed

        for listing displays.
      operationId: listAllPosts
      security:
        - readTokenAuth: []
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/preview'
        - name: exclude_body
          in: query
          description: >
            When `true`, excludes the full post body from the response.


            **Performance benefit**: Significantly reduces response size when
            displaying lists of blog posts.
          schema:
            type: boolean
            default: false
          example: true
        - name: author_slug
          in: query
          description: Filter posts by an author's slug.
          schema:
            type: string
          example: api-test
        - name: category_slug
          in: query
          description: Filter posts by a category's slug.
          schema:
            type: string
          example: test-category
        - name: tag_slug
          in: query
          description: Filter posts by a tag's slug.
          schema:
            type: string
          example: test-tag
        - $ref: '#/components/parameters/auth_token'
      responses:
        '200':
          description: >
            **Success - Blog Posts Retrieved**


            Returns a list of blog posts matching the specified criteria. Posts
            are

            sorted by publish date with the most recent posts first.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PageBasedPostsResponse'
                  - $ref: '#/components/schemas/OffsetBasedPostsResponse'
              examples:
                page_based_pagination:
                  summary: Page-based pagination (default)
                  description: Using ?page=2&page_size=5 parameters
                  value:
                    meta:
                      count: 25
                      next_page: 3
                      previous_page: 1
                    data:
                      - url: http://www.example.com/blog/this-is-a-blog-post
                        created: '2020-10-08T18:29:19.987936Z'
                        updated: '2020-10-09T15:49:54.580309Z'
                        published: '2020-10-08T18:08:00Z'
                        author:
                          first_name: API
                          last_name: Test
                          email: apitest@buttercms.com
                          slug: api-test
                          bio: This is my bio.
                          title: API
                          linkedin_url: https://www.linkedin.com/in/API
                          facebook_url: https://www.facebook.com/API
                          twitter_handle: buttercmsapi
                          profile_image: https://buttercms.com/api.png
                        categories:
                          - name: test category
                            slug: test-category
                        tags:
                          - name: test tag
                            slug: test-tag
                        featured_image: null
                        featured_image_alt: ''
                        slug: this-is-a-blog-post
                        title: This is a blog post
                        body: <p class="">This is a blog post to test the API.</p>
                        summary: This is a blog post to test the API.
                        seo_title: This is a blog post
                        meta_description: This is a blog post to test the API.
                        status: published
                offset_based_pagination:
                  summary: Offset-based pagination
                  description: Using ?limit=5&offset=10 parameters
                  value:
                    meta:
                      count: 25
                      next_offset: 15
                      previous_offset: 5
                    data:
                      - url: http://www.example.com/blog/this-is-a-blog-post
                        created: '2020-10-08T18:29:19.987936Z'
                        updated: '2020-10-09T15:49:54.580309Z'
                        published: '2020-10-08T18:08:00Z'
                        author:
                          first_name: API
                          last_name: Test
                          email: apitest@buttercms.com
                          slug: api-test
                          bio: This is my bio.
                          title: API
                          linkedin_url: https://www.linkedin.com/in/API
                          facebook_url: https://www.facebook.com/API
                          twitter_handle: buttercmsapi
                          profile_image: https://buttercms.com/api.png
                        categories:
                          - name: test category
                            slug: test-category
                        tags:
                          - name: test tag
                            slug: test-tag
                        featured_image: null
                        featured_image_alt: ''
                        slug: this-is-a-blog-post
                        title: This is a blog post
                        body: <p class="">This is a blog post to test the API.</p>
                        summary: This is a blog post to test the API.
                        seo_title: This is a blog post
                        meta_description: This is a blog post to test the API.
                        status: published
                exclude_body_response:
                  summary: Response with exclude_body=true (lighter payload)
                  description: Using page-based pagination with exclude_body parameter
                  value:
                    meta:
                      count: 25
                      next_page: 3
                      previous_page: 1
                    data:
                      - url: http://www.example.com/blog/this-is-a-blog-post
                        created: '2020-10-08T18:29:19.987936Z'
                        updated: '2020-10-09T15:49:54.580309Z'
                        published: '2020-10-08T18:08:00Z'
                        author:
                          first_name: API
                          last_name: Test
                          email: apitest@buttercms.com
                          slug: api-test
                          bio: This is my bio.
                          title: API
                          linkedin_url: https://www.linkedin.com/in/API
                          facebook_url: https://www.facebook.com/API
                          twitter_handle: buttercmsapi
                          profile_image: https://buttercms.com/api.png
                        categories:
                          - name: test category
                            slug: test-category
                        tags:
                          - name: test tag
                            slug: test-tag
                        featured_image: null
                        featured_image_alt: ''
                        slug: this-is-a-blog-post
                        title: This is a blog post
                        summary: This is a blog post to test the API.
                        seo_title: This is a blog post
                        meta_description: This is a blog post to test the API.
                        status: published
        '400':
          description: |
            **Bad Request - Invalid Query Parameters**

            Invalid or malformed query parameters provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Invalid query parameters.
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
    post:
      tags:
        - Blog Posts - Write
      summary: Create Blog Post via Write API
      description: >
        Create a new blog post using the Write API with support for rich media,
        categorization, and automatic author assignment. This endpoint enables
        programmatic content creation for blogs, news sites, and content
        management workflows.


        **Required Fields**: Every blog post must include a `title` (post title)
        and `slug` (URL-friendly identifier). The slug must be unique across all
        posts in your organization and will become part of the post's permanent
        URL.


        **Author Management**: The author must already exist in your ButterCMS
        account before creating posts. You can specify the author by email
        address or slug. If no author is specified, the post will be
        automatically assigned to your organization owner, ensuring every post
        has proper attribution.


        **Dynamic Categorization**: Categories and tags can be provided as
        string arrays in your request. If you specify categories or tags that
        don't exist yet, they will be automatically created in your account,
        making it easy to expand your content taxonomy organically.


        **Media Integration**: Featured images are always uploaded to your
        ButterCMS media library for reliable hosting. For images within the post
        body content, set `upload_images_to_media_library=true` to automatically
        download and host external images through ButterCMS's CDN
        infrastructure.


        **Publication & Scheduling**: Blog posts default to `draft` unless
        `status=published` is provided. Scheduling future publication is not
        supported via the Write API; scheduling-related fields will result in
        validation errors.


        **Asynchronous Processing**: This endpoint returns `202 Accepted`
        immediately to ensure fast response times for your application. The
        actual post creation, including media processing, category creation, and
        webhook notifications, happens in the background processing queue.
      operationId: createBlogPost
      security:
        - writeTokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBlogPostRequest'
            examples:
              complete_blog_post:
                summary: Complete blog post with all fields
                value:
                  title: This is a blog post
                  slug: this-is-a-blog-post
                  status: published
                  author:
                    email: your@author.com
                  categories:
                    - Recipes
                    - Meals
                  tags:
                    - Butter
                    - Sushi
                    - Really Good Recipes
                  featured_image: >-
                    https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg
                  featured_image_alt: Featured image alt text example.
                  body: <h1>Butter</h1><p>I am so hungry!</p>
                  summary: This is a blog post summary.
                  seo_title: This is a blog post
                  meta_description: This is a blog post to test the API.
                  upload_images_to_media_library: false
              minimal_blog_post:
                summary: Minimal blog post with required fields only
                value:
                  title: My First Blog Post
                  slug: my-first-blog-post
              draft_with_author_slug:
                summary: Draft post with author specified by slug
                value:
                  title: Draft Post Example
                  slug: draft-post-example
                  author:
                    slug: firstname-lastname
                  body: <p>This is a draft post.</p>
                  summary: A draft post example.
      responses:
        '202':
          description: >
            **Accepted - Post Creation Initiated**


            A validated POST request will return a response with HTTP status
            code 202. Full post creation occurs asynchronously, meaning a
            successfully created post may not show immediately.


            Posts are validated prior to returning the API response but it is
            also possible that post creation may fail after returning a 202
            response. If this happens please contact support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogPostCreateSuccessResponse'
              example:
                status: pending
        '400':
          description: >
            **Bad Request - Validation Error**


            The API will return HTTP status code 400 if your data does not pass
            the initial validation stage. This may happen if:


            - You are missing a required field (title or slug)

            - The slug is already in use

            - The remote URL for a media field returns a 404

            - You attempt to schedule a blog post (not supported)

            - Invalid author email or slug provided


            Error explanations will be returned in a single JSON array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                missing_title:
                  summary: Missing required title field
                  value:
                    title:
                      - This field is required.
                missing_slug:
                  summary: Missing required slug field
                  value:
                    slug:
                      - This field is required.
                duplicate_slug:
                  summary: Slug already exists
                  value:
                    slug:
                      - Blog post with this slug already exists.
                scheduling_not_supported:
                  summary: Scheduling attempt during creation
                  value:
                    scheduled:
                      - >-
                        Scheduling a blog post during creation is not supported
                        by the write API at this time.
                scheduling_status_not_supported:
                  summary: Scheduled status not supported
                  value:
                    status_field:
                      - >-
                        Scheduling a blog post during creation is not supported
                        by the write API at this time.
                invalid_featured_image:
                  summary: Invalid featured image URL
                  value:
                    featured_image:
                      - Could not retrieve image from URL.
                unsupported_file_type:
                  summary: Unsupported media file type
                  value:
                    featured_image:
                      - >-
                        We don't support 'application/x-unknown' files, please
                        contact us about possible support.
                video_enterprise_only:
                  summary: Video upload requires enterprise plan
                  value:
                    featured_image:
                      - >-
                        Video upload is not allowed with your current plan.
                        Please contact support.
                svg_security_violation:
                  summary: SVG contains security risk
                  value:
                    featured_image:
                      - We don't allow <script> tag in the SVG files.
                invalid_author_email:
                  summary: Author with email not found
                  value:
                    author:
                      - Author with email 'nonexistent@email.com' not found.
                invalid_author_slug:
                  summary: Author with slug not found
                  value:
                    author:
                      - Author with slug 'nonexistent-author' not found.
        '401':
          $ref: '#/components/responses/UnauthorizedWriteResponse'
        '403':
          description: |
            **Forbidden - Blog Post Limit Exceeded or Insufficient Permissions**

            This can happen when:
            - Your organization has reached the blog post limit for your plan
            - Your API token does not have write permissions
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - $ref: '#/components/schemas/LimitErrorResponse'
              examples:
                blog_post_limit:
                  summary: Blog post limit exceeded
                  value:
                    error: Blog post limit is over
                write_permission_denied:
                  summary: API token lacks write permissions
                  value:
                    detail: Your API token does not allow writes.
        '404':
          description: >
            **Not Found - Organization Blog Missing or Invalid Pagination**


            - Could not find this organization's blog. This is a rare error that
            typically indicates a configuration issue.

            - Invalid pagination parameters (page number out of range).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                blog_missing:
                  summary: Organization blog missing
                  value:
                    detail: Could not find this organization's blog
                invalid_pagination:
                  summary: Invalid pagination
                  value:
                    detail: Invalid Page.
  /posts/{slug}/:
    get:
      tags:
        - Blog Posts - Read
      summary: Retrieve Single Post
      description: >
        Retrieve a specific blog post by its unique slug, including complete
        post content, metadata, and navigation information. This endpoint is
        ideal for building individual blog post pages with full content display.


        **Universal Access**: This endpoint retrieves posts regardless of their
        publication status (published, draft, or scheduled), making it perfect
        for preview functionality and content management workflows. Note that
        draft and scheduled posts won't appear in listing endpoints unless
        preview mode is specifically enabled.


        **Navigation Support**: The response includes a helpful `meta` object
        containing `next_post` and `previous_post` navigation links, allowing
        you to easily implement "Previous/Next" navigation on your blog post
        pages without additional API calls.


        > **Important**: You must append a trailing slash to the URL path:
        `/v2/posts/your-post-slug/`. This is required for the endpoint to
        function correctly.
      operationId: retrieveSinglePost
      security:
        - readTokenAuth: []
      parameters:
        - name: slug
          in: path
          required: true
          description: >
            The unique slug of the blog post to retrieve.


            **Important**: The URL must end with a trailing slash
            (`/v2/posts/your-slug/`).
          schema:
            type: string
            maxLength: 100
          example: hello-world
        - $ref: '#/components/parameters/auth_token'
      responses:
        '200':
          description: >
            **Success - Blog Post Retrieved**


            Returns the complete blog post object along with navigation metadata
            for browsing between posts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveSinglePostResponse'
              examples:
                published_post:
                  summary: Published blog post with navigation
                  value:
                    meta:
                      next_post: null
                      previous_post:
                        slug: >-
                          google-analytics-is-now-integrated-with-your-butter-blog
                        title: >-
                          Google Analytics is now integrated with your Butter
                          blog
                        featured_image: >-
                          https://d2devwt40at1e2.cloudfront.net/api/file/etSDYJUIFDADGEEAQ/
                    data:
                      url: http://www.example.com/blog/hello-world
                      created: '2015-06-12T13:59:32.441289Z'
                      published: '2015-06-12T00:00:00Z'
                      author:
                        first_name: API
                        last_name: Test
                        email: apitest@buttercms.com
                        slug: api-test
                        bio: This is my bio.
                        title: API
                        linkedin_url: https://www.linkedin.com/in/API
                        facebook_url: https://www.facebook.com/API
                        twitter_handle: buttercmsapi
                        profile_image: https://buttercms.com/api.png
                      categories:
                        - name: test category
                          slug: test-category
                      tags:
                        - name: test tag
                          slug: test-tag
                      featured_image: null
                      featured_image_alt: ''
                      slug: hello-world
                      title: This is a blog post
                      body: <p class="">This is a blog post to test the API.</p>
                      summary: This is a blog post to test the API.
                      seo_title: This is a blog post
                      meta_description: This is a blog post to test the API.
                      status: published
                draft_post_preview:
                  summary: >-
                    Draft post accessible via direct slug (preview
                    functionality)
                  value:
                    meta:
                      next_post:
                        slug: upcoming-blog-post
                        title: Upcoming Blog Post
                        featured_image: null
                      previous_post: null
                    data:
                      url: http://www.example.com/blog/draft-post-preview
                      created: '2023-12-01T14:30:00.000000Z'
                      published: null
                      author:
                        first_name: Content
                        last_name: Creator
                        email: creator@example.com
                        slug: content-creator
                        bio: Creating amazing content.
                        title: Content Creator
                        linkedin_url: null
                        facebook_url: null
                        twitter_handle: '@creator'
                        profile_image: null
                      categories: []
                      tags: []
                      featured_image: https://example.com/draft-image.jpg
                      featured_image_alt: Draft post image
                      slug: draft-post-preview
                      title: Draft Post Preview
                      body: >-
                        <h1>Preview Content</h1><p>This is a draft post that can
                        be previewed via direct slug access.</p>
                      summary: A draft post demonstrating preview functionality.
                      seo_title: Draft Post Preview
                      meta_description: Preview of draft content via direct slug access.
                      status: draft
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          description: >
            **Not Found - Blog Post Does Not Exist**


            The blog post with the specified slug was not found. This can happen
            if:


            - The blog post doesn't exist

            - The blog post belongs to a different organization

            - You don't have access to the blog post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Not found.
    patch:
      tags:
        - Blog Posts - Write
      summary: Update Blog Post via Write API
      description: >
        Update an existing blog post using partial updates, allowing you to
        modify specific fields while preserving all other content. This endpoint
        is perfect for content updates, SEO optimization, or adding new media to
        existing posts.


        **Partial Update Flexibility**: All fields in the request body are
        optional - include only the fields you want to modify. Any omitted
        fields will retain their current values, making it safe to update
        specific content without affecting the entire post structure.


        > **Important**: The URL must append a trailing slash to the blog post
        slug in the URL path (`/v2/posts/your-post-slug/`). This is required for
        the endpoint to function correctly.


        **Scheduling Limitations**: Blog post scheduling is not available
        through the Write API. Any scheduled parameters in your request will be
        silently ignored (not treated as errors), allowing you to safely update
        posts that are currently scheduled without affecting their publication
        timing.


        **Media Integration**: Include `upload_images_to_media_library=true` in
        your request to automatically download and upload any image URLs within
        the post body to your ButterCMS media library. This ensures reliable
        hosting and CDN performance for your content images.


        **Asynchronous Processing**: This endpoint returns `202 Accepted`
        immediately to ensure fast response times for your application. The
        actual update processing, including media uploads, content validation,
        and webhook notifications, happens in the background processing queue.
      operationId: updateBlogPost
      security:
        - writeTokenAuth: []
      parameters:
        - name: slug
          in: path
          required: true
          description: >
            The slug of the blog post to update.


            **Important**: The URL must end with a trailing slash
            (`/v2/posts/your-slug/`).
          schema:
            type: string
            maxLength: 100
          example: this-is-a-blog-post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBlogPostRequest'
            examples:
              partial_update:
                summary: Partial update (only specified fields changed)
                value:
                  slug: the-new-post-slug
                  body: <h1>Updated</h1><p>This blog post was updated via API</p>
              content_update:
                summary: Update content and SEO fields
                value:
                  title: Updated Blog Post Title
                  body: >-
                    <h1>Fresh Content</h1><p>Completely new content for this
                    post.</p>
                  summary: Updated summary of the post.
                  seo_title: Updated SEO Title
                  meta_description: Updated meta description for better SEO.
              category_tag_update:
                summary: Update categories and tags
                value:
                  categories:
                    - Updated Category
                    - New Category
                  tags:
                    - updated
                    - refresh
                    - api
              status_update:
                summary: Change post status
                value:
                  status: published
              media_library_update:
                summary: Update with media library upload
                value:
                  body: >-
                    <h1>Updated with Images</h1><p><img
                    src='https://example.com/new-image.jpg' alt='New image'></p>
                  upload_images_to_media_library: true
              scheduled_ignored:
                summary: Scheduled fields ignored (with warnings)
                value:
                  title: Updated Title
                  scheduled: '2024-12-25T10:00:00Z'
                  status: scheduled
      responses:
        '202':
          description: >
            **Accepted - Post Update Initiated**


            The update request has been accepted and will be processed
            asynchronously. The response may include warning messages if certain
            fields were ignored (such as scheduling-related fields).


            **Warning Messages**: If you provided `scheduled` timestamp or
            `status: "scheduled"`, these will be ignored and warning messages
            will be included in the response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogPostUpdateSuccessResponse'
              examples:
                simple_update:
                  summary: Simple update without warnings
                  value:
                    status: pending
                update_with_scheduled_warning:
                  summary: Update with scheduled field ignored
                  value:
                    status: pending
                    'warning: scheduled field': >-
                      Scheduled timestamps cannot be created or altered via
                      write API. This field will be ignored.
                update_with_status_warning:
                  summary: Update with scheduled status ignored
                  value:
                    status: pending
                    'warning: status field': >-
                      A blog post's status cannot be set as `scheduled` via
                      write API at this time. This field will be ignored.
                update_with_both_warnings:
                  summary: Update with both scheduling warnings
                  value:
                    status: pending
                    'warning: scheduled field': >-
                      Scheduled timestamps cannot be created or altered via
                      write API. This field will be ignored.
                    'warning: status field': >-
                      A blog post's status cannot be set as `scheduled` via
                      write API at this time. This field will be ignored.
        '400':
          description: >
            **Bad Request - Validation Error**


            The API will return HTTP status code 400 if your data does not pass
            validation. This may happen if:


            - Invalid field values provided

            - The remote URL for a media field returns a 404

            - Invalid author email or slug provided

            - Malformed request data


            Error explanations will be returned in a single JSON array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                invalid_featured_image:
                  summary: Invalid featured image URL
                  value:
                    featured_image:
                      - Could not retrieve image from URL.
                invalid_author_email:
                  summary: Author with email not found
                  value:
                    author:
                      - Author with email 'nonexistent@email.com' not found.
                invalid_status:
                  summary: Invalid status value
                  value:
                    status:
                      - >-
                        Select a valid choice. 'invalid_status' is not one of
                        the available choices.
        '401':
          $ref: '#/components/responses/UnauthorizedWriteResponse'
        '403':
          description: >
            **Forbidden - Insufficient Permissions**


            Your API token does not have write permissions or you don't have
            permission to update this blog post.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Your API token does not allow writes.
        '404':
          description: >
            **Not Found - Blog Post Does Not Exist**


            The blog post with the specified slug was not found or you don't
            have access to it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Not found.
    delete:
      tags:
        - Blog Posts - Write
      summary: Delete Blog Post via Write API
      description: >
        Delete an existing blog post using a soft delete operation that marks
        the post as deleted while preserving the content for potential recovery.
        This approach ensures data safety while removing posts from public
        visibility.


        > **Important**: You must append a trailing slash to the end of the blog
        post slug in the URL path: `/v2/posts/your-post-slug/`. This is required
        for the endpoint to function correctly.


        **Soft Delete Behavior**: The post is marked as deleted in the system
        and will no longer appear in blog listings, search results, RSS feeds,
        or other public endpoints. However, the actual content and metadata are
        preserved in the database, allowing for potential recovery through
        support channels if needed.


        **Access Control**: You can only delete blog posts that belong to your
        organization. Attempting to delete posts from other organizations will
        result in a 404 Not Found response, ensuring proper data isolation and
        security.
      operationId: deleteBlogPost
      security:
        - writeTokenAuth: []
      parameters:
        - name: slug
          in: path
          required: true
          description: >
            The slug of the blog post to delete.


            **Important**: The URL must end with a trailing slash
            (`/v2/posts/your-slug/`).
          schema:
            type: string
            maxLength: 100
          example: this-is-a-blog-post
      responses:
        '204':
          description: >
            **No Content - Blog Post Successfully Deleted**


            The blog post has been successfully deleted (soft delete). The
            response body is empty.


            **Note**: This is a soft delete operation. The post is marked as
            deleted but not physically removed from the system.
        '401':
          $ref: '#/components/responses/UnauthorizedWriteResponse'
        '403':
          description: >
            **Forbidden - Insufficient Permissions**


            Your API token does not have write permissions. Only write-enabled
            API tokens can delete blog posts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Your API token does not allow writes.
        '404':
          description: >
            **Not Found - Blog Post Does Not Exist or Already Deleted**


            The blog post with the specified slug was not found. This can happen
            if:


            - The blog post doesn't exist

            - The blog post belongs to a different organization

            - The blog post has already been deleted

            - You don't have access to the blog post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Not found.
  /authors/:
    get:
      tags:
        - Blog Metadata
      summary: List All Authors
      operationId: listAllAuthors
      description: >
        Retrieve a complete list of all blog post authors in your organization,
        including their profile information and optional recent post data. This
        endpoint is ideal for building author pages, contributor listings, and
        author-based navigation.


        **Author Profiles**: Returns comprehensive profile information for each
        author, including personal details like name and bio, social media
        profiles, profile images, and author metadata. This provides everything
        needed to build rich author profile pages.


        **Recent Posts Integration**: Use the `include=recent_posts` parameter
        to enrich the response with each author's most recent blog posts. This
        is particularly useful for creating author archive pages that showcase
        both the author's profile and their latest content contributions.
      parameters:
        - $ref: '#/components/parameters/auth_token'
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - recent_posts
          description: >
            Include additional data in the response.


            When set to `recent_posts`, each author object will include a
            `recent_posts` array containing their latest blog posts.
          example: recent_posts
      responses:
        '200':
          description: Authors retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAuthorsResponse'
              examples:
                basic_authors:
                  summary: Basic authors list
                  value:
                    data:
                      - slug: api-test
                        first_name: API
                        last_name: Test
                        email: apitest@buttercms.com
                        bio: This is my bio.
                        title: API
                        linkedin_url: https://www.linkedin.com/in/API
                        facebook_url: https://www.facebook.com/API
                        pinterest_url: https://www.pinterest.com/API
                        instagram_url: https://www.instagram.com/API
                        twitter_handle: buttercmsapi
                        profile_image: https://buttercms.com/api.png
                      - slug: john-doe
                        first_name: John
                        last_name: Doe
                        email: john@example.com
                        bio: Experienced content writer and blogger.
                        title: Senior Writer
                        linkedin_url: https://www.linkedin.com/in/johndoe
                        facebook_url: null
                        pinterest_url: null
                        instagram_url: https://www.instagram.com/johndoe
                        twitter_handle: johndoe
                        profile_image: https://cdn.buttercms.com/profiles/john-doe.jpg
                authors_with_posts:
                  summary: Authors with recent posts included
                  value:
                    data:
                      - slug: jane-smith
                        first_name: Jane
                        last_name: Smith
                        email: jane@example.com
                        bio: Tech writer specializing in web development.
                        title: Lead Technical Writer
                        linkedin_url: https://www.linkedin.com/in/janesmith
                        facebook_url: https://www.facebook.com/janesmith
                        pinterest_url: null
                        instagram_url: null
                        twitter_handle: janesmith_dev
                        profile_image: https://cdn.buttercms.com/profiles/jane-smith.jpg
                        recent_posts:
                          - slug: web-development-trends-2024
                            title: Web Development Trends in 2024
                            published: '2024-01-15T10:00:00.000Z'
                          - slug: javascript-best-practices
                            title: JavaScript Best Practices
                            published: '2024-01-10T14:30:00.000Z'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
      security:
        - readTokenAuth: []
  /authors/{slug}/:
    get:
      tags:
        - Blog Metadata
      summary: Retrieve Author
      operationId: retrieveAuthor
      description: >
        Retrieve detailed information about a specific author by their unique
        slug identifier, including complete profile data and optional recent
        posts integration.


        **Author Profile Information**: Returns comprehensive author profile
        including personal details (name, email, bio, title), complete social
        media profiles (LinkedIn, Facebook, Pinterest, Instagram, Twitter),
        profile image CDN URL, and unique slug identifier for URL-friendly
        referencing.


        **Recent Posts Integration**: Use the `include=recent_posts` parameter
        to enrich the response with the author's most recent blog posts. This is
        particularly useful for creating detailed author profile pages that
        showcase both their biography and latest content contributions.
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
            maxLength: 100
          description: |
            The unique slug identifier of the author to retrieve.

            Must match an existing author slug in your organization.
          example: jennifer-smith
        - $ref: '#/components/parameters/auth_token'
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - recent_posts
          description: >
            Include additional data in the response.


            When set to `recent_posts`, the author object will include a
            `recent_posts` array containing their latest blog posts.
          example: recent_posts
      responses:
        '200':
          description: Author retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveAuthorResponse'
              examples:
                basic_author:
                  summary: Basic author information
                  value:
                    data:
                      slug: jennifer-smith
                      first_name: Jennifer
                      last_name: Smith
                      email: jennifersmith@buttercms.com
                      bio: I love coffee!
                      title: President
                      linkedin_url: https://www.linkedin.com/in/jennifersmith
                      facebook_url: https://www.facebook.com/jennifersmith
                      pinterest_url: https://www.pinterest.com/jennifersmith
                      instagram_url: https://www.instagram.com/jennifersmith
                      twitter_handle: jennifersmith
                      profile_image: >-
                        https://d2devwt40at1e2.cloudfront.net/api/file/etSDYJUIFDADGEEAQ.png
                author_with_posts:
                  summary: Author with recent posts included
                  value:
                    data:
                      slug: jennifer-smith
                      first_name: Jennifer
                      last_name: Smith
                      email: jennifersmith@buttercms.com
                      bio: I love coffee!
                      title: President
                      linkedin_url: https://www.linkedin.com/in/jennifersmith
                      facebook_url: https://www.facebook.com/jennifersmith
                      pinterest_url: https://www.pinterest.com/jennifersmith
                      instagram_url: https://www.instagram.com/jennifersmith
                      twitter_handle: jennifersmith
                      profile_image: >-
                        https://d2devwt40at1e2.cloudfront.net/api/file/etSDYJUIFDADGEEAQ.png
                      recent_posts:
                        - slug: leadership-principles
                          title: Key Leadership Principles for Success
                          published: '2024-01-20T09:00:00.000Z'
                        - slug: coffee-productivity
                          title: How Coffee Boosts Productivity
                          published: '2024-01-15T14:30:00.000Z'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          description: Not Found - Author not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                author_not_found:
                  summary: Author not found
                  value:
                    detail: Not found.
      security:
        - readTokenAuth: []
  /categories/:
    get:
      tags:
        - Blog Metadata
      summary: List All Categories
      operationId: listAllCategories
      description: >
        Retrieve a complete list of all blog post categories in your
        organization, including category information and optional recent post
        data. This endpoint is perfect for building category navigation, content
        organization systems, and category-based filtering interfaces.


        **Category Information**: Returns the category name and URL-friendly
        slug for each category that contains published posts. This provides the
        essential data needed for building category-based navigation and
        filtering systems on your blog.


        **Recent Posts Integration**: Use the `include=recent_posts` parameter
        to enrich the response with each category's most recent blog posts. This
        is ideal for creating category landing pages that display both the
        category information and a preview of the latest content within that
        category.
      parameters:
        - $ref: '#/components/parameters/auth_token'
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - recent_posts
          description: >
            Include additional data in the response.


            When set to `recent_posts`, each category object will include a
            `recent_posts` array containing the latest blog posts in that
            category.
          example: recent_posts
      responses:
        '200':
          description: Categories retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCategoriesResponse'
              examples:
                basic_categories:
                  summary: Basic categories list
                  value:
                    data:
                      - name: test category
                        slug: test-category
                      - name: Product Updates
                        slug: product-updates
                      - name: Company News
                        slug: company-news
                      - name: Technology
                        slug: technology
                categories_with_posts:
                  summary: Categories with recent posts included
                  value:
                    data:
                      - name: Product Updates
                        slug: product-updates
                        recent_posts:
                          - slug: new-features-release
                            title: Exciting New Features in Our Latest Release
                            published: '2024-01-20T10:00:00.000Z'
                          - slug: api-improvements
                            title: API Performance Improvements
                            published: '2024-01-15T14:30:00.000Z'
                      - name: Technology
                        slug: technology
                        recent_posts:
                          - slug: future-of-web-development
                            title: The Future of Web Development
                            published: '2024-01-18T11:00:00.000Z'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
      security:
        - readTokenAuth: []
  /categories/{slug}/:
    get:
      tags:
        - Blog Metadata
      summary: Retrieve Category
      operationId: retrieveCategory
      description: >
        Retrieve a specific blog post category by its unique slug identifier,
        providing category information and optional recent posts integration.
        Categories help organize blog content into logical topical groups for
        improved navigation and content discovery.


        **Category Information**: The category object contains the display name
        (e.g., "Product Updates") and URL-friendly slug identifier (e.g.,
        "product-updates") that can be used for building category-based
        navigation and content organization systems.


        **Recent Posts Integration**: Use the `include=recent_posts` parameter
        to enrich the response with the category's recent blog posts. This adds
        a `recent_posts` array containing up to 10 of the most recently
        published posts in this category, ideal for creating category landing
        pages that showcase both the category information and latest content.
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
          description: |
            The unique slug identifier of the category to retrieve.
          example: product-updates
        - $ref: '#/components/parameters/auth_token'
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - recent_posts
          description: >
            Include additional data in the response.


            When set to `recent_posts`, the category object will include a
            `recent_posts` array containing the latest blog posts in this
            category (up to 10 posts, ordered by most recent first).
          example: recent_posts
      responses:
        '200':
          description: Category retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveCategoryResponse'
              examples:
                basic_category:
                  summary: Basic category without recent posts
                  value:
                    data:
                      name: Product Updates
                      slug: product-updates
                category_with_posts:
                  summary: Category with recent posts included
                  value:
                    data:
                      name: Product Updates
                      slug: product-updates
                      recent_posts:
                        - slug: new-features-release
                          title: Exciting New Features in Our Latest Release
                          published: '2024-01-20T10:00:00.000Z'
                        - slug: api-improvements
                          title: API Performance Improvements
                          published: '2024-01-15T14:30:00.000Z'
                        - slug: security-updates
                          title: Important Security Updates
                          published: '2024-01-10T09:30:00.000Z'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          description: Not Found - Category with specified slug does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                category_not_found:
                  summary: Category not found
                  value:
                    detail: Not found.
      security:
        - readTokenAuth: []
  /tags/:
    get:
      tags:
        - Blog Metadata
      summary: List All Tags
      operationId: listAllTags
      description: >
        Retrieve a complete list of all blog post tags in your organization,
        providing granular categorization and labeling information for your blog
        content. This endpoint is essential for building tag-based navigation,
        content discovery features, and detailed content organization systems.


        **Tag Information**: Returns the tag name and URL-friendly slug for each
        tag that contains published posts. Tags offer more granular content
        categorization than categories, allowing for detailed topical
        organization and improved content discoverability.


        **Recent Posts Integration**: Use the `include=recent_posts` parameter
        to enrich the response with each tag's most recent blog posts. This is
        particularly useful for creating tag cloud interfaces, topic-based
        landing pages, and tag archive pages that showcase recent activity for
        specific topics.
      parameters:
        - $ref: '#/components/parameters/auth_token'
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - recent_posts
          description: >
            Include additional data in the response.


            When set to `recent_posts`, each tag object will include a
            `recent_posts` array containing the latest blog posts tagged with
            that tag.
          example: recent_posts
      responses:
        '200':
          description: Tags retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTagsResponse'
              examples:
                basic_tags:
                  summary: Basic tags list
                  value:
                    data:
                      - name: test tag
                        slug: test-tag
                      - name: API Development
                        slug: api-development
                      - name: Tutorial
                        slug: tutorial
                      - name: Best Practices
                        slug: best-practices
                      - name: JavaScript
                        slug: javascript
                tags_with_posts:
                  summary: Tags with recent posts included
                  value:
                    data:
                      - name: API Development
                        slug: api-development
                        recent_posts:
                          - slug: rest-api-best-practices
                            title: REST API Best Practices for Modern Development
                            published: '2024-01-22T09:00:00.000Z'
                          - slug: graphql-vs-rest
                            title: 'GraphQL vs REST: Choosing the Right API'
                            published: '2024-01-18T14:30:00.000Z'
                      - name: JavaScript
                        slug: javascript
                        recent_posts:
                          - slug: es2024-features
                            title: New JavaScript Features in ES2024
                            published: '2024-01-20T11:00:00.000Z'
                          - slug: async-await-patterns
                            title: Advanced Async/Await Patterns
                            published: '2024-01-16T13:45:00.000Z'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
      security:
        - readTokenAuth: []
  /tags/{slug}/:
    get:
      tags:
        - Blog Metadata
      summary: Retrieve Tag
      operationId: retrieveTag
      description: >
        Retrieve a specific blog post tag by its unique slug identifier,
        providing detailed tag information and optional recent posts
        integration. Tags provide granular categorization and labeling for blog
        content, enabling detailed content organization and enhanced discovery
        capabilities.


        **Tag Information**: The tag object contains the display name (e.g.,
        "API Development") and URL-friendly slug identifier (e.g.,
        "api-development") that can be used for building tag-based navigation,
        content filtering, and topic-specific landing pages.


        **Recent Posts Integration**: Use the `include=recent_posts` parameter
        to enrich the response with the tag's recent blog posts. This adds a
        `recent_posts` array containing up to 10 of the most recently published
        posts tagged with this tag, perfect for creating comprehensive tag pages
        that showcase both tag information and the latest related content.
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
          description: |
            The unique slug identifier of the tag to retrieve.
          example: api-development
        - $ref: '#/components/parameters/auth_token'
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum:
              - recent_posts
          description: >
            Include additional data in the response.


            When set to `recent_posts`, the tag object will include a
            `recent_posts` array containing the latest blog posts tagged with
            this tag (up to 10 posts, ordered by most recent first).
          example: recent_posts
      responses:
        '200':
          description: Tag retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveTagResponse'
              examples:
                basic_tag:
                  summary: Basic tag without recent posts
                  value:
                    data:
                      name: API Development
                      slug: api-development
                tag_with_posts:
                  summary: Tag with recent posts included
                  value:
                    data:
                      name: API Development
                      slug: api-development
                      recent_posts:
                        - slug: rest-api-best-practices
                          title: REST API Best Practices for Modern Development
                          published: '2024-01-22T09:00:00.000Z'
                        - slug: graphql-vs-rest
                          title: 'GraphQL vs REST: Choosing the Right API'
                          published: '2024-01-18T14:30:00.000Z'
                        - slug: api-versioning-strategies
                          title: API Versioning Strategies for Long-term Success
                          published: '2024-01-14T16:15:00.000Z'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          description: Not Found - Tag with specified slug does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                tag_not_found:
                  summary: Tag not found
                  value:
                    detail: Not found.
      security:
        - readTokenAuth: []
  /posts/search/:
    get:
      tags:
        - Blog Metadata
      summary: Search Posts
      operationId: searchPosts
      description: >
        Search blog posts using advanced full-text search capabilities across
        titles and content, with intelligent relevance scoring to surface the
        most relevant results first.


        **Search Algorithm**: The search engine performs comprehensive full-text
        indexing across post titles, body content, and summary fields using
        natural language processing. Results are ranked by relevance score,
        taking into account factors like keyword frequency, title matches,
        content quality signals, and publication recency.


        **Content Scope**: The search indexes all published post content
        including titles, body text, summary fields, and associated metadata.
        Draft and scheduled posts are excluded from search results unless you're
        using preview mode through other endpoints.


        **Result Optimization**: Returns complete post objects with calculated
        relevance scores by default. Use the `exclude_body=true` parameter when
        building search result pages to significantly reduce response size and
        improve loading performance, particularly for mobile applications.


        **Performance Features**: Search results are automatically cached to
        ensure fast response times for repeated queries. The search index is
        updated in real-time as content is published, ensuring fresh results
        without manual reindexing.
      parameters:
        - name: query
          in: query
          required: false
          schema:
            type: string
            maxLength: 100
            default: ''
          description: >
            Search query string to find matching blog posts.


            The search will look for matches in both post titles and body
            content. Uses natural language processing for best results. If empty
            or not provided, no results will be returned.
          example: API development best practices
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - name: exclude_body
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: >
            Exclude the full blog post body content from results to reduce
            response size.


            When set to `true`, the response will omit the `body` field from
            each post object, making responses faster and lighter for cases
            where only post metadata is needed.
          example: false
        - $ref: '#/components/parameters/auth_token'
      responses:
        '200':
          description: Search completed successfully
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PageBasedSearchResponse'
                  - $ref: '#/components/schemas/OffsetBasedSearchResponse'
              examples:
                search_results:
                  summary: Search results with relevance ranking
                  value:
                    meta:
                      count: 2
                      next_page: null
                      previous_page: null
                    data:
                      - url: >-
                          https://api.buttercms.com/blog/api-development-best-practices
                        created: '2024-01-15T08:30:00.000Z'
                        published: '2024-01-15T10:00:00.000Z'
                        author:
                          first_name: John
                          last_name: Developer
                          email: john@buttercms.com
                          slug: john-developer
                          bio: Senior API Developer with 10+ years experience
                          title: Senior Developer
                          linkedin_url: https://linkedin.com/in/johndeveloper
                          facebook_url: null
                          twitter_handle: johndev
                          profile_image: https://cdn.buttercms.com/authors/john-developer.jpg
                        categories:
                          - name: Development
                            slug: development
                        tags:
                          - name: API
                            slug: api
                          - name: Best Practices
                            slug: best-practices
                        featured_image: https://cdn.buttercms.com/featured/api-guide.jpg
                        featured_image_alt: API Development Guide
                        slug: api-development-best-practices
                        title: API Development Best Practices for 2024
                        body: >-
                          <h2>Introduction</h2><p>Building robust APIs requires
                          following established best practices...</p>
                        summary: >-
                          Learn the essential best practices for building
                          scalable and maintainable APIs in 2024.
                        seo_title: API Development Best Practices for 2024
                        meta_description: >-
                          Complete guide to API development best practices
                          including REST design, authentication, and
                          documentation.
                        status: published
                        rank: 0.8573
                      - url: >-
                          https://api.buttercms.com/blog/rest-api-design-principles
                        created: '2024-01-10T14:20:00.000Z'
                        published: '2024-01-12T09:00:00.000Z'
                        author:
                          first_name: Sarah
                          last_name: Architect
                          email: sarah@buttercms.com
                          slug: sarah-architect
                          bio: API Architect specializing in distributed systems
                          title: API Architect
                          linkedin_url: https://linkedin.com/in/saraharchitect
                          facebook_url: null
                          twitter_handle: sarahapi
                          profile_image: >-
                            https://cdn.buttercms.com/authors/sarah-architect.jpg
                        categories:
                          - name: Architecture
                            slug: architecture
                        tags:
                          - name: REST
                            slug: rest
                          - name: API Design
                            slug: api-design
                        featured_image: https://cdn.buttercms.com/featured/rest-design.jpg
                        featured_image_alt: REST API Design
                        slug: rest-api-design-principles
                        title: RESTful API Design Principles
                        body: >-
                          <h2>Core Principles</h2><p>RESTful API design follows
                          key principles that ensure scalability...</p>
                        summary: >-
                          Master the fundamental principles of RESTful API
                          design for better developer experience.
                        seo_title: RESTful API Design Principles
                        meta_description: >-
                          Learn the core principles of REST API design for
                          building intuitive and scalable web services.
                        status: published
                        rank: 0.7234
                offset_search_results:
                  summary: Search results with offset-based pagination
                  description: Using ?limit=5&offset=0 parameters
                  value:
                    meta:
                      count: 2
                      next_offset: null
                      previous_offset: null
                    data:
                      - url: >-
                          https://api.buttercms.com/blog/api-development-best-practices
                        created: '2024-01-15T08:30:00.000Z'
                        published: '2024-01-15T10:00:00.000Z'
                        author:
                          first_name: John
                          last_name: Developer
                          email: john@buttercms.com
                          slug: john-developer
                          bio: Senior API Developer with 10+ years experience
                          title: Senior Developer
                          linkedin_url: https://linkedin.com/in/johndeveloper
                          facebook_url: null
                          twitter_handle: johndev
                          profile_image: https://cdn.buttercms.com/authors/john-developer.jpg
                        categories:
                          - name: Development
                            slug: development
                        tags:
                          - name: API
                            slug: api
                          - name: Best Practices
                            slug: best-practices
                        featured_image: https://cdn.buttercms.com/featured/api-guide.jpg
                        featured_image_alt: API Development Guide
                        slug: api-development-best-practices
                        title: API Development Best Practices for 2024
                        body: >-
                          <h2>Introduction</h2><p>Building robust APIs requires
                          following established best practices...</p>
                        summary: >-
                          Learn the essential best practices for building
                          scalable and maintainable APIs in 2024.
                        seo_title: API Development Best Practices for 2024
                        meta_description: >-
                          Complete guide to API development best practices
                          including REST design, authentication, and
                          documentation.
                        status: published
                        rank: 0.8573
                      - url: >-
                          https://api.buttercms.com/blog/rest-api-design-principles
                        created: '2024-01-10T14:20:00.000Z'
                        published: '2024-01-12T09:00:00.000Z'
                        author:
                          first_name: Sarah
                          last_name: Architect
                          email: sarah@buttercms.com
                          slug: sarah-architect
                          bio: API Architect specializing in distributed systems
                          title: API Architect
                          linkedin_url: https://linkedin.com/in/saraharchitect
                          facebook_url: null
                          twitter_handle: sarahapi
                          profile_image: >-
                            https://cdn.buttercms.com/authors/sarah-architect.jpg
                        categories:
                          - name: Architecture
                            slug: architecture
                        tags:
                          - name: REST
                            slug: rest
                          - name: API Design
                            slug: api-design
                        featured_image: https://cdn.buttercms.com/featured/rest-design.jpg
                        featured_image_alt: REST API Design
                        slug: rest-api-design-principles
                        title: RESTful API Design Principles
                        body: >-
                          <h2>Core Principles</h2><p>RESTful API design follows
                          key principles that ensure scalability...</p>
                        summary: >-
                          Master the fundamental principles of RESTful API
                          design for better developer experience.
                        seo_title: RESTful API Design Principles
                        meta_description: >-
                          Learn the core principles of REST API design for
                          building intuitive and scalable web services.
                        status: published
                        rank: 0.7234
                no_results:
                  summary: No search results found
                  value:
                    meta:
                      count: 0
                      next_page: null
                      previous_page: null
                    data: []
                excluded_body:
                  summary: Search results with body content excluded
                  value:
                    meta:
                      count: 1
                      next_page: null
                      previous_page: null
                    data:
                      - url: https://api.buttercms.com/blog/api-development-guide
                        created: '2024-01-15T08:30:00.000Z'
                        published: '2024-01-15T10:00:00.000Z'
                        author:
                          first_name: John
                          last_name: Developer
                          email: john@buttercms.com
                          slug: john-developer
                          bio: Senior API Developer
                          title: Senior Developer
                          linkedin_url: https://linkedin.com/in/johndeveloper
                          facebook_url: null
                          twitter_handle: johndev
                          profile_image: https://cdn.buttercms.com/authors/john.jpg
                        categories:
                          - name: Development
                            slug: development
                        tags:
                          - name: API
                            slug: api
                        featured_image: https://cdn.buttercms.com/featured/api.jpg
                        featured_image_alt: API Development
                        slug: api-development-guide
                        title: Complete API Development Guide
                        summary: Everything you need to know about API development.
                        seo_title: API Development Guide
                        meta_description: Complete guide to API development best practices.
                        status: published
                        rank: 0.9012
        '400':
          description: Bad Request - Invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                invalid_pagination:
                  summary: Invalid pagination parameters
                  value:
                    page:
                      - Ensure this value is greater than or equal to 1.
                    page_size:
                      - Ensure this value is greater than or equal to 1.
                query_too_long:
                  summary: Search query too long
                  value:
                    query:
                      - Ensure this field has no more than 100 characters.
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
      security:
        - readTokenAuth: []
  /feeds/rss/:
    get:
      tags:
        - Feeds & Utilities
      summary: RSS Feed
      operationId: getRssFeed
      description: >
        Generate a fully compliant RSS 2.0 XML feed for your blog content,
        perfect for syndication, feed readers, and content distribution. This
        endpoint automatically formats your blog posts into the standard RSS
        format with optional filtering capabilities.


        **RSS 2.0 Compliance**: Produces a standards-compliant RSS 2.0 XML feed
        that works with all major feed readers, news aggregators, and
        syndication services. The feed includes post titles, descriptions,
        publication dates, and permalinks.


        **Filtering Options**: Apply category or tag filters to create
        specialized feeds for specific content topics. This allows you to offer
        targeted RSS feeds for different audience segments or content verticals.
      parameters:
        - $ref: '#/components/parameters/auth_token'
        - name: category_slug
          in: query
          required: false
          schema:
            type: string
          description: >
            Filter the RSS feed to include only posts from a specific category.


            Provide the URL-friendly slug of the category. When specified, only
            blog posts assigned to this category will be included in the RSS
            feed.
          example: announcements
        - name: tag_slug
          in: query
          required: false
          schema:
            type: string
          description: >
            Filter the RSS feed to include only posts with a specific tag.


            Provide the URL-friendly slug of the tag. When specified, only blog
            posts tagged with this tag will be included in the RSS feed.
          example: product-updates
      responses:
        '200':
          description: RSS feed generated successfully
          content:
            application/xml:
              schema:
                type: string
                format: xml
                description: Complete RSS 2.0 XML feed with blog posts
              examples:
                rss_feed:
                  summary: Standard RSS feed with blog posts
                  value: >
                    <?xml version="1.0" encoding="UTF-8"?>

                    <rss xmlns:atom="http://www.w3.org/2005/Atom"
                    xmlns:content="http://purl.org/rss/1.0/modules/content/"
                    xmlns:media="http://search.yahoo.com/mrss/" version="2.0">
                       <channel>
                          <title>Latest blog posts</title>
                          <link>https://example.buttercms.com/blog/rss/</link>
                          <description />
                          <atom:link href="https://example.buttercms.com/blog/rss/" rel="self" />
                          <language>en-us</language>
                          <lastBuildDate>Mon, 15 Jan 2024 10:00:00 +0000</lastBuildDate>
                          <item>
                             <title>API Development Best Practices for 2024</title>
                             <link>https://example.buttercms.com/blog/api-development-best-practices</link>
                             <media:content medium="image" url="https://cdn.buttercms.com/featured/api-guide.jpg"/>
                             <dc:creator xmlns:dc="http://purl.org/dc/elements/1.1/">John Developer</dc:creator>
                             <pubDate>Mon, 15 Jan 2024 10:00:00 +0000</pubDate>
                             <guid>https://example.buttercms.com/blog/api-development-best-practices</guid>
                             <description>Learn the essential best practices for building scalable and maintainable APIs in 2024.</description>
                             <content:encoded>
                            <![CDATA[<h2>Introduction</h2><p>Building robust APIs requires following established best practices. In this comprehensive guide, we'll explore the key principles that ensure your APIs are scalable, maintainable, and developer-friendly.</p><h3>Key Principles</h3><p>Modern API development focuses on consistency, documentation, and performance optimization...</p>]]>
                          </content:encoded>
                          </item>
                          <item>
                             <title>RESTful API Design Principles</title>
                             <link>https://example.buttercms.com/blog/restful-api-design-principles</link>
                             <media:content medium="image" url="https://cdn.buttercms.com/featured/rest-design.jpg"/>
                             <dc:creator xmlns:dc="http://purl.org/dc/elements/1.1/">Sarah Architect</dc:creator>
                             <pubDate>Fri, 12 Jan 2024 09:00:00 +0000</pubDate>
                             <guid>https://example.buttercms.com/blog/restful-api-design-principles</guid>
                             <description>Master the fundamental principles of RESTful API design for better developer experience.</description>
                             <content:encoded>
                            <![CDATA[<h2>Core Principles</h2><p>RESTful API design follows key principles that ensure scalability and intuitive usage. Understanding these principles is crucial for creating APIs that developers love to use.</p>]]>
                          </content:encoded>
                          </item>
                       </channel>
                    </rss>
                filtered_by_category:
                  summary: RSS feed filtered by category
                  value: >
                    <?xml version="1.0" encoding="UTF-8"?>

                    <rss xmlns:atom="http://www.w3.org/2005/Atom"
                    xmlns:content="http://purl.org/rss/1.0/modules/content/"
                    xmlns:media="http://search.yahoo.com/mrss/" version="2.0">
                       <channel>
                          <title>Latest blog posts</title>
                          <link>https://example.buttercms.com/blog/rss/</link>
                          <description />
                          <atom:link href="https://example.buttercms.com/blog/rss/" rel="self" />
                          <language>en-us</language>
                          <lastBuildDate>Wed, 10 Jan 2024 15:30:00 +0000</lastBuildDate>
                          <item>
                             <title>Product Launch: New API Features</title>
                             <link>https://example.buttercms.com/blog/product-launch-new-api-features</link>
                             <media:content medium="image" url="https://cdn.buttercms.com/featured/product-launch.jpg"/>
                             <dc:creator xmlns:dc="http://purl.org/dc/elements/1.1/">Product Team</dc:creator>
                             <pubDate>Wed, 10 Jan 2024 15:30:00 +0000</pubDate>
                             <guid>https://example.buttercms.com/blog/product-launch-new-api-features</guid>
                             <description>Announcing exciting new API features and improvements in our latest release.</description>
                             <content:encoded>
                            <![CDATA[<h2>What's New</h2><p>We're excited to announce several new API features that will enhance your development experience...</p>]]>
                          </content:encoded>
                          </item>
                       </channel>
                    </rss>
        '401':
          $ref: '#/components/responses/UnauthorizedXmlResponse'
        '404':
          description: Not Found - Invalid feed type or no posts found
          content:
            application/xml:
              schema:
                type: string
                format: xml
                description: Error response when feed type is invalid
              examples:
                feed_not_found:
                  summary: Invalid feed type
                  value: |
                    <?xml version="1.0" encoding="UTF-8"?>
                    <error>Feed type not found</error>
      security:
        - readTokenAuth: []
  /feeds/atom/:
    get:
      tags:
        - Feeds & Utilities
      summary: Atom Feed
      operationId: getAtomFeed
      description: >
        Generate a fully compliant Atom 1.0 XML feed for your blog content,
        offering an alternative syndication format with rich metadata support.
        This endpoint is ideal for feed readers that prefer the Atom standard
        and applications requiring detailed content metadata.


        **Atom 1.0 Compliance**: Produces a standards-compliant Atom 1.0 XML
        feed with enhanced metadata support compared to RSS. The feed includes
        detailed author information, updated timestamps, content types, and rich
        linking relationships.


        **Filtering Capabilities**: Apply category or tag filters to generate
        specialized Atom feeds for specific content topics. This enables you to
        provide targeted content syndication for different audiences or subject
        areas.
      parameters:
        - $ref: '#/components/parameters/auth_token'
        - name: category_slug
          in: query
          required: false
          schema:
            type: string
          description: >
            Filter the Atom feed to include only posts from a specific category.


            Provide the URL-friendly slug of the category. When specified, only
            blog posts assigned to this category will be included in the Atom
            feed.
          example: announcements
        - name: tag_slug
          in: query
          required: false
          schema:
            type: string
          description: >
            Filter the Atom feed to include only posts with a specific tag.


            Provide the URL-friendly slug of the tag. When specified, only blog
            posts tagged with this tag will be included in the Atom feed.
          example: product-updates
      responses:
        '200':
          description: Atom feed generated successfully
          content:
            application/xml:
              schema:
                type: string
                format: xml
                description: Complete Atom 1.0 XML feed with blog posts
              examples:
                atom_feed:
                  summary: Standard Atom feed with blog posts
                  value: |
                    <?xml version="1.0" encoding="UTF-8"?>
                    <feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en-us">
                       <title>Latest blog posts</title>
                       <link href="https://example.buttercms.com/blog/rss/" rel="alternate" />
                       <link href="https://example.buttercms.com/blog/atom/" rel="self" />
                       <id>https://example.buttercms.com/blog/rss/</id>
                       <updated>2024-01-15T10:00:00Z</updated>
                       <entry>
                          <title>API Development Best Practices for 2024</title>
                          <link href="https://example.buttercms.com/blog/api-development-best-practices" rel="alternate" />
                          <published>2024-01-15T10:00:00Z</published>
                          <updated>2024-01-15T10:00:00Z</updated>
                          <author>
                             <name>John Developer</name>
                          </author>
                          <id>https://example.buttercms.com/blog/api-development-best-practices</id>
                          <summary type="html">Learn the essential best practices for building scalable and maintainable APIs in 2024.</summary>
                       </entry>
                       <entry>
                          <title>RESTful API Design Principles</title>
                          <link href="https://example.buttercms.com/blog/restful-api-design-principles" rel="alternate" />
                          <published>2024-01-12T09:00:00Z</published>
                          <updated>2024-01-12T09:00:00Z</updated>
                          <author>
                             <name>Sarah Architect</name>
                          </author>
                          <id>https://example.buttercms.com/blog/restful-api-design-principles</id>
                          <summary type="html">Master the fundamental principles of RESTful API design for better developer experience.</summary>
                       </entry>
                    </feed>
                filtered_by_tag:
                  summary: Atom feed filtered by tag
                  value: |
                    <?xml version="1.0" encoding="UTF-8"?>
                    <feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en-us">
                       <title>Latest blog posts</title>
                       <link href="https://example.buttercms.com/blog/rss/" rel="alternate" />
                       <link href="https://example.buttercms.com/blog/atom/" rel="self" />
                       <id>https://example.buttercms.com/blog/rss/</id>
                       <updated>2024-01-10T15:30:00Z</updated>
                       <entry>
                          <title>New Features in Our API</title>
                          <link href="https://example.buttercms.com/blog/new-features-in-our-api" rel="alternate" />
                          <published>2024-01-10T15:30:00Z</published>
                          <updated>2024-01-10T15:30:00Z</updated>
                          <author>
                             <name>Product Team</name>
                          </author>
                          <id>https://example.buttercms.com/blog/new-features-in-our-api</id>
                          <summary type="html">Announcing exciting new API features and improvements in our latest release.</summary>
                       </entry>
                    </feed>
        '401':
          $ref: '#/components/responses/UnauthorizedXmlResponse'
        '404':
          description: Not Found - Invalid feed type or no posts found
          content:
            application/xml:
              schema:
                type: string
                format: xml
                description: Error response when feed type is invalid
              examples:
                feed_not_found:
                  summary: Invalid feed type
                  value: |
                    <?xml version="1.0" encoding="UTF-8"?>
                    <error>Feed type not found</error>
      security:
        - readTokenAuth: []
  /feeds/sitemap/:
    get:
      tags:
        - Feeds & Utilities
      summary: Sitemap
      operationId: getSitemap
      description: >
        Generate a comprehensive XML sitemap for your blog posts, optimized for
        search engine discovery and indexing. This endpoint creates a
        standards-compliant sitemap that helps search engines efficiently crawl
        and index your blog content.


        **SEO Optimization**: Produces an XML sitemap following the sitemaps.org
        protocol that includes post URLs, last modification dates, and change
        frequency information. This helps search engines understand your content
        structure and prioritize crawling of updated content.


        **Filtering for Focused Sitemaps**: Apply category or tag filters to
        create specialized sitemaps for specific content sections. This is
        useful for large blogs where you want to submit targeted sitemaps to
        search engines or create separate indexing strategies for different
        content types.
      parameters:
        - $ref: '#/components/parameters/auth_token'
        - name: category_slug
          in: query
          required: false
          schema:
            type: string
          description: >
            Filter the sitemap to include only posts from a specific category.


            Provide the URL-friendly slug of the category. When specified, only
            blog posts assigned to this category will be included in the
            sitemap.
          example: announcements
        - name: tag_slug
          in: query
          required: false
          schema:
            type: string
          description: >
            Filter the sitemap to include only posts with a specific tag.


            Provide the URL-friendly slug of the tag. When specified, only blog
            posts tagged with this tag will be included in the sitemap.
          example: seo-tips
      responses:
        '200':
          description: XML sitemap generated successfully
          content:
            application/xml:
              schema:
                type: string
                format: xml
                description: Complete XML sitemap with blog post URLs
              examples:
                standard_sitemap:
                  summary: Standard XML sitemap with blog posts
                  value: >
                    <?xml version="1.0" encoding="UTF-8"?>

                    <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9
                    http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd">
                      <url>
                        <loc>https://example.buttercms.com/blog/api-development-best-practices</loc>
                        <lastmod>2024-01-15</lastmod>
                      </url>
                      <url>
                        <loc>https://example.buttercms.com/blog/restful-api-design-principles</loc>
                        <lastmod>2024-01-12</lastmod>
                      </url>
                      <url>
                        <loc>https://example.buttercms.com/blog/microservices-architecture-guide</loc>
                        <lastmod>2024-01-10</lastmod>
                      </url>
                      <url>
                        <loc>https://example.buttercms.com/blog/database-optimization-techniques</loc>
                        <lastmod>2024-01-08</lastmod>
                      </url>
                    </urlset>
                filtered_by_category:
                  summary: Sitemap filtered by category
                  value: >
                    <?xml version="1.0" encoding="UTF-8"?>

                    <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9
                    http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd">
                      <url>
                        <loc>https://example.buttercms.com/blog/new-api-features-released</loc>
                        <lastmod>2024-01-10</lastmod>
                      </url>
                      <url>
                        <loc>https://example.buttercms.com/blog/product-roadmap-update</loc>
                        <lastmod>2024-01-05</lastmod>
                      </url>
                    </urlset>
        '401':
          $ref: '#/components/responses/UnauthorizedXmlResponse'
        '404':
          description: Not Found - Invalid feed type or no posts found
          content:
            application/xml:
              schema:
                type: string
                format: xml
                description: Error response when feed type is invalid
              examples:
                feed_not_found:
                  summary: Invalid feed type
                  value: |
                    <?xml version="1.0" encoding="UTF-8"?>
                    <error>Feed type not found</error>
      security:
        - readTokenAuth: []
components:
  securitySchemes:
    readTokenAuth:
      type: apiKey
      in: query
      name: auth_token
      description: >
        Read API authentication is performed by passing your API token via the
        `auth_token` parameter on every request: `?auth_token=your_api_token`.
        You can access your API token from your settings page.


        Requests made with a missing or invalid token will get a 401
        Unauthorized response. All requests must be made over HTTPS.
    writeTokenAuth:
      type: http
      scheme: Token
      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.
  schemas:
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message describing what went wrong
          example: Authentication credentials were not provided
    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
    PaginationMeta:
      type: object
      properties:
        previous_page:
          type:
            - integer
            - 'null'
          description: Previous page number if it exists
        next_page:
          type:
            - integer
            - 'null'
          description: Next page number if it exists
        count:
          type: integer
          description: Total number of items
    OffsetPaginationMeta:
      type: object
      description: Pagination metadata for limit/offset pagination
      properties:
        count:
          type: integer
          description: Total number of items
          example: 25
        next_offset:
          type:
            - integer
            - 'null'
          description: Offset for the next page, null if no next page
          example: 20
        previous_offset:
          type:
            - integer
            - 'null'
          description: Offset for the previous page, null if no previous page
          example: null
    PageObject:
      type: object
      description: A single page object that can be either a Single Page or Page Type page
      properties:
        slug:
          type: string
          description: Unique identifier
          example: example-news-page
        name:
          type: string
          description: Name of the Page
          example: Example News Page
        page_type:
          type:
            - string
            - 'null'
          description: >-
            API slug identifier of the page_type for the Page. null for Single
            Pages
          example: news
        published:
          type:
            - string
            - 'null'
          format: date-time
          description: Timestamp of when the page was first published
          example: '2019-11-12T17:23:53.109696Z'
        updated:
          type: string
          format: date-time
          description: Timestamp of when the page was most recently published
          example: '2020-10-22T20:07:52.965850Z'
        scheduled:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Timestamp of when the page is scheduled to be published. If not
            scheduled, this field will be null
          example: null
        status:
          type: string
          enum:
            - published
            - draft
            - scheduled
          description: Status of the current version of the page
          example: published
        fields:
          type: object
          description: >-
            Contains all of the actual content for the Page - fields are
            customizable
          additionalProperties: true
          example:
            seo:
              title: Example News Page
              description: SEO Description
              keywords: SEO, Keywords
            headline: This is an example news page
            sections:
              - fields:
                  headline: ...
                  subheadline: ...
                  call_to_action: ...
                type: hero
    SinglePage:
      type: object
      properties:
        slug:
          type: string
          description: Unique identifier
          example: single-page-1
        page_type:
          type:
            - string
            - 'null'
          description: Page type - null for single pages
          example: null
        published:
          type: string
          format: date-time
          description: Timestamp of when the page was first published
          example: '2019-11-12T17:23:53.109696Z'
        updated:
          type: string
          format: date-time
          description: Timestamp of when the page was most recently published
          example: '2020-10-22T20:07:52.965850Z'
        fields:
          type: object
          description: >-
            Contains all of the actual content for the Page - fields are
            customizable
          additionalProperties: true
          example:
            title: This is a single page
            body: <p>Single PAGE!</p>
    PageTypePage:
      type: object
      properties:
        slug:
          type: string
          description: Unique identifier
          example: example-news-page
        name:
          type: string
          description: Name of the Page
          example: Example News Page
        page_type:
          type: string
          description: API slug identifier of the page_type for the Page
          example: news
        published:
          type: string
          format: date-time
          description: Timestamp of when the page was first published
          example: '2019-11-12T17:23:53.109696Z'
        updated:
          type: string
          format: date-time
          description: Timestamp of when the page was most recently published
          example: '2020-10-22T20:07:52.965850Z'
        fields:
          type: object
          description: >-
            Contains all of the actual content for the Page - fields are
            customizable
          additionalProperties: true
          example:
            seo:
              title: Example News Page
              description: SEO Description
              keywords: SEO, Keywords
            headline: This is an example news page
            tag: example
            genre: api
    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.
    UpdatePageRequest:
      type: object
      description: >
        **Flexible request schema for updating 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`)


        **Partial Updates**: You only need to specify the fields you want to
        update.

        Note: Pages accept both PATCH and PUT; PUT behaves like PATCH (partial
        update).


        **Immutable Fields**: Cannot update `title` or `slug` via PATCH.


        **Field Name Flexibility**: You can use either `title` or `name` in the
        request - both are accepted and `name` will be automatically converted
        to `title`.
      properties:
        title:
          type: string
          description: >
            The title of the page. Note: This field cannot be updated via PATCH
            - it's included here for documentation completeness only.


            **Alternative**: You can also use `name` which will be automatically
            converted to `title`.
        status:
          type: string
          enum:
            - draft
            - published
          description: >
            Status of the update. Can be 'draft' or 'published'. Defaults to
            'draft'. Setting to 'published' will make your update live
            immediately.


            Note: If `scheduled` timestamp or status is passed, these fields
            will be ignored to allow updating already scheduled pages.
          example: draft
        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.

            - **Partial update behavior**
              - Only specify the fields you want to update; omitted fields remain unchanged.
              - Repeater fields must be replaced in full; delta changes are not supported. If you need
                to clear a repeater, provide an empty array (`[]`).
              - Images and media can be updated by providing remote URLs.

            - **Examples**: See the Examples section below for sample request
            bodies.
    PageWebhookData:
      type: object
      description: Webhook data payload for page events
      properties:
        id:
          type: string
          description: Page slug
          example: example-page-slug
        buttercms_id:
          type: integer
          description: Page numeric ID
          example: 1234
        page_type:
          type: string
          description: Page type key, or '*' for single pages
          example: news
        editor:
          type: string
          description: Full name of the editor who made the change
          example: John Doe
        name:
          type: string
          description: Human-readable page name
          example: Example Page
        timestamp:
          type: string
          description: Current timestamp when webhook was generated
          example: '2024-01-15T18:11:09'
        locale:
          type:
            - string
            - 'null'
          description: Locale code for localized content, null for default locale
          example: en
        status:
          type: string
          description: Current page status
          enum:
            - draft
            - published
            - scheduled
            - deleted
          example: published
        updated:
          type: string
          format: date-time
          description: Last updated timestamp in ISO 8601 format
          example: '2024-01-15T18:11:09.791061Z'
        published:
          type:
            - string
            - 'null'
          format: date-time
          description: Published timestamp in ISO 8601 format, null if not published
          example: '2024-01-15T18:10:00.000000Z'
        scheduled:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Scheduled publication timestamp in ISO 8601 format, null if not
            scheduled
          example: null
      required:
        - id
        - buttercms_id
        - page_type
        - editor
        - name
        - timestamp
        - status
        - updated
    SinglePageResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PageObject'
    SinglePagesResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/PaginationMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/SinglePage'
    CollectionItemObject:
      type: object
      description: Individual collection item with dynamic field structure and metadata
      properties:
        meta:
          $ref: '#/components/schemas/CollectionItemMeta'
      additionalProperties: true
      example:
        meta:
          id: 123
        name: The Beatles
        genre: Rock
        formed_year: 1960
        members:
          - John Lennon
          - Paul McCartney
          - George Harrison
          - Ringo Starr
        description: Legendary British rock band
    CollectionItemMeta:
      type: object
      description: Metadata for collection items containing unique identifier
      properties:
        id:
          type: integer
          description: >-
            Unique identifier for the collection item, used for updates and
            deletions
          example: 123
      required:
        - id
    CollectionItemStatus:
      type: string
      enum:
        - published
        - draft
      default: draft
      description: |
        Status of the collection item:

        - **draft**: Item is saved but not publicly available
        - **published**: Item is live and publicly accessible

        Defaults to "draft" if not specified.
      example: published
    CollectionPaginationMeta:
      type: object
      description: Pagination metadata for collection retrieval
      properties:
        count:
          type: integer
          description: Total number of items in the collection (across all pages)
          example: 150
        next_page:
          type:
            - integer
            - 'null'
          description: Next page number if more pages exist, null if this is the last page
          example: 3
        previous_page:
          type:
            - integer
            - 'null'
          description: >-
            Previous page number if previous pages exist, null if this is the
            first page
          example: 1
    CreateCollectionItemRequest:
      type: object
      required:
        - key
        - fields
      properties:
        key:
          type: string
          description: |
            The unique identifier/slug of the Collection to create an item in.

            Must match an existing collection in your organization.
          example: team_members
        status:
          $ref: '#/components/schemas/CollectionItemStatus'
        fields:
          type: array
          description: >
            Array of collection item data. Structure varies based on locale
            configuration:


            - **Without Locales**: Array of objects with direct field key-value
            pairs

            - **With Locales**: Array of objects with locale codes as keys,
            containing field data


            **Dynamic Nature**: Field names and types are defined by your
            collection schema and can vary completely between collections.
          items:
            type: object
            description: >
              **Flexible collection item data - supports both single-locale and
              multi-locale formats.**


              System automatically detects the format based on the structure of
              the object:


              **Without Locales Format**: Direct field properties (e.g., `name`,
              `position`, `bio`)

              **With Locales Format**: Locale codes as keys (e.g., `en`, `es`,
              `fr`)


              **Dynamic Schema**: Field names and types are completely
              user-defined based on your collection configuration.
            additionalProperties: true
          minItems: 1
          example:
            - name: John Smith
              position: Senior Developer
              email: john@company.com
    UpdateCollectionItemRequest:
      type: object
      description: >
        **Flexible request schema for updating collection items - supports both
        single-locale and multi-locale formats.**


        **Update Types**:

        - **PUT**: Requires `fields` for full replacement

        - **PATCH**: `fields` is optional for partial updates (e.g., status-only
        updates)
      properties:
        status:
          $ref: '#/components/schemas/CollectionItemStatus'
          description: |
            Publication status of the collection item.

            - If omitted in PATCH requests, the current status is preserved
            - If provided in PUT/PATCH requests, the status will be updated
        fields:
          type: object
          description: >
            **Optional for PATCH, Required for PUT**. Collection item field data
            with flexible format support.


            System automatically detects the format based on the structure of
            the object:


            **Without Locales Format**: Direct field properties (e.g., `name`,
            `position`, `bio`)

            **With Locales Format**: Locale codes as keys (e.g., `en`, `es`,
            `fr`)


            **Update Behavior**:

            - **PUT**: All fields should be provided (full replacement)

            - **PATCH**: Only provided fields are updated, others remain
            unchanged


            **Dynamic Schema**: Field names and types are completely
            user-defined based on your collection configuration.


            **Reference Fields**: Support updating relationships to Pages and
            other Collections

            - Page references: Use page slugs (e.g., `"related_page":
            "example-slug"`)

            - Collection references: Use collection item IDs (e.g., `"tags": [1,
            2, 3]`)

            - Remove references: Use `""`, `[]`, or `null`


            **Media Fields**: Support remote URL upload - content is
            automatically uploaded to ButterCMS
          additionalProperties: true
          example:
            name: Updated Team Member Name
            position: Lead Developer
            bio: Updated biography content
    CreateCollectionItemResponse:
      type: object
      description: Response for successful collection item creation (202 Accepted)
      properties:
        status:
          type: string
          enum:
            - pending
          description: >-
            Indicates that the collection item creation is being processed
            asynchronously
          example: pending
    UpdateSuccessResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - pending
          description: >-
            Indicates that the page update request has been accepted and is
            being processed asynchronously
          example: pending
      additionalProperties:
        type: string
        description: Warning messages for fields that were ignored during the update
      example:
        status: pending
        'warning: scheduled field': >-
          Scheduled timestamps cannot be created or altered via write API. This
          field will be ignored.
    CollectionItemWebhookData:
      type: object
      description: Webhook data payload for collection item events
      properties:
        id:
          type: string
          description: Collection key identifier
          example: your_collection
        itemid:
          type: string
          description: API URI for retrieving the specific collection item
          example: /v2/content/?keys=your_collection[_id=1234]
        label:
          type: string
          description: Display label for the collection item
          example: Your Collection Item
        editor:
          type: string
          description: Full name of the editor who made the change
          example: John Doe
        timestamp:
          type: string
          description: Current timestamp when webhook was generated
          example: '2024-01-15T18:11:09'
        locale:
          type:
            - string
            - 'null'
          description: Locale code for localized content, null for default locale
          example: en
        status:
          type: string
          description: Current collection item status
          enum:
            - draft
            - published
            - deleted
          example: published
      required:
        - id
        - itemid
        - label
        - editor
        - timestamp
    BlogPostObject:
      type: object
      description: Complete blog post object with all fields and related data
      properties:
        url:
          type: string
          format: uri
          description: Full URL to the blog post
          example: http://www.example.com/blog/this-is-a-blog-post
        created:
          type: string
          format: date-time
          description: Timestamp when the blog post was created
          example: '2020-10-08T18:29:19.987936Z'
        updated:
          type: string
          format: date-time
          description: Timestamp when the blog post was last updated
          example: '2020-10-09T15:49:54.580309Z'
        published:
          type:
            - string
            - 'null'
          format: date-time
          description: Timestamp when the blog post was published
          example: '2020-10-08T18:08:00Z'
        author:
          $ref: '#/components/schemas/BlogPostAuthorObject'
        categories:
          type: array
          items:
            $ref: '#/components/schemas/CategoryObject'
          description: Array of categories assigned to the blog post
        tags:
          type: array
          items:
            $ref: '#/components/schemas/TagObject'
          description: Array of tags assigned to the blog post
        featured_image:
          type:
            - string
            - 'null'
          format: uri
          description: URL to the featured image, null if no featured image
          example: null
        featured_image_alt:
          type: string
          description: Alt text for the featured image
          example: ''
        slug:
          type: string
          description: URL-friendly slug for the blog post
          example: this-is-a-blog-post
        title:
          type: string
          description: Title of the blog post
          example: This is a blog post
        body:
          type: string
          description: HTML content body of the blog post (excluded if exclude_body=true)
          example: <p class="">This is a blog post to test the API.</p>
        summary:
          type: string
          description: Plain text summary of the blog post
          example: This is a blog post to test the API.
        seo_title:
          type: string
          description: SEO-optimized title for the blog post
          example: This is a blog post
        meta_description:
          type: string
          description: Meta description for SEO and social sharing
          example: This is a blog post to test the API.
        status:
          type: string
          enum:
            - draft
            - published
            - scheduled
          description: Publication status of the blog post
          example: published
        scheduled:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Timestamp when the blog post is scheduled to be published. If not
            scheduled, this field will be null
          example: null
    BlogPostSearchResult:
      type: object
      description: Blog post object with search relevance ranking
      properties:
        url:
          type: string
          format: uri
          description: Full URL to the blog post
          example: https://api.buttercms.com/blog/api-development-best-practices
        created:
          type: string
          format: date-time
          description: Creation date and time in ISO 8601 format
          example: '2024-01-15T08:30:00.000Z'
        published:
          type: string
          format: date-time
          description: Publication date and time in ISO 8601 format
          example: '2024-01-15T10:00:00.000Z'
        author:
          $ref: '#/components/schemas/BlogPostAuthorObject'
          description: Author information
        categories:
          type: array
          items:
            $ref: '#/components/schemas/CategoryObject'
          description: Array of category objects
        tags:
          type: array
          items:
            $ref: '#/components/schemas/TagObject'
          description: Array of tag objects
        featured_image:
          type:
            - string
            - 'null'
          format: uri
          description: CDN URL of the featured image, null if no image
          example: https://cdn.buttercms.com/featured/api-guide.jpg
        featured_image_alt:
          type: string
          description: Alt text for the featured image
          example: API Development Guide
        slug:
          type: string
          description: URL-friendly slug identifier
          example: api-development-best-practices
        title:
          type: string
          description: Blog post title
          example: API Development Best Practices for 2024
        body:
          type: string
          description: Full HTML content of the blog post (excluded when exclude_body=true)
          example: >-
            <h2>Introduction</h2><p>Building robust APIs requires following
            established best practices...</p>
        summary:
          type: string
          description: Summary or excerpt of the blog post
          example: >-
            Learn the essential best practices for building scalable and
            maintainable APIs in 2024.
        seo_title:
          type: string
          description: SEO-optimized title
          example: API Development Best Practices for 2024
        meta_description:
          type: string
          description: Meta description for SEO
          example: >-
            Complete guide to API development best practices including REST
            design, authentication, and documentation.
        status:
          type: string
          enum:
            - published
          description: Publication status (only published posts appear in search results)
          example: published
        rank:
          type: number
          format: float
          description: Search relevance score (higher values indicate better matches)
          example: 0.8573
          minimum: 0
          maximum: 1
    CreateBlogPostRequest:
      type: object
      description: Request schema for creating a new blog post
      required:
        - title
      properties:
        title:
          type: string
          description: The title of the blog post
          maxLength: 200
          example: This is a blog post
        slug:
          type: string
          description: >
            The slug of the blog post (must be unique).


            **Auto-Generation**: If not provided, the slug will be automatically
            generated from the title using unicode slugification. You can
            provide a custom slug or let the API generate one for you.
          maxLength: 100
          example: this-is-a-blog-post
        status:
          type: string
          description: The status of the post. Defaults to 'draft'. Cannot be 'scheduled'.
          enum:
            - draft
            - published
          default: draft
          example: published
        author:
          $ref: '#/components/schemas/BlogPostAuthor'
        categories:
          type: array
          description: >-
            Array of category names. Categories will be created if they don't
            exist.
          items:
            type: string
          example:
            - Recipes
            - Meals
        tags:
          type: array
          description: Array of tag names. Tags will be created if they don't exist.
          items:
            type: string
          example:
            - Butter
            - Sushi
            - Really Good Recipes
        featured_image:
          type: string
          format: uri
          description: >
            Can be a remote URL to an image.


            The image will always be uploaded to the media library (the value of
            `upload_images_to_media_library` is ignored for featured images).
          example: https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg
        featured_image_alt:
          type: string
          description: Alt text for the featured image
          maxLength: 250
          example: Featured image alt text example.
        body:
          type: string
          description: >
            Should be a string of escaped HTML.


            In case it contains any remote URLs to images, the
            `upload_images_to_media_library` flag controls the behavior.
          example: <h1>Butter</h1><p>I am so hungry!</p>
        summary:
          type: string
          description: Plain-text summary of the blog post
          maxLength: 2000
          example: This is a blog post summary.
        seo_title:
          type: string
          description: SEO title for HTML title tag
          maxLength: 100
          example: This is a blog post
        meta_description:
          type: string
          description: Meta description for SEO and social sharing
          example: This is a blog post to test the API.
        upload_images_to_media_library:
          type: boolean
          description: >
            Defaults to `false`.


            If set to `true`, any image URLs in the `body` property will be
            uploaded to the Butter Media Library and the original URL will be
            replaced with the media library URL.


            **Note**: Featured images are always uploaded regardless of this
            setting.
          default: false
          example: false
    UpdateBlogPostRequest:
      type: object
      description: >
        Request schema for updating an existing blog post. All fields are
        optional for partial updates.


        **Note**: If `scheduled` timestamp or `status: "scheduled"` are
        provided, they will be ignored and warning messages will be included in
        the response.
      properties:
        title:
          type: string
          description: The title of the blog post
          maxLength: 200
          example: Updated Blog Post Title
        slug:
          type: string
          description: >
            The slug of the blog post.


            **Auto-Slugification**: The API automatically converts your input to
            a valid slug format using unicode slugification.
          maxLength: 100
          example: updated-blog-post-slug
        status:
          type: string
          description: >
            The status of the post.


            **Note**: `"scheduled"` status will be ignored and a warning message
            will be included in the response.
          enum:
            - draft
            - published
            - scheduled
          example: published
        author:
          $ref: '#/components/schemas/BlogPostAuthor'
        categories:
          type: array
          description: >-
            Array of category names. Categories will be created if they don't
            exist.
          items:
            type: string
          example:
            - Updated Category
            - New Category
        tags:
          type: array
          description: Array of tag names. Tags will be created if they don't exist.
          items:
            type: string
          example:
            - updated
            - refresh
            - api
        featured_image:
          type: string
          format: uri
          description: >
            Can be a remote URL to an image.


            The image will always be uploaded to the media library (the value of
            `upload_images_to_media_library` is ignored for featured images).
          example: https://example.com/updated-featured-image.jpg
        featured_image_alt:
          type: string
          description: Alt text for the featured image
          maxLength: 250
          example: Updated featured image alt text.
        body:
          type: string
          description: >
            Should be a string of escaped HTML.


            In case it contains any remote URLs to images, the
            `upload_images_to_media_library` flag controls the behavior.
          example: <h1>Updated Content</h1><p>This blog post was updated via API</p>
        summary:
          type: string
          description: Plain-text summary of the blog post
          maxLength: 2000
          example: Updated summary of the blog post.
        seo_title:
          type: string
          description: SEO title for HTML title tag
          maxLength: 100
          example: Updated SEO Title
        meta_description:
          type: string
          description: Meta description for SEO and social sharing
          example: Updated meta description for better SEO.
        upload_images_to_media_library:
          type: boolean
          description: >
            Defaults to `false`.


            If set to `true`, any image URLs in the `body` property will be
            uploaded to the Butter Media Library and the original URL will be
            replaced with the media library URL.


            **Note**: Featured images are always uploaded regardless of this
            setting.
          default: false
          example: true
        scheduled:
          type: string
          format: date-time
          description: >
            **Note**: This field will be ignored - scheduled timestamps cannot
            be created or altered via write API.


            If provided, this field will be removed from the request and a
            warning message will be included in the response.
          example: '2024-12-25T10:00:00Z'
    BlogPostCreateSuccessResponse:
      type: object
      description: Success response for blog post creation (202 Accepted)
      properties:
        status:
          type: string
          enum:
            - pending
          description: >-
            Indicates that the blog post creation is being processed
            asynchronously
          example: pending
    BlogPostUpdateSuccessResponse:
      type: object
      description: >
        Success response for blog post updates (202 Accepted). May include
        warning messages for ignored fields.
      properties:
        status:
          type: string
          enum:
            - pending
          description: >-
            Indicates that the blog post update is being processed
            asynchronously
          example: pending
        'warning: scheduled field':
          type: string
          description: Warning message when scheduled field is ignored
          example: >-
            Scheduled timestamps cannot be created or altered via write API.
            This field will be ignored.
        'warning: status field':
          type: string
          description: Warning message when scheduled status is ignored
          example: >-
            A blog post's status cannot be set as `scheduled` via write API at
            this time. This field will be ignored.
      additionalProperties:
        type: string
        description: Additional warning messages for other ignored fields
    PageBasedPostsResponse:
      type: object
      description: Blog posts response using page-based pagination (default)
      properties:
        meta:
          $ref: '#/components/schemas/PaginationMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BlogPostObject'
          description: Array of blog post objects sorted by publish date (newest first)
      required:
        - meta
        - data
    OffsetBasedPostsResponse:
      type: object
      description: Blog posts response using offset-based pagination (alternative)
      properties:
        meta:
          $ref: '#/components/schemas/OffsetPaginationMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BlogPostObject'
          description: Array of blog post objects sorted by publish date (newest first)
      required:
        - meta
        - data
    RetrieveSinglePostResponse:
      type: object
      description: Response for retrieving a single blog post with navigation metadata
      properties:
        meta:
          $ref: '#/components/schemas/SinglePostMeta'
        data:
          $ref: '#/components/schemas/BlogPostObject'
          description: Complete blog post object with all fields and related data
    PageBasedSearchResponse:
      type: object
      description: Blog post search response using page-based pagination
      properties:
        meta:
          $ref: '#/components/schemas/PaginationMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BlogPostSearchResult'
          description: Array of blog post search results with relevance ranking
      required:
        - meta
        - data
    OffsetBasedSearchResponse:
      type: object
      description: Blog post search response using offset-based pagination
      properties:
        meta:
          $ref: '#/components/schemas/OffsetPaginationMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BlogPostSearchResult'
          description: Array of blog post search results with relevance ranking
      required:
        - meta
        - data
    PageBasedCollectionResponse:
      type: object
      description: Collection response using page-based pagination
      properties:
        meta:
          $ref: '#/components/schemas/CollectionPaginationMeta'
        data:
          type: object
          description: Collection data object with dynamic key based on collection name
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/CollectionItemObject'
      required:
        - meta
        - data
    OffsetBasedCollectionResponse:
      type: object
      description: Collection response using offset-based pagination
      properties:
        meta:
          $ref: '#/components/schemas/OffsetPaginationMeta'
        data:
          type: object
          description: Collection data object with dynamic key based on collection name
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/CollectionItemObject'
      required:
        - meta
        - data
    PageBasedPagesResponse:
      type: object
      description: Page type response using page-based pagination
      properties:
        meta:
          $ref: '#/components/schemas/PaginationMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/PageTypePage'
      required:
        - meta
        - data
    OffsetBasedPagesResponse:
      type: object
      description: Page type response using offset-based pagination
      properties:
        meta:
          $ref: '#/components/schemas/OffsetPaginationMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/PageTypePage'
      required:
        - meta
        - data
    PageBasedPageSearchResponse:
      type: object
      description: Page search response using page-based pagination
      properties:
        meta:
          $ref: '#/components/schemas/PaginationMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/PageObject'
          description: Array of pages matching the search query, sorted by relevancy
      required:
        - meta
        - data
    OffsetBasedPageSearchResponse:
      type: object
      description: Page search response using offset-based pagination
      properties:
        meta:
          $ref: '#/components/schemas/OffsetPaginationMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/PageObject'
          description: Array of pages matching the search query, sorted by relevancy
      required:
        - meta
        - data
    PostNavigationObject:
      type: object
      description: Navigation object containing essential information for blog post links
      properties:
        slug:
          type: string
          description: URL-friendly slug of the post for navigation
          example: google-analytics-is-now-integrated-with-your-butter-blog
        title:
          type: string
          description: Title of the post for display in navigation
          example: Google Analytics is now integrated with your Butter blog
        featured_image:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            URL to the featured image for navigation thumbnails, null if no
            featured image
          example: https://d2devwt40at1e2.cloudfront.net/api/file/etSDYJUIFDADGEEAQ/
    SinglePostMeta:
      type: object
      description: Navigation metadata for single blog post responses
      properties:
        next_post:
          anyOf:
            - $ref: '#/components/schemas/PostNavigationObject'
            - type: 'null'
          description: Next blog post for navigation, null if no next post exists
        previous_post:
          anyOf:
            - $ref: '#/components/schemas/PostNavigationObject'
            - type: 'null'
          description: Previous blog post for navigation, null if no previous post exists
    BlogPostWebhookData:
      type: object
      description: Webhook data payload for blog post events
      properties:
        id:
          type: string
          description: Blog post slug
          example: example-blog-post-slug
        _id:
          type: integer
          description: Blog post numeric ID
          example: 1234
      required:
        - id
        - _id
    AuthorObject:
      type: object
      description: Complete author information with optional recent posts
      properties:
        slug:
          type: string
          description: Unique identifier/slug for the author
          example: api-test
        first_name:
          type: string
          description: Author's first name
          example: API
        last_name:
          type: string
          description: Author's last name
          example: Test
        email:
          type: string
          format: email
          description: Author's email address
          example: apitest@buttercms.com
        bio:
          type: string
          description: Author's biography/description
          example: This is my bio.
        title:
          type: string
          description: Author's professional title
          example: API
        linkedin_url:
          type:
            - string
            - 'null'
          format: uri
          description: Author's LinkedIn profile URL
          example: https://www.linkedin.com/in/API
        facebook_url:
          type:
            - string
            - 'null'
          format: uri
          description: Author's Facebook profile URL
          example: https://www.facebook.com/API
        pinterest_url:
          type:
            - string
            - 'null'
          format: uri
          description: Author's Pinterest profile URL
          example: https://www.pinterest.com/API
        instagram_url:
          type:
            - string
            - 'null'
          format: uri
          description: Author's Instagram profile URL
          example: https://www.instagram.com/API
        twitter_handle:
          type: string
          description: Author's Twitter handle (without @ symbol)
          example: buttercmsapi
        profile_image:
          type:
            - string
            - 'null'
          format: uri
          description: CDN URL of author's profile image
          example: https://buttercms.com/api.png
        recent_posts:
          type: array
          items:
            $ref: '#/components/schemas/AuthorRecentPost'
          description: >-
            Array of recent posts by this author (only included when
            include=recent_posts parameter is used)
    BlogPostAuthor:
      type: object
      description: >
        Author reference for blog posts. Author must exist in your account prior
        to POST.


        You can specify the author either by email or by slug. If no author is
        specified, defaults to the organization owner.
      oneOf:
        - type: object
          required:
            - email
          properties:
            email:
              type: string
              format: email
              description: Email address of the existing author
              example: your@author.com
        - type: object
          required:
            - slug
          properties:
            slug:
              type: string
              description: Slug of the existing author
              example: firstname-lastname
    BlogPostAuthorObject:
      type: object
      description: Author information for blog posts
      properties:
        first_name:
          type: string
          description: Author's first name
          example: API
        last_name:
          type: string
          description: Author's last name
          example: Test
        email:
          type: string
          format: email
          description: Author's email address
          example: apitest@buttercms.com
        slug:
          type: string
          description: Author's URL-friendly slug
          example: api-test
        bio:
          type: string
          description: Author's biography
          example: This is my bio.
        title:
          type: string
          description: Author's professional title
          example: API
        linkedin_url:
          type:
            - string
            - 'null'
          format: uri
          description: Author's LinkedIn profile URL
          example: https://www.linkedin.com/in/API
        facebook_url:
          type:
            - string
            - 'null'
          format: uri
          description: Author's Facebook profile URL
          example: https://www.facebook.com/API
        twitter_handle:
          type: string
          description: Author's Twitter handle
          example: buttercmsapi
        instagram_url:
          type:
            - string
            - 'null'
          format: uri
          description: Author's Instagram profile URL
          example: https://www.instagram.com/API
        pinterest_url:
          type:
            - string
            - 'null'
          format: uri
          description: Author's Pinterest profile URL
          example: https://www.pinterest.com/API
        profile_image:
          type:
            - string
            - 'null'
          format: uri
          description: URL to author's profile image
          example: https://buttercms.com/api.png
    AuthorRecentPost:
      type: object
      description: Simplified blog post information for author's recent posts
      properties:
        slug:
          type: string
          description: Blog post slug/identifier
          example: web-development-trends-2024
        title:
          type: string
          description: Blog post title
          example: Web Development Trends in 2024
        published:
          type: string
          format: date-time
          description: Publication date and time in ISO 8601 format
          example: '2024-01-15T10:00:00.000Z'
    ListAuthorsResponse:
      type: object
      description: Response structure for listing all authors
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AuthorObject'
          description: Array of author objects
    RetrieveAuthorResponse:
      type: object
      description: Response structure for retrieving a single author
      properties:
        data:
          $ref: '#/components/schemas/AuthorObject'
          description: Single author object
    CategoryObject:
      type: object
      description: Category information for blog posts
      properties:
        name:
          type: string
          description: Display name of the category
          example: test category
        slug:
          type: string
          description: URL-friendly slug of the category
          example: test-category
    CategoryObjectWithPosts:
      type: object
      description: Category information with optional recent posts
      properties:
        name:
          type: string
          description: Display name of the category
          example: Product Updates
        slug:
          type: string
          description: URL-friendly slug of the category
          example: product-updates
        recent_posts:
          type: array
          items:
            $ref: '#/components/schemas/CategoryRecentPost'
          description: >-
            Array of recent posts in this category (only included when
            include=recent_posts parameter is used)
    CategoryRecentPost:
      type: object
      description: Simplified blog post information for category's recent posts
      properties:
        slug:
          type: string
          description: Blog post slug/identifier
          example: new-features-release
        title:
          type: string
          description: Blog post title
          example: Exciting New Features in Our Latest Release
        published:
          type: string
          format: date-time
          description: Publication date and time in ISO 8601 format
          example: '2024-01-20T10:00:00.000Z'
    ListCategoriesResponse:
      type: object
      description: Response structure for listing all categories
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CategoryObjectWithPosts'
          description: Array of category objects
    RetrieveCategoryResponse:
      type: object
      description: Response structure for retrieving a single category
      properties:
        data:
          $ref: '#/components/schemas/CategoryObjectWithPosts'
          description: Single category object
    TagObject:
      type: object
      description: Tag information for blog posts
      properties:
        name:
          type: string
          description: Display name of the tag
          example: test tag
        slug:
          type: string
          description: URL-friendly slug of the tag
          example: test-tag
    TagObjectWithPosts:
      type: object
      description: Tag information with optional recent posts
      properties:
        name:
          type: string
          description: Display name of the tag
          example: API Development
        slug:
          type: string
          description: URL-friendly slug of the tag
          example: api-development
        recent_posts:
          type: array
          items:
            $ref: '#/components/schemas/TagRecentPost'
          description: >-
            Array of recent posts with this tag (only included when
            include=recent_posts parameter is used)
    TagRecentPost:
      type: object
      description: Simplified blog post information for tag's recent posts
      properties:
        slug:
          type: string
          description: Blog post slug/identifier
          example: rest-api-best-practices
        title:
          type: string
          description: Blog post title
          example: REST API Best Practices for Modern Development
        published:
          type: string
          format: date-time
          description: Publication date and time in ISO 8601 format
          example: '2024-01-22T09:00:00.000Z'
    ListTagsResponse:
      type: object
      description: Response structure for listing all tags
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TagObjectWithPosts'
          description: Array of tag objects
    RetrieveTagResponse:
      type: object
      description: Response structure for retrieving a single tag
      properties:
        data:
          $ref: '#/components/schemas/TagObjectWithPosts'
          description: Single tag object
    WebhookMeta:
      type: object
      description: Webhook metadata included in all webhook payloads
      properties:
        event:
          type: string
          enum:
            - post.all
            - post.published
            - post.draft
            - post.delete
            - page.all
            - page.published
            - page.draft
            - page.delete
            - page.unpublished
            - collectionitem.all
            - collectionitem.published
            - collectionitem.draft
            - collectionitem.delete
            - collectionitem.unpublished
            - media.videouploaded
          description: The event type that triggered this webhook
        target:
          type: string
          format: uri
          description: The webhook endpoint URL that received this notification
      required:
        - event
        - target
  responses:
    UnauthorizedResponse:
      description: Unauthorized - Invalid or missing API token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_token:
              summary: Missing API token
              value:
                detail: Authentication credentials were not provided
            invalid_token:
              summary: Invalid API token
              value:
                detail: Invalid token
    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
    NoContentResponse:
      description: Operation completed successfully - No content returned
    CollectionItemAcceptedResponse:
      description: Collection item operation accepted for async processing
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - pending
                description: >-
                  Indicates the request was accepted and is being processed
                  asynchronously
                example: pending
          example:
            status: pending
    UnauthorizedXmlResponse:
      description: Unauthorized - Invalid or missing API token
      content:
        application/xml:
          schema:
            type: string
            format: xml
            description: Error response in XML format
          examples:
            missing_token:
              summary: Missing API token
              value: |
                <?xml version="1.0" encoding="UTF-8"?>
                <detail>Authentication credentials were not provided</detail>
            invalid_token:
              summary: Invalid API token
              value: |
                <?xml version="1.0" encoding="UTF-8"?>
                <detail>Invalid token</detail>
  parameters:
    auth_token:
      name: auth_token
      in: query
      required: true
      schema:
        type: string
      description: |
        Your ButterCMS read API token
      example: your_api_token
    preview:
      name: preview
      in: query
      description: >
        Set to 1 to return the latest draft version of a page. Useful for
        previewing changes before publishing live. i.e. `&preview=1`. If you are
        trying to view a scheduled page for which the most recent page version
        is published, you must pass the preview parameter to see the scheduled
        changes.


        Set to `1` to access unpublished/draft collection items. Useful for
        staging environments.
      required: false
      schema:
        type: integer
        enum:
          - 0
          - 1
        default: 0
      example: 1
    locale:
      name: locale
      in: query
      description: >
        Set to the api slug of your configured locale (e.g. `en` or `fr`). When
        omitted, this query parameter will default to your organization's
        default locale.
      required: false
      schema:
        type: string
        maxLength: 10
        example: en
      examples:
        english:
          value: en
          description: English locale
        spanish:
          value: es
          description: Spanish locale
        french:
          value: fr
          description: French locale
    page:
      name: page
      in: query
      description: |
        Page number for page-based pagination.

        **Mutually exclusive with limit/offset parameters.**
      required: false
      schema:
        type: integer
        default: 1
        minimum: 1
      example: 2
    page_size:
      name: page_size
      in: query
      description: |
        Number of items per page for page-based pagination.

        **Mutually exclusive with limit/offset parameters.**
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 100
      example: 5
    order:
      name: order
      in: query
      description: >
        Can order by page level `published`, `updated`, or a content field of
        the Page Type. Defaults to ascending, prepend '-' to sort descending.


        **Note**: Only available for Page Type endpoints, not for Single Pages
        (`page_type=*`).
      required: false
      schema:
        type: string
      examples:
        ascending_title:
          value: title
          description: Order by title ascending
        descending_published:
          value: '-published'
          description: Order by published date descending
        ascending_updated:
          value: updated
          description: Order by updated date ascending
    limit:
      name: limit
      in: query
      description: |
        Maximum number of items to return for offset-based pagination.

        **Mutually exclusive with page/page_size parameters.**
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
      example: 5
    offset:
      name: offset
      in: query
      description: |
        Number of items to skip before starting to return results.

        **Mutually exclusive with page/page_size parameters.**
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
      example: 10
    levels:
      name: levels
      in: query
      description: >
        Depth of relationship serialization.


        Controls how many levels of referenced content to include:

        - **1**: Direct fields only, references as URIs

        - **2**: Direct fields + one level of references (default)

        - **3-5**: Deeper relationship traversal


        **Important**: Higher levels increase response size. Maximum 10MB per
        response.


        Valid range: 1-5 (inclusive). Values outside this range will be
        automatically capped.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 5
        default: 2
      examples:
        shallow:
          value: 1
          description: Minimal depth (1 level)
        default:
          value: 2
          description: Default depth (2 levels)
        deep:
          value: 5
          description: Maximum depth (5 levels)
    alt_media_text:
      name: alt_media_text
      in: query
      description: >
        Media field response format.


        Affects only media-typed fields. Other field types are unchanged.


        - **0** (default): Media fields return simple URL strings

        - **1**: Media fields return objects with at least `url` and, when
        available,
          `alt`. If the stored media value is just a URL string, the object will
          include `url` only.
      required: false
      schema:
        type: integer
        enum:
          - 0
          - 1
        default: 0
      examples:
        url_only:
          value: 0
          description: Return media as URL strings (default)
        object_format:
          value: 1
          description: >-
            Return media as objects with at least url (alt included when
            available)
webhooks:
  page-published:
    post:
      operationId: webhookPagePublished
      summary: Page - Published
      description: |
        Triggered when a page is published or republished.

        This event fires when:
        - A draft page is published for the first time
        - An already published page is republished after changes
        - A scheduled page is automatically published
      tags:
        - Webhooks - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/PageWebhookData'
                webhook:
                  allOf:
                    - $ref: '#/components/schemas/WebhookMeta'
                    - properties:
                        event:
                          enum:
                            - page.published
            examples:
              page_published:
                summary: Page published
                value:
                  data:
                    id: product-launch
                    buttercms_id: 5678
                    page_type: landing
                    editor: Marketing Team
                    name: Product Launch Landing Page
                    timestamp: '2024-01-15T14:30:00'
                    locale: null
                    status: published
                    updated: '2024-01-15T14:30:00.123456Z'
                    published: '2024-01-15T14:30:00.123456Z'
                    scheduled: null
                  webhook:
                    event: page.published
                    target: https://yourapp.com/webhooks/buttercms
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
      security: []
  page-draft:
    post:
      operationId: webhookPageDraft
      summary: Page - Draft Saved
      description: |
        Triggered when a draft page version is saved.

        This event fires when:
        - A new page is created and saved as draft
        - An existing draft page is updated and saved
        - A published page is updated but not yet republished
      tags:
        - Webhooks - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/PageWebhookData'
                webhook:
                  allOf:
                    - $ref: '#/components/schemas/WebhookMeta'
                    - properties:
                        event:
                          enum:
                            - page.draft
            examples:
              draft_saved:
                summary: Page draft saved
                value:
                  data:
                    id: upcoming-event
                    buttercms_id: 9012
                    page_type: event
                    editor: Event Coordinator
                    name: Upcoming Conference Event
                    timestamp: '2024-01-15T16:45:00'
                    locale: en
                    status: draft
                    updated: '2024-01-15T16:45:00.987654Z'
                    published: null
                    scheduled: '2024-02-01T09:00:00.000000Z'
                  webhook:
                    event: page.draft
                    target: https://yourapp.com/webhooks/buttercms
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
      security: []
  page-unpublished:
    post:
      operationId: webhookPageUnpublished
      summary: Page - Unpublished
      description: |
        Triggered when a published page is unpublished (but not deleted).

        This event fires when:
        - A published page is deliberately unpublished but kept in the system
        - A page is temporarily taken offline without permanent deletion
      tags:
        - Webhooks - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/PageWebhookData'
                webhook:
                  allOf:
                    - $ref: '#/components/schemas/WebhookMeta'
                    - properties:
                        event:
                          enum:
                            - page.unpublished
            examples:
              page_unpublished:
                summary: Page unpublished
                value:
                  data:
                    id: maintenance-notice
                    buttercms_id: 7890
                    page_type: notice
                    editor: Site Administrator
                    name: Maintenance Notice
                    timestamp: '2024-01-15T22:00:00'
                    locale: null
                    status: draft
                    updated: '2024-01-15T22:00:00.333444Z'
                    published: null
                    scheduled: null
                  webhook:
                    event: page.unpublished
                    target: https://yourapp.com/webhooks/buttercms
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
      security: []
  page-delete:
    post:
      operationId: webhookPageDelete
      summary: Page - Deleted
      description: |
        Triggered when a published page is permanently deleted.

        This event fires when:
        - A page is permanently removed from the system
        - A page is moved to trash and then permanently deleted
      tags:
        - Webhooks - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/PageWebhookData'
                webhook:
                  allOf:
                    - $ref: '#/components/schemas/WebhookMeta'
                    - properties:
                        event:
                          enum:
                            - page.delete
            examples:
              page_deleted:
                summary: Page deleted
                value:
                  data:
                    id: old-promotion
                    buttercms_id: 3456
                    page_type: promo
                    editor: Content Manager
                    name: Old Promotion Page
                    timestamp: '2024-01-15T20:15:00'
                    locale: null
                    status: deleted
                    updated: '2024-01-15T20:15:00.111222Z'
                    published: '2024-01-10T10:00:00.000000Z'
                    scheduled: null
                  webhook:
                    event: page.delete
                    target: https://yourapp.com/webhooks/buttercms
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
      security: []
  page-all:
    post:
      operationId: webhookPageAll
      summary: Page - Any Activity
      description: >
        Triggered when any activity occurs on a page (create, update, publish,
        unpublish, delete).


        This is a catch-all event that fires for all page changes, useful for
        comprehensive page monitoring and cache invalidation across all page
        types.
      tags:
        - Webhooks - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/PageWebhookData'
                webhook:
                  allOf:
                    - $ref: '#/components/schemas/WebhookMeta'
                    - properties:
                        event:
                          enum:
                            - page.all
            examples:
              page_updated:
                summary: Page updated
                value:
                  data:
                    id: company-news
                    buttercms_id: 1234
                    page_type: news
                    editor: Jane Editor
                    name: Company News Page
                    timestamp: '2024-01-15T18:11:09'
                    locale: en
                    status: published
                    updated: '2024-01-15T18:11:09.791061Z'
                    published: '2024-01-15T18:10:00.000000Z'
                    scheduled: null
                  webhook:
                    event: page.all
                    target: https://yourapp.com/webhooks/buttercms
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
      security: []
  post-published:
    post:
      operationId: webhookPostPublished
      summary: Blog Post - Published
      description: |
        Triggered when a blog post is published or republished.

        This event fires when:
        - A draft blog post is published for the first time
        - An already published post is republished after changes
        - A scheduled post is automatically published
      tags:
        - Webhooks - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/BlogPostWebhookData'
                webhook:
                  allOf:
                    - $ref: '#/components/schemas/WebhookMeta'
                    - properties:
                        event:
                          enum:
                            - post.published
            examples:
              post_published:
                summary: Blog post published
                value:
                  data:
                    id: announcing-new-features
                    _id: 5678
                  webhook:
                    event: post.published
                    target: https://yourapp.com/webhooks/buttercms
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
      security: []
  post-draft:
    post:
      operationId: webhookPostDraft
      summary: Blog Post - Draft Saved
      description: >
        Triggered when a draft blog post is saved.


        This event fires when:

        - A new blog post is created and saved as draft

        - An existing draft is updated and saved

        - A published post is updated and saved as draft (effectively
        unpublishing)
      tags:
        - Webhooks - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/BlogPostWebhookData'
                webhook:
                  allOf:
                    - $ref: '#/components/schemas/WebhookMeta'
                    - properties:
                        event:
                          enum:
                            - post.draft
            examples:
              draft_saved:
                summary: Draft blog post saved
                value:
                  data:
                    id: work-in-progress-post
                    _id: 9012
                  webhook:
                    event: post.draft
                    target: https://yourapp.com/webhooks/buttercms
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
      security: []
  post-delete:
    post:
      operationId: webhookPostDelete
      summary: Blog Post - Deleted
      description: |
        Triggered when a published blog post is unpublished or deleted.

        This event fires when:
        - A published blog post is moved to trash
        - A published blog post is permanently deleted
        - A published blog post is unpublished (soft delete)
      tags:
        - Webhooks - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/BlogPostWebhookData'
                webhook:
                  allOf:
                    - $ref: '#/components/schemas/WebhookMeta'
                    - properties:
                        event:
                          enum:
                            - post.delete
            examples:
              post_deleted:
                summary: Blog post deleted
                value:
                  data:
                    id: outdated-announcement
                    _id: 3456
                  webhook:
                    event: post.delete
                    target: https://yourapp.com/webhooks/buttercms
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
      security: []
  post-all:
    post:
      operationId: webhookPostAll
      summary: Blog Post - Any Activity
      description: >
        Triggered when any activity occurs on a blog post (create, update,
        publish, unpublish, delete).


        This is a catch-all event that fires for all blog post changes, making
        it useful for general blog post monitoring and cache invalidation.
      tags:
        - Webhooks - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/BlogPostWebhookData'
                webhook:
                  allOf:
                    - $ref: '#/components/schemas/WebhookMeta'
                    - properties:
                        event:
                          enum:
                            - post.all
            examples:
              post_updated:
                summary: Blog post updated
                value:
                  data:
                    id: api-development-best-practices
                    _id: 1234
                  webhook:
                    event: post.all
                    target: https://yourapp.com/webhooks/buttercms
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
      security: []
  collectionitem-published:
    post:
      operationId: webhookCollectionItemPublished
      summary: Collection Item - Published
      description: |
        Triggered when a collection item is published or republished.

        This event fires when:
        - A draft collection item is published for the first time
        - An already published item is republished after changes
        - A scheduled item is automatically published
      tags:
        - Webhooks - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/CollectionItemWebhookData'
                webhook:
                  allOf:
                    - $ref: '#/components/schemas/WebhookMeta'
                    - properties:
                        event:
                          enum:
                            - collectionitem.published
            examples:
              item_published:
                summary: Collection item published
                value:
                  data:
                    id: products
                    itemid: /v2/content/?keys=products[_id=5678]
                    label: Wireless Headphones Pro
                    editor: Product Manager
                    timestamp: '2024-01-15T13:45:00'
                    locale: null
                    status: published
                  webhook:
                    event: collectionitem.published
                    target: https://yourapp.com/webhooks/buttercms
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
      security: []
  collectionitem-draft:
    post:
      operationId: webhookCollectionItemDraft
      summary: Collection Item - Draft Saved
      description: |
        Triggered when a collection item draft is saved.

        This event fires when:
        - A new collection item is created and saved as draft
        - An existing draft item is updated and saved
        - A published item is updated but not yet republished
      tags:
        - Webhooks - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/CollectionItemWebhookData'
                webhook:
                  allOf:
                    - $ref: '#/components/schemas/WebhookMeta'
                    - properties:
                        event:
                          enum:
                            - collectionitem.draft
            examples:
              draft_saved:
                summary: Collection item draft saved
                value:
                  data:
                    id: events
                    itemid: /v2/content/?keys=events[_id=9012]
                    label: Annual Developer Conference 2024
                    editor: Event Planner
                    timestamp: '2024-01-15T15:20:00'
                    locale: en
                    status: draft
                  webhook:
                    event: collectionitem.draft
                    target: https://yourapp.com/webhooks/buttercms
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
      security: []
  collectionitem-unpublished:
    post:
      operationId: webhookCollectionItemUnpublished
      summary: Collection Item - Unpublished
      description: >
        Triggered when a collection item is unpublished (but not deleted).


        This event fires when:

        - A published collection item is deliberately unpublished but kept in
        the system

        - An item is temporarily taken offline without permanent deletion
      tags:
        - Webhooks - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/CollectionItemWebhookData'
                webhook:
                  allOf:
                    - $ref: '#/components/schemas/WebhookMeta'
                    - properties:
                        event:
                          enum:
                            - collectionitem.unpublished
            examples:
              item_unpublished:
                summary: Collection item unpublished
                value:
                  data:
                    id: promotions
                    itemid: /v2/content/?keys=promotions[_id=7890]
                    label: Holiday Sale 2023
                    editor: Marketing Manager
                    timestamp: '2024-01-15T21:00:00'
                    locale: en
                    status: draft
                  webhook:
                    event: collectionitem.unpublished
                    target: https://yourapp.com/webhooks/buttercms
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
      security: []
  collectionitem-delete:
    post:
      operationId: webhookCollectionItemDelete
      summary: Collection Item - Deleted
      description: |
        Triggered when a collection item is deleted.

        This event fires when:
        - A collection item is permanently removed from the system
        - A collection item is moved to trash and then permanently deleted
      tags:
        - Webhooks - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/CollectionItemWebhookData'
                webhook:
                  allOf:
                    - $ref: '#/components/schemas/WebhookMeta'
                    - properties:
                        event:
                          enum:
                            - collectionitem.delete
            examples:
              item_deleted:
                summary: Collection item deleted
                value:
                  data:
                    id: testimonials
                    itemid: /v2/content/?keys=testimonials[_id=3456]
                    label: Customer Review - ABC Corp
                    editor: Content Moderator
                    timestamp: '2024-01-15T19:30:00'
                    locale: null
                    status: deleted
                  webhook:
                    event: collectionitem.delete
                    target: https://yourapp.com/webhooks/buttercms
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
      security: []
  collectionitem-all:
    post:
      operationId: webhookCollectionItemAll
      summary: Collection Item - Any Activity
      description: >
        Triggered when any activity occurs on a collection item (create, update,
        publish, unpublish, delete).


        This is a catch-all event that fires for all collection item changes,
        useful for comprehensive content monitoring across all collections.
      tags:
        - Webhooks - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/CollectionItemWebhookData'
                webhook:
                  allOf:
                    - $ref: '#/components/schemas/WebhookMeta'
                    - properties:
                        event:
                          enum:
                            - collectionitem.all
            examples:
              item_updated:
                summary: Collection item updated
                value:
                  data:
                    id: team_members
                    itemid: /v2/content/?keys=team_members[_id=1234]
                    label: John Smith - Senior Developer
                    editor: HR Manager
                    timestamp: '2024-01-15T11:30:00'
                    locale: en
                    status: published
                  webhook:
                    event: collectionitem.all
                    target: https://yourapp.com/webhooks/buttercms
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
      security: []
  media-videouploaded:
    post:
      operationId: webhookMediaVideoUploaded
      summary: Media - Video Uploaded
      description: |
        Triggered when a video file is uploaded to the media library.

        This event fires when:
        - A new video file is uploaded to ButterCMS media library
        - Video processing is completed and the file is available
      tags:
        - Webhooks - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  description: Video upload event data (structure may vary)
                  additionalProperties: true
                webhook:
                  allOf:
                    - $ref: '#/components/schemas/WebhookMeta'
                    - properties:
                        event:
                          enum:
                            - media.videouploaded
            examples:
              video_uploaded:
                summary: Video uploaded to media library
                value:
                  data:
                    id: promotional-video-2024
                    media_id: 12345
                    filename: company-promo.mp4
                    size: 52428800
                    url: https://cdn.buttercms.com/video/company-promo.mp4
                  webhook:
                    event: media.videouploaded
                    target: https://yourapp.com/webhooks/buttercms
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
      security: []
security:
  - readTokenAuth: []
