### ButterCMS Collection Reference Examples Source: https://buttercms.com/docs/api/collections-key-concepts/reference-architecture Examples of how to implement collection references for featured content, related resources, and associations in ButterCMS. These examples use string slugs for page references and numeric IDs for collection references. ```json { "featured_page": "landing-page-slug", "related_pages": ["guide-1-slug", "guide-2-slug"], "product_page": "product-details-slug", "parent_category": 123, "related_products": [456, 789, 101], "department": 234, "region": 345 } ``` -------------------------------- ### Example Media Integration JSON Source: https://buttercms.com/docs/api/pages-components/advanced-features This JSON example demonstrates how external image URLs provided in component fields are processed by ButterCMS. After processing, these URLs are replaced with ButterCMS CDN URLs for optimized delivery. ```json { "hero_section": { "background_image": "https://external-site.com/image.jpg", "logo": "https://company-assets.com/logo.png" } } ``` -------------------------------- ### GET /feeds/sitemap/ Source: https://buttercms.com/docs/api/feeds-and-utilities 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. ```APIDOC ## GET /feeds/sitemap/ ### Description Generate a comprehensive XML sitemap for your blog posts, optimized for search engine discovery and indexing. ### Method GET ### Endpoint /feeds/sitemap/ ### Parameters #### Query Parameters - **category** (string) - Optional - Filter sitemap by category - **tag** (string) - Optional - Filter sitemap by tag ### Response #### Success Response (200) XML formatted sitemap following the sitemaps.org protocol including post URLs, last modification dates, and change frequency information. #### Response Example ```xml https://example.com/post 2024-01-01 weekly ``` ``` -------------------------------- ### GET /feeds/sitemap/ Source: https://buttercms.com/docs/api/feeds-and-utilities/getsitemap Generates 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. ```APIDOC ## GET /feeds/sitemap/ ### Description Generate a comprehensive XML sitemap for your blog posts, optimized for search engine discovery and indexing. This endpoint creates a standards-compliant sitemap that helps search engines efficiently crawl and index your blog content. SEO Optimization: Produces an XML sitemap following the sitemaps.org protocol that includes post URLs, last modification dates, and change frequency information. This helps search engines understand your content structure and prioritize crawling of updated content. Filtering for Focused Sitemaps: Apply category or tag filters to create specialized sitemaps for specific content sections. This is useful for large blogs where you want to submit targeted sitemaps to search engines or create separate indexing strategies for different content types. ### Method GET ### Endpoint /feeds/sitemap/ ### Parameters #### Query Parameters - **auth_token** (string) - Required - Your ButterCMS read API token Example: "your_api_token" - **category_slug** (string) - Optional - Filter the sitemap to include only posts from a specific category. Provide the URL-friendly slug of the category. When specified, only blog posts assigned to this category will be included in the sitemap. Example: "announcements" - **tag_slug** (string) - Optional - Filter the sitemap to include only posts with a specific tag. Provide the URL-friendly slug of the tag. When specified, only blog posts tagged with this tag will be included in the sitemap. Example: "seo-tips" ### Request Example ```json { "query": { "auth_token": "your_api_token", "category_slug": "announcements", "tag_slug": "seo-tips" } } ``` ### Response #### Success Response (200) - **sitemap** (string) - The generated XML sitemap content. #### Response Example ```xml https://yourdomain.com/blog/post-1/ 2023-10-27T10:00:00+00:00 daily https://yourdomain.com/blog/post-2/ 2023-10-26T15:30:00+00:00 weekly ``` ``` -------------------------------- ### GET /tags/ Source: https://buttercms.com/docs/api/blog-metadata/listalltags Retrieves a complete list of all blog post tags, 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. ```APIDOC ## GET /tags/ ### Description Retrieve a complete list of all blog post tags in your organization, providing granular categorization and labeling information for your blog content. This endpoint is essential for building tag-based navigation, content discovery features, and detailed content organization systems. Tag Information: Returns the tag name and URL-friendly slug for each tag that contains published posts. Tags offer more granular content categorization than categories, allowing for detailed topical organization and improved content discoverability. Recent Posts Integration: Use the include=recent_posts parameter to enrich the response with each tag's most recent blog posts. This is particularly useful for creating tag cloud interfaces, topic-based landing pages, and tag archive pages that showcase recent activity for specific topics. ### Method GET ### Endpoint /tags/ ### Parameters #### Query Parameters - **auth_token** (string) - Required - Your ButterCMS read API token Example: "your_api_token" - **include** (string) - Optional - Include additional data in the response. When set to recent_posts, each tag object will include a recent_posts array containing the latest blog posts tagged with that tag. Enum: "recent_posts" ### Response #### Success Response (200) - **data** (array) - Array of tag objects - **data.name** (string) - Display name of the tag Example: "API Development" - **data.slug** (string) - URL-friendly slug of the tag Example: "api-development" - **data.recent_posts** (array) - Array of recent posts with this tag (only included when include=recent_posts parameter is used) - **data.recent_posts.slug** (string) - Blog post slug/identifier Example: "rest-api-best-practices" - **data.recent_posts.title** (string) - Blog post title Example: "REST API Best Practices for Modern Development" - **data.recent_posts.published** (string) - Publication date and time in ISO 8601 format Example: "2024-01-22T09:00:00.000Z" #### Error Response (401) - **detail** (string) - Error message describing what went wrong Example: "Authentication credentials were not provided" ### Request Example ```http GET /tags?auth_token=your_api_token&include=recent_posts HTTP/1.1 Host: api.buttercms.com ``` ### Response Example (Success) ```json { "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" } ] } ] } ``` ### Response Example (Error) ```json { "detail": "Authentication credentials were not provided" } ``` ``` -------------------------------- ### POST /posts/ Source: https://buttercms.com/docs/api/blog-posts-write Creates a new blog post with rich media, categories, tags, and optional author assignment. Returns immediately with a 202 status while processing the post asynchronously. ```APIDOC ## POST /posts/\n\n### Description\nCreate a new blog post using the Write API with support for rich media, categorization, and automatic author assignment.\n\n### Method\nPOST\n\n### Endpoint\n/v2/posts/\n\n### Parameters\n#### Path Parameters\n*(none)*\n\n#### Query Parameters\n*(none)*\n\n#### Request Body\n- **title** (string) - Required - Title of the blog post.\n- **slug** (string) - Required - URL-friendly identifier, must be unique.\n- **author** (string) - Optional - Author email or slug; defaults to organization owner if omitted.\n- **categories** (array[string]) - Optional - List of category names; non‑existing categories are created automatically.\n- **tags** (array[string]) - Optional - List of tag names; non‑existing tags are created automatically.\n- **featured_image** (string) - Optional - URL of the featured image; will be uploaded to the media library.\n- **upload_images_to_media_library** (boolean) - Optional - Set to true to download and host external images in the post body.\n- **status** (string) - Optional - Publish status; `published` to make the post live, otherwise defaults to draft.\n\n### Request Example\n{\n \"title\": \"My First Blog Post\",\n \"slug\": \"my-first-blog-post\",\n \"author\": \"author@example.com\",\n \"categories\": [\"Tech\", \"Announcements\"],\n \"tags\": [\"release\", \"update\"],\n \"featured_image\": \"https://example.com/image.jpg\",\n \"upload_images_to_media_library\": true,\n \"status\": \"published\"\n}\n\n### Response\n#### Success Response (202)\n- **message** (string) - Indicates that the post creation request has been accepted for asynchronous processing.\n\n### Response Example\n{\n \"message\": \"Post creation accepted and is being processed.\"\n} ``` -------------------------------- ### POST /posts/ Source: https://buttercms.com/docs/api/blog-posts-write/createblogpost This endpoint allows creating a new blog post with rich media support, categorization, and author assignment. It processes requests asynchronously, returning 202 Accepted immediately while handling post creation in the background. The API supports automatic slug generation, category/tag creation, and image uploads to the media library. ```APIDOC ## POST /posts/ ### 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. ### Method POST ### Endpoint /posts/ ### Parameters #### Path Parameters - None #### Query Parameters - None #### Request Body - **title** (string) - Required - The title of the blog post - **slug** (string) - Optional - The slug of the blog post (must be unique). Auto-Generation: If not provided, the slug will be automatically generated from the title using unicode slugification. - **status** (string) - Optional - The status of the post. Defaults to 'draft'. Cannot be 'scheduled'. Enum: "draft", "published" - **author** (any) - Optional - The author must already exist in your ButterCMS account. You can specify by email address or slug. - **categories** (array) - Optional - Array of category names. Categories will be created if they don't exist. - **tags** (array) - Optional - Array of tag names. Tags will be created if they don't exist. - **featured_image** (string) - Optional - Can be a remote URL to an image. The image will always be uploaded to the media library. - **featured_image_alt** (string) - Optional - Alt text for the featured image - **body** (string) - Optional - Should be a string of escaped HTML. In case it contains any remote URLs to images, the upload_images_to_media_library flag controls the behavior. - **summary** (string) - Optional - Plain-text summary of the blog post - **seo_title** (string) - Optional - SEO title for HTML title tag - **meta_description** (string) - Optional - Meta description for SEO and social sharing - **upload_images_to_media_library** (boolean) - Optional - Defaults to false. If set to true, any image URLs in the body property will be uploaded to the Butter Media Library and the original URL will be replaced with the media library URL. ### Request Example { "title": "This is a blog post", "slug": "this-is-a-blog-post", "status": "draft", "author": "author@example.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": "

Butter

I am so hungry!

", "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 } ### Response #### Success Response (202) - **status** (string) - Indicates that the blog post creation is being processed asynchronously. Enum: "pending" #### Response Example { "status": "pending" } #### Error Responses - **401 Unauthorized** - Authentication credentials not provided - **detail** (string) - Error message - **404 Not Found** - Resource not found or invalid request - **detail** (string) - Error message ``` -------------------------------- ### GET /pages/{page_type}/{page_slug}/ - Get a single Page Source: https://buttercms.com/docs/api/pages-read Retrieves a specific page by its page type and slug. Ideal for fetching individual pages for display on your website or application. ```APIDOC ## GET /pages/{page_type}/{page_slug}/ ### Description Retrieves a specific page by its page type and slug. This endpoint is ideal for fetching individual pages for display on your website or application. ### Method GET ### Endpoint /pages/{page_type}/{page_slug}/ ### Parameters #### Path Parameters - **page_type** (string) - Required - The page type slug, or * for Single Pages. - **page_slug** (string) - Required - The slug of the page to retrieve. #### Query Parameters - **fields** (string) - Optional - Dotted notation for field filters (e.g., fields.title=Example). ### Request Example { "fields": "fields.title, fields.body" } ### Response #### Success Response (200) - **fields** (object) - The fields of the page. #### Response Example { "fields": { "title": "Example Page Title", "body": "This is the body of the example page." } } ``` -------------------------------- ### GET /pages/{page_type}/ - Retrieve Multiple Pages Source: https://buttercms.com/docs/api/pages-read/getmultiplepages Fetches a paginated list of pages. Use '*' for page_type to get Single Pages, or a specific page type slug for collections. Supports filtering, sorting, and previewing drafts. ```APIDOC ## GET /pages/{page_type}/ ### Description Retrieve a paginated list of pages for a given page type, or all Single Pages when using the wildcard * as the page type. This endpoint supports comprehensive filtering and sorting for Page Type collections. - **Single Pages**: Use `*` to retrieve Single Pages (e.g., Homepage, About page). Useful for sitemaps or navigation. - **Page Type Collections**: Use the actual page type slug (e.g., 'blog_posts', 'products') to retrieve pages that share the same structural template. *Note*: Advanced filtering and ordering are only available for Page Type endpoints, not for Single Pages (`page_type=*`). ### Method GET ### Endpoint /pages/{page_type}/ ### Parameters #### Path Parameters - **page_type** (string, required) - The slug of the type of pages you want to retrieve, or `*` for Single Pages. #### Query Parameters - **preview** (integer, optional) - Set to `1` to return the latest draft version of a page. Useful for previewing unpublished changes. Enum: 0, 1. - **page** (integer, optional) - Page number for page-based pagination. Mutually exclusive with `limit`/`offset`. - **page_size** (integer, optional) - Number of items per page for page-based pagination. Mutually exclusive with `limit`/`offset`. - **limit** (integer, optional) - Maximum number of items to return for offset-based pagination. Mutually exclusive with `page`/`page_size`. - **offset** (integer, optional) - Number of items to skip before starting to return results. Mutually exclusive with `page`/`page_size`. - **locale** (string, optional) - The API slug of your configured locale (e.g., `en`, `fr`). Defaults to the organization's default locale. - **levels** (integer, optional) - Depth of relationship serialization. Controls how many levels of referenced content to include. Valid range: 1-5. Default: 2. - **alt_media_text** (integer, optional) - Media field response format. `0` (default): Media fields return URL strings. `1`: Media fields return objects with `url` and `alt`. - **auth_token** (string, required) - Your ButterCMS read API token. - **order** (string, optional) - Sort order. Can order by `published`, `updated`, or a content field. Prepend `-` for descending order. *Note*: Only available for Page Type endpoints. - **fields.seo.title** (string, optional) - Filter by a nested field value (e.g., `fields.seo.title=Home`). *Note*: Only available for Page Type endpoints. - **fields.headline** (string, optional) - Filter by a top-level field value (e.g., `fields.headline=Welcome`). *Note*: Only available for Page Type endpoints. ### Request Example ``` GET /v2.0.0/pages/blog_posts/?limit=10&fields.category=Technology&order=-published&auth_token=your_api_token ``` ### Response #### Success Response (200 OK) - **count** (integer) - The total number of pages matching the query. - **next** (string) - URL for the next page of results, or null if there are no more pages. - **previous** (string) - URL for the previous page of results, or null if there are no more pages. - **results** (array) - An array of page objects. - Each page object contains its fields, metadata (like `slug`, `published`, `updated`), etc. #### Response Example ```json { "count": 25, "next": "/v2.0.0/pages/blog_posts/?limit=10&offset=10&fields.category=Technology&order=-published&auth_token=your_api_token", "previous": null, "results": [ { "slug": "first-post", "title": "My First Blog Post", "published": "2023-10-27T10:00:00Z", "updated": "2023-10-27T10:00:00Z", "custom_fields": { "headline": "Welcome to ButterCMS!", "body": "

This is the content of my first post.

", "category": "Technology" } }, { "slug": "second-post", "title": "Another Post", "published": "2023-10-26T11:30:00Z", "updated": "2023-10-26T11:30:00Z", "custom_fields": { "headline": "Exploring Features", "body": "

ButterCMS has many features to explore.

", "category": "Technology" } } ] } ``` #### Error Response (401 Unauthorized) - **detail** (string) - Error message describing authentication failure. #### Error Response Example (401) ```json { "detail": "Authentication credentials were not provided" } ``` #### Error Response (404 Not Found) - **detail** (string) - Error message describing resource not found. #### Error Response Example (404) ```json { "detail": "The requested resource could not be found." } ``` ``` -------------------------------- ### Blog Posts - Key Concepts Source: https://buttercms.com/docs/api/index Explains the core concepts of working with ButterCMS Blog Posts, including built-in features and content characteristics. ```APIDOC ## Blogs - Key Concepts ### Description Essential concepts for working with ButterCMS Blog Posts, including predefined schemas, built-in organizational features, and publication characteristics. Blog Posts are designed for chronological content with standardized blog functionality. ### Key Concepts * **Built-in Features**: Comes with out-of-the-box categorization, tagging, predefined SEO fields, and author management. * **Chronological Content**: Optimized for content that is published and displayed in a time-based sequence. * **Standardized Functionality**: Offers standard blog features like post listings, individual post views, and related content suggestions. * **SEO Optimized**: Predefined fields and structures to help optimize blog content for search engines. ``` -------------------------------- ### GET /pages/{page_type}/ - Get multiple Pages Source: https://buttercms.com/docs/api/pages-read Retrieves a paginated list of pages for a given page type, or all Single Pages when using the wildcard * as the page type. Supports comprehensive filtering and sorting for Page Type collections. ```APIDOC ## GET /pages/{page_type}/ ### Description Retrieves 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. ### Method GET ### Endpoint /pages/{page_type}/ ### Parameters #### Path Parameters - **page_type** (string) - Required - The page type slug, or * for Single Pages. #### Query Parameters - **fields** (string) - Optional - Dotted notation for field filters (e.g., fields.title=Home). ### Request Example { "fields": "fields.title, fields.body" } ### Response #### Success Response (200) - **data** (array) - An array of page objects. - **total** (integer) - The total number of pages matching the query. #### Response Example { "data": [ { "fields": { "title": "Example Page 1", "body": "This is the body of the first example page." } }, { "fields": { "title": "Example Page 2", "body": "This is the body of the second example page." } } ], "total": 2 } ``` -------------------------------- ### POST /pages/ Source: https://buttercms.com/docs/api/pages-write/createpage Creates a new page via the ButterCMS Write API. Supports single or multi-locale content, automatic media uploads, and setting page status to 'draft' or 'published'. ```APIDOC ## POST /pages/ ### Description Creates a new page using the ButterCMS Write API. This endpoint supports multiple locales and automatic media uploads. Pages are created as drafts by default; set `status=published` to publish immediately. Scheduling future publication is not supported. ### Method POST ### Endpoint /pages/ ### Query Parameters #### `locale` (string) - Optional Set to the API slug of a pre-configured locale (e.g., 'en' or 'fr'). Applicable only when using the single-locale request format. Defaults to your organization's default locale if omitted and using single-locale format. Example: "en" ### Request Body #### `title` (string) - Required The title of the page. Example: "Frequently Asked Questions" #### `slug` (string) - Required The slug of the page. Example: "faq" #### `status` (string) - Optional Status of the page. Can be 'draft' or 'published'. Defaults to 'draft'. Enum: "draft", "published" #### `page_type` (string) - Required The key of the page type. The page type must already exist in your Butter account. Example: "questions" #### `fields` (object) - Required Flexible Fields Object. Supports two formats: 1. **Single-locale/direct fields**: Contains field names as keys (e.g., headline, questions). 2. **Multi-locale**: Contains locale codes as keys (e.g., en, es, fr), with field data nested inside each locale. The system automatically detects the format. All field keys defined in your page type schema must be included, even optional ones (provide empty strings if not populated). Providing a remote URL in any Media field triggers automatic download and upload to your ButterCMS media library. ### Request Example (Multi-locale) ```json { "title": "About Us", "slug": "about-us", "status": "published", "page_type": "about_page", "fields": { "en": { "headline": "Welcome to ButterCMS", "body": "

ButterCMS is a content management system.

", "hero_image": "https://example.com/images/hero.jpg" }, "es": { "headline": "Bienvenido a ButterCMS", "body": "

ButterCMS es un sistema de gestión de contenido.

", "hero_image": "https://example.com/images/hero_es.jpg" } } } ``` ### Request Example (Single-locale) ```json { "title": "Contact Us", "slug": "contact", "status": "draft", "page_type": "contact_form", "fields": { "headline": "Get in Touch", "email_address": "info@example.com", "phone_number": "123-456-7890" } } ``` ### Response #### Success Response (202 Accepted) - **status** (string) - Indicates that the page creation request has been accepted and is being processed asynchronously. Enum: "pending" #### Response Example (202 Accepted) ```json { "status": "pending" } ``` #### Error Response (401 Unauthorized) - **detail** (string) - Error message describing what went wrong. Example: "Authentication credentials were not provided" #### Error Response (403 Forbidden) - **error** (string) - Error message when subscription plan limits are exceeded. Example: "Page creation limit is over" ``` -------------------------------- ### GET /pages/search/ Source: https://buttercms.com/docs/api/pages-read/searchpages Searches for pages based on a text query. Results are sorted by relevancy and can be filtered by page type, locale, and pagination parameters. ```APIDOC ## GET /pages/search/ ### Description Searches 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. ### Method GET ### Endpoint /pages/search/ ### Parameters #### Query Parameters - **query** (string) - Required - The search query string to match against page content. Maximum 100 characters. - **page_type** (string) - Optional - The slug of the type of pages to limit the search to. Use '*' to search only Single Pages. Maximum 100 characters. - **locale** (string) - Optional - Set to the API slug of your configured locale (e.g., 'en' or 'fr'). Defaults to the organization's default locale. - **levels** (integer) - Optional - Depth of relationship serialization, controlling how many levels of referenced content to include. Valid range: 1-5. Defaults to 2. - **page** (integer) - Optional - Page number for page-based pagination. Mutually exclusive with limit/offset parameters. - **page_size** (integer) - Optional - Number of items per page for page-based pagination. Mutually exclusive with limit/offset parameters. - **limit** (integer) - Optional - Maximum number of items to return for offset-based pagination. Mutually exclusive with page/page_size parameters. - **offset** (integer) - Optional - Number of items to skip before starting to return results. Mutually exclusive with page/page_size parameters. - **auth_token** (string) - Required - Your ButterCMS read API token. ### Request Example ``` GET /pages/search/?query=example&page_type=blog&locale=en&auth_token=your_api_token ``` ### Response #### Success Response (200) - **data** (array) - An array of page objects matching the search query. - **meta** (object) - Pagination and meta-information about the results. #### Response Example ```json { "data": [ { "title": "Example Blog Post", "slug": "example-blog-post", "content": "This is the content of the example blog post.", "page_type": "blog" } ], "meta": { "count": 1, "next_page": null, "previous_page": null } } ``` #### Error Response (400, 401, 404) - **detail** (string) - Error message describing what went wrong. #### Error Response Example (400) ```json { "detail": "Invalid query parameter value." } ``` ``` -------------------------------- ### GET /categories/ Source: https://buttercms.com/docs/api/blog-metadata/listallcategories Retrieves a list of all blog post categories. You can optionally include recent posts for each category by using the `include=recent_posts` query parameter. ```APIDOC ## GET /categories/ ### Description Retrieve a complete list of all blog post categories in your organization, including category information and optional recent post data. This endpoint is perfect for building category navigation, content organization systems, and category-based filtering interfaces. Category Information: Returns the category name and URL-friendly slug for each category that contains published posts. This provides the essential data needed for building category-based navigation and filtering systems on your blog. Recent Posts Integration: Use the `include=recent_posts` parameter to enrich the response with each category's most recent blog posts. This is ideal for creating category landing pages that display both the category information and a preview of the latest content within that category. ### Method GET ### Endpoint /categories/ ### Parameters #### Query Parameters - **auth_token** (string) - Required - Your ButterCMS read API token. Example: "your_api_token" - **include** (string) - Optional - Include additional data in the response. When set to `recent_posts`, each category object will include a `recent_posts` array containing the latest blog posts in that category. Enum: "recent_posts" ### Request Example ```json { "example": "GET /categories/?auth_token=your_api_token&include=recent_posts" } ``` ### Response #### Success Response (200) - **data** (array) - Array of category objects. - **data.name** (string) - Display name of the category. Example: "Product Updates" - **data.slug** (string) - URL-friendly slug of the category. Example: "product-updates" - **data.recent_posts** (array) - Array of recent posts in this category (only included when `include=recent_posts` parameter is used). - **data.recent_posts.slug** (string) - Blog post slug/identifier. Example: "new-features-release" - **data.recent_posts.title** (string) - Blog post title. Example: "Exciting New Features in Our Latest Release" - **data.recent_posts.published** (string) - Publication date and time in ISO 8601 format. Example: "2024-01-20T10:00:00.000Z" #### Response Example ```json { "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" } ] } ] } ``` #### Error Response (401) - **detail** (string) - Error message describing what went wrong. Example: "Authentication credentials were not provided" ``` -------------------------------- ### Component Picker Fields JSON Structure Example Source: https://buttercms.com/docs/api/pages-components/component-system-overview Illustrates JSON array structure for component picker fields with multiple component types like FAQ, trivia, and gallery. Defined in dashboard; enables dynamic layouts. Outputs ordered array of components; each component identified by type key with associated data. ```json { "sections": [ { "faq_item": { "question": "Are dogs allowed in the facility?", "answer": "Leashed dogs are welcome in all common areas and outdoor spaces.", "category": "Pets", "featured_image": "https://example.com/dog-friendly.jpg" } }, { "trivia_block": { "title": "Did You Know?", "facts": [ "Our facility was built in 1892", "We've hosted over 10,000 events" ], "background_color": "blue" } }, { "image_gallery": { "title": "Recent Photos", "images": [ { "url": "https://example.com/photo1.jpg", "caption": "Summer event 2024" }, { "url": "https://example.com/photo2.jpg", "caption": "Holiday celebration" } ] } } ] } ``` -------------------------------- ### GET /content/{collection_key}/ Source: https://buttercms.com/docs/api/collections-read/retrievecollection Retrieve items from a specific Collection with filtering, pagination, and relationship serialization. Supports multiple query parameters for precise content retrieval. ```APIDOC ## GET /content/{collection_key}/ ### Description Retrieve items from a specific Collection with comprehensive filtering, pagination, and relationship serialization capabilities. ### Method GET ### Endpoint /content/{collection_key}/ ### Parameters #### Path Parameters - **collection_key** (string) - Required - The unique identifier/slug of the Collection to retrieve. #### Query Parameters - **auth_token** (string) - Required - Your ButterCMS read API token - **keys** (string) - Optional - Comma-delimited list of Collection keys for multi-collection retrieval - **preview** (integer) - Optional - Set to 1 to return the latest draft version of a page - **order** (string) - Optional - Order by page level published, updated, or a content field - **page** (integer) - Optional - Page number for page-based pagination - **page_size** (integer) - Optional - Number of items per page for page-based pagination - **limit** (integer) - Optional - Maximum number of items to return for offset-based pagination - **offset** (integer) - Optional - Number of items to skip before starting to return results - **locale** (string) - Optional - Set to the api slug of your configured locale - **levels** (integer) - Optional - Depth of relationship serialization (1-5) - **alt_media_text** (integer) - Optional - Media field response format (0 or 1) - **fields** (object) - Optional - Dynamic field filtering using dot notation ### Request Example { "auth_token": "your_api_token", "page": 1, "page_size": 10, "locale": "en" } ### Response #### Success Response (200) - **meta** (object) - Pagination information and result counts - **data** (array) - Collection items - **item.meta** (object) - Unique IDs for update and delete operations #### Response Example { "meta": { "count": 25, "next_page": 2, "previous_page": null }, "data": [ { "id": 1, "fields": { "title": "Example Item", "content": "Sample content" }, "meta": { "id": "abc123" } } ] } #### Error Responses - **400 Bad Request** - {"detail": "Error message describing what went wrong"} - **401 Unauthorized** - {"detail": "Authentication credentials were not provided"} - **404 Not Found** - {"detail": "Collection not found"} ``` -------------------------------- ### Pages - Write API Source: https://buttercms.com/docs/api/index Endpoints for creating and updating pages programmatically. Note that PUT acts as a PATCH for partial updates. ```APIDOC ## POST /pages/ ### Description Creates a new page. ### Method POST ### Endpoint /pages/ ### Parameters #### Request Body - **data** (object) - Required - The content of the page to be created. ### Request Example ```json { "page_type": "about_us", "title": "About Our Company", "content": { "body": "

This is the body of the about us page.

" } } ``` ### Response #### Success Response (201 Created) - **id** (integer) - The unique identifier of the created page. - **title** (string) - The title of the page. - **slug** (string) - The slug of the page. - **content** (object) - The content fields of the page. #### Response Example ```json { "id": 123, "title": "About Our Company", "slug": "about-our-company", "content": { "body": "

This is the body of the about us page.

" } } ``` ## PATCH /pages/{page_type}/{page_slug}/ ### Description Performs a partial update on an existing page. ### Method PATCH ### Endpoint /pages/{page_type}/{page_slug}/ ### Parameters #### Path Parameters - **page_type** (string) - Required - The type of the page. - **page_slug** (string) - Required - The slug of the page to update. #### Request Body - **data** (object) - Required - The fields to update for the page. ### Request Example ```json { "content": { "body": "

Updated body content.

" } } ``` ### Response #### Success Response (200 OK) - **id** (integer) - The unique identifier of the updated page. - **title** (string) - The title of the page. - **slug** (string) - The slug of the page. - **content** (object) - The updated content fields of the page. #### Response Example ```json { "id": 123, "title": "About Our Company", "slug": "about-our-company", "content": { "body": "

Updated body content.

" } } ``` ## PUT /pages/{page_type}/{page_slug}/ ### Description Performs a partial update on an existing page. Note: For Pages, PUT behaves like PATCH. ### Method PUT ### Endpoint /pages/{page_type}/{page_slug}/ ### Parameters #### Path Parameters - **page_type** (string) - Required - The type of the page. - **page_slug** (string) - Required - The slug of the page to update. #### Request Body - **data** (object) - Required - The fields to update for the page. ### Request Example ```json { "content": { "body": "

Updated body content via PUT.

" } } ``` ### Response #### Success Response (200 OK) - **id** (integer) - The unique identifier of the updated page. - **title** (string) - The title of the page. - **slug** (string) - The slug of the page. - **content** (object) - The updated content fields of the page. #### Response Example ```json { "id": 123, "title": "About Our Company", "slug": "about-our-company", "content": { "body": "

Updated body content via PUT.

" } } ``` ``` -------------------------------- ### GET /posts/ Source: https://buttercms.com/docs/api/blog-posts-read/listallposts Retrieves a paginated list of all published blog posts, sorted by publication date with the newest posts first. Supports various query parameters for filtering and pagination. ```APIDOC ## GET /posts/ ### Description Retrieve a paginated list of all published blog posts, automatically sorted by publication date with the newest posts appearing first. This endpoint is ideal for building blog listing pages, RSS feeds, or content archives. Use `exclude_body=true` for performance optimization on listing pages. ### Method GET ### Endpoint /posts/ ### Parameters #### Query Parameters - **page** (integer) - Optional - Page number for page-based pagination. Mutually exclusive with limit/offset parameters. Example: 2 - **page_size** (integer) - Optional - Number of items per page for page-based pagination. Mutually exclusive with limit/offset parameters. Example: 5 - **limit** (integer) - Optional - Maximum number of items to return for offset-based pagination. Mutually exclusive with page/page_size parameters. Example: 5 - **offset** (integer) - Optional - Number of items to skip before starting to return results. Mutually exclusive with page/page_size parameters. Example: 10 - **preview** (integer) - Optional - 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. Enum: 0, 1 - **exclude_body** (boolean) - Optional - When true, excludes the full post body from the response. Example: true - **author_slug** (string) - Optional - Filter posts by an author's slug. Example: "api-test" - **category_slug** (string) - Optional - Filter posts by a category's slug. Example: "test-category" - **tag_slug** (string) - Optional - Filter posts by a tag's slug. Example: "test-tag" - **auth_token** (string) - Required - Your ButterCMS read API token. Example: "your_api_token" ### Response #### Success Response (200) - **status** (string) - API response status. - **data** (object) - Contains the list of posts. - **posts** (array) - Array of blog post objects. - **title** (string) - The title of the post. - **slug** (string) - The unique slug for the post. - **summary** (string) - A brief summary of the post content. - **published** (string) - The publication date and time of the post. - **author** (object) - Author details. - **first_name** (string) - Author's first name. - **last_name** (string) - Author's last name. - **slug** (string) - Author's slug. - **tags** (array) - Array of tag objects associated with the post. - **title** (string) - Tag title. - **slug** (string) - Tag slug. - **category** (object) - Category details. - **title** (string) - Category title. - **slug** (string) - Category slug. - **custom_fields** (object) - Any custom fields associated with the post. #### Error Response (400) - **detail** (string) - Error message describing what went wrong. Example: "Authentication credentials were not provided" #### Error Response (401) - **detail** (string) - Error message describing what went wrong. Example: "Authentication credentials were not provided" ### Request Example ``` GET /posts/?page=2&page_size=5&auth_token=your_api_token ``` ### Response Example (Success) ```json { "status": "ok", "data": { "posts": [ { "title": "My First Blog Post", "slug": "my-first-blog-post", "summary": "This is a summary of my first blog post.", "published": "2023-10-27T10:00:00Z", "author": { "first_name": "John", "last_name": "Doe", "slug": "john-doe" }, "tags": [ { "title": "Technology", "slug": "technology" } ], "category": { "title": "News", "slug": "news" }, "custom_fields": {} } ] } } ``` ```