{
  "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.\n\n### New Documentation Version\nThis 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).\n## API Overview\nThe 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.\n\nOur 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.\n---\nThe API supports creating, updating, and deleting items of three main content types:\n\n**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.\n\n**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.\n\n**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.\n---\nAuthentication is handled through an access token; read operations can use either header-based authentication or a query parameter (`auth_token`) while write operations require header-based authentication for enhanced security.\n",
    "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.\n\n## Overview\n\n**Content Types**\n\nThe ButterCMS API supports creating, updating, and deleting items of three main content types:\n\n**Pages**\n\nFully 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).\n\n**Collections**\n\nLighter-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.\n\n**Blog Posts**\n\nBuilt-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.\n\n---\n\n**API Architecture**\n\nButterCMS 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.\n\n**Content Types**\n\nThe 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).\n\n```\n┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐\n│     Pages       │◄────▶│   Collections   │◄────▶│   Blog Posts    │\n│                 │      │                 │      │                 │\n│ • Single Pages  │      │ • Categories    │      │ • Authors       │\n│ • Page Types    │      │ • Products      │      │ • Categories    │\n│                 │      │ • Team Members  │      │ • Tags          │\n└─────────────────┘      └─────────────────┘      └─────────────────┘\n         │                         │                         │\n         └─────────────────────────┼─────────────────────────┘\n                                   │\n                    Reference Fields (slugs/IDs)\n                    One-to-One or One-to-Many\n```\n\n**Publication States**\n\nContent 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.\n\n```\n┌─────────────┐    Publish    ┌─────────────┐    Schedule   ┌─────────────┐\n│    Draft    │──────────────▶│  Published  │──────────────▶│  Scheduled  │\n│             │               │             │               │             │\n│ • Preview   │◄──────────────┤ • Live API  │◄──────────────┤ • Auto-pub  │\n│ • Editable  │   Unpublish   │ • Cached    │   Update      │ • Queued    │\n└─────────────┘               └─────────────┘               └─────────────┘\n```\n\nAll 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.\n\n**Important Differences**\n\nPages 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.\n\n---\n\n**Request Flow**\n\nRead 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.\n\n```\n┌─────────────┐    ┌──────────────┐    ┌─────────────┐    ┌──────────────┐\n│   Client    │───▶│ Global CDN   │───▶│ ButterCMS   │───▶│  Background  │\n│ Application │    │ (150+ edges) │    │    API      │    │  Processing  │\n└─────────────┘    └──────────────┘    └─────────────┘    └──────────────┘\n                           │                   │                   │\n                   Cache Hit (50-100ms)   Cache Miss        Media Upload\n                    ┌──────────────┐      (200-500ms)        Validation\n                    │   Cached     │                         Webhooks\n                    │   Response   │                         Cache Refresh\n                    └──────────────┘\n```\n\n**Authentication**\n\nRead operations use either header-based token authentication or 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.\n\n---\n\n## Performance and Integration\n\n**Performance and Caching**\n\nContent 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.\n\n**Cache Behavior**\n\nInitial 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.\n\n**Reference Serialization Performance**\n\nWhen 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.\n\n```\nList Request (levels=2):\n┌─────────────┐\n│ 100 Pages   │ ──────┐\n└─────────────┘       │\n                      ▼\n            ┌─────────────────────┐\n            │ Serialization Load  │\n            │                     │\n            │ Page 1 + refs (3)   │ ──┐\n            │ Page 2 + refs (5)   │   │\n            │ Page 3 + refs (2)   │   │ Exponential\n            │ ...                 │   │ Growth\n            │ Page 100 + refs (4) │   │\n            │                     │   │\n            │ Total: 400+ objects │ ◄─┘\n            └─────────────────────┘\n\nSolution: Use levels=1 for lists\n```\n\n**Cache Invalidation**\n\nContent 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.\n\n```\nContent Update:\n┌─────────────┐\n│   Page A    │ (updated)\n└─────────────┘\n       │\n       ▼ triggers invalidation\n┌─────────────────────────────────────┐\n│          Cache Layers               │\n│ ┌─────────────────────────────────┐ │\n│ │ Object Cache        │ ✗ Invalid │ │\n│ ├─────────────────────┼───────────┤ │\n│ │ Response Cache      │ ✗ Invalid │ │\n│ ├─────────────────────┼───────────┤ │\n│ │ Global CDN Cache    │ ✗ Invalid │ │\n│ └─────────────────────────────────┘ │\n└─────────────────────────────────────┘\n       │\n       ▼ cascades to\n┌─────────────┐  ┌─────────────┐  ┌─────────────┐\n│   Page B    │  │Collection C │  │   Page D    │\n│(refs Page A)│  │(refs Page A)│  │(refs Page A)│\n└─────────────┘  └─────────────┘  └─────────────┘\nAll referencing content also invalidated\n```\n\n**Optimization Parameters**\n\nFor 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.\n\n**Write Operations**\n\nCreate 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.\n\n---\n\n**Integration Best Practices**\n\nFor 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.\n\n**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.\n\n**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.\n\n**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.\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                    Integration Patterns                         │\n├─────────────────────────────────────────────────────────────────┤\n│                                                                 │\n│ SSG (Build Time):                                               │\n│ Content ──▶ Build Process ──▶ Static Files ──▶ CDN ──▶ Users    │\n│              ▲                                                  │\n│ Webhook triggers rebuild                                        │\n│                                                                 │\n│ SSR (Request Time):                                             │\n│ User Request ──▶ Server ──▶ API Call ──▶ Dynamic Page ──▶ User  │\n│                   │                                             │\n│                   ▼ App-level cache                             │\n│                                                                 │\n│ SPA (Client Side):                                              │\n│ User ──▶ App Shell ──▶ API Calls ──▶ Dynamic Updates ──▶ UI     │\n│           │                                                     │\n│           ▼ Browser cache                                       │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n**API Efficiency**\n\nStrategic 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.\n\n**Error Handling**\n\nImplement 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.\n"
    },
    {
      "name": "Pages - Key Concepts",
      "description": "Essential concepts for working with ButterCMS Pages, including unique features, publication states, and architectural patterns.\n\n## Overview and Core Features\n\nPages 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.\n\n**Unique Page Capabilities**\n\n- **Components**: Structured content blocks including individual components and component picker fields for dynamic layouts\n- **Repeaters**: Fields that allow multiple instances of the same field structure\n- **Form Integrations**: Direct integration with third-party form services\n- **Slug-based Retrieval**: Human-readable URL identification system\n- **True Versioning**: Draft versions can be created over existing published content\n\n---\n\n**Page Types**\n\nPages 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.\n\n**Content Architecture**\n\nPages 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.\n\n---\n\n**Content Publication States**\n\nPages support a comprehensive three-state lifecycle that provides maximum flexibility for content management workflows.\n\n- **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.\n- **Published State**: Content live and accessible via standard API endpoints, served through the global CDN with automatic caching and optimization.\n- **Scheduled State**: Content automatically published at specified times through dashboard configuration, enabling time-based content strategies and editorial calendar management.\n\n**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.\n\n---\n\n**Previewing**\n\nPreview functionality enables content teams to review draft pages in full website context before publishing, providing confidence in content presentation and layout.\n\n**Pages Preview Workflow**:\n1. Configure preview URLs for Page Types in your ButterCMS dashboard\n2. Content creators click \"Preview\" button and are redirected to your preview URL with `preview=1` parameter\n3. Your application detects the parameter and includes it in ButterCMS API calls\n4. Draft page content is returned and displayed in complete website context\n5. Content teams can review layout, styling, and content presentation before publication\n\n**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.\n\n**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.\n\n## Reference Architecture\n\nPages participate in ButterCMS's reference system, enabling complex content relationships and reusable data patterns that scale with your content needs.\n\n**Page-to-Page References**\n\nReference fields pointing to other pages use page slugs as identifiers, providing human-readable and URL-friendly relationships that support navigation and content discovery patterns.\n\n**Implementation Examples**\n\n- **One-to-one relationships**: `\"related_page\": \"example-page-slug\"` for featured content\n- **One-to-many relationships**: `\"related_pages\": [\"page-1-slug\", \"page-2-slug\"]` for content series\n- **Navigational references**: Supporting breadcrumbs, previous/next navigation, and content recommendations\n\n**Page-to-Collection References**\n\nPages can reference Collection items to incorporate structured data like categories, team members, or product information, creating dynamic content that leverages centralized data management.\n\n**Reference Patterns**\n\n- **Category Assignment**: `\"category\": 123` using Collection item ID\n- **Author Information**: `\"authors\": [456, 789]` for multi-author content\n- **Product References**: `\"featured_products\": [101, 102, 103]` for e-commerce integration\n\n---\n\n**Reference Management**\n\n**Adding References**\n\nProvide appropriate identifiers (slug for pages, ID for collections) in Write API requests. References are validated during processing to ensure target content exists.\n\n**Removing References**\n\nClear relationships using appropriate empty values:\n- **Empty string** (`\"\"`): Removes one-to-one relationships\n- **Empty array** (`[]`): Removes one-to-many relationships\n- **Null value** (`null`): Removes either relationship type\n\n**Update Behavior**\n\n- **PATCH requests**: Omitted reference fields remain unchanged, enabling selective updates\n- **PUT requests**: For Pages, PUT behaves like PATCH (partial update), allowing flexible field management\n\n---\n\n**Reference Levels**\n\nThe `levels` parameter controls reference field depth in API responses, balancing data completeness with response size and performance for optimal page loading.\n\n**Parameter Configuration**\n- **Default**: `levels=2` covers most page display scenarios\n- **Range**: 1-5 (values outside this range are automatically adjusted)\n- **Level 1**: Reference fields return API URIs only (minimal data transfer)\n- **Level 2+**: Reference fields return complete object data\n- **Level 5 (max)**: Returns URIs for any remaining references beyond specified depth\n\n**Performance Guidelines for Pages**\n- **Use `levels=1`** for page listing or navigation menus where you need minimal data\n- **Use `levels=2`** (default) for standard page display with basic reference information\n- **Use `levels=3-5`** when displaying pages with complex nested reference chains\n- **10MB response limit**: Reduce levels if responses approach this size limit\n\n**Response Examples**\n\n**Level 1 Example** (URIs only for faster loading):\n```json\n{\n  \"data\": {\n    \"fields\": {\n      \"related_pages\": [\"/v2/pages/example-page-type/example-page-slug\"],\n      \"category\": [\"/v2/content/?keys=categories[_id=1234]\"]\n    }\n  }\n}\n```\n\n**Level 2+ Example** (Complete objects for rich display):\n```json\n{\n  \"data\": {\n    \"fields\": {\n      \"related_pages\": [\n        {\n          \"slug\": \"example-page-slug\",\n          \"fields\": {\"title\": \"Example Page\", \"summary\": \"...\"}\n        }\n      ],\n      \"category\": [\n        {\"meta\": {\"id\": 1234}, \"name\": \"Technology\", \"description\": \"...\"}\n      ]\n    }\n  }\n}\n```\n\n## Advanced Features\n\n**Localization**\n\nMulti-language support enables Pages to serve international audiences with locale-specific content while maintaining consistent schemas and reference relationships.\n\n**Account Configuration**\n\nLocale 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.\n\n**Important**: Once locales are added to an account, they cannot be removed. Plan your internationalization strategy carefully before configuration.\n\n**Content Versions**\n\nPages 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.\n\n**API Integration**:\n- **Specify locale**: Add `locale=en` parameter to retrieve pages in specific language\n- **Default locale**: Omit parameter to receive content in your organization's default locale\n- **Write API**: Create localized versions by providing locale-specific field data in write requests\n\n**Reference Behavior**\n\nReference 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.\n\n**Use Cases**\n\n- **Marketing Sites**: Landing pages tailored to regional markets with localized messaging\n- **Product Pages**: E-commerce content adapted to local currencies, regulations, and preferences\n- **Corporate Content**: Company information, policies, and resources in multiple languages\n- **Content Hubs**: Resource centers and knowledge bases serving international audiences\n\n**Field Format Options**\n\nPages support two localization formats depending on your organization's setup:\n- **Single-language**: Use direct `fields` object for accounts without localization\n- **Multi-language**: Nest field data under locale codes within the `fields` object (e.g., `\"en\"`, `\"es\"`)\n"
    },
    {
      "name": "Pages - Components",
      "description": "Complete guide to ButterCMS component system, exclusively available for Pages to create dynamic, structured layouts with reusable content blocks.\n\n**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.\n\n## Component System Overview\n\nComponents 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.\n\n**Component Architecture**\n\nComponents 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.\n\n**Schema Management**\n\nComponent 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.\n\n**Content Creation Workflow**:\n1. **Developer Phase**: Define component schemas in ButterCMS dashboard with specific field types and structures\n2. **Content Phase**: Content creators populate component fields with data using dashboard or Write API\n3. **Delivery Phase**: API responses include structured component data for rendering in your application\n\n---\n\n**Individual Components**\n\nSingle, 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.\n\n**Field Organization**\n\nIndividual component fields are organized as nested JSON objects that preserve the component's internal structure while remaining easily accessible through API responses.\n\n```json\n{\n  \"hero\": {\n    \"image\": \"https://example.com/hero-image.jpg\",\n    \"alt_text\": \"Hero section background image\",\n    \"headline\": \"Welcome to Our Platform\",\n    \"subtitle\": \"Powerful content management made simple\",\n    \"cta_button\": {\n      \"text\": \"Get Started\",\n      \"url\": \"/signup\"\n    }\n  }\n}\n```\n\n**Update Behavior**\n\nIndividual 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.\n\n**Example Update Request**:\n```json\n{\n  \"fields\": {\n    \"hero\": {\n      \"headline\": \"Updated Welcome Message\"\n    }\n  }\n}\n```\nIn this example, only the headline field is updated while image, alt_text, subtitle, and cta_button retain their existing values.\n\n**Use Cases**:\n- **Header Sections**: Consistent hero areas with image, headline, and call-to-action elements\n- **Contact Information**: Standardized contact blocks with address, phone, and email fields\n- **Feature Highlights**: Structured feature presentations with icons, titles, and descriptions\n- **Testimonials**: Consistent testimonial formats with quotes, attribution, and images\n\n---\n\n**Component Picker Fields**\n\nComponent 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.\n\n**Dynamic Layout Structure**\n\nComponent 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.\n\n**Array-Based Organization**\n\nEach element in a component picker array represents a single component instance with its type identifier and associated field data:\n\n```json\n{\n  \"sections\": [\n    {\n      \"faq_item\": {\n        \"question\": \"Are dogs allowed in the facility?\",\n        \"answer\": \"Leashed dogs are welcome in all common areas and outdoor spaces.\",\n        \"category\": \"Pets\",\n        \"featured_image\": \"https://example.com/dog-friendly.jpg\"\n      }\n    },\n    {\n      \"trivia_block\": {\n        \"title\": \"Did You Know?\",\n        \"facts\": [\n          \"Our facility was built in 1892\",\n          \"We've hosted over 10,000 events\"\n        ],\n        \"background_color\": \"blue\"\n      }\n    },\n    {\n      \"image_gallery\": {\n        \"title\": \"Recent Photos\",\n        \"images\": [\n          {\n            \"url\": \"https://example.com/photo1.jpg\",\n            \"caption\": \"Summer event 2024\"\n          },\n          {\n            \"url\": \"https://example.com/photo2.jpg\",\n            \"caption\": \"Holiday celebration\"\n          }\n        ]\n      }\n    }\n  ]\n}\n```\n\n**Component Type Selection**\n\nEach 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.\n\n**Update Limitations**\n\nComponent 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.\n\n**Complete Update Example**:\n```json\n{\n  \"fields\": {\n    \"sections\": [\n      {\n        \"faq_item\": {\n          \"question\": \"Updated question text\",\n          \"answer\": \"Updated answer with more detail\",\n          \"category\": \"Updated Category\",\n          \"featured_image\": \"https://example.com/new-image.jpg\"\n        }\n      },\n      {\n        \"trivia_block\": {\n          \"title\": \"New Trivia Section\",\n          \"facts\": [\"New fact one\", \"New fact two\"],\n          \"background_color\": \"green\"\n        }\n      }\n    ]\n  }\n}\n```\n\n**Ordering and Management**\n\nThe 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.\n\n**Use Cases**:\n- **Landing Pages**: Mixed content sections with headers, features, testimonials, and calls-to-action\n- **Resource Pages**: Combination of text blocks, image galleries, downloads, and embedded content\n- **Event Pages**: Dynamic sections for schedules, speakers, locations, and registration information\n- **Product Pages**: Flexible layouts combining specifications, images, reviews, and related products\n\n## Advanced Features\n\n**Media Integration**\n\nComponents seamlessly integrate with ButterCMS media management system, enabling automatic media processing and CDN optimization for component-based content.\n\n**Media Field Support**\n\nWhen 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.\n\n**Automatic Processing**\n\nRemote 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.\n\n**Example Media Integration**:\n```json\n{\n  \"hero_section\": {\n    \"background_image\": \"https://external-site.com/image.jpg\",\n    \"logo\": \"https://company-assets.com/logo.png\"\n  }\n}\n```\n\nAfter processing, these external URLs are replaced with ButterCMS CDN URLs, providing optimized delivery and eliminating external dependencies.\n\n**CDN Benefits**\n\nMedia processed through components receives full CDN integration including global distribution, automatic optimization, and image transformation capabilities through Filestack integration.\n\n**Media Management**\n\nAll component media becomes part of your centralized ButterCMS media library, enabling reuse across multiple pages and providing centralized organization and management capabilities.\n\n---\n\n**Component Development Guidelines**\n\n**Schema Design**\n\nDesign component schemas with reusability and flexibility in mind. Consider common use cases and provide appropriate field types that balance structure with content creator freedom.\n\n**Field Validation**\n\nLeverage ButterCMS field validation options within component schemas to ensure data quality and consistency across component instances.\n\n**Naming Conventions**\n\nUse clear, descriptive names for component types and fields that help content creators understand purpose and expected content without requiring extensive documentation.\n\n**Performance Considerations**\n\nDesign 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.\n\n**Content Creator Experience**\n\nConsider the dashboard editing experience when designing components, ensuring that field order and grouping create intuitive content creation workflows.\n"
    },
    {
      "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.\n\n## Overview and Core Features\n\nCollections 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.\n\n**Core Collection Characteristics**\n\n- **ID-based Retrieval**: Numeric ID identification system for precise, efficient data access\n- **Optimized Structure**: Streamlined schemas focused on data integrity and query performance\n- **Reference-Oriented**: Designed primarily to be referenced by Pages and other content types\n- **Simplified Management**: Straightforward field structures without component complexity\n- **Flexible Schemas**: Completely customizable field definitions to match your data requirements\n\n**Collections vs. Pages Comparison**\n\n- **No Components**: Collections do not support individual components, component picker fields, or component libraries\n- **No Repeaters**: Collections cannot use repeater field types that allow multiple instances of field structures\n- **No Form Integrations**: Direct form service integrations are not available for Collections\n- **Simpler Updates**: Streamlined update patterns without component-specific update behaviors\n- **Performance Focus**: Optimized for faster querying and smaller response sizes\n\n**Ideal Use Cases**\n\n- **Categories and Tags**: Organizational taxonomies for content classification\n- **Team Members**: Staff directories with contact information, roles, and expertise\n- **Product Catalogs**: Basic product information that Pages can reference and expand upon\n- **Location Data**: Store and office information for multi-location organizations\n- **Reference Lists**: Any structured data that enhances content without requiring complex layouts\n\n---\n\n**Content Publication States**\n\nCollections follow the same unified publication state system as other ButterCMS content types, with implementation details optimized for data management workflows.\n\n- **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.\n- **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.\n- **Scheduled State**: Collection items support scheduled publication for time-based data release, enabling coordinated content launches and editorial calendar integration.\n\n**Publication Workflow**\n\nCollection publication states integrate seamlessly with Page and Blog publication workflows, allowing coordinated content releases where Pages can reference Collections that publish simultaneously.\n\n**State Management**\n\nCollection items support standard state transitions (draft to published, published to draft, scheduled publication) through both dashboard interface and Write API operations.\n\n---\n\n**Previewing**\n\nPreview functionality enables data validation and quality assurance for draft collection items before publication, supporting content review processes and data accuracy verification.\n\n**Collections Preview Strategy**\n\nEnable 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.\n\n**Data Validation Workflow**\n\n1. Create or update collection items in draft status\n2. Use preview mode to fetch draft items through API calls\n3. Validate data structure, content accuracy, and integration behavior\n4. Review how draft items appear when referenced by Pages\n5. Publish collection items after validation confirms expected behavior\n\n**Environment Integration**\n\nConsider implementing environment-based configuration that automatically includes the preview parameter in non-production environments, enabling seamless data validation workflows across different deployment contexts.\n\n**Reference Preview**\n\nWhen 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.\n\n**API Behavior**\n\nWhen `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.\n\n## Reference Architecture\n\nCollections serve as both reference targets and reference sources within ButterCMS's content relationship system, enabling sophisticated data organization and content connections.\n\n**Collection-to-Page References**\n\nCollection items can reference Pages using page slugs, creating bidirectional content relationships that support navigation, feature highlighting, and content discovery patterns.\n\n**Implementation Patterns**\n\n- **Featured Content**: `\"featured_page\": \"landing-page-slug\"` for highlighting specific pages\n- **Related Resources**: `\"related_pages\": [\"guide-1-slug\", \"guide-2-slug\"]` for content series\n- **Landing Page Association**: `\"product_page\": \"product-details-slug\"` for e-commerce integration\n\n**Collection-to-Collection References**\n\nCollection items can reference other collection items using numeric IDs, enabling hierarchical data structures and complex organizational patterns.\n\n**Organizational Examples**\n\n- **Hierarchical Categories**: `\"parent_category\": 123` for taxonomy structures\n- **Related Items**: `\"related_products\": [456, 789, 101]` for cross-selling and recommendations\n- **Team Relationships**: `\"department\": 234` for organizational structure\n- **Location Hierarchies**: `\"region\": 345` for geographic organization\n\n---\n\n**Collection Reference Management**\n\n**Adding References**\n\nProvide appropriate identifiers in Write API requests—page slugs for Page references, numeric IDs for Collection references. The system validates reference targets during processing.\n\n**Removing References**\n\nClear relationships using appropriate empty values:\n- **Empty string** (`\"\"`): Removes one-to-one relationships\n- **Empty array** (`[]`): Removes one-to-many relationships\n- **Null value** (`null`): Removes either relationship type\n\n**Update Behavior**\n\n- **PATCH requests**: Omitted reference fields remain unchanged, enabling selective relationship updates\n- **PUT requests**: Provide all fields including references; full replacement semantics apply to Collections\n\n**Reference Validation**\n\nCollection reference fields are validated to ensure target content exists and is accessible, preventing broken relationships in your content architecture.\n\n---\n\n**Reference Levels**\n\nThe `levels` parameter controls reference field depth in Collection API responses, optimizing data delivery for different use cases while managing response size and performance.\n\n**Parameter Configuration for Collections**\n\n- **Default**: `levels=2` provides complete referenced data for most collection use cases\n- **Range**: 1-5 (values outside this range are automatically adjusted)\n- **Level 1**: Reference fields return API URIs only (optimal for collection listings)\n- **Level 2+**: Reference fields return complete object data (ideal for detailed displays)\n- **Level 5 (max)**: Returns URIs for any remaining references beyond specified depth\n\n**Collection-Specific Performance Guidelines**\n\n- **Use `levels=1`** for collection listings or when building dropdown/select options\n- **Use `levels=2`** (default) for individual collection item display with reference context\n- **Use `levels=3-5`** when displaying collections with deep reference chains\n- **Pagination Considerations**: Use `levels=1` for paginated collection lists to minimize serialization overhead\n\n**Response Format Examples**\n\n**Level 1 Response** (URIs for minimal data transfer)\n\n```json\n{\n  \"data\": [\n    {\n      \"meta\": {\"id\": 123},\n      \"name\": \"Technology\",\n      \"related_items\": [\"/v2/content/?keys=categories[_id=456]\"],\n      \"featured_page\": [\"/v2/pages/product-guides/tech-overview\"]\n    }\n  ]\n}\n```\n\n**Level 2+ Response** (Complete objects for rich data access)\n\n```json\n{\n  \"data\": [\n    {\n      \"meta\": {\"id\": 123},\n      \"name\": \"Technology\",\n      \"related_items\": [\n        {\"meta\": {\"id\": 456}, \"name\": \"Software\", \"description\": \"...\"}\n      ],\n      \"featured_page\": [\n        {\"slug\": \"tech-overview\", \"fields\": {\"title\": \"Technology Guide\", \"summary\": \"...\"}}\n      ]\n    }\n  ]\n}\n```\n\n**Cross-Content Type References**\n\nThe levels parameter works consistently whether references point to Pages or other Collections, providing predictable behavior across your entire content architecture.\n\n## Localization and Best Practices\n\n**Localization**\n\nMulti-language support enables Collections to serve international content strategies with locale-specific data while maintaining consistent schemas and reference relationships.\n\n**Account Configuration**\n\nLocale 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.\n\n**Important Limitation**: Once locales are added to an account, they cannot be removed. Plan your internationalization approach carefully before configuration to avoid schema constraints.\n\n**Content Versions**\n\nCollections 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.\n\n**API Integration Patterns**\n\n- **Specify locale**: Add `locale=en` parameter to retrieve collection items in specific language\n- **Default locale**: Omit parameter to receive content in your organization's default locale\n- **Write API**: Create localized versions by providing locale-specific field data in write requests\n\n**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.\n\n**Collection Localization Use Cases**\n\n- **Product Catalogs**: International product information with localized descriptions, pricing, and availability\n- **Team Directories**: Multi-regional staff information with localized roles and contact details\n- **Category Systems**: Taxonomies adapted to regional content organization and cultural preferences\n- **Location Data**: Multi-language address information, operating hours, and regional service details\n\n**Field Data Organization**\n\nCollections support two localization formats:\n- **Single-language**: Use direct field values for accounts without localization enabled\n- **Multi-language**: Nest field data under locale codes for accounts with localization (e.g., fields organized by `\"en\"`, `\"es\"`, `\"fr\"` keys)\n\n---\n**Best Practices**\n\n**Localization Best Practices**\n\n- **Consistent References**: Maintain reference relationships across locales where appropriate, or create locale-specific references when regional variations are needed\n- **Data Validation**: Validate localized collection data to ensure completeness across all configured locales\n- **Reference Planning**: Design reference patterns that work effectively across different language and cultural contexts\n\n**Performance Optimization**\n\n- **Use appropriate `levels` parameters**: Start with `levels=1` for listing operations and increase only when necessary\n- **Implement pagination**: For large collections, use pagination to maintain responsive API performance\n- **Cache strategically**: Leverage ButterCMS CDN caching for frequently accessed collection data\n\n**Content Architecture**\n\n- **Design for scale**: Plan collection schemas that can accommodate future data requirements\n- **Reference strategy**: Create logical reference patterns that support your content relationships\n- **Validation planning**: Use appropriate field validation to maintain data quality across collection items\n"
    },
    {
      "name": "Blogs - Key Concepts",
      "description": "Essential concepts for working with ButterCMS Blog Posts, including predefined schemas, built-in organizational features, and publication characteristics.\n\n## Overview and Built-in Features\n\n**Predefined Blog Schema**\n\nButterCMS Blog Posts use a standardized, predefined schema that provides out-of-the-box functionality for chronological content with built-in organizational and authoring features.\n\n**Standardized Field Structure**\n\nBlog 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.\n\n**Core Blog Fields**\n\n- **Title**: SEO-optimized title field with automatic URL slug generation\n- **Body**: Rich HTML content field supporting full editorial formatting\n- **Summary**: Optional excerpt field for post previews and social sharing\n- **Featured Image**: Dedicated image field with automatic CDN optimization\n- **SEO Metadata**: Built-in meta title, meta description, and Open Graph fields\n- **Publication Date**: Automatic timestamp management with scheduling capabilities\n- **Status**: Draft, published, and scheduled state management\n\n**Content Richness**\n\nThe 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.\n\n**SEO Integration**\n\nBlog 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.\n\n---\n\n**Built-in Categorization and Tagging**\n\nBlog Posts provide sophisticated organizational capabilities through predefined categorization and tagging systems that enable flexible content discovery and filtering.\n\n**Categories System**\n\n- **Hierarchical Organization**: Categories support parent-child relationships for sophisticated content taxonomy\n- **URL Integration**: Categories automatically generate SEO-friendly URLs for category pages\n- **Filtering Capability**: API endpoints support category-based filtering for content queries\n- **RSS Integration**: Category-specific RSS feeds are automatically generated\n\n**Tagging System**\n\n- **Flexible Labeling**: Tags provide flexible, non-hierarchical content labeling for cross-cutting themes\n- **Tag-based Discovery**: Readers can discover related content through tag-based navigation\n- **API Filtering**: Tags support API filtering for precise content queries\n- **Tag Clouds**: Automatic tag frequency calculation for tag cloud generation\n\n**Organizational Benefits**\n\nThe 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.\n\n**Content Strategy Integration**\n\nUse 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.\n\n---\n\n**Predefined Metadata and Features**\n\nBlog Posts include comprehensive metadata and built-in features that eliminate the need for custom field configuration while providing professional blogging capabilities.\n\n**Author Management**\n\n- **Author Profiles**: Dedicated author entities with names, biographies, profile images, and social links\n- **Multi-author Support**: Blog posts can be attributed to multiple authors for collaborative content\n- **Author Archives**: Automatic generation of author-specific content archives and RSS feeds\n- **API Access**: Author information is accessible through dedicated API endpoints\n\n**Publication Metadata**\n\n- **Creation Timestamps**: Automatic tracking of content creation time\n- **Publication Dates**: Separate publication date management for editorial calendar control\n- **Update Tracking**: Last modified timestamps for content freshness indication\n- **URL Slug Management**: Automatic SEO-friendly URL generation with manual override capability\n\n**Built-in Features**\n\n- **RSS Feeds**: Automatic RSS 2.0 and Atom feed generation for content syndication\n- **XML Sitemaps**: Search engine sitemap integration for improved discoverability\n- **Previous/Next Navigation**: Automatic post navigation for chronological content browsing\n- **Related Posts**: Built-in content relationship suggestions based on categories and tags\n\n**Social Media Integration**\n\nBlog Posts include Open Graph and Twitter Card metadata that ensure proper social media presentation when content is shared across platforms.\n\n---\n\n**Publication States and Workflow**\n\nBlog Posts follow a simplified publication state system optimized for editorial workflows and content scheduling, with important differences from Pages regarding versioning capabilities.\n\n**Simplified State Management**\n\nBlog 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.\n\n**State Characteristics**\n\n- **Draft State**: Content accessible only through preview mode, enabling editorial review and revision\n- **Published State**: Content live and accessible through all blog endpoints with full CDN caching\n- **Scheduled State**: Content automatically published at specified times through dashboard scheduling\n\n**Versioning Limitations**\n\nUnlike 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.\n\n**Editorial Workflow**\n\nThe simplified state system supports traditional blog editorial workflows where content moves linearly from draft to published, with scheduling capabilities for time-based publication strategies.\n\n**Publication Behavior**\n\nBlog 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.\n\n## Limitations and Advanced Topics\n\n**Localization Limitations and Alternatives**\n\n**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.\n\n**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.\n\n**Page Type Blog Implementation**\n\n- **Custom Schema**: Create Page Types with blog-like fields (title, body, date, author references)\n- **Localization Support**: Page Types inherit full localization capabilities from the Pages system\n- **Component Integration**: Page Types can include components for rich content layouts beyond traditional blog formats\n- **Reference Integration**: Page Types can reference Collections for author information, categories, and tags\n\n**Migration Considerations**\n\nOrganizations planning international blog expansion should evaluate Page Types early in their content strategy to avoid complex migration scenarios from Blog Posts to Pages.\n\n**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.\n\n---\n\n**Content Import Capabilities**\n\n**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.\n\n**Import Features**\n\n- **Content Preservation**: Blog post titles, bodies, publication dates, and metadata are transferred accurately\n- **Category Migration**: WordPress categories are mapped to ButterCMS categories with hierarchy preservation\n- **Tag Transfer**: WordPress tags are converted to ButterCMS tags maintaining content relationships\n- **Author Mapping**: WordPress authors are created as ButterCMS author entities with profile information\n- **Media Import**: WordPress media attachments are transferred to ButterCMS media library with CDN integration\n\n**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.\n\n**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.\n\n---\n\n**Blog API Characteristics**\n\n**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.\n\n**Performance Features**\n\n- **Body Exclusion**: Use `exclude_body=true` parameter to reduce response size by 50-70% for listing operations\n- **Category Filtering**: Native support for category-based content filtering without complex query construction\n- **Tag Filtering**: Built-in tag filtering for precise content queries\n- **Date Range Queries**: Support for publication date filtering to build archive functionality\n\n**Integration Patterns**\n\nBlog 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.\n"
    },
    {
      "name": "Webhooks - Key Concepts",
      "description": "Complete Webhooks - Events system for real-time content change notifications.\n\nButterCMS 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.\n\n## Overview and Setup\n\n**How Webhooks Work**\n\n1. **Configure Endpoints**: Set up webhook URLs in your ButterCMS account settings\n2. **Choose Events**: Select which content events should trigger notifications\n3. **Receive Notifications**: ButterCMS sends HTTP POST requests to your endpoints\n4. **Process Changes**: Your application processes the webhook payload and takes action\n\n---\n\n**Locale Support**\n\nFor 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.\n\n---\n\n**Security Best Practices**\n\n**Authentication**\n- **Custom Headers**: Use custom authentication headers (e.g., `X-API-Key`, `Authorization`) to verify webhook source\n- **IP Allowlisting**: Restrict webhook endpoints to accept requests only from ButterCMS IP ranges\n- **HTTPS Only**: Always use HTTPS endpoints to ensure encrypted data transmission\n\n**Payload Validation**\n- **Verify Headers**: Check authentication headers before processing webhook payload\n- **Validate Structure**: Ensure payload matches expected webhook event schema\n- **Idempotency**: Handle duplicate webhook deliveries gracefully using event IDs or timestamps\n\n**Error Handling**\n- **Return 2xx Status**: Return 200-299 status codes to acknowledge successful webhook processing\n- **Fail Fast**: Return error status codes (4xx/5xx) immediately for invalid requests\n- **Timeout Compliance**: Respond within 30 seconds to avoid ButterCMS timeout and retries\n\n## Implementation Details\n\n**Delivery Guarantees**\n\n- **At-least-once delivery**: Webhooks may be delivered multiple times\n- **Retry logic**: Failed webhooks are retried with exponential backoff\n- **Timeout**: Webhook endpoints must respond within 30 seconds\n- **Status codes**: Return 2xx status codes to acknowledge successful processing\n\n---\n\n**Integration Use Cases**\n\n- **Real-time Cache Invalidation**: Clear CDN cache when content updates\n- **Multi-channel Publishing**: Sync content to social media, email lists, mobile apps\n- **Automated Workflows**: Trigger deployments or notifications on content changes\n"
    },
    {
      "name": "Pages - Write",
      "description": "Create new pages using ButterCMS Write API. Programmatically create content to enable powerful use cases and scale your content faster.\n\nNote: For Pages, PUT behaves like PATCH (partial update). Use either method to perform partial updates.\n"
    },
    {
      "name": "Pages - Read",
      "description": "Retrieve pages from your ButterCMS account.\n\n**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.\n\n**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.\n\n**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.\n"
    },
    {
      "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.\n"
    },
    {
      "name": "Collections - Read",
      "description": "Retrieve collection items from your ButterCMS account. Collections are flexible, user-defined content structures with completely customizable field schemas.\n\nSee also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.\n"
    },
    {
      "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.\n"
    },
    {
      "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.\n"
    },
    {
      "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.\n"
    },
    {
      "name": "Webhooks - Events",
      "description": "Webhook event notifications sent by ButterCMS when content changes occur in your account.\n\nButterCMS 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.\n\n**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.\n\n**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.\n\n**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.\n"
    },
    {
      "name": "Feeds & Utilities",
      "description": "Generate XML feeds for content syndication and SEO.\n\n- **RSS Feed**: Fully generated RSS 2.0 feed for your blog\n- **Atom Feed**: Standards-compliant Atom 1.0 feed\n- **Sitemap**: XML sitemap for search engine discovery\n\nAll feeds can be filtered by category or tag and include only published content from your organization.\n"
    },
    {
      "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.\n\nAfter you upload an image, to create a thumbnail, here's an example:\n\n- **Original URL**: `https://cdn.buttercms.com/3ccPHhYHTNK2zQ14gCOy`\n- **Thumbnail URL**: `https://cdn.buttercms.com/resize=width:100,height:100/3ccPHhYHTNK2zQ14gCOy`\n\nFor complete transformation options and parameters, see the [full Filestack documentation](https://www.filestack.com/docs/api/processing/).\n"
    }
  ],
  "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.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n",
        "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').\n\n**Usage:** Only applicable when using the single-locale request format (WITHOUT Locales format).\nIf 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`.\n\n**Not applicable** when using the multi-locale format (WITH Locales format), as locale codes are specified within the request body under the `fields` object.\n\nWhen omitted and using single-locale format, defaults to your organization's default locale.\n",
            "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.\n\n**Request Body Formats**:\n- **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`.\n- **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.\n",
          "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.\n\nIf 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.\n\nNote: 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`.\n",
                  "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.\n\nThis 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.\n",
                  "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**\n\nThe request has been accepted for processing. Full page creation occurs asynchronously,\nmeaning the successfully created page may not show immediately. Pages are validated\nprior to returning this response, but it is possible that page creation may fail\nafter returning a `202` response. If this happens, please contact support.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                },
                "example": {
                  "status": "pending"
                }
              }
            }
          },
          "400": {
            "description": "**Bad Request - Validation Error**\n\nYour data did not pass the initial validation stage. This may happen if you are:\n- Missing a required field\n- Missing a field that's required in your page type\n- Providing a remote URL for a media field that returns a 404\n\nError explanations will be returned in a JSON array.\n",
            "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**\n\nThe organization has exceeded its page creation limit. This can happen when you've reached\nthe maximum number of pages allowed for your plan.\n",
            "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.\n\n**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.\n\n**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.\n\n> **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`).\nSee also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.\n",
        "operationId": "getMultiplePages",
        "security": [
          {
            "readTokenAuthHeader": []
          },
          {
            "readTokenAuthQuery": []
          }
        ],
        "parameters": [
          {
            "name": "page_type",
            "in": "path",
            "description": "The slug of the type of pages you want to retrieve, or `*` for Single Pages.\n\n- Use `*` to get Single Pages (those without a Page Type)\n- Use the actual page type slug to get pages of that specific type\n",
            "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>`.\n\nYou can pass in multiple filters at once. For example: `&fields.seo.title=Home&fields.headline=Welcome`\n\nTo filter on Reference or Component fields use dot notation. For example: `fields.hero.title=value` or `fields.hero.reference.title=value`\n\n**Note**: Field filtering is only available for Page Type endpoints, not for Single Pages (`page_type=*`).\n",
            "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>`.\n\n**Note**: Field filtering is only available for Page Type endpoints, not for Single Pages (`page_type=*`).\n",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "Welcome"
          }
        ],
        "responses": {
          "200": {
            "description": "**Success**\n\nReturns a hash with a `data` property that contains an array of pages, and a `meta` property that contains pagination information.\n\n- For Single Pages (`page_type=*`): Returns pages without a page type\n- For Page Types: Returns pages of the specified type\n",
            "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.\n",
                    "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**\n\n- The requested page type doesn't exist or you don't have access to it.\n- Invalid pagination parameters (page number out of range).\n",
            "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.\n\n**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`).\nSee also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.\n",
        "operationId": "getSinglePage",
        "security": [
          {
            "readTokenAuthHeader": []
          },
          {
            "readTokenAuthQuery": []
          }
        ],
        "parameters": [
          {
            "name": "page_type",
            "in": "path",
            "description": "The type of page to retrieve.\n\n- Use `*` to search across all page types\n- Use a specific page type slug to limit search to that type\n",
            "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.\n",
            "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**\n\nA hash with a `data` property that contains the page matching the page slug.\n",
            "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.\n",
                    "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**\n\nInvalid parameter value provided. This can happen when:\n- The `levels` parameter is not a valid integer between 1 and 5\n- Invalid locale parameter provided\n",
            "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**\n\nAuthentication credentials were not provided. Make sure to include your read API token in the `Authorization` header or as the `auth_token` query parameter.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "detail": "Authentication credentials were not provided"
                }
              }
            }
          },
          "403": {
            "description": "**Forbidden - Multiple Pages Found**\n\nMultiple 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.\n",
            "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**\n\nThe requested page doesn't exist, or you don't have access to it. This could be because:\n- The page slug doesn't exist\n- The page type doesn't exist\n- The page exists but not in the specified page type\n",
            "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.\n\n**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.\n\n**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.\nNote: PUT behaves like PATCH (partial update) for Pages. Use either method to perform partial updates.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n",
        "operationId": "updatePage",
        "security": [
          {
            "writeTokenAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page_type",
            "in": "path",
            "description": "The type of page to update.\n\n- Use `*` to search across all page types\n- Use a specific page type slug to limit search to that type\n",
            "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.\n",
            "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').\n\n**Usage:** Only applicable when using the single-locale request format (WITHOUT Locales format).\nIf 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`.\n\n**Not applicable** when using the multi-locale format (WITH Locales format), as locale codes are specified within the request body under the `fields` object.\n\nWhen omitted and using single-locale format, updates the organization's default locale.\n",
            "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.\n\n**Partial Updates**: Unlike creating pages, you only need to specify the fields you want to update. You don't need to include all fields.\n\n**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`.\n\n**Request Body Formats**:\n- **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.\n- **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.\n",
          "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.\n\nNote: You only need to specify the fields you want to update, not all fields.\n",
                  "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.\n\nNote: You only need to specify the fields you want to update for each locale.\n",
                  "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**\n\nThe request has been accepted for processing. Full page update occurs asynchronously,\nmeaning the successfully updated page may not show changes immediately. Page updates are validated\nprior to returning this response, but it is possible that page update may fail\nafter returning a `202` response. If this happens, please contact support.\n\n**Warning Messages**: If you include fields that cannot be updated (like `scheduled` timestamp or `scheduled` status),\nthe API will return warning messages explaining which fields were ignored.\n",
            "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**\n\nYour data did not pass the initial validation stage. This may happen if you are:\n- Missing a required field for the specific page type\n- Providing a remote URL for a media field that returns a 404\n- Trying to update immutable fields (title, slug)\n- Providing invalid field values\n\nError explanations will be returned in a JSON array.\n",
            "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**\n\nYou don't have permission to update this page. This could be due to:\n- Page update limits exceeded\n- Insufficient permissions for the page type\n- Organization-level restrictions\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "detail": "Permission denied"
                }
              }
            }
          },
          "404": {
            "description": "**Not Found - Page Does Not Exist**\n\nThe requested page doesn't exist, or you don't have access to it. This could be because:\n- The page slug doesn't exist\n- The page type doesn't exist\n- The page exists but not in the specified page type\n",
            "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.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n",
        "operationId": "updatePagePut",
        "security": [
          {
            "writeTokenAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page_type",
            "in": "path",
            "description": "The type of page to update.\n\n- Use `*` to search across all page types\n- Use a specific page type slug to limit search to that type\n",
            "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.\n",
            "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').\n\n**Usage:** Only applicable when using the single-locale request format (WITHOUT Locales format).\nIf 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`.\n\n**Not applicable** when using the multi-locale format (WITH Locales format), as locale codes are specified within the request body under the `fields` object.\n\nWhen omitted and using single-locale format, updates the organization's default locale.\n",
            "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.\n\n**Partial Updates**: You only need to specify the fields you want to update. You don't need to include all fields.\n\n**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`.\n\n**Request Body Formats**:\n- **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.\n- **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.\n",
          "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.\n\nNote: You only need to specify the fields you want to update, not all fields.\n",
                  "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.\n\nNote: You only need to specify the fields you want to update for each locale.\n",
                  "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**\n\nThe request has been accepted for processing. Full page update occurs asynchronously,\nmeaning the successfully updated page may not show changes immediately. Page updates are validated\nprior to returning this response, but it is possible that page update may fail\nafter returning a `202` response. If this happens, please contact support.\n\n**Warning Messages**: If you include fields that cannot be updated (like `scheduled` timestamp or `scheduled` status),\nthe API will return warning messages explaining which fields were ignored.\n",
            "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**\n\nYour data did not pass the initial validation stage. This may happen if you are:\n- Missing a required field for the specific page type\n- Providing a remote URL for a media field that returns a 404\n- Trying to update immutable fields (title, slug)\n- Providing invalid field values\n\nError explanations will be returned in a JSON array.\n",
            "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**\n\nYou don't have permission to update this page. This could be due to:\n- Page update limits exceeded\n- Insufficient permissions for the page type\n- Organization-level restrictions\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "detail": "Permission denied"
                }
              }
            }
          },
          "404": {
            "description": "**Not Found - Page Does Not Exist**\n\nThe requested page doesn't exist, or you don't have access to it. This could be because:\n- The page slug doesn't exist\n- The page type doesn't exist\n- The page exists but not in the specified page type\n",
            "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.\n\n**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.\n\n**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.\n\n**Empty Results**: If no results are found, the API returns an empty array: `\"data\": []`\nSee also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.\n",
        "operationId": "searchPages",
        "security": [
          {
            "readTokenAuthHeader": []
          },
          {
            "readTokenAuthQuery": []
          }
        ],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "description": "The search query string to match against page content.\n\nOnly the direct content of pages will be searched. References are excluded from search but will still appear in results.\n\n**Maximum Length**: 100 characters\n",
            "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.\n\n- Use `*` if you want to search only Single Pages (without a Page Type)\n- Use a specific page type slug to limit search to that type\n- If left empty, searching will not be limited to a specific Page Type\n\n**Maximum Length**: 100 characters\n",
            "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**\n\nReturns a hash with a `data` property that contains an array of pages matching the search query, and a `meta` property that contains pagination information.\n\n**Search Results**: Pages are returned sorted by relevancy. If no results are found, returns an empty array: `\"data\": []`\n\n**Content Searched**: Only direct page content is searched. References are excluded from search but included in response based on `levels` parameter.\n",
            "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**\n\nInvalid parameter value provided. This can happen when:\n- The `levels` parameter is not a valid integer between 1 and 5\n- Invalid locale parameter provided\n- Missing required `query` parameter\n",
            "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**\n\nThe 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.\n",
            "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.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\nSee also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.\n",
        "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**\n\nThe collection item has passed initial validation and creation has been queued for asynchronous processing.\n\n**Important**: The item may not be immediately available in collection queries. Background processing includes:\n\n- Field validation against collection schema\n- Media download and upload to Butter Media Library\n- Reference field resolution\n- Search index updates\n\nIf creation fails during background processing, contact support for assistance.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateCollectionItemResponse"
                },
                "example": {
                  "status": "pending"
                }
              }
            }
          },
          "400": {
            "description": "**Bad Request - Validation Failed**\n\nThe request failed initial validation. Common causes:\n\n- **Missing Required Fields**: `key` or `fields` not provided\n- **Invalid Status**: Status must be 'published' or 'draft'\n- **Invalid Collection Key**: Collection doesn't exist or access denied\n- **Field Validation**: Missing required fields or invalid field values\n- **Invalid Media URLs**: Remote URLs are not accessible or return 404\n- **Locale Errors**: Invalid locale codes or mismatched locale format\n- **Organization Limits**: Collection item limit reached for subscription plan\n",
            "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**\n\nThis error occurs when the provided token doesn't have write permissions or the collection item limit has been reached for your subscription plan.\n",
            "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.\n\n**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.\n\n**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.\nSee also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.\n",
        "parameters": [
          {
            "name": "collection_key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "The unique identifier/slug of the Collection to retrieve.\n\nMust match an existing collection in your organization.\n",
            "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.\n\n**Note**: This is a legacy parameter. For single collection retrieval, use the path parameter instead.\n",
            "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.\n\nFilter collection items by any field using the pattern `fields.{field_name}=value`:\n- `fields.genre=Rock` - Filter by genre field\n- `fields.status=published` - Filter by status field\n- `fields.year=2023` - Filter by year field\n\nMultiple field filters can be combined in a single request.\n",
            "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.\n",
                    "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.\n",
                    "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": [
          {
            "readTokenAuthHeader": []
          },
          {
            "readTokenAuthQuery": []
          }
        ]
      }
    },
    "/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.\n\n**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.\n\n> **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.\n\n**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.\n\n**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.\n\n**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.\n",
        "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.\n\nMust match an existing collection in your organization.\n",
            "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.\n\n**Important**: The URL must end with a trailing slash after this parameter.\n\nThis ID can be found in the `meta` field of collection items returned by GET operations.\n",
            "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.\n\n**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.\n\n**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.\n\n> **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.\n\n**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.\n\n**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.\n\n**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.\n",
        "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.\n\nMust match an existing collection in your organization.\n",
            "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.\n\n**Important**: The URL must end with a trailing slash after this parameter.\n\nThis ID can be found in the `meta` field of collection items returned by GET operations.\n",
            "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.\n\n**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.\n\n> **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.\n\n**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.\n\n**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.\n\n**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.\n",
        "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.\n\nMust match an existing collection in your organization.\n",
            "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.\n\n**Important**: The URL must end with a trailing slash after this parameter.\n\nThis ID can be found in the `meta` field of collection items returned by GET operations.\n",
            "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\nby publication date with the newest posts appearing first. This endpoint is\nideal for building blog listing pages, RSS feeds, or content archives.\n\n**Performance Optimization**: Use the `exclude_body=true` parameter when\nbuilding post listing pages to significantly reduce response size by\nexcluding the full post content. This improves loading performance while\nstill providing titles, summaries, metadata, and author information needed\nfor listing displays.\n",
        "operationId": "listAllPosts",
        "security": [
          {
            "readTokenAuthHeader": []
          },
          {
            "readTokenAuthQuery": []
          }
        ],
        "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.\n\n**Performance benefit**: Significantly reduces response size when displaying lists of blog posts.\n",
            "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**\n\nReturns a list of blog posts matching the specified criteria. Posts are\nsorted by publish date with the most recent posts first.\n",
            "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**\n\nInvalid or malformed query parameters provided.\n",
            "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.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n",
        "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**\n\nA 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.\n\nPosts 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.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlogPostCreateSuccessResponse"
                },
                "example": {
                  "status": "pending"
                }
              }
            }
          },
          "400": {
            "description": "**Bad Request - Validation Error**\n\nThe API will return HTTP status code 400 if your data does not pass the initial validation stage. This may happen if:\n\n- You are missing a required field (title or slug)\n- The slug is already in use\n- The remote URL for a media field returns a 404\n- You attempt to schedule a blog post (not supported)\n- Invalid author email or slug provided\n\nError explanations will be returned in a single JSON array.\n",
            "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**\n\nThis can happen when:\n- Your organization has reached the blog post limit for your plan\n- Your API token does not have write permissions\n",
            "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**\n\n- Could not find this organization's blog. This is a rare error that typically indicates a configuration issue.\n- Invalid pagination parameters (page number out of range).\n",
            "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.\n\n**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.\n\n**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.\n\n> **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.\n",
        "operationId": "retrieveSinglePost",
        "security": [
          {
            "readTokenAuthHeader": []
          },
          {
            "readTokenAuthQuery": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The unique slug of the blog post to retrieve.\n\n**Important**: The URL must end with a trailing slash (`/v2/posts/your-slug/`).\n",
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "example": "hello-world"
          },
          {
            "$ref": "#/components/parameters/auth_token"
          }
        ],
        "responses": {
          "200": {
            "description": "**Success - Blog Post Retrieved**\n\nReturns the complete blog post object along with navigation metadata for browsing between posts.\n",
            "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**\n\nThe blog post with the specified slug was not found. This can happen if:\n\n- The blog post doesn't exist\n- The blog post belongs to a different organization\n- You don't have access to the blog post\n",
            "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.\n\n**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.\n\n> **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.\n\n**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.\n\n**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.\n\n**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.\n",
        "operationId": "updateBlogPost",
        "security": [
          {
            "writeTokenAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The slug of the blog post to update.\n\n**Important**: The URL must end with a trailing slash (`/v2/posts/your-slug/`).\n",
            "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**\n\nThe 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).\n\n**Warning Messages**: If you provided `scheduled` timestamp or `status: \"scheduled\"`, these will be ignored and warning messages will be included in the response.\n",
            "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**\n\nThe API will return HTTP status code 400 if your data does not pass validation. This may happen if:\n\n- Invalid field values provided\n- The remote URL for a media field returns a 404\n- Invalid author email or slug provided\n- Malformed request data\n\nError explanations will be returned in a single JSON array.\n",
            "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**\n\nYour API token does not have write permissions or you don't have permission to update this blog post.\n",
            "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**\n\nThe blog post with the specified slug was not found or you don't have access to it.\n",
            "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.\n\n> **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.\n\n**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.\n\n**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.\n",
        "operationId": "deleteBlogPost",
        "security": [
          {
            "writeTokenAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The slug of the blog post to delete.\n\n**Important**: The URL must end with a trailing slash (`/v2/posts/your-slug/`).\n",
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "example": "this-is-a-blog-post"
          }
        ],
        "responses": {
          "204": {
            "description": "**No Content - Blog Post Successfully Deleted**\n\nThe blog post has been successfully deleted (soft delete). The response body is empty.\n\n**Note**: This is a soft delete operation. The post is marked as deleted but not physically removed from the system.\n"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedWriteResponse"
          },
          "403": {
            "description": "**Forbidden - Insufficient Permissions**\n\nYour API token does not have write permissions. Only write-enabled API tokens can delete blog posts.\n",
            "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**\n\nThe blog post with the specified slug was not found. This can happen if:\n\n- The blog post doesn't exist\n- The blog post belongs to a different organization\n- The blog post has already been deleted\n- You don't have access to the blog post\n",
            "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.\n\n**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.\n\n**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.\n",
        "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.\n\nWhen set to `recent_posts`, each author object will include a `recent_posts` array containing their latest blog posts.\n",
            "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": [
          {
            "readTokenAuthHeader": []
          },
          {
            "readTokenAuthQuery": []
          }
        ]
      }
    },
    "/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.\n\n**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.\n\n**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.\n",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "The unique slug identifier of the author to retrieve.\n\nMust match an existing author slug in your organization.\n",
            "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.\n\nWhen set to `recent_posts`, the author object will include a `recent_posts` array containing their latest blog posts.\n",
            "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": [
          {
            "readTokenAuthHeader": []
          },
          {
            "readTokenAuthQuery": []
          }
        ]
      }
    },
    "/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.\n\n**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.\n\n**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.\n",
        "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.\n\nWhen set to `recent_posts`, each category object will include a `recent_posts` array containing the latest blog posts in that category.\n",
            "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": [
          {
            "readTokenAuthHeader": []
          },
          {
            "readTokenAuthQuery": []
          }
        ]
      }
    },
    "/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.\n\n**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.\n\n**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.\n",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The unique slug identifier of the category to retrieve.\n",
            "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.\n\nWhen 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).\n",
            "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": [
          {
            "readTokenAuthHeader": []
          },
          {
            "readTokenAuthQuery": []
          }
        ]
      }
    },
    "/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.\n\n**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.\n\n**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.\n",
        "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.\n\nWhen set to `recent_posts`, each tag object will include a `recent_posts` array containing the latest blog posts tagged with that tag.\n",
            "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": [
          {
            "readTokenAuthHeader": []
          },
          {
            "readTokenAuthQuery": []
          }
        ]
      }
    },
    "/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.\n\n**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.\n\n**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.\n",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The unique slug identifier of the tag to retrieve.\n",
            "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.\n\nWhen 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).\n",
            "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": [
          {
            "readTokenAuthHeader": []
          },
          {
            "readTokenAuthQuery": []
          }
        ]
      }
    },
    "/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.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "default": ""
            },
            "description": "Search query string to find matching blog posts.\n\nThe 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.\n",
            "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.\n\nWhen 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.\n",
            "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": [
          {
            "readTokenAuthHeader": []
          },
          {
            "readTokenAuthQuery": []
          }
        ]
      }
    },
    "/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.\n\n**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.\n\n**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.\n",
        "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.\n\nProvide the URL-friendly slug of the category. When specified, only blog posts assigned to this category will be included in the RSS feed.\n",
            "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.\n\nProvide the URL-friendly slug of the tag. When specified, only blog posts tagged with this tag will be included in the RSS feed.\n",
            "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\"?>\n<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\">\n   <channel>\n      <title>Latest blog posts</title>\n      <link>https://example.buttercms.com/blog/rss/</link>\n      <description />\n      <atom:link href=\"https://example.buttercms.com/blog/rss/\" rel=\"self\" />\n      <language>en-us</language>\n      <lastBuildDate>Mon, 15 Jan 2024 10:00:00 +0000</lastBuildDate>\n      <item>\n         <title>API Development Best Practices for 2024</title>\n         <link>https://example.buttercms.com/blog/api-development-best-practices</link>\n         <media:content medium=\"image\" url=\"https://cdn.buttercms.com/featured/api-guide.jpg\"/>\n         <dc:creator xmlns:dc=\"http://purl.org/dc/elements/1.1/\">John Developer</dc:creator>\n         <pubDate>Mon, 15 Jan 2024 10:00:00 +0000</pubDate>\n         <guid>https://example.buttercms.com/blog/api-development-best-practices</guid>\n         <description>Learn the essential best practices for building scalable and maintainable APIs in 2024.</description>\n         <content:encoded>\n        <![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>]]>\n      </content:encoded>\n      </item>\n      <item>\n         <title>RESTful API Design Principles</title>\n         <link>https://example.buttercms.com/blog/restful-api-design-principles</link>\n         <media:content medium=\"image\" url=\"https://cdn.buttercms.com/featured/rest-design.jpg\"/>\n         <dc:creator xmlns:dc=\"http://purl.org/dc/elements/1.1/\">Sarah Architect</dc:creator>\n         <pubDate>Fri, 12 Jan 2024 09:00:00 +0000</pubDate>\n         <guid>https://example.buttercms.com/blog/restful-api-design-principles</guid>\n         <description>Master the fundamental principles of RESTful API design for better developer experience.</description>\n         <content:encoded>\n        <![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>]]>\n      </content:encoded>\n      </item>\n   </channel>\n</rss>\n"
                  },
                  "filtered_by_category": {
                    "summary": "RSS feed filtered by category",
                    "value": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<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\">\n   <channel>\n      <title>Latest blog posts</title>\n      <link>https://example.buttercms.com/blog/rss/</link>\n      <description />\n      <atom:link href=\"https://example.buttercms.com/blog/rss/\" rel=\"self\" />\n      <language>en-us</language>\n      <lastBuildDate>Wed, 10 Jan 2024 15:30:00 +0000</lastBuildDate>\n      <item>\n         <title>Product Launch: New API Features</title>\n         <link>https://example.buttercms.com/blog/product-launch-new-api-features</link>\n         <media:content medium=\"image\" url=\"https://cdn.buttercms.com/featured/product-launch.jpg\"/>\n         <dc:creator xmlns:dc=\"http://purl.org/dc/elements/1.1/\">Product Team</dc:creator>\n         <pubDate>Wed, 10 Jan 2024 15:30:00 +0000</pubDate>\n         <guid>https://example.buttercms.com/blog/product-launch-new-api-features</guid>\n         <description>Announcing exciting new API features and improvements in our latest release.</description>\n         <content:encoded>\n        <![CDATA[<h2>What's New</h2><p>We're excited to announce several new API features that will enhance your development experience...</p>]]>\n      </content:encoded>\n      </item>\n   </channel>\n</rss>\n"
                  }
                }
              }
            }
          },
          "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\"?>\n<error>Feed type not found</error>\n"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "readTokenAuthHeader": []
          },
          {
            "readTokenAuthQuery": []
          }
        ]
      }
    },
    "/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.\n\n**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.\n\n**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.\n",
        "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.\n\nProvide the URL-friendly slug of the category. When specified, only blog posts assigned to this category will be included in the Atom feed.\n",
            "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.\n\nProvide the URL-friendly slug of the tag. When specified, only blog posts tagged with this tag will be included in the Atom feed.\n",
            "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\"?>\n<feed xmlns=\"http://www.w3.org/2005/Atom\" xml:lang=\"en-us\">\n   <title>Latest blog posts</title>\n   <link href=\"https://example.buttercms.com/blog/rss/\" rel=\"alternate\" />\n   <link href=\"https://example.buttercms.com/blog/atom/\" rel=\"self\" />\n   <id>https://example.buttercms.com/blog/rss/</id>\n   <updated>2024-01-15T10:00:00Z</updated>\n   <entry>\n      <title>API Development Best Practices for 2024</title>\n      <link href=\"https://example.buttercms.com/blog/api-development-best-practices\" rel=\"alternate\" />\n      <published>2024-01-15T10:00:00Z</published>\n      <updated>2024-01-15T10:00:00Z</updated>\n      <author>\n         <name>John Developer</name>\n      </author>\n      <id>https://example.buttercms.com/blog/api-development-best-practices</id>\n      <summary type=\"html\">Learn the essential best practices for building scalable and maintainable APIs in 2024.</summary>\n   </entry>\n   <entry>\n      <title>RESTful API Design Principles</title>\n      <link href=\"https://example.buttercms.com/blog/restful-api-design-principles\" rel=\"alternate\" />\n      <published>2024-01-12T09:00:00Z</published>\n      <updated>2024-01-12T09:00:00Z</updated>\n      <author>\n         <name>Sarah Architect</name>\n      </author>\n      <id>https://example.buttercms.com/blog/restful-api-design-principles</id>\n      <summary type=\"html\">Master the fundamental principles of RESTful API design for better developer experience.</summary>\n   </entry>\n</feed>\n"
                  },
                  "filtered_by_tag": {
                    "summary": "Atom feed filtered by tag",
                    "value": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<feed xmlns=\"http://www.w3.org/2005/Atom\" xml:lang=\"en-us\">\n   <title>Latest blog posts</title>\n   <link href=\"https://example.buttercms.com/blog/rss/\" rel=\"alternate\" />\n   <link href=\"https://example.buttercms.com/blog/atom/\" rel=\"self\" />\n   <id>https://example.buttercms.com/blog/rss/</id>\n   <updated>2024-01-10T15:30:00Z</updated>\n   <entry>\n      <title>New Features in Our API</title>\n      <link href=\"https://example.buttercms.com/blog/new-features-in-our-api\" rel=\"alternate\" />\n      <published>2024-01-10T15:30:00Z</published>\n      <updated>2024-01-10T15:30:00Z</updated>\n      <author>\n         <name>Product Team</name>\n      </author>\n      <id>https://example.buttercms.com/blog/new-features-in-our-api</id>\n      <summary type=\"html\">Announcing exciting new API features and improvements in our latest release.</summary>\n   </entry>\n</feed>\n"
                  }
                }
              }
            }
          },
          "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\"?>\n<error>Feed type not found</error>\n"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "readTokenAuthHeader": []
          },
          {
            "readTokenAuthQuery": []
          }
        ]
      }
    },
    "/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.\n\n**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.\n\n**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.\n",
        "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.\n\nProvide the URL-friendly slug of the category. When specified, only blog posts assigned to this category will be included in the sitemap.\n",
            "example": "announcements"
          },
          {
            "name": "tag_slug",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter the sitemap to include only posts with a specific tag.\n\nProvide the URL-friendly slug of the tag. When specified, only blog posts tagged with this tag will be included in the sitemap.\n",
            "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\"?>\n<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\">\n  <url>\n    <loc>https://example.buttercms.com/blog/api-development-best-practices</loc>\n    <lastmod>2024-01-15</lastmod>\n  </url>\n  <url>\n    <loc>https://example.buttercms.com/blog/restful-api-design-principles</loc>\n    <lastmod>2024-01-12</lastmod>\n  </url>\n  <url>\n    <loc>https://example.buttercms.com/blog/microservices-architecture-guide</loc>\n    <lastmod>2024-01-10</lastmod>\n  </url>\n  <url>\n    <loc>https://example.buttercms.com/blog/database-optimization-techniques</loc>\n    <lastmod>2024-01-08</lastmod>\n  </url>\n</urlset>\n"
                  },
                  "filtered_by_category": {
                    "summary": "Sitemap filtered by category",
                    "value": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<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\">\n  <url>\n    <loc>https://example.buttercms.com/blog/new-api-features-released</loc>\n    <lastmod>2024-01-10</lastmod>\n  </url>\n  <url>\n    <loc>https://example.buttercms.com/blog/product-roadmap-update</loc>\n    <lastmod>2024-01-05</lastmod>\n  </url>\n</urlset>\n"
                  }
                }
              }
            }
          },
          "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\"?>\n<error>Feed type not found</error>\n"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "readTokenAuthHeader": []
          },
          {
            "readTokenAuthQuery": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "readTokenAuthQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "auth_token",
        "description": "Pass your API token via the `auth_token` parameter on every request: `?auth_token=your_read_api_token`.\n\nYou can access your API token from your settings page.\n\nRequests made with a missing or invalid token will get a 401 Unauthorized response. All requests must be made over HTTPS.\n"
      },
      "readTokenAuthHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Set the `Authorization` header to `Token your_read_api_token`.\n\nExample: `Authorization: Token abc123def456`\n\nNote: The header value includes the `Token` prefix.\n\nYou can access your API token from your settings page.\n"
      },
      "writeTokenAuth": {
        "type": "http",
        "scheme": "Token",
        "description": "Write-enabled API token required for creating content.\n\nThe 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.\n\nSet the `Authorization` header to `Token your_write_api_token`.\n\nExample: `Authorization: Token abc123def456`\n\nYour write-enabled token should never be used anywhere it would be exposed, e.g. in client-side JavaScript.\n"
      }
    },
    "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.**\n\nSystem automatically detects the format based on the structure of the `fields` object:\n\n**Single-Locale Format**: `fields` contains field names as keys (e.g., `headline`, `questions`)\n**Multi-Locale Format**: `fields` contains locale codes as keys (e.g., `en`, `es`, `fr`)\n\n**Request Body Formats**:\n- **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`.\n- **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.\n",
        "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'.\nNote that you cannot create a page with a status of 'scheduled' via the write API.\n",
            "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**\n- **Format 1: Single-locale/direct fields**\n  - `fields` contains field names as keys (e.g., `headline`, `questions`).\n\n- **Format 2: Multi-locale**\n  - `fields` contains locale codes as keys (e.g., `en`, `es`, `fr`).\n\n- **Detection**: The system automatically detects the format based on whether the\n  top-level keys are locale codes or field names.\n\n- **Field requirements**\n  - All field keys are required for each locale/format you include. If a field is not\n    required in your page type, set it to an empty string.\n  - Repeater fields must be JSON arrays of the repeater groups. For optional repeater\n    fields, use an empty array (`[]`).\n  - Providing a remote URL in any Media field triggers automatic download and upload\n    to your ButterCMS media library.\n\n- **Examples**: See the Examples section for sample request bodies.\n"
          }
        }
      },
      "UpdatePageRequest": {
        "type": "object",
        "description": "**Flexible request schema for updating pages - supports both single-locale and multi-locale formats.**\n\nSystem automatically detects the format based on the structure of the `fields` object:\n\n**Single-Locale Format**: `fields` contains field names as keys (e.g., `headline`, `questions`)\n**Multi-Locale Format**: `fields` contains locale codes as keys (e.g., `en`, `es`, `fr`)\n\n**Partial Updates**: You only need to specify the fields you want to update.\nNote: Pages accept both PATCH and PUT; PUT behaves like PATCH (partial update).\n\n**Immutable Fields**: Cannot update `title` or `slug` via PATCH.\n\n**Field Name Flexibility**: You can use either `title` or `name` in the request - both are accepted and `name` will be automatically converted to `title`.\n",
        "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.\n\n**Alternative**: You can also use `name` which will be automatically converted to `title`.\n"
          },
          "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.\n\nNote: If `scheduled` timestamp or status is passed, these fields will be ignored to allow updating already scheduled pages.\n",
            "example": "draft"
          },
          "fields": {
            "type": "object",
            "description": "**Flexible Fields Object - Two Supported Formats**\n- **Format 1: Single-locale/direct fields**\n  - `fields` contains field names as keys (e.g., `headline`, `questions`).\n\n- **Format 2: Multi-locale**\n  - `fields` contains locale codes as keys (e.g., `en`, `es`, `fr`).\n\n- **Detection**: The system automatically detects the format based on whether the\n  top-level keys are locale codes or field names.\n\n- **Partial update behavior**\n  - Only specify the fields you want to update; omitted fields remain unchanged.\n  - Repeater fields must be replaced in full; delta changes are not supported. If you need\n    to clear a repeater, provide an empty array (`[]`).\n  - Images and media can be updated by providing remote URLs.\n\n- **Examples**: See the Examples section below for sample request bodies.\n"
          }
        }
      },
      "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:\n\n- **draft**: Item is saved but not publicly available\n- **published**: Item is live and publicly accessible\n\nDefaults to \"draft\" if not specified.\n",
        "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.\n\nMust match an existing collection in your organization.\n",
            "example": "team_members"
          },
          "status": {
            "$ref": "#/components/schemas/CollectionItemStatus"
          },
          "fields": {
            "type": "array",
            "description": "Array of collection item data. Structure varies based on locale configuration:\n\n- **Without Locales**: Array of objects with direct field key-value pairs\n- **With Locales**: Array of objects with locale codes as keys, containing field data\n\n**Dynamic Nature**: Field names and types are defined by your collection schema and can vary completely between collections.\n",
            "items": {
              "type": "object",
              "description": "**Flexible collection item data - supports both single-locale and multi-locale formats.**\n\nSystem automatically detects the format based on the structure of the object:\n\n**Without Locales Format**: Direct field properties (e.g., `name`, `position`, `bio`)\n**With Locales Format**: Locale codes as keys (e.g., `en`, `es`, `fr`)\n\n**Dynamic Schema**: Field names and types are completely user-defined based on your collection configuration.\n",
              "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.**\n\n**Update Types**:\n- **PUT**: Requires `fields` for full replacement\n- **PATCH**: `fields` is optional for partial updates (e.g., status-only updates)\n",
        "properties": {
          "status": {
            "$ref": "#/components/schemas/CollectionItemStatus",
            "description": "Publication status of the collection item.\n\n- If omitted in PATCH requests, the current status is preserved\n- If provided in PUT/PATCH requests, the status will be updated\n"
          },
          "fields": {
            "type": "object",
            "description": "**Optional for PATCH, Required for PUT**. Collection item field data with flexible format support.\n\nSystem automatically detects the format based on the structure of the object:\n\n**Without Locales Format**: Direct field properties (e.g., `name`, `position`, `bio`)\n**With Locales Format**: Locale codes as keys (e.g., `en`, `es`, `fr`)\n\n**Update Behavior**:\n- **PUT**: All fields should be provided (full replacement)\n- **PATCH**: Only provided fields are updated, others remain unchanged\n\n**Dynamic Schema**: Field names and types are completely user-defined based on your collection configuration.\n\n**Reference Fields**: Support updating relationships to Pages and other Collections\n- Page references: Use page slugs (e.g., `\"related_page\": \"example-slug\"`)\n- Collection references: Use collection item IDs (e.g., `\"tags\": [1, 2, 3]`)\n- Remove references: Use `\"\"`, `[]`, or `null`\n\n**Media Fields**: Support remote URL upload - content is automatically uploaded to ButterCMS\n",
            "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).\n\n**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.\n",
            "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.\n\nThe image will always be uploaded to the media library (the value of `upload_images_to_media_library` is ignored for featured images).\n",
            "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.\n\nIn case it contains any remote URLs to images, the `upload_images_to_media_library` flag controls the behavior.\n",
            "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`.\n\nIf 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.\n\n**Note**: Featured images are always uploaded regardless of this setting.\n",
            "default": false,
            "example": false
          }
        }
      },
      "UpdateBlogPostRequest": {
        "type": "object",
        "description": "Request schema for updating an existing blog post. All fields are optional for partial updates.\n\n**Note**: If `scheduled` timestamp or `status: \"scheduled\"` are provided, they will be ignored and warning messages will be included in the response.\n",
        "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.\n\n**Auto-Slugification**: The API automatically converts your input to a valid slug format using unicode slugification.\n",
            "maxLength": 100,
            "example": "updated-blog-post-slug"
          },
          "status": {
            "type": "string",
            "description": "The status of the post.\n\n**Note**: `\"scheduled\"` status will be ignored and a warning message will be included in the response.\n",
            "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.\n\nThe image will always be uploaded to the media library (the value of `upload_images_to_media_library` is ignored for featured images).\n",
            "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.\n\nIn case it contains any remote URLs to images, the `upload_images_to_media_library` flag controls the behavior.\n",
            "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`.\n\nIf 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.\n\n**Note**: Featured images are always uploaded regardless of this setting.\n",
            "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.\n\nIf provided, this field will be removed from the request and a warning message will be included in the response.\n",
            "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.\n",
        "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.\n\nYou can specify the author either by email or by slug. If no author is specified, defaults to the organization owner.\n",
        "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**\n\nNo valid write API key provided. The API token you use for reading from the ButterCMS API\nwill not allow you to create content. You need a different write-enabled token.\nContact support@buttercms.com to get yours.\n",
        "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\"?>\n<detail>Authentication credentials were not provided</detail>\n"
              },
              "invalid_token": {
                "summary": "Invalid API token",
                "value": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<detail>Invalid token</detail>\n"
              }
            }
          }
        }
      }
    },
    "parameters": {
      "auth_token": {
        "name": "auth_token",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Your ButterCMS read API token\n",
        "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.\n\nSet to `1` to access unpublished/draft collection items. Useful for staging environments.\n",
        "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.\n",
        "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.\n\n**Mutually exclusive with limit/offset parameters.**\n",
        "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.\n\n**Mutually exclusive with limit/offset parameters.**\n",
        "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.\n\n**Note**: Only available for Page Type endpoints, not for Single Pages (`page_type=*`).\n",
        "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.\n\n**Mutually exclusive with page/page_size parameters.**\n",
        "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.\n\n**Mutually exclusive with page/page_size parameters.**\n",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 0,
          "default": 0
        },
        "example": 10
      },
      "levels": {
        "name": "levels",
        "in": "query",
        "description": "Depth of relationship serialization.\n\nControls how many levels of referenced content to include:\n- **1**: Direct fields only, references as URIs\n- **2**: Direct fields + one level of references (default)\n- **3-5**: Deeper relationship traversal\n\n**Important**: Higher levels increase response size. Maximum 10MB per response.\n\nValid range: 1-5 (inclusive). Values outside this range will be automatically capped.\n",
        "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.\n\nAffects only media-typed fields. Other field types are unchanged.\n\n- **0** (default): Media fields return simple URL strings\n- **1**: Media fields return objects with at least `url` and, when available,\n  `alt`. If the stored media value is just a URL string, the object will\n  include `url` only.\n",
        "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.\n\nThis event fires when:\n- A draft page is published for the first time\n- An already published page is republished after changes\n- A scheduled page is automatically published\n",
        "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.\n\nThis event fires when:\n- A new page is created and saved as draft\n- An existing draft page is updated and saved\n- A published page is updated but not yet republished\n",
        "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).\n\nThis event fires when:\n- A published page is deliberately unpublished but kept in the system\n- A page is temporarily taken offline without permanent deletion\n",
        "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.\n\nThis event fires when:\n- A page is permanently removed from the system\n- A page is moved to trash and then permanently deleted\n",
        "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).\n\nThis is a catch-all event that fires for all page changes, useful for comprehensive page monitoring and cache invalidation across all page types.\n",
        "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.\n\nThis event fires when:\n- A draft blog post is published for the first time\n- An already published post is republished after changes\n- A scheduled post is automatically published\n",
        "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.\n\nThis event fires when:\n- A new blog post is created and saved as draft\n- An existing draft is updated and saved\n- A published post is updated and saved as draft (effectively unpublishing)\n",
        "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.\n\nThis event fires when:\n- A published blog post is moved to trash\n- A published blog post is permanently deleted\n- A published blog post is unpublished (soft delete)\n",
        "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).\n\nThis is a catch-all event that fires for all blog post changes, making it useful for general blog post monitoring and cache invalidation.\n",
        "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.\n\nThis event fires when:\n- A draft collection item is published for the first time\n- An already published item is republished after changes\n- A scheduled item is automatically published\n",
        "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.\n\nThis event fires when:\n- A new collection item is created and saved as draft\n- An existing draft item is updated and saved\n- A published item is updated but not yet republished\n",
        "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).\n\nThis event fires when:\n- A published collection item is deliberately unpublished but kept in the system\n- An item is temporarily taken offline without permanent deletion\n",
        "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.\n\nThis event fires when:\n- A collection item is permanently removed from the system\n- A collection item is moved to trash and then permanently deleted\n",
        "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).\n\nThis is a catch-all event that fires for all collection item changes, useful for comprehensive content monitoring across all collections.\n",
        "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.\n\nThis event fires when:\n- A new video file is uploaded to ButterCMS media library\n- Video processing is completed and the file is available\n",
        "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": [
    {
      "readTokenAuthHeader": []
    },
    {
      "readTokenAuthQuery": []
    }
  ]
}