### GET /categories/

Source: https://buttercms.com/docs/api/_bundle/index.yaml

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.


```markdown
### Parameters

- **auth_token** (string, query, required): Your ButterCMS read API token

- **include** (string (recent_posts), query, 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.


### Responses

#### 200 - Categories retrieved successfully

**ListCategoriesResponse**
- **data** (array (object)): Array of category objects
  Array items:
    - **name** (string): Display name of the category (example: "Product Updates")
    - **slug** (string): URL-friendly slug of the category (example: "product-updates")
    - **recent_posts** (array (object)): Array of recent posts in this category (only included when include=recent_posts parameter is used)
      Array items:
        - **slug** (string): Blog post slug/identifier (example: "new-features-release")
        - **title** (string): Blog post title (example: "Exciting New Features in Our Latest Release")
        - **published** (string (date-time)): Publication date and time in ISO 8601 format (example: "2024-01-20T10:00:00.000Z")

#### 401 - response

**ErrorResponse**
- **detail** (string): Error message describing what went wrong (example: "Authentication credentials were not provided")

### Example Usage

```bash
curl -X GET "https://api.buttercms.com/v2/categories/?auth_token=string&include=recent_posts"
```

```

--------------------------------

### GET /pages/{page_type}/{page_slug}/

Source: https://buttercms.com/docs/api/_bundle/index.yaml

Retrieve a specific page by its page type and slug. This endpoint is ideal for fetching individual pages for display on your website or application.

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


```markdown
### Parameters

- **page_type** (string, path, required): The type of page to retrieve.

- Use `*` to search across all page types
- Use a specific page type slug to limit search to that type

- **page_slug** (string, path, required): The slug of the page to retrieve.

- **preview** (integer, query, 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.

Set to `1` to access unpublished/draft collection items. Useful for staging environments.

- **locale** (string, query, optional): 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.
 (example: "en")
- **levels** (integer, query, optional): Depth of relationship serialization.

Controls how many levels of referenced content to include:
- **1**: Direct fields only, references as URIs
- **2**: Direct fields + one level of references (default)
- **3-5**: Deeper relationship traversal

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

Valid range: 1-5 (inclusive). Values outside this range will be automatically capped.

- **alt_media_text** (integer, query, optional): Media field response format.

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

- **0** (default): Media fields return simple URL strings
- **1**: Media fields return objects with at least `url` and, when available,
  `alt`. If the stored media value is just a URL string, the object will
  include `url` only.

- **auth_token** (string, query, required): Your ButterCMS read API token


### Responses

#### 200 - **Success**

A hash with a `data` property that contains the page matching the page slug.


**SinglePageResponse**
- **data** (object): A single page object that can be either a Single Page or Page Type page
  - **slug** (string): Unique identifier (example: "example-news-page")
  - **name** (string): Name of the Page (example: "Example News Page")
  - **page_type** (string,null): API slug identifier of the page_type for the Page. null for Single Pages (example: "news")
  - **published** (string,null): Timestamp of when the page was first published (example: "2019-11-12T17:23:53.109696Z")
  - **updated** (string (date-time)): Timestamp of when the page was most recently published (example: "2020-10-22T20:07:52.965850Z")
  - **scheduled** (string,null): Timestamp of when the page is scheduled to be published. If not scheduled, this field will be null (example: null)
  - **status** (string (published|draft|scheduled)): Status of the current version of the page (example: "published") ("published"|"draft"|"scheduled")
  - **fields** (object): Contains all of the actual content for the Page - fields are customizable (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"}]})

#### 400 - **Bad Request - Invalid Parameter**

Invalid parameter value provided. This can happen when:
- The `levels` parameter is not a valid integer between 1 and 5
- Invalid locale parameter provided


**ErrorResponse**
- **detail** (string): Error message describing what went wrong (example: "Authentication credentials were not provided")

#### 401 - **Unauthorized - Invalid or Missing API Token**

Authentication credentials were not provided. Make sure to include your read API token as the `auth_token` query parameter.


**ErrorResponse**
- **detail** (string): Error message describing what went wrong (example: "Authentication credentials were not provided")

#### 403 - **Forbidden - Multiple Pages Found**

Multiple pages were found with the same slug when using wildcard page type. This typically indicates a data integrity issue where the same slug exists across different page types.


**ErrorResponse**
- **detail** (string): Error message describing what went wrong (example: "Authentication credentials were not provided")

#### 404 - **Not Found - Page Does Not Exist**

The requested page doesn't exist, or you don't have access to it. This could be because:
- The page slug doesn't exist
- The page type doesn't exist
- The page exists but not in the specified page type


**ErrorResponse**
- **detail** (string): Error message describing what went wrong (example: "Authentication credentials were not provided")

### Example Usage

```bash
curl -X GET "https://api.buttercms.com/v2/pages/{page_type}/{page_slug}/?preview=0&locale=en&levels=2&alt_media_text=0&auth_token=string"
```

```

--------------------------------

### GET /feeds/sitemap/

Source: https://buttercms.com/docs/api/_bundle/index.yaml

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.


```markdown
### Parameters

- **auth_token** (string, query, required): Your ButterCMS read API token

- **category_slug** (string, query, 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.

- **tag_slug** (string, query, 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.


### Responses

#### 200 - XML sitemap generated successfully


#### 401 - response


#### 404 - Not Found - Invalid feed type or no posts found


### Example Usage

```bash
curl -X GET "https://api.buttercms.com/v2/feeds/sitemap/?auth_token=string&category_slug=string&tag_slug=string"
```

```

--------------------------------

### GET /posts/{slug}/

Source: https://buttercms.com/docs/api/_bundle/index.yaml

Retrieve a specific blog post by its unique slug, including complete post content, metadata, and navigation information. This endpoint is ideal for building individual blog post pages with full content display.

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

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

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


```markdown
### Parameters

- **slug** (string, path, required): The unique slug of the blog post to retrieve.

**Important**: The URL must end with a trailing slash (`/v2/posts/your-slug/`).

- **auth_token** (string, query, required): Your ButterCMS read API token


### Responses

#### 200 - **Success - Blog Post Retrieved**

Returns the complete blog post object along with navigation metadata for browsing between posts.


**RetrieveSinglePostResponse**
- **meta** (object): Navigation metadata for single blog post responses
  - **next_post** (object): Navigation object containing essential information for blog post links
    - **slug** (string): URL-friendly slug of the post for navigation (example: "google-analytics-is-now-integrated-with-your-butter-blog")
    - **title** (string): Title of the post for display in navigation (example: "Google Analytics is now integrated with your Butter blog")
    - **featured_image** (string,null): URL to the featured image for navigation thumbnails, null if no featured image (example: "https://d2devwt40at1e2.cloudfront.net/api/file/etSDYJUIFDADGEEAQ/")
  - **previous_post** (object): Navigation object containing essential information for blog post links
- **data** (object): Complete blog post object with all fields and related data
  - **url** (string (uri)): Full URL to the blog post (example: "http://www.example.com/blog/this-is-a-blog-post")
  - **created** (string (date-time)): Timestamp when the blog post was created (example: "2020-10-08T18:29:19.987936Z")
  - **updated** (string (date-time)): Timestamp when the blog post was last updated (example: "2020-10-09T15:49:54.580309Z")
  - **published** (string,null): Timestamp when the blog post was published (example: "2020-10-08T18:08:00Z")
  - **author** (object): Author information for blog posts
    - **first_name** (string): Author's first name (example: "API")
    - **last_name** (string): Author's last name (example: "Test")
    - **email** (string (email)): Author's email address (example: "apitest@buttercms.com")
    - **slug** (string): Author's URL-friendly slug (example: "api-test")
    - **bio** (string): Author's biography (example: "This is my bio.")
    - **title** (string): Author's professional title (example: "API")
    - **linkedin_url** (string,null): Author's LinkedIn profile URL (example: "https://www.linkedin.com/in/API")
    - **facebook_url** (string,null): Author's Facebook profile URL (example: "https://www.facebook.com/API")
    - **twitter_handle** (string): Author's Twitter handle (example: "buttercmsapi")
    - **instagram_url** (string,null): Author's Instagram profile URL (example: "https://www.instagram.com/API")
    - **pinterest_url** (string,null): Author's Pinterest profile URL (example: "https://www.pinterest.com/API")
    - **profile_image** (string,null): URL to author's profile image (example: "https://buttercms.com/api.png")
  - **categories** (array (object)): Array of categories assigned to the blog post
    Array items:
      - **name** (string): Display name of the category (example: "test category")
      - **slug** (string): URL-friendly slug of the category (example: "test-category")
  - **tags** (array (object)): Array of tags assigned to the blog post
    Array items:
      - **name** (string): Display name of the tag (example: "test tag")
      - **slug** (string): URL-friendly slug of the tag (example: "test-tag")
  - **featured_image** (string,null): URL to the featured image, null if no featured image (example: null)
  - **featured_image_alt** (string): Alt text for the featured image (example: "")
  - **slug** (string): URL-friendly slug for the blog post (example: "this-is-a-blog-post")
  - **title** (string): Title of the blog post (example: "This is a blog post")
  - **body** (string): 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** (string): Plain text summary of the blog post (example: "This is a blog post to test the API.")
  - **seo_title** (string): SEO-optimized title for the blog post (example: "This is a blog post")
  - **meta_description** (string): Meta description for SEO and social sharing (example: "This is a blog post to test the API.")
  - **status** (string (draft|published|scheduled)): Publication status of the blog post (example: "published") ("draft"|"published"|"scheduled")
  - **scheduled** (string,null): Timestamp when the blog post is scheduled to be published. If not scheduled, this field will be null (example: null)

#### 401 - response

**ErrorResponse**
- **detail** (string): Error message describing what went wrong (example: "Authentication credentials were not provided")

#### 404 - **Not Found - Blog Post Does Not Exist**

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

- The blog post doesn't exist
- The blog post belongs to a different organization
- You don't have access to the blog post


**ErrorResponse**
- **detail** (string): Error message describing what went wrong (example: "Authentication credentials were not provided")

### Example Usage

```bash
curl -X GET "https://api.buttercms.com/v2/posts/{slug}/?auth_token=string"
```

```

--------------------------------

### GET /tags/

Source: https://buttercms.com/docs/api/_bundle/index.yaml

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.


```markdown
### Parameters

- **auth_token** (string, query, required): Your ButterCMS read API token

- **include** (string (recent_posts), query, 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.


### Responses

#### 200 - Tags retrieved successfully

**ListTagsResponse**
- **data** (array (object)): Array of tag objects
  Array items:
    - **name** (string): Display name of the tag (example: "API Development")
    - **slug** (string): URL-friendly slug of the tag (example: "api-development")
    - **recent_posts** (array (object)): Array of recent posts with this tag (only included when include=recent_posts parameter is used)
      Array items:
        - **slug** (string): Blog post slug/identifier (example: "rest-api-best-practices")
        - **title** (string): Blog post title (example: "REST API Best Practices for Modern Development")
        - **published** (string (date-time)): Publication date and time in ISO 8601 format (example: "2024-01-22T09:00:00.000Z")

#### 401 - response

**ErrorResponse**
- **detail** (string): Error message describing what went wrong (example: "Authentication credentials were not provided")

### Example Usage

```bash
curl -X GET "https://api.buttercms.com/v2/tags/?auth_token=string&include=recent_posts"
```

```

--------------------------------

### GET /authors/

Source: https://buttercms.com/docs/api/_bundle/index.yaml

Retrieve a complete list of all blog post authors in your organization, including their profile information and optional recent post data. This endpoint is ideal for building author pages, contributor listings, and author-based navigation.

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

**Recent Posts Integration**: Use the `include=recent_posts` parameter to enrich the response with each author's most recent blog posts. This is particularly useful for creating author archive pages that showcase both the author's profile and their latest content contributions.


```markdown
### Parameters

- **auth_token** (string, query, required): Your ButterCMS read API token

- **include** (string (recent_posts), query, optional): Include additional data in the response.

When set to `recent_posts`, each author object will include a `recent_posts` array containing their latest blog posts.


### Responses

#### 200 - Authors retrieved successfully

**ListAuthorsResponse**
- **data** (array (object)): Array of author objects
  Array items:
    - **slug** (string): Unique identifier/slug for the author (example: "api-test")
    - **first_name** (string): Author's first name (example: "API")
    - **last_name** (string): Author's last name (example: "Test")
    - **email** (string (email)): Author's email address (example: "apitest@buttercms.com")
    - **bio** (string): Author's biography/description (example: "This is my bio.")
    - **title** (string): Author's professional title (example: "API")
    - **linkedin_url** (string,null): Author's LinkedIn profile URL (example: "https://www.linkedin.com/in/API")
    - **facebook_url** (string,null): Author's Facebook profile URL (example: "https://www.facebook.com/API")
    - **pinterest_url** (string,null): Author's Pinterest profile URL (example: "https://www.pinterest.com/API")
    - **instagram_url** (string,null): Author's Instagram profile URL (example: "https://www.instagram.com/API")
    - **twitter_handle** (string): Author's Twitter handle (without @ symbol) (example: "buttercmsapi")
    - **profile_image** (string,null): CDN URL of author's profile image (example: "https://buttercms.com/api.png")
    - **recent_posts** (array (object)): Array of recent posts by this author (only included when include=recent_posts parameter is used)
      Array items:
        - **slug** (string): Blog post slug/identifier (example: "web-development-trends-2024")
        - **title** (string): Blog post title (example: "Web Development Trends in 2024")
        - **published** (string (date-time)): Publication date and time in ISO 8601 format (example: "2024-01-15T10:00:00.000Z")

#### 401 - response

**ErrorResponse**
- **detail** (string): Error message describing what went wrong (example: "Authentication credentials were not provided")

### Example Usage

```bash
curl -X GET "https://api.buttercms.com/v2/authors/?auth_token=string&include=recent_posts"
```

```

--------------------------------

### GET /categories/{slug}/

Source: https://buttercms.com/docs/api/_bundle/index.yaml

Retrieve a specific blog post category by its unique slug identifier, providing category information and optional recent posts integration. Categories help organize blog content into logical topical groups for improved navigation and content discovery.

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

**Recent Posts Integration**: Use the `include=recent_posts` parameter to enrich the response with the category's recent blog posts. This adds a `recent_posts` array containing up to 10 of the most recently published posts in this category, ideal for creating category landing pages that showcase both the category information and latest content.


```markdown
### Parameters

- **slug** (string, path, required): The unique slug identifier of the category to retrieve.

- **auth_token** (string, query, required): Your ButterCMS read API token

- **include** (string (recent_posts), query, optional): Include additional data in the response.

When set to `recent_posts`, the category object will include a `recent_posts` array containing the latest blog posts in this category (up to 10 posts, ordered by most recent first).


### Responses

#### 200 - Category retrieved successfully

**RetrieveCategoryResponse**
- **data** (object): Category information with optional recent posts
  - **name** (string): Display name of the category (example: "Product Updates")
  - **slug** (string): URL-friendly slug of the category (example: "product-updates")
  - **recent_posts** (array (object)): Array of recent posts in this category (only included when include=recent_posts parameter is used)
    Array items:
      - **slug** (string): Blog post slug/identifier (example: "new-features-release")
      - **title** (string): Blog post title (example: "Exciting New Features in Our Latest Release")
      - **published** (string (date-time)): Publication date and time in ISO 8601 format (example: "2024-01-20T10:00:00.000Z")

#### 401 - response

**ErrorResponse**
- **detail** (string): Error message describing what went wrong (example: "Authentication credentials were not provided")

#### 404 - Not Found - Category with specified slug does not exist

**ErrorResponse**
- **detail** (string): Error message describing what went wrong (example: "Authentication credentials were not provided")

### Example Usage

```bash
curl -X GET "https://api.buttercms.com/v2/categories/{slug}/?auth_token=string&include=recent_posts"
```

```

--------------------------------

### GET /pages/{page_type}/

Source: https://buttercms.com/docs/api/_bundle/index.yaml

Retrieve a paginated list of pages for a given page type, or all Single Pages when using the wildcard `*` as the page type. This endpoint supports comprehensive filtering and sorting for Page Type collections.

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

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

> **Important**: Advanced filtering and ordering capabilities are only available for Page Type endpoints, not when retrieving Single Pages with the `*` wildcard. Use dotted notation for field filters (e.g., `fields.title=Home`).
See also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.


```markdown
### Parameters

- **page_type** (string, path, required): The slug of the type of pages you want to retrieve, or `*` for Single Pages.

- Use `*` to get Single Pages (those without a Page Type)
- Use the actual page type slug to get pages of that specific type

- **preview** (integer, query, 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.

Set to `1` to access unpublished/draft collection items. Useful for staging environments.

- **page** (integer, query, optional): Page number for page-based pagination.

**Mutually exclusive with limit/offset parameters.**

- **page_size** (integer, query, optional): Number of items per page for page-based pagination.

**Mutually exclusive with limit/offset parameters.**

- **limit** (integer, query, optional): Maximum number of items to return for offset-based pagination.

**Mutually exclusive with page/page_size parameters.**

- **offset** (integer, query, optional): Number of items to skip before starting to return results.

**Mutually exclusive with page/page_size parameters.**

- **locale** (string, query, optional): 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.
 (example: "en")
- **levels** (integer, query, optional): Depth of relationship serialization.

Controls how many levels of referenced content to include:
- **1**: Direct fields only, references as URIs
- **2**: Direct fields + one level of references (default)
- **3-5**: Deeper relationship traversal

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

Valid range: 1-5 (inclusive). Values outside this range will be automatically capped.

- **alt_media_text** (integer, query, optional): Media field response format.

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

- **0** (default): Media fields return simple URL strings
- **1**: Media fields return objects with at least `url` and, when available,
  `alt`. If the stored media value is just a URL string, the object will
  include `url` only.

- **auth_token** (string, query, required): Your ButterCMS read API token

- **order** (string, query, optional): Can order by page level `published`, `updated`, or a content field of the Page Type. Defaults to ascending, prepend '-' to sort descending.

**Note**: Only available for Page Type endpoints, not for Single Pages (`page_type=*`).

- **fields.seo.title** (string, query, optional): Filter the result set by a nested field value. This is an example of field filtering — you can filter by any field using the pattern `fields.<field_name>=<value>`.

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

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

**Note**: Field filtering is only available for Page Type endpoints, not for Single Pages (`page_type=*`).

- **fields.headline** (string, query, optional): Filter the result set by a top-level field value. This is an example of field filtering — you can filter by any field using the pattern `fields.<field_name>=<value>`.

**Note**: Field filtering is only available for Page Type endpoints, not for Single Pages (`page_type=*`).


### Responses

#### 200 - **Success**

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

- For Single Pages (`page_type=*`): Returns pages without a page type
- For Page Types: Returns pages of the specified type


- **meta** (object)
  - **previous_page** (integer,null): Previous page number if it exists
  - **next_page** (integer,null): Next page number if it exists
  - **count** (integer): Total number of items
- **data** (array (object))
  Array items:
    - **slug** (string): Unique identifier (example: "single-page-1")
    - **page_type** (string,null): Page type - null for single pages (example: null)
    - **published** (string (date-time)): Timestamp of when the page was first published (example: "2019-11-12T17:23:53.109696Z")
    - **updated** (string (date-time)): Timestamp of when the page was most recently published (example: "2020-10-22T20:07:52.965850Z")
    - **fields** (object): Contains all of the actual content for the Page - fields are customizable (example: {"title":"This is a single page","body":"<p>Single PAGE!</p>"})

#### 401 - response

**ErrorResponse**
- **detail** (string): Error message describing what went wrong (example: "Authentication credentials were not provided")

#### 404 - **Not Found - Page Type Does Not Exist or Invalid Pagination**

- The requested page type doesn't exist or you don't have access to it.
- Invalid pagination parameters (page number out of range).


**ErrorResponse**
- **detail** (string): Error message describing what went wrong (example: "Authentication credentials were not provided")

### Example Usage

```bash
curl -X GET "https://api.buttercms.com/v2/pages/{page_type}/?preview=0&page=1&page_size=10&limit=10&offset=0&locale=en&levels=2&alt_media_text=0&auth_token=string&order=string&fields.seo.title=string&fields.headline=string"
```

```

--------------------------------

### API Overview: ButterCMS API

Source: https://buttercms.com/docs/api/_bundle/index.yaml

This OpenAPI specification covers the complete ButterCMS API, including read and write operations for Pages, Blog Posts, Collections, and more.

### New Documentation Version
This is a new version of our API documentation built with OpenAPI standards. If you encounter any issues, inaccuracies, or have suggestions for improvement, please report them to [support@buttercms.com](mailto:support@buttercms.com).
> The previous version of our documentation is still available at: **[https://buttercms.com/docs/previous-api/](https://buttercms.com/docs/previous-api/)**

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

Our API provides comprehensive content management capabilities through both read and write operations. Content is served through a global CDN with 150+ edge locations, ensuring fast delivery worldwide.
---
The API supports creating, updating, and deleting items of three main content types:

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

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

**Blog Posts**: Built-in content type from our blog engine, which comes out-of-the-box with categorization, tagging, predefined SEO, and authors. Designed for chronological content with standardized blog functionality.
---
Authentication is handled through token-based access; read operations can use a query parameter (`auth_token`) while write operations require header-based authentication for enhanced security.


```yaml
# ButterCMS API
# Version: 2.0.0

This OpenAPI specification covers the complete ButterCMS API, including read and write operations for Pages, Blog Posts, Collections, and more.

### New Documentation Version
This is a new version of our API documentation built with OpenAPI standards. If you encounter any issues, inaccuracies, or have suggestions for improvement, please report them to [support@buttercms.com](mailto:support@buttercms.com).
> The previous version of our documentation is still available at: **[https://buttercms.com/docs/previous-api/](https://buttercms.com/docs/previous-api/)**

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

Our API provides comprehensive content management capabilities through both read and write operations. Content is served through a global CDN with 150+ edge locations, ensuring fast delivery worldwide.
---
The API supports creating, updating, and deleting items of three main content types:

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

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

**Blog Posts**: Built-in content type from our blog engine, which comes out-of-the-box with categorization, tagging, predefined SEO, and authors. Designed for chronological content with standardized blog functionality.
---
Authentication is handled through token-based access; read operations can use a query parameter (`auth_token`) while write operations require header-based authentication for enhanced security.


# Base URL: https://api.buttercms.com/v2
```

--------------------------------

### Security: writeTokenAuth

Source: https://buttercms.com/docs/api/_bundle/index.yaml

Write-enabled API token required for creating content.

The API token you use for reading from the ButterCMS API will not allow you to create content in the API. For this you will need to use a different write-enabled token. Chat or email support@buttercms.com to get yours.

Set the `Authorization` header to `Token your_write_api_token`.

Example: `Authorization: Token abc123def456`

Your write-enabled token should never be used anywhere it would be exposed, e.g. in client-side JavaScript.


```markdown
## Security: writeTokenAuth

**Description:** Write-enabled API token required for creating content.

The API token you use for reading from the ButterCMS API will not allow you to create content in the API. For this you will need to use a different write-enabled token. Chat or email support@buttercms.com to get yours.

Set the `Authorization` header to `Token your_write_api_token`.

Example: `Authorization: Token abc123def456`

Your write-enabled token should never be used anywhere it would be exposed, e.g. in client-side JavaScript.


**Type:** http

**Scheme:** Token


```

--------------------------------

### POST /posts/

Source: https://buttercms.com/docs/api/_bundle/index.yaml

Create a new blog post using the Write API with support for rich media, categorization, and automatic author assignment. This endpoint enables programmatic content creation for blogs, news sites, and content management workflows.

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

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

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

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

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

**Asynchronous Processing**: This endpoint returns `202 Accepted` immediately to ensure fast response times for your application. The actual post creation, including media processing, category creation, and webhook notifications, happens in the background processing queue.


```markdown
### Request Body

**Content-Type:** application/json

- **title** (string) (required): The title of the blog post (example: "This is a blog post")
- **slug** (string): The slug of the blog post (must be unique).

**Auto-Generation**: If not provided, the slug will be automatically generated from the title using unicode slugification. You can provide a custom slug or let the API generate one for you.
 (example: "this-is-a-blog-post")
- **status** (string (draft|published)): The status of the post. Defaults to 'draft'. Cannot be 'scheduled'. (example: "published") ("draft"|"published")
- **author** (object)
  - **email** (string (email)) (required): Email address of the existing author (example: "your@author.com")
- **categories** (array (string)): Array of category names. Categories will be created if they don't exist. (example: ["Recipes","Meals"])
- **tags** (array (string)): Array of tag names. Tags will be created if they don't exist. (example: ["Butter","Sushi","Really Good Recipes"])
- **featured_image** (string (uri)): Can be a remote URL to an image.

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

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

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

**Note**: Featured images are always uploaded regardless of this setting.
 (example: false)

### Responses

#### 202 - **Accepted - Post Creation Initiated**

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

Posts are validated prior to returning the API response but it is also possible that post creation may fail after returning a 202 response. If this happens please contact support.


**BlogPostCreateSuccessResponse**
- **status** (string (pending)): Indicates that the blog post creation is being processed asynchronously (example: "pending") ("pending")

#### 400 - **Bad Request - Validation Error**

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

- You are missing a required field (title or slug)
- The slug is already in use
- The remote URL for a media field returns a 404
- You attempt to schedule a blog post (not supported)
- Invalid author email or slug provided

Error explanations will be returned in a single JSON array.


**ValidationErrorResponse**

#### 401 - response

**ErrorResponse**
- **detail** (string): Error message describing what went wrong (example: "Authentication credentials were not provided")

#### 403 - **Forbidden - Blog Post Limit Exceeded or Insufficient Permissions**

This can happen when:
- Your organization has reached the blog post limit for your plan
- Your API token does not have write permissions


- **detail** (string): Error message describing what went wrong (example: "Authentication credentials were not provided")

#### 404 - **Not Found - Organization Blog Missing or Invalid Pagination**

- Could not find this organization's blog. This is a rare error that typically indicates a configuration issue.
- Invalid pagination parameters (page number out of range).


**ErrorResponse**
- **detail** (string): Error message describing what went wrong (example: "Authentication credentials were not provided")

### Example Usage

```bash
curl -X POST "https://api.buttercms.com/v2/posts/" \
  -H "Content-Type: application/json" \
  -d '{
  "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
}'
```

```

--------------------------------

### Security: auth_token

Source: https://buttercms.com/docs/api/_bundle/index.yaml

Read API authentication is performed by passing your API token via the `auth_token` parameter on every request: `?auth_token=your_api_token`. You can access your API token from your settings page.

Requests made with a missing or invalid token will get a 401 Unauthorized response. All requests must be made over HTTPS.


```markdown
## Security: auth_token

**Description:** Read API authentication is performed by passing your API token via the `auth_token` parameter on every request: `?auth_token=your_api_token`. You can access your API token from your settings page.

Requests made with a missing or invalid token will get a 401 Unauthorized response. All requests must be made over HTTPS.


**Type:** apiKey


```