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

FieldDescription
TitleSEO-optimized title with automatic URL slug generation
BodyRich HTML content supporting full editorial formatting
SummaryOptional excerpt for post previews and social sharing
Featured ImageDedicated image field with automatic CDN optimization
SEO MetadataBuilt-in meta title, meta description, and Open Graph fields
Publication DateTimestamp management with scheduling capabilities
StatusDraft, published, and scheduled state management
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

FeatureDescription
RSS 2.0 & Atom feedsAutomatic feed generation for content syndication
XML sitemapsSearch engine sitemap integration
Previous/Next navigationAutomatic post navigation for chronological browsing
WordPress importBuilt-in migration tool from WordPress

​
Publication states

Blog Posts use a simplified three-state system (draft, published, scheduled) without the complex versioning available to Pages.
StateDescription
DraftAccessible only via preview mode
PublishedLive and accessible through all blog endpoints with CDN caching
ScheduledAutomatically published at a specified time via dashboard scheduling
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 limitations

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.
Alternative approach for international content: Use Page Types instead of Blog Posts. Page Types can be configured to replicate blog functionality while providing full localization support:
  • Create Page Types with blog-like fields (title, body, date, author references)
  • Page Types inherit full localization capabilities
  • Page Types support components for rich layouts beyond traditional blog formats
  • Reference Collections for author information, categories, and tags
Organizations planning international blog expansion should evaluate Page Types early to avoid complex migrations later.

​
WordPress import

ButterCMS provides built-in WordPress import functionality:
DataMigration behavior
Post titles, bodies, datesTransferred accurately
CategoriesMapped with hierarchy preservation
TagsConverted maintaining content relationships
AuthorsCreated as ButterCMS author entities
MediaTransferred to ButterCMS media library with CDN integration
WordPress import is a one-time migration tool requiring careful planning for large content volumes.

​
API characteristics

Performance parameters:
  • 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: 
GET /v2/posts/?auth_token=TOKEN&exclude_body=true&category_slug=technology
Example — filter by tag: 
GET /v2/posts/?auth_token=TOKEN&tag_slug=getting-started
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