Skip to main content

​
Overview

ButterCMS Blog Posts use a standardized, predefined schema that provides out-of-the-box functionality for chronological content with built-in organizational and authoring features. Unlike Pages and Collections, the Blog Post schema 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.

​
Predefined field structure

The body field supports comprehensive HTML including embedded media, formatted text, links, and other rich content. Blog Posts include built-in Open Graph and Twitter Card metadata for proper social media presentation when content is shared.

​
Categorization and tagging

​
Categories

  • Hierarchical organization: Categories support parent-child relationships for content taxonomy
  • URL integration: Categories automatically generate SEO-friendly URLs
  • Filtering: API endpoints support category-based filtering
  • RSS integration: Category-specific RSS feeds are automatically generated

​
Tags

  • Flexible labeling: Non-hierarchical content labeling for cross-cutting themes
  • API filtering: tag_slug parameter for precise content queries
  • Tag clouds: Automatic tag frequency calculation
Use categories for broad, permanent organizational structure and tags for specific topics or temporal content connections.

​
Author management

  • Author profiles: Dedicated author entities with names, biographies, profile images, and social links
  • Multi-author support: Posts can be attributed to multiple authors
  • Author archives: Automatic author-specific content archives and RSS feeds
  • API access: Author information is accessible through dedicated endpoints (/authors/, /authors/{slug}/)

​
Built-in features

​
Publication states

Blog Posts use a simplified three-state system (draft, published, scheduled) without the complex versioning available to Pages. Versioning limitation: Unlike Pages, Blog Posts do not support creating draft versions over existing published content. Once published, a post can be unpublished (returned to draft) but cannot maintain simultaneous draft and published versions. Write API behavior: Blog Posts are created and published immediately when using the Write API unless explicitly set to draft status.

​
Localization

Blog Posts support native localization via the locale query parameter on all blog API endpoints (list, retrieve, search, create, update, delete).
  • Creating translations: To create a translated version of an existing post, use the Update endpoint (PATCH) with the desired locale parameter. A new locale variant is created and linked to the original post
  • Default locale: When locale is omitted, the API returns content in your organization’s default locale
  • Independent publishing: Each locale version can be published independently
  • Backward compatible: The locale field is not included in API responses — use the query parameter to control which locale is returned
Example — list posts in Spanish:

​
WordPress import

ButterCMS provides built-in WordPress import functionality: WordPress import is a one-time migration tool requiring careful planning for large content volumes.

​
API characteristics

Performance parameters:
  • locale — filter posts by locale (defaults to organization’s default locale)
  • exclude_body=true — reduces response size by 50–70% for listing operations
  • category_slug — native category-based filtering
  • tag_slug — built-in tag filtering
  • author_slug — filter by author
Example — list posts excluding body:
Example — filter by tag:
Blog Post APIs are optimized for chronological access patterns with built-in pagination, sorting, and filtering that support common blog functionality requirements.

​
Next steps

Read API — Blog Posts

Fetch blog posts via the Read API

Write API — Blog Posts

Create and update blog posts

Blog metadata

Authors, categories, and tags endpoints

Pages — key concepts

Use Page Types for localized blog content