{ "openapi": "3.1.0", "info": { "title": "ButterCMS Read API", "version": "2.0.0", "description": "Read endpoints for the ButterCMS API — Pages, Collections, Blog Posts, Blog Metadata, and Feeds.\n", "contact": { "email": "support@buttercms.com" }, "license": { "name": "ButterCMS Terms of Service", "url": "https://buttercms.com/terms/" } }, "servers": [ { "url": "https://api.buttercms.com/v2", "description": "ButterCMS API v2" } ], "tags": [ { "name": "Pages", "description": "Retrieve pages from your ButterCMS account.\n\n**Single Pages**: Use `*` as the page_type to get Single Pages (those without a Page Type) which represent unique pages on your site like your Homepage. Useful for creating your sitemap.xml.\n\n**Page Type Pages**: Use the actual page type slug to get pages of that specific type. Page Types allow you to create many pages with the same structure.\n\n**Note:** The fields of a page are defined by you, they are customizable. Sample responses below contain a basic set of fields for illustrative purposes.\n" }, { "name": "Collections", "description": "Retrieve collection items from your ButterCMS account. Collections are flexible, user-defined content structures with completely customizable field schemas.\n\nSee also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.\n" }, { "name": "Blog posts", "description": "Retrieve blog posts from your ButterCMS account. List blog posts with pagination and filtering options, or retrieve individual posts by slug.\n" }, { "name": "Blog metadata", "description": "Retrieve blog-related metadata including authors, categories, and tags. These endpoints provide access to the organizational structure of your blog content.\n" }, { "name": "Feeds and utilities", "description": "Generate XML feeds for content syndication and SEO.\n\n- **RSS Feed**: Fully generated RSS 2.0 feed for your blog\n- **Atom Feed**: Standards-compliant Atom 1.0 feed\n- **Sitemap**: XML sitemap for search engine discovery\n\nAll feeds can be filtered by category or tag and include only published content from your organization.\n" }, { "name": "Images - Info", "description": "ButterCMS has an integration with [Filestack](https://www.filestack.com/docs/api/processing/) for image transformations. You can leverage their robust set of image transformation capabilities.\n\nAfter you upload an image, to create a thumbnail, here's an example:\n\n- **Original URL**: `https://cdn.buttercms.com/3ccPHhYHTNK2zQ14gCOy`\n- **Thumbnail URL**: `https://cdn.buttercms.com/resize=width:100,height:100/3ccPHhYHTNK2zQ14gCOy`\n\nFor complete transformation options and parameters, see the [full Filestack documentation](https://www.filestack.com/docs/api/processing/).\n" } ], "paths": { "/pages/{page_type}/": { "get": { "tags": [ "Pages" ], "summary": "Get multiple Pages", "description": "Retrieve a paginated list of pages for a given page type, or all Single\nPages when using the wildcard `*` as the page type. This endpoint supports\ncomprehensive filtering and sorting for Page Type collections.\n\n\n**Single Pages**: Use `*` as your `page_type` parameter to retrieve Single Pages,\nwhich are unique pages\nlike your Homepage, About page, or Contact page. This is particularly useful\nfor generating sitemaps or building navigation structures that include your\nstandalone pages.\n\n\n**Page Types**: Use the actual page type slug to retrieve all\nPages of that type, like new articles, product pages, etc. Pages will all\nhave the same field schema.\n\n\n> **Important**: Advanced filtering and ordering capabilities are only\navailable for Page Type endpoints, not when retrieving Single Pages with the\n`*` wildcard. Use dotted notation for field filters (e.g., `fields.title=Home`).\n\nSee also: Architecture & Performance for guidance on `levels`, pagination, and\nperformance best practices.\n", "x-mint": { "metadata": { "description": "Retrieve a paginated list of pages for a given page type, or all Single Pages using the wildcard *." }, "content": "Retrieve a paginated list of pages for a given page type, or all Single\nPages when using the wildcard `*` as the page type. This endpoint supports\ncomprehensive filtering and sorting for Page Type collections.\n\n\n**Single Pages**: Use `*` as your `page_type` parameter to retrieve Single Pages,\nwhich are unique pages\nlike your Homepage, About page, or Contact page. This is particularly useful\nfor generating sitemaps or building navigation structures that include your\nstandalone pages.\n\n\n**Page Types**: Use the actual page type slug to retrieve all\nPages of that type, like new articles, product pages, etc. Pages will all\nhave the same field schema.\n\n\n> **Important**: Advanced filtering and ordering capabilities are only\navailable for Page Type endpoints, not when retrieving Single Pages with the\n`*` wildcard. Use dotted notation for field filters (e.g., `fields.title=Home`).\n\nSee also: Architecture & Performance for guidance on `levels`, pagination, and\nperformance best practices.\n" }, "operationId": "getMultiplePages", "security": [ { "readTokenAuthQuery": [] }, { "readTokenAuthHeader": [] } ], "parameters": [ { "name": "page_type", "in": "path", "description": "The slug of the type of pages you want to retrieve, or `*` for Single Pages.\n\n- Use `*` to get Single Pages (those without a Page Type)\n- Use the actual page type slug to get pages of that specific type\n", "required": true, "schema": { "type": "string" }, "examples": { "single_pages": { "value": "*", "description": "Get all Single Pages" }, "news_pages": { "value": "news", "description": "Get pages of type 'news'" }, "faq_pages": { "value": "faq", "description": "Get pages of type 'faq'" } } }, { "$ref": "#/components/parameters/preview" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/locale" }, { "$ref": "#/components/parameters/levels" }, { "$ref": "#/components/parameters/alt_media_text" }, { "$ref": "#/components/parameters/auth_token" }, { "$ref": "#/components/parameters/order" }, { "name": "fields.seo.title", "in": "query", "description": "Filter the result set by a nested field value. This is an example of field filtering — you can filter by any field using the pattern `fields.=`.\n\nYou can pass in multiple filters at once. For example: `&fields.seo.title=Home&fields.headline=Welcome`\n\nTo filter on Reference or Component fields use dot notation. For example: `fields.hero.title=value` or `fields.hero.reference.title=value`\n\n**Note**: Field filtering is only available for Page Type endpoints, not for Single Pages (`page_type=*`).\n", "required": false, "schema": { "type": "string" }, "example": "Home" }, { "name": "fields.headline", "in": "query", "description": "Filter the result set by a top-level field value. This is an example of field filtering — you can filter by any field using the pattern `fields.=`.\n\n**Note**: Field filtering is only available for Page Type endpoints, not for Single Pages (`page_type=*`).\n", "required": false, "schema": { "type": "string" }, "example": "Welcome" } ], "responses": { "200": { "description": "**Success**\n\nReturns a hash with a `data` property that contains an array of pages, and a `meta` property that contains pagination information.\n\n- For Single Pages (`page_type=*`): Returns pages without a page type\n- For Page Types: Returns pages of the specified type\n", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SinglePagesResponse" }, { "$ref": "#/components/schemas/PageBasedPagesResponse" }, { "$ref": "#/components/schemas/OffsetBasedPagesResponse" } ] }, "examples": { "single_pages": { "summary": "Single Pages Response (page_type=*)", "value": { "meta": { "previous_page": null, "next_page": null, "count": 2 }, "data": [ { "slug": "single-page-1", "page_type": null, "published": "2019-11-12T17:23:53.109696Z", "updated": "2020-10-22T20:07:52.965850Z", "fields": { "title": "This is a single page", "body": "

Single PAGE!

" } }, { "slug": "single-page-2", "page_type": null, "published": "2019-11-12T17:23:53.109696Z", "updated": "2020-10-22T20:07:52.965850Z", "fields": { "title": "Amazing Single Page", "body": "

Another single page!

" } } ] } }, "page_type_pages": { "summary": "Page Type Response (page_type=news)", "value": { "meta": { "previous_page": null, "next_page": null, "count": 2 }, "data": [ { "slug": "example-news-page", "name": "Example News Page", "page_type": "news", "published": "2019-11-12T17:23:53.109696Z", "updated": "2020-10-22T20:07:52.965850Z", "fields": { "seo": { "title": "Example News Page", "description": "SEO Description", "keywords": "SEO, Keywords" }, "headline": "This is an example news page" } } ] } }, "media_url_format": { "summary": "Media field as URL string (alt_media_text=0)", "description": "When `alt_media_text=0` (default), media fields are returned as URL strings.", "value": { "meta": { "previous_page": null, "next_page": null, "count": 1 }, "data": [ { "slug": "poster-page", "name": "Poster Page", "page_type": "posters", "published": "2020-01-01T10:00:00Z", "updated": "2020-01-02T10:00:00Z", "fields": { "title": "Poster Details", "media": "https://cdn.example.com/media/poster.jpg" } } ] } }, "media_object_format": { "summary": "Media field as object (alt_media_text=1)", "description": "When `alt_media_text=1`, media fields are returned as objects. The object always includes `url`, and `alt` is included when available.\n", "value": { "meta": { "previous_page": null, "next_page": null, "count": 1 }, "data": [ { "slug": "poster-page", "name": "Poster Page", "page_type": "posters", "published": "2020-01-01T10:00:00Z", "updated": "2020-01-02T10:00:00Z", "fields": { "title": "Poster Details", "media": { "url": "https://cdn.example.com/media/poster.jpg", "alt": "Movie poster artwork" } } } ] } }, "offset_page_type_response": { "summary": "Offset-based pagination for page types", "description": "Using ?limit=10&offset=5 parameters for page type 'news'", "value": { "meta": { "count": 15, "next_offset": 15, "previous_offset": null }, "data": [ { "slug": "news-page-3", "name": "News Page 3", "page_type": "news", "published": "2019-11-13T17:23:53.109696Z", "updated": "2020-10-23T20:07:52.965850Z", "fields": { "seo": { "title": "Latest News Update", "description": "Breaking news content", "keywords": "News, Updates" }, "headline": "Breaking news story" } } ] } }, "offset_single_pages_response": { "summary": "Offset-based pagination for single pages", "description": "Using ?limit=10&offset=5 parameters for page_type='*'", "value": { "meta": { "count": 8, "next_offset": null, "previous_offset": null }, "data": [ { "slug": "about-us-page", "page_type": "*", "published": "2019-11-14T17:23:53.109696Z", "updated": "2020-10-24T20:07:52.965850Z", "fields": { "title": "About Our Company", "body": "

Learn about our mission and values

" } } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "description": "**Not Found - Page Type Does Not Exist or Invalid Pagination**\n\n- The requested page type doesn't exist or you don't have access to it.\n- Invalid pagination parameters (page number out of range).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "page_type_not_found": { "summary": "Page type not found", "value": { "detail": "Page type not found." } }, "missing_page_type": { "summary": "Missing page type key format", "value": { "detail": "Page Type Key missing. Please format request like so /pages/" } }, "invalid_pagination": { "summary": "Invalid pagination", "value": { "detail": "Invalid Page." } } } } } } } } }, "/pages/{page_type}/{page_slug}/": { "get": { "tags": [ "Pages" ], "summary": "Get a single Page", "description": "Retrieve a specific page by its page type and slug. This endpoint is ideal for fetching individual pages for display on your website or application.\n\n**Page Type Flexibility**: You can search across all page types using `*` as a wildcard, or optimize your query by providing a specific page type slug. Using the wildcard is useful when you know the page slug but aren't certain of its type, while specifying the page type can improve query performance. Use dotted notation for field filters (e.g., `fields.title=Example`).\nSee also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.\n", "x-mint": { "metadata": { "description": "Retrieve a specific page by page type and slug. Use the wildcard * as the page type for Single Pages." }, "content": "Retrieve a specific page by its page type and slug. This endpoint is ideal for fetching individual pages for display on your website or application.\n\n**Page Type Flexibility**: You can search across all page types using `*` as a wildcard, or optimize your query by providing a specific page type slug. Using the wildcard is useful when you know the page slug but aren't certain of its type, while specifying the page type can improve query performance. Use dotted notation for field filters (e.g., `fields.title=Example`).\nSee also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.\n" }, "operationId": "getSinglePage", "security": [ { "readTokenAuthHeader": [] }, { "readTokenAuthQuery": [] } ], "parameters": [ { "name": "page_type", "in": "path", "description": "The type of page to retrieve.\n\n- Use `*` to search across all page types\n- Use a specific page type slug to limit search to that type\n", "required": true, "schema": { "type": "string" }, "examples": { "wildcard": { "value": "*", "description": "Search across all page types" }, "specific_type": { "value": "news", "description": "Search within news page type only" } } }, { "name": "page_slug", "in": "path", "description": "The slug of the page to retrieve.\n", "required": true, "schema": { "type": "string" }, "example": "example-news-page" }, { "$ref": "#/components/parameters/preview" }, { "$ref": "#/components/parameters/locale" }, { "$ref": "#/components/parameters/levels" }, { "$ref": "#/components/parameters/alt_media_text" }, { "$ref": "#/components/parameters/auth_token" } ], "responses": { "200": { "description": "**Success**\n\nA hash with a `data` property that contains the page matching the page slug.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SinglePageResponse" }, "examples": { "basic_page": { "summary": "Basic page response", "value": { "data": { "slug": "example-news-page", "name": "Example News Page", "page_type": "news", "published": "2019-11-12T17:23:53.109696Z", "updated": "2020-10-22T20:07:52.965850Z", "fields": { "seo": { "title": "Example News Page", "description": "SEO Description", "keywords": "SEO, Keywords" }, "headline": "This is an example news page", "sections": [ { "fields": { "headline": "...", "subheadline": "...", "call_to_action": "..." }, "type": "hero" }, { "fields": { "video_headline": "...", "video_link": "..." }, "type": "product_video" } ] } } } }, "media_url_format": { "summary": "Media field as URL string (alt_media_text=0)", "description": "When `alt_media_text=0` (default), media fields are returned as URL strings.", "value": { "data": { "slug": "poster-page", "name": "Poster Page", "page_type": "posters", "published": "2020-01-01T10:00:00Z", "updated": "2020-01-02T10:00:00Z", "fields": { "title": "Poster Details", "media": "https://cdn.example.com/media/poster.jpg" } } } }, "media_object_format": { "summary": "Media field as object (alt_media_text=1)", "description": "When `alt_media_text=1`, media fields are returned as objects. The object always includes `url`, and `alt` is included when available.\n", "value": { "data": { "slug": "poster-page", "name": "Poster Page", "page_type": "posters", "published": "2020-01-01T10:00:00Z", "updated": "2020-01-02T10:00:00Z", "fields": { "title": "Poster Details", "media": { "url": "https://cdn.example.com/media/poster.jpg", "alt": "Movie poster artwork" } } } } } } } } }, "400": { "description": "**Bad Request - Invalid Parameter**\n\nInvalid parameter value provided. This can happen when:\n- The `levels` parameter is not a valid integer between 1 and 5\n- Invalid locale parameter provided\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_levels": { "summary": "Invalid levels parameter", "value": { "detail": "levels query parameter should be an integer between 1 and 5 (inclusive)" } }, "invalid_locale": { "summary": "Invalid locale parameter", "value": { "detail": "Invalid locale parameter" } } } } } }, "401": { "description": "**Unauthorized - Invalid or Missing API Token**\n\nAuthentication credentials were not provided. Make sure to include your read API token in the `Authorization` header or as the `auth_token` query parameter.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Authentication credentials were not provided" } } } }, "403": { "description": "**Forbidden - Multiple Pages Found**\n\nMultiple pages were found with the same slug when using wildcard page type. This typically indicates a data integrity issue where the same slug exists across different page types.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Multiple pages found with the same slug. Please specify a page type or contact support." } } } }, "404": { "description": "**Not Found - Page Does Not Exist**\n\nThe requested page doesn't exist, or you don't have access to it. This could be because:\n- The page slug doesn't exist\n- The page type doesn't exist\n- The page exists but not in the specified page type\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "page_not_found": { "summary": "Page not found", "value": { "detail": "Page not found." } }, "page_type_not_found": { "summary": "Page type not found", "value": { "detail": "Page type not found." } } } } } } } } }, "/pages/search/": { "get": { "tags": [ "Pages" ], "summary": "Search Pages", "description": "Search for pages using a text query, returning a list of pages that match the search query sorted by relevancy. This endpoint provides flexible page discovery capabilities across your entire page structure.\n\n**Search Behavior**: Only the direct content of the Pages is searched. Any references that the Page might include are ignored during search, but references are still included in the response based on the `levels` parameter provided. Pages are returned sorted by relevancy to the search query.\n\n**Page Type Filtering**: You can optionally limit your search to a specific page type, or search only Single Pages using `*` as the page type parameter.\n\n**Empty Results**: If no results are found, the API returns an empty array: `\"data\": []`\nSee also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.\n", "x-mint": { "metadata": { "description": "Search for pages using a text query. Results are sorted by relevance and can be filtered by page type." }, "content": "Search for pages using a text query, returning a list of pages that match the search query sorted by relevancy. This endpoint provides flexible page discovery capabilities across your entire page structure.\n\n**Search Behavior**: Only the direct content of the Pages is searched. Any references that the Page might include are ignored during search, but references are still included in the response based on the `levels` parameter provided. Pages are returned sorted by relevancy to the search query.\n\n**Page Type Filtering**: You can optionally limit your search to a specific page type, or search only Single Pages using `*` as the page type parameter.\n\n**Empty Results**: If no results are found, the API returns an empty array: `\"data\": []`\nSee also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.\n" }, "operationId": "searchPages", "security": [ { "readTokenAuthHeader": [] }, { "readTokenAuthQuery": [] } ], "parameters": [ { "name": "query", "in": "query", "description": "The search query string to match against page content.\n\nOnly the direct content of pages will be searched. References are excluded from search but will still appear in results.\n\n**Maximum Length**: 100 characters\n", "required": true, "schema": { "type": "string", "maxLength": 100 }, "examples": { "simple_search": { "value": "buttercmsapi", "description": "Simple keyword search" }, "phrase_search": { "value": "frequently asked questions", "description": "Multi-word phrase search" } } }, { "name": "page_type", "in": "query", "description": "The slug of the type of pages you want to limit your search to.\n\n- Use `*` if you want to search only Single Pages (without a Page Type)\n- Use a specific page type slug to limit search to that type\n- Omit this parameter to search across all page types\n\n**Maximum Length**: 100 characters\n", "required": false, "schema": { "type": "string", "maxLength": 100 }, "examples": { "single_pages": { "value": "*", "description": "Search only Single Pages" }, "specific_type": { "value": "news", "description": "Search only pages of type 'news'" } } }, { "$ref": "#/components/parameters/locale" }, { "$ref": "#/components/parameters/levels" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/auth_token" } ], "responses": { "200": { "description": "**Success**\n\nReturns a hash with a `data` property that contains an array of pages matching the search query, and a `meta` property that contains pagination information.\n\n**Search Results**: Pages are returned sorted by relevancy. If no results are found, returns an empty array: `\"data\": []`\n\n**Content Searched**: Only direct page content is searched. References are excluded from search but included in response based on `levels` parameter.\n", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PageBasedPageSearchResponse" }, { "$ref": "#/components/schemas/OffsetBasedPageSearchResponse" } ] }, "examples": { "search_results": { "summary": "Search results found", "value": { "meta": { "previous_page": null, "next_page": null, "count": 2 }, "data": [ { "slug": "example-news-page", "name": "Example News Page", "page_type": "news", "published": "2019-11-12T17:23:53.109696Z", "updated": "2020-10-22T20:07:52.965850Z", "fields": { "seo": { "title": "Example News Page", "description": "SEO Description", "keywords": "SEO, Keywords" }, "headline": "This is an example news page", "sections": [ { "fields": { "headline": "...", "subheadline": "...", "call_to_action": "..." }, "type": "hero" } ] } }, { "slug": "example-news-page-2", "name": "Example News Page 2", "page_type": "news", "published": "2019-11-12T17:23:53.109696Z", "updated": "2020-10-22T20:07:52.965850Z", "fields": { "seo": { "title": "Example News Page", "description": "SEO Description", "keywords": "SEO, Keywords" }, "headline": "This is another news page", "sections": [ { "fields": { "video_headline": "...", "video_link": "..." }, "type": "product_video" } ] } } ] } }, "offset_search_results": { "summary": "Offset-based pagination search results", "description": "Using ?limit=10&offset=5 parameters", "value": { "meta": { "count": 15, "next_offset": 15, "previous_offset": null }, "data": [ { "slug": "offset-news-page", "name": "Offset News Page", "page_type": "news", "published": "2019-11-15T17:23:53.109696Z", "updated": "2020-10-25T20:07:52.965850Z", "fields": { "seo": { "title": "Offset News Page", "description": "SEO Description for offset example", "keywords": "SEO, Keywords, Offset" }, "headline": "This is an offset-based search result", "sections": [ { "fields": { "headline": "Offset Section", "subheadline": "Demonstrating offset pagination", "call_to_action": "Learn More" }, "type": "hero" } ] } } ] } }, "no_results": { "summary": "No search results found", "value": { "meta": { "previous_page": null, "next_page": null, "count": 0 }, "data": [] } } } } } }, "400": { "description": "**Bad Request - Invalid Parameter**\n\nInvalid parameter value provided. This can happen when:\n- The `levels` parameter is not a valid integer between 1 and 5\n- Invalid locale parameter provided\n- Missing required `query` parameter\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_query": { "summary": "Missing required query parameter", "value": { "detail": "Query parameter is required for search." } }, "invalid_levels": { "summary": "Invalid levels parameter", "value": { "detail": "levels query parameter should be an integer between 1 and 5 (inclusive)" } }, "invalid_locale": { "summary": "Invalid locale parameter", "value": { "detail": "Invalid locale parameter" } }, "invalid_locale_validation": { "summary": "Locale not configured for organization", "value": { "detail": "fr is not a valid locale" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "description": "**Not Found - Page Type Does Not Exist**\n\nThe requested page type doesn't exist or you don't have access to it. This only applies when using the `page_type` parameter with a specific page type slug.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not found." } } } } } } }, "/content/{collection_key}/": { "get": { "tags": [ "Collections" ], "summary": "Retrieve Collection", "description": "Retrieve items from a specific Collection with comprehensive filtering, pagination, and relationship serialization capabilities. This endpoint provides flexible access to your dynamic content with powerful query options.\n\n**Collection Structure**: Collections contain completely user-defined content with customizable field schemas that you configure through the dashboard. Each collection can have different field types, validation rules, and structural requirements based on your content needs.\n\n**Response Format**: The response includes a `meta` object containing pagination information and result counts, a `data` array with the actual collection items, and individual `item.meta` objects containing unique IDs that you'll need for update and delete operations.\nSee also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.\n", "x-mint": { "metadata": { "description": "Retrieve items from a specific Collection with comprehensive filtering, pagination, and relationship serialization." }, "content": "Retrieve items from a specific Collection with comprehensive filtering, pagination, and relationship serialization capabilities. This endpoint provides flexible access to your dynamic content with powerful query options.\n\n**Collection Structure**: Collections contain completely user-defined content with customizable field schemas that you configure through the dashboard. Each collection can have different field types, validation rules, and structural requirements based on your content needs.\n\n**Response Format**: The response includes a `meta` object containing pagination information and result counts, a `data` array with the actual collection items, and individual `item.meta` objects containing unique IDs that you'll need for update and delete operations.\nSee also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.\n" }, "operationId": "retrieveCollection", "parameters": [ { "name": "collection_key", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 }, "description": "The unique identifier/slug of the Collection to retrieve.\n\nMust match an existing collection in your organization.\n", "example": "artists" }, { "$ref": "#/components/parameters/auth_token" }, { "name": "keys", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-delimited list of Collection keys for multi-collection retrieval.\n\n**Note**: This is a legacy parameter. For single collection retrieval, use the path parameter instead.\n", "example": "artists,albums" }, { "$ref": "#/components/parameters/preview" }, { "$ref": "#/components/parameters/order" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/locale" }, { "$ref": "#/components/parameters/levels" }, { "$ref": "#/components/parameters/alt_media_text" }, { "name": "fields", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "Dynamic field filtering using dot notation.\n\nFilter collection items by any field using the pattern `fields.{field_name}=value`:\n- `fields.genre=Rock` - Filter by genre field\n- `fields.status=published` - Filter by status field\n- `fields.year=2023` - Filter by year field\n\nMultiple field filters can be combined in a single request.\n", "examples": { "genre_filter": { "summary": "Filter by genre", "value": { "genre": "Rock" } }, "status_filter": { "summary": "Filter by status", "value": { "status": "published" } }, "multi_filter": { "summary": "Multiple filters", "value": { "genre": "Rock", "year": "2023" } } } } ], "responses": { "200": { "description": "Collection retrieved successfully", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PageBasedCollectionResponse" }, { "$ref": "#/components/schemas/OffsetBasedCollectionResponse" } ] }, "examples": { "artists_collection": { "summary": "Artists collection response", "value": { "meta": { "count": 25, "next_page": 3, "previous_page": 1 }, "data": { "artists": [ { "meta": { "id": 123 }, "name": "The Beatles", "genre": "Rock", "formed_year": 1960, "description": "Legendary British rock band" }, { "meta": { "id": 124 }, "name": "The Rolling Stones", "genre": "Rock", "formed_year": 1962, "description": "Iconic rock and roll band" } ] } } }, "filtered_response": { "summary": "Filtered collection response", "value": { "meta": { "count": 5, "next_page": null, "previous_page": null }, "data": { "products": [ { "meta": { "id": 456 }, "title": "Premium Headphones", "category": "Electronics", "price": 299.99, "in_stock": true } ] } } }, "localized_response": { "summary": "Localized collection response", "value": { "meta": { "count": 10, "next_page": 2, "previous_page": null }, "data": { "articles": [ { "meta": { "id": 789 }, "title": "Bonjour le monde", "content": "Contenu en français...", "locale": "fr" } ] } } }, "offset_collection_response": { "summary": "Offset-based pagination collection response", "description": "Using ?limit=10&offset=5 parameters", "value": { "meta": { "count": 25, "next_offset": 15, "previous_offset": null }, "data": { "artists": [ { "meta": { "id": 125 }, "name": "Pink Floyd", "genre": "Progressive Rock", "formed_year": 1965, "description": "English rock band known for philosophical lyrics" }, { "meta": { "id": 126 }, "name": "Led Zeppelin", "genre": "Hard Rock", "formed_year": 1968, "description": "Influential English rock band" } ] } } }, "media_url_format": { "summary": "Media field as URL string (alt_media_text=0)", "description": "When `alt_media_text=0` (default), media fields are returned as URL strings.\n", "value": { "meta": { "count": 1, "next_page": null, "previous_page": null }, "data": { "products": [ { "meta": { "id": 900 }, "title": "Poster", "media": "https://cdn.example.com/media/poster.jpg" } ] } } }, "media_object_format": { "summary": "Media field as object (alt_media_text=1)", "description": "When `alt_media_text=1`, media fields are returned as objects. The object always includes `url`, and `alt` is included when available.\n", "value": { "meta": { "count": 1, "next_page": null, "previous_page": null }, "data": { "products": [ { "meta": { "id": 901 }, "title": "Poster", "media": { "url": "https://cdn.example.com/media/poster.jpg", "alt": "Movie poster artwork" } } ] } } } } } } }, "400": { "description": "Bad Request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_locale": { "summary": "Invalid locale", "value": { "detail": "Invalid locale 'xyz' specified" } }, "invalid_levels": { "summary": "Invalid levels parameter", "value": { "detail": "levels query parameter should be an integer between 1 and 5 (inclusive)" } }, "invalid_filter": { "summary": "Invalid filter key", "value": { "detail": "Invalid filter key 'nonexistent_field'" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "description": "Not Found - Collection not found or Invalid Pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "collection_not_found": { "summary": "Collection not found", "value": { "detail": "Not found." } }, "invalid_pagination": { "summary": "Invalid pagination", "value": { "detail": "Invalid Page." } } } } } } }, "security": [ { "readTokenAuthHeader": [] }, { "readTokenAuthQuery": [] } ] } }, "/posts/": { "get": { "tags": [ "Blog posts" ], "summary": "List All Posts", "description": "Retrieve a paginated list of all published blog posts, automatically sorted\nby publication date with the newest posts appearing first. This endpoint is\nideal for building blog listing pages, RSS feeds, or content archives.\n\n**Performance Optimization**: Use the `exclude_body=true` parameter when\nbuilding post listing pages to significantly reduce response size by\nexcluding the full post content. This improves loading performance while\nstill providing titles, summaries, metadata, and author information needed\nfor listing displays.\n", "x-mint": { "metadata": { "description": "Retrieve a paginated list of published blog posts sorted by publication date, with filtering and performance options." }, "content": "Retrieve a paginated list of all published blog posts, automatically sorted\nby publication date with the newest posts appearing first. This endpoint is\nideal for building blog listing pages, RSS feeds, or content archives.\n\n**Performance Optimization**: Use the `exclude_body=true` parameter when\nbuilding post listing pages to significantly reduce response size by\nexcluding the full post content. This improves loading performance while\nstill providing titles, summaries, metadata, and author information needed\nfor listing displays.\n" }, "operationId": "listAllPosts", "security": [ { "readTokenAuthHeader": [] }, { "readTokenAuthQuery": [] } ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/preview" }, { "name": "locale", "in": "query", "description": "Return only posts in the given locale (e.g. `en`, `es`). When omitted, defaults to your organization's default locale.\n\nReturns `400` if the value is not a locale configured on your organization.\n", "required": false, "schema": { "type": "string", "maxLength": 10 }, "example": "en" }, { "name": "exclude_body", "in": "query", "description": "When `true`, excludes the full post body from the response.\n\n**Performance benefit**: Significantly reduces response size when displaying lists of blog posts.\n", "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "author_slug", "in": "query", "description": "Filter posts by an author's slug.", "schema": { "type": "string" }, "example": "api-test" }, { "name": "category_slug", "in": "query", "description": "Filter posts by a category's slug.", "schema": { "type": "string" }, "example": "test-category" }, { "name": "tag_slug", "in": "query", "description": "Filter posts by a tag's slug.", "schema": { "type": "string" }, "example": "test-tag" }, { "$ref": "#/components/parameters/auth_token" } ], "responses": { "200": { "description": "**Success - Blog Posts Retrieved**\n\nReturns a list of blog posts matching the specified criteria. Posts are\nsorted by publish date with the most recent posts first.\n", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PageBasedPostsResponse" }, { "$ref": "#/components/schemas/OffsetBasedPostsResponse" } ] }, "examples": { "page_based_pagination": { "summary": "Page-based pagination (default)", "description": "Using ?page=2&page_size=5 parameters", "value": { "meta": { "count": 25, "next_page": 3, "previous_page": 1 }, "data": [ { "url": "http://www.example.com/blog/this-is-a-blog-post", "created": "2020-10-08T18:29:19.987936Z", "updated": "2020-10-09T15:49:54.580309Z", "published": "2020-10-08T18:08:00Z", "author": { "first_name": "API", "last_name": "Test", "email": "apitest@buttercms.com", "slug": "api-test", "bio": "This is my bio.", "title": "API", "linkedin_url": "https://www.linkedin.com/in/API", "facebook_url": "https://www.facebook.com/API", "twitter_handle": "buttercmsapi", "profile_image": "https://buttercms.com/api.png" }, "categories": [ { "name": "test category", "slug": "test-category" } ], "tags": [ { "name": "test tag", "slug": "test-tag" } ], "featured_image": null, "featured_image_alt": "", "slug": "this-is-a-blog-post", "title": "This is a blog post", "body": "

This is a blog post to test the API.

", "summary": "This is a blog post to test the API.", "seo_title": "This is a blog post", "meta_description": "This is a blog post to test the API.", "status": "published" } ] } }, "offset_based_pagination": { "summary": "Offset-based pagination", "description": "Using ?limit=5&offset=10 parameters", "value": { "meta": { "count": 25, "next_offset": 15, "previous_offset": 5 }, "data": [ { "url": "http://www.example.com/blog/this-is-a-blog-post", "created": "2020-10-08T18:29:19.987936Z", "updated": "2020-10-09T15:49:54.580309Z", "published": "2020-10-08T18:08:00Z", "author": { "first_name": "API", "last_name": "Test", "email": "apitest@buttercms.com", "slug": "api-test", "bio": "This is my bio.", "title": "API", "linkedin_url": "https://www.linkedin.com/in/API", "facebook_url": "https://www.facebook.com/API", "twitter_handle": "buttercmsapi", "profile_image": "https://buttercms.com/api.png" }, "categories": [ { "name": "test category", "slug": "test-category" } ], "tags": [ { "name": "test tag", "slug": "test-tag" } ], "featured_image": null, "featured_image_alt": "", "slug": "this-is-a-blog-post", "title": "This is a blog post", "body": "

This is a blog post to test the API.

", "summary": "This is a blog post to test the API.", "seo_title": "This is a blog post", "meta_description": "This is a blog post to test the API.", "status": "published" } ] } }, "exclude_body_response": { "summary": "Response with exclude_body=true (lighter payload)", "description": "Using page-based pagination with exclude_body parameter", "value": { "meta": { "count": 25, "next_page": 3, "previous_page": 1 }, "data": [ { "url": "http://www.example.com/blog/this-is-a-blog-post", "created": "2020-10-08T18:29:19.987936Z", "updated": "2020-10-09T15:49:54.580309Z", "published": "2020-10-08T18:08:00Z", "author": { "first_name": "API", "last_name": "Test", "email": "apitest@buttercms.com", "slug": "api-test", "bio": "This is my bio.", "title": "API", "linkedin_url": "https://www.linkedin.com/in/API", "facebook_url": "https://www.facebook.com/API", "twitter_handle": "buttercmsapi", "profile_image": "https://buttercms.com/api.png" }, "categories": [ { "name": "test category", "slug": "test-category" } ], "tags": [ { "name": "test tag", "slug": "test-tag" } ], "featured_image": null, "featured_image_alt": "", "slug": "this-is-a-blog-post", "title": "This is a blog post", "summary": "This is a blog post to test the API.", "seo_title": "This is a blog post", "meta_description": "This is a blog post to test the API.", "status": "published" } ] } } } } } }, "400": { "description": "**Bad Request - Invalid Query Parameters**\n\nInvalid or malformed query parameters provided.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Invalid query parameters." } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" } } } }, "/posts/{slug}/": { "get": { "tags": [ "Blog posts" ], "summary": "Retrieve Single Post", "description": "Retrieve a specific blog post by its unique slug, including complete post content, metadata, and navigation information. This endpoint is ideal for building individual blog post pages with full content display.\n\n**Universal Access**: This endpoint retrieves posts regardless of their publication status (published, draft, or scheduled), making it perfect for preview functionality and content management workflows. Note that draft and scheduled posts won't appear in listing endpoints unless preview mode is specifically enabled.\n\n**Navigation Support**: The response includes a helpful `meta` object containing `next_post` and `previous_post` navigation links, allowing you to easily implement \"Previous/Next\" navigation on your blog post pages without additional API calls.\n\n> **Important**: You must append a trailing slash to the URL path: `/v2/posts/your-post-slug/`. This is required for the endpoint to function correctly.\n", "x-mint": { "metadata": { "description": "Retrieve a specific blog post by slug with complete content, metadata, and next/previous post navigation." }, "content": "Retrieve a specific blog post by its unique slug, including complete post content, metadata, and navigation information. This endpoint is ideal for building individual blog post pages with full content display.\n\n**Universal Access**: This endpoint retrieves posts regardless of their publication status (published, draft, or scheduled), making it perfect for preview functionality and content management workflows. Note that draft and scheduled posts won't appear in listing endpoints unless preview mode is specifically enabled.\n\n**Navigation Support**: The response includes a helpful `meta` object containing `next_post` and `previous_post` navigation links, allowing you to easily implement \"Previous/Next\" navigation on your blog post pages without additional API calls.\n\n> **Important**: You must append a trailing slash to the URL path: `/v2/posts/your-post-slug/`. This is required for the endpoint to function correctly.\n" }, "operationId": "retrieveSinglePost", "security": [ { "readTokenAuthHeader": [] }, { "readTokenAuthQuery": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The unique slug of the blog post to retrieve.\n\n**Important**: The URL must end with a trailing slash (`/v2/posts/your-slug/`).\n", "schema": { "type": "string", "maxLength": 100 }, "example": "hello-world" }, { "name": "locale", "in": "query", "description": "Return the locale variant of this post (e.g. `en`, `es`). Slugs are unique within a blog, so the slug identifies a specific post; this parameter follows the post's locale group to return its sibling translation. Sibling translations may have different slugs from the post identified in the URL path. When omitted, defaults to the locale the post itself was created in.\n\nReturns `404` if no sibling exists in the requested locale (or the post has no locale group). Returns `400` if the value is not a locale configured on your organization.\n", "required": false, "schema": { "type": "string", "maxLength": 10 }, "example": "en" }, { "$ref": "#/components/parameters/auth_token" } ], "responses": { "200": { "description": "**Success - Blog Post Retrieved**\n\nReturns the complete blog post object along with navigation metadata for browsing between posts.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveSinglePostResponse" }, "examples": { "published_post": { "summary": "Published blog post with navigation", "value": { "meta": { "next_post": null, "previous_post": { "slug": "google-analytics-is-now-integrated-with-your-butter-blog", "title": "Google Analytics is now integrated with your Butter blog", "featured_image": "https://d2devwt40at1e2.cloudfront.net/api/file/etSDYJUIFDADGEEAQ/" } }, "data": { "url": "http://www.example.com/blog/hello-world", "created": "2015-06-12T13:59:32.441289Z", "published": "2015-06-12T00:00:00Z", "author": { "first_name": "API", "last_name": "Test", "email": "apitest@buttercms.com", "slug": "api-test", "bio": "This is my bio.", "title": "API", "linkedin_url": "https://www.linkedin.com/in/API", "facebook_url": "https://www.facebook.com/API", "twitter_handle": "buttercmsapi", "profile_image": "https://buttercms.com/api.png" }, "categories": [ { "name": "test category", "slug": "test-category" } ], "tags": [ { "name": "test tag", "slug": "test-tag" } ], "featured_image": null, "featured_image_alt": "", "slug": "hello-world", "title": "This is a blog post", "body": "

This is a blog post to test the API.

", "summary": "This is a blog post to test the API.", "seo_title": "This is a blog post", "meta_description": "This is a blog post to test the API.", "status": "published" } } }, "draft_post_preview": { "summary": "Draft post accessible via direct slug (preview functionality)", "value": { "meta": { "next_post": { "slug": "upcoming-blog-post", "title": "Upcoming Blog Post", "featured_image": null }, "previous_post": null }, "data": { "url": "http://www.example.com/blog/draft-post-preview", "created": "2023-12-01T14:30:00.000000Z", "published": null, "author": { "first_name": "Content", "last_name": "Creator", "email": "creator@example.com", "slug": "content-creator", "bio": "Creating amazing content.", "title": "Content Creator", "linkedin_url": null, "facebook_url": null, "twitter_handle": "@creator", "profile_image": null }, "categories": [], "tags": [], "featured_image": "https://example.com/draft-image.jpg", "featured_image_alt": "Draft post image", "slug": "draft-post-preview", "title": "Draft Post Preview", "body": "

Preview Content

This is a draft post that can be previewed via direct slug access.

", "summary": "A draft post demonstrating preview functionality.", "seo_title": "Draft Post Preview", "meta_description": "Preview of draft content via direct slug access.", "status": "draft" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "description": "**Not Found - Blog Post Does Not Exist**\n\nThe blog post with the specified slug was not found. This can happen if:\n\n- The blog post doesn't exist\n- The blog post belongs to a different organization\n- You don't have access to the blog post\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Not found." } } } } } } }, "/authors/": { "get": { "tags": [ "Blog metadata" ], "summary": "List All Authors", "description": "Retrieve a complete list of all blog post authors in your organization, including their profile information and optional recent post data. This endpoint is ideal for building author pages, contributor listings, and author-based navigation.\n\n**Author Profiles**: Returns comprehensive profile information for each author, including personal details like name and bio, social media profiles, profile images, and author metadata. This provides everything needed to build rich author profile pages.\n\n**Recent Posts Integration**: Use the `include=recent_posts` parameter to enrich the response with each author's most recent blog posts. This is particularly useful for creating author archive pages that showcase both the author's profile and their latest content contributions.\n", "x-mint": { "metadata": { "description": "Retrieve a complete list of blog post authors, including profile information and optional recent post data." }, "content": "Retrieve a complete list of all blog post authors in your organization, including their profile information and optional recent post data. This endpoint is ideal for building author pages, contributor listings, and author-based navigation.\n\n**Author Profiles**: Returns comprehensive profile information for each author, including personal details like name and bio, social media profiles, profile images, and author metadata. This provides everything needed to build rich author profile pages.\n\n**Recent Posts Integration**: Use the `include=recent_posts` parameter to enrich the response with each author's most recent blog posts. This is particularly useful for creating author archive pages that showcase both the author's profile and their latest content contributions.\n" }, "operationId": "listAllAuthors", "parameters": [ { "$ref": "#/components/parameters/auth_token" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "recent_posts" ] }, "description": "Include additional data in the response.\n\nWhen set to `recent_posts`, each author object will include a `recent_posts` array containing their latest blog posts.\n", "example": "recent_posts" }, { "name": "locale", "in": "query", "description": "Filter the embedded `recent_posts` list to posts in the given locale (e.g. `en`, `es`). The author itself is shared across locales and is always returned. When omitted, defaults to your organization's default locale.\n\nReturns `400` if the value is not a locale configured on your organization.\n", "required": false, "schema": { "type": "string", "maxLength": 10 }, "example": "en" } ], "responses": { "200": { "description": "Authors retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuthorsResponse" }, "examples": { "basic_authors": { "summary": "Basic authors list", "value": { "data": [ { "slug": "api-test", "first_name": "API", "last_name": "Test", "email": "apitest@buttercms.com", "bio": "This is my bio.", "title": "API", "linkedin_url": "https://www.linkedin.com/in/API", "facebook_url": "https://www.facebook.com/API", "pinterest_url": "https://www.pinterest.com/API", "instagram_url": "https://www.instagram.com/API", "twitter_handle": "buttercmsapi", "profile_image": "https://buttercms.com/api.png" }, { "slug": "john-doe", "first_name": "John", "last_name": "Doe", "email": "john@example.com", "bio": "Experienced content writer and blogger.", "title": "Senior Writer", "linkedin_url": "https://www.linkedin.com/in/johndoe", "facebook_url": null, "pinterest_url": null, "instagram_url": "https://www.instagram.com/johndoe", "twitter_handle": "johndoe", "profile_image": "https://cdn.buttercms.com/profiles/john-doe.jpg" } ] } }, "authors_with_posts": { "summary": "Authors with recent posts included", "value": { "data": [ { "slug": "jane-smith", "first_name": "Jane", "last_name": "Smith", "email": "jane@example.com", "bio": "Tech writer specializing in web development.", "title": "Lead Technical Writer", "linkedin_url": "https://www.linkedin.com/in/janesmith", "facebook_url": "https://www.facebook.com/janesmith", "pinterest_url": null, "instagram_url": null, "twitter_handle": "janesmith_dev", "profile_image": "https://cdn.buttercms.com/profiles/jane-smith.jpg", "recent_posts": [ { "slug": "web-development-trends-2024", "title": "Web Development Trends in 2024", "published": "2024-01-15T10:00:00.000Z" }, { "slug": "javascript-best-practices", "title": "JavaScript Best Practices", "published": "2024-01-10T14:30:00.000Z" } ] } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" } }, "security": [ { "readTokenAuthHeader": [] }, { "readTokenAuthQuery": [] } ] } }, "/authors/{slug}/": { "get": { "tags": [ "Blog metadata" ], "summary": "Retrieve Author", "description": "Retrieve detailed information about a specific author by their unique slug identifier, including complete profile data and optional recent posts integration.\n\n**Author Profile Information**: Returns comprehensive author profile including personal details (name, email, bio, title), complete social media profiles (LinkedIn, Facebook, Pinterest, Instagram, Twitter), profile image CDN URL, and unique slug identifier for URL-friendly referencing.\n\n**Recent Posts Integration**: Use the `include=recent_posts` parameter to enrich the response with the author's most recent blog posts. This is particularly useful for creating detailed author profile pages that showcase both their biography and latest content contributions.\n", "x-mint": { "metadata": { "description": "Retrieve detailed author information by slug, including profile data and optional recent posts." }, "content": "Retrieve detailed information about a specific author by their unique slug identifier, including complete profile data and optional recent posts integration.\n\n**Author Profile Information**: Returns comprehensive author profile including personal details (name, email, bio, title), complete social media profiles (LinkedIn, Facebook, Pinterest, Instagram, Twitter), profile image CDN URL, and unique slug identifier for URL-friendly referencing.\n\n**Recent Posts Integration**: Use the `include=recent_posts` parameter to enrich the response with the author's most recent blog posts. This is particularly useful for creating detailed author profile pages that showcase both their biography and latest content contributions.\n" }, "operationId": "retrieveAuthor", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 }, "description": "The unique slug identifier of the author to retrieve.\n\nMust match an existing author slug in your organization.\n", "example": "jennifer-smith" }, { "$ref": "#/components/parameters/auth_token" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "recent_posts" ] }, "description": "Include additional data in the response.\n\nWhen set to `recent_posts`, the author object will include a `recent_posts` array containing their latest blog posts.\n", "example": "recent_posts" }, { "name": "locale", "in": "query", "description": "Filter the embedded `recent_posts` list to posts in the given locale (e.g. `en`, `es`). The author itself is shared across locales and is always returned. When omitted, defaults to your organization's default locale.\n\nReturns `400` if the value is not a locale configured on your organization.\n", "required": false, "schema": { "type": "string", "maxLength": 10 }, "example": "en" } ], "responses": { "200": { "description": "Author retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveAuthorResponse" }, "examples": { "basic_author": { "summary": "Basic author information", "value": { "data": { "slug": "jennifer-smith", "first_name": "Jennifer", "last_name": "Smith", "email": "jennifersmith@buttercms.com", "bio": "I love coffee!", "title": "President", "linkedin_url": "https://www.linkedin.com/in/jennifersmith", "facebook_url": "https://www.facebook.com/jennifersmith", "pinterest_url": "https://www.pinterest.com/jennifersmith", "instagram_url": "https://www.instagram.com/jennifersmith", "twitter_handle": "jennifersmith", "profile_image": "https://d2devwt40at1e2.cloudfront.net/api/file/etSDYJUIFDADGEEAQ.png" } } }, "author_with_posts": { "summary": "Author with recent posts included", "value": { "data": { "slug": "jennifer-smith", "first_name": "Jennifer", "last_name": "Smith", "email": "jennifersmith@buttercms.com", "bio": "I love coffee!", "title": "President", "linkedin_url": "https://www.linkedin.com/in/jennifersmith", "facebook_url": "https://www.facebook.com/jennifersmith", "pinterest_url": "https://www.pinterest.com/jennifersmith", "instagram_url": "https://www.instagram.com/jennifersmith", "twitter_handle": "jennifersmith", "profile_image": "https://d2devwt40at1e2.cloudfront.net/api/file/etSDYJUIFDADGEEAQ.png", "recent_posts": [ { "slug": "leadership-principles", "title": "Key Leadership Principles for Success", "published": "2024-01-20T09:00:00.000Z" }, { "slug": "coffee-productivity", "title": "How Coffee Boosts Productivity", "published": "2024-01-15T14:30:00.000Z" } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "description": "Not Found - Author not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "author_not_found": { "summary": "Author not found", "value": { "detail": "Not found." } } } } } } }, "security": [ { "readTokenAuthHeader": [] }, { "readTokenAuthQuery": [] } ] } }, "/categories/": { "get": { "tags": [ "Blog metadata" ], "summary": "List All Categories", "description": "Retrieve a complete list of all blog post categories in your organization, including category information and optional recent post data. This endpoint is perfect for building category navigation, content organization systems, and category-based filtering interfaces.\n\n**Category Information**: Returns the category name and URL-friendly slug for each category that contains published posts. This provides the essential data needed for building category-based navigation and filtering systems on your blog.\n\n**Recent Posts Integration**: Use the `include=recent_posts` parameter to enrich the response with each category's most recent blog posts. This is ideal for creating category landing pages that display both the category information and a preview of the latest content within that category.\n", "x-mint": { "metadata": { "description": "Retrieve a complete list of blog post categories with optional recent post data for category-based navigation." }, "content": "Retrieve a complete list of all blog post categories in your organization, including category information and optional recent post data. This endpoint is perfect for building category navigation, content organization systems, and category-based filtering interfaces.\n\n**Category Information**: Returns the category name and URL-friendly slug for each category that contains published posts. This provides the essential data needed for building category-based navigation and filtering systems on your blog.\n\n**Recent Posts Integration**: Use the `include=recent_posts` parameter to enrich the response with each category's most recent blog posts. This is ideal for creating category landing pages that display both the category information and a preview of the latest content within that category.\n" }, "operationId": "listAllCategories", "parameters": [ { "$ref": "#/components/parameters/auth_token" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "recent_posts" ] }, "description": "Include additional data in the response.\n\nWhen set to `recent_posts`, each category object will include a `recent_posts` array containing the latest blog posts in that category.\n", "example": "recent_posts" }, { "name": "locale", "in": "query", "description": "Filter the embedded `recent_posts` list to posts in the given locale (e.g. `en`, `es`). The category itself is shared across locales and is always returned. When omitted, defaults to your organization's default locale.\n\nReturns `400` if the value is not a locale configured on your organization.\n", "required": false, "schema": { "type": "string", "maxLength": 10 }, "example": "en" } ], "responses": { "200": { "description": "Categories retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCategoriesResponse" }, "examples": { "basic_categories": { "summary": "Basic categories list", "value": { "data": [ { "name": "test category", "slug": "test-category" }, { "name": "Product Updates", "slug": "product-updates" }, { "name": "Company News", "slug": "company-news" }, { "name": "Technology", "slug": "technology" } ] } }, "categories_with_posts": { "summary": "Categories with recent posts included", "value": { "data": [ { "name": "Product Updates", "slug": "product-updates", "recent_posts": [ { "slug": "new-features-release", "title": "Exciting New Features in Our Latest Release", "published": "2024-01-20T10:00:00.000Z" }, { "slug": "api-improvements", "title": "API Performance Improvements", "published": "2024-01-15T14:30:00.000Z" } ] }, { "name": "Technology", "slug": "technology", "recent_posts": [ { "slug": "future-of-web-development", "title": "The Future of Web Development", "published": "2024-01-18T11:00:00.000Z" } ] } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" } }, "security": [ { "readTokenAuthHeader": [] }, { "readTokenAuthQuery": [] } ] } }, "/categories/{slug}/": { "get": { "tags": [ "Blog metadata" ], "summary": "Retrieve Category", "description": "Retrieve a specific blog post category by its unique slug identifier, providing category information and optional recent posts integration. Categories help organize blog content into logical topical groups for improved navigation and content discovery.\n\n**Category Information**: The category object contains the display name (e.g., \"Product Updates\") and URL-friendly slug identifier (e.g., \"product-updates\") that can be used for building category-based navigation and content organization systems.\n\n**Recent Posts Integration**: Use the `include=recent_posts` parameter to enrich the response with the category's recent blog posts. This adds a `recent_posts` array containing up to 10 of the most recently published posts in this category, ideal for creating category landing pages that showcase both the category information and latest content.\n", "x-mint": { "metadata": { "description": "Retrieve a specific blog post category by slug with optional recent posts integration." }, "content": "Retrieve a specific blog post category by its unique slug identifier, providing category information and optional recent posts integration. Categories help organize blog content into logical topical groups for improved navigation and content discovery.\n\n**Category Information**: The category object contains the display name (e.g., \"Product Updates\") and URL-friendly slug identifier (e.g., \"product-updates\") that can be used for building category-based navigation and content organization systems.\n\n**Recent Posts Integration**: Use the `include=recent_posts` parameter to enrich the response with the category's recent blog posts. This adds a `recent_posts` array containing up to 10 of the most recently published posts in this category, ideal for creating category landing pages that showcase both the category information and latest content.\n" }, "operationId": "retrieveCategory", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique slug identifier of the category to retrieve.\n", "example": "product-updates" }, { "$ref": "#/components/parameters/auth_token" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "recent_posts" ] }, "description": "Include additional data in the response.\n\nWhen set to `recent_posts`, the category object will include a `recent_posts` array containing the latest blog posts in this category (up to 10 posts, ordered by most recent first).\n", "example": "recent_posts" }, { "name": "locale", "in": "query", "description": "Filter the embedded `recent_posts` list to posts in the given locale (e.g. `en`, `es`). The category itself is shared across locales and is always returned. When omitted, defaults to your organization's default locale.\n\nReturns `400` if the value is not a locale configured on your organization.\n", "required": false, "schema": { "type": "string", "maxLength": 10 }, "example": "en" } ], "responses": { "200": { "description": "Category retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveCategoryResponse" }, "examples": { "basic_category": { "summary": "Basic category without recent posts", "value": { "data": { "name": "Product Updates", "slug": "product-updates" } } }, "category_with_posts": { "summary": "Category with recent posts included", "value": { "data": { "name": "Product Updates", "slug": "product-updates", "recent_posts": [ { "slug": "new-features-release", "title": "Exciting New Features in Our Latest Release", "published": "2024-01-20T10:00:00.000Z" }, { "slug": "api-improvements", "title": "API Performance Improvements", "published": "2024-01-15T14:30:00.000Z" }, { "slug": "security-updates", "title": "Important Security Updates", "published": "2024-01-10T09:30:00.000Z" } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "description": "Not Found - Category with specified slug does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "category_not_found": { "summary": "Category not found", "value": { "detail": "Not found." } } } } } } }, "security": [ { "readTokenAuthHeader": [] }, { "readTokenAuthQuery": [] } ] } }, "/tags/": { "get": { "tags": [ "Blog metadata" ], "summary": "List All Tags", "description": "Retrieve a complete list of all blog post tags in your organization, providing granular categorization and labeling information for your blog content. This endpoint is essential for building tag-based navigation, content discovery features, and detailed content organization systems.\n\n**Tag Information**: Returns the tag name and URL-friendly slug for each tag that contains published posts. Tags offer more granular content categorization than categories, allowing for detailed topical organization and improved content discoverability.\n\n**Recent Posts Integration**: Use the `include=recent_posts` parameter to enrich the response with each tag's most recent blog posts. This is particularly useful for creating tag cloud interfaces, topic-based landing pages, and tag archive pages that showcase recent activity for specific topics.\n", "x-mint": { "metadata": { "description": "Retrieve a complete list of blog post tags with optional recent post data for tag-based navigation." }, "content": "Retrieve a complete list of all blog post tags in your organization, providing granular categorization and labeling information for your blog content. This endpoint is essential for building tag-based navigation, content discovery features, and detailed content organization systems.\n\n**Tag Information**: Returns the tag name and URL-friendly slug for each tag that contains published posts. Tags offer more granular content categorization than categories, allowing for detailed topical organization and improved content discoverability.\n\n**Recent Posts Integration**: Use the `include=recent_posts` parameter to enrich the response with each tag's most recent blog posts. This is particularly useful for creating tag cloud interfaces, topic-based landing pages, and tag archive pages that showcase recent activity for specific topics.\n" }, "operationId": "listAllTags", "parameters": [ { "$ref": "#/components/parameters/auth_token" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "recent_posts" ] }, "description": "Include additional data in the response.\n\nWhen set to `recent_posts`, each tag object will include a `recent_posts` array containing the latest blog posts tagged with that tag.\n", "example": "recent_posts" }, { "name": "locale", "in": "query", "description": "Filter the embedded `recent_posts` list to posts in the given locale (e.g. `en`, `es`). The tag itself is shared across locales and is always returned. When omitted, defaults to your organization's default locale.\n\nReturns `400` if the value is not a locale configured on your organization.\n", "required": false, "schema": { "type": "string", "maxLength": 10 }, "example": "en" } ], "responses": { "200": { "description": "Tags retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTagsResponse" }, "examples": { "basic_tags": { "summary": "Basic tags list", "value": { "data": [ { "name": "test tag", "slug": "test-tag" }, { "name": "API Development", "slug": "api-development" }, { "name": "Tutorial", "slug": "tutorial" }, { "name": "Best Practices", "slug": "best-practices" }, { "name": "JavaScript", "slug": "javascript" } ] } }, "tags_with_posts": { "summary": "Tags with recent posts included", "value": { "data": [ { "name": "API Development", "slug": "api-development", "recent_posts": [ { "slug": "rest-api-best-practices", "title": "REST API Best Practices for Modern Development", "published": "2024-01-22T09:00:00.000Z" }, { "slug": "graphql-vs-rest", "title": "GraphQL vs REST: Choosing the Right API", "published": "2024-01-18T14:30:00.000Z" } ] }, { "name": "JavaScript", "slug": "javascript", "recent_posts": [ { "slug": "es2024-features", "title": "New JavaScript Features in ES2024", "published": "2024-01-20T11:00:00.000Z" }, { "slug": "async-await-patterns", "title": "Advanced Async/Await Patterns", "published": "2024-01-16T13:45:00.000Z" } ] } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" } }, "security": [ { "readTokenAuthHeader": [] }, { "readTokenAuthQuery": [] } ] } }, "/tags/{slug}/": { "get": { "tags": [ "Blog metadata" ], "summary": "Retrieve Tag", "description": "Retrieve a specific blog post tag by its unique slug identifier, providing detailed tag information and optional recent posts integration. Tags provide granular categorization and labeling for blog content, enabling detailed content organization and enhanced discovery capabilities.\n\n**Tag Information**: The tag object contains the display name (e.g., \"API Development\") and URL-friendly slug identifier (e.g., \"api-development\") that can be used for building tag-based navigation, content filtering, and topic-specific landing pages.\n\n**Recent Posts Integration**: Use the `include=recent_posts` parameter to enrich the response with the tag's recent blog posts. This adds a `recent_posts` array containing up to 10 of the most recently published posts tagged with this tag, perfect for creating comprehensive tag pages that showcase both tag information and the latest related content.\n", "x-mint": { "metadata": { "description": "Retrieve a specific blog post tag by slug with tag details and optional recent posts integration." }, "content": "Retrieve a specific blog post tag by its unique slug identifier, providing detailed tag information and optional recent posts integration. Tags provide granular categorization and labeling for blog content, enabling detailed content organization and enhanced discovery capabilities.\n\n**Tag Information**: The tag object contains the display name (e.g., \"API Development\") and URL-friendly slug identifier (e.g., \"api-development\") that can be used for building tag-based navigation, content filtering, and topic-specific landing pages.\n\n**Recent Posts Integration**: Use the `include=recent_posts` parameter to enrich the response with the tag's recent blog posts. This adds a `recent_posts` array containing up to 10 of the most recently published posts tagged with this tag, perfect for creating comprehensive tag pages that showcase both tag information and the latest related content.\n" }, "operationId": "retrieveTag", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique slug identifier of the tag to retrieve.\n", "example": "api-development" }, { "$ref": "#/components/parameters/auth_token" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "recent_posts" ] }, "description": "Include additional data in the response.\n\nWhen set to `recent_posts`, the tag object will include a `recent_posts` array containing the latest blog posts tagged with this tag (up to 10 posts, ordered by most recent first).\n", "example": "recent_posts" }, { "name": "locale", "in": "query", "description": "Filter the embedded `recent_posts` list to posts in the given locale (e.g. `en`, `es`). The tag itself is shared across locales and is always returned. When omitted, defaults to your organization's default locale.\n\nReturns `400` if the value is not a locale configured on your organization.\n", "required": false, "schema": { "type": "string", "maxLength": 10 }, "example": "en" } ], "responses": { "200": { "description": "Tag retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveTagResponse" }, "examples": { "basic_tag": { "summary": "Basic tag without recent posts", "value": { "data": { "name": "API Development", "slug": "api-development" } } }, "tag_with_posts": { "summary": "Tag with recent posts included", "value": { "data": { "name": "API Development", "slug": "api-development", "recent_posts": [ { "slug": "rest-api-best-practices", "title": "REST API Best Practices for Modern Development", "published": "2024-01-22T09:00:00.000Z" }, { "slug": "graphql-vs-rest", "title": "GraphQL vs REST: Choosing the Right API", "published": "2024-01-18T14:30:00.000Z" }, { "slug": "api-versioning-strategies", "title": "API Versioning Strategies for Long-term Success", "published": "2024-01-14T16:15:00.000Z" } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "description": "Not Found - Tag with specified slug does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "tag_not_found": { "summary": "Tag not found", "value": { "detail": "Not found." } } } } } } }, "security": [ { "readTokenAuthHeader": [] }, { "readTokenAuthQuery": [] } ] } }, "/posts/search/": { "get": { "tags": [ "Blog posts" ], "summary": "Search Posts", "description": "Search blog posts using advanced full-text search capabilities across titles and content, with intelligent relevance scoring to surface the most relevant results first.\n\n**Search Algorithm**: The search engine performs comprehensive full-text indexing across post titles, body content, and summary fields using natural language processing. Results are ranked by relevance score, taking into account factors like keyword frequency, title matches, content quality signals, and publication recency.\n\n**Content Scope**: The search indexes all published post content including titles, body text, summary fields, and associated metadata. Draft and scheduled posts are excluded from search results unless you're using preview mode through other endpoints.\n\n**Result Optimization**: Returns complete post objects with calculated relevance scores by default. Use the `exclude_body=true` parameter when building search result pages to significantly reduce response size and improve loading performance, particularly for mobile applications.\n\n**Performance Features**: Search results are automatically cached to ensure fast response times for repeated queries. The search index is updated in real-time as content is published, ensuring fresh results without manual reindexing.\n", "x-mint": { "metadata": { "description": "Search blog posts using full-text search with intelligent relevance scoring and filtering options." }, "content": "Search blog posts using advanced full-text search capabilities across titles and content, with intelligent relevance scoring to surface the most relevant results first.\n\n**Search Algorithm**: The search engine performs comprehensive full-text indexing across post titles, body content, and summary fields using natural language processing. Results are ranked by relevance score, taking into account factors like keyword frequency, title matches, content quality signals, and publication recency.\n\n**Content Scope**: The search indexes all published post content including titles, body text, summary fields, and associated metadata. Draft and scheduled posts are excluded from search results unless you're using preview mode through other endpoints.\n\n**Result Optimization**: Returns complete post objects with calculated relevance scores by default. Use the `exclude_body=true` parameter when building search result pages to significantly reduce response size and improve loading performance, particularly for mobile applications.\n\n**Performance Features**: Search results are automatically cached to ensure fast response times for repeated queries. The search index is updated in real-time as content is published, ensuring fresh results without manual reindexing.\n" }, "operationId": "searchPosts", "parameters": [ { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100, "default": "" }, "description": "Search query string to find matching blog posts.\n\nThe search will look for matches in both post titles and body content. Uses natural language processing for best results. If empty or not provided, no results will be returned.\n", "example": "API development best practices" }, { "name": "locale", "in": "query", "description": "Search only posts in the given locale (e.g. `en`, `es`). When omitted, searches posts in your organization's default locale.\n\nReturns `400` if the value is not a locale configured on your organization.\n", "required": false, "schema": { "type": "string", "maxLength": 10 }, "example": "en" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "name": "exclude_body", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Exclude the full blog post body content from results to reduce response size.\n\nWhen set to `true`, the response will omit the `body` field from each post object, making responses faster and lighter for cases where only post metadata is needed.\n", "example": false }, { "$ref": "#/components/parameters/auth_token" } ], "responses": { "200": { "description": "Search completed successfully", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PageBasedSearchResponse" }, { "$ref": "#/components/schemas/OffsetBasedSearchResponse" } ] }, "examples": { "search_results": { "summary": "Search results with relevance ranking", "value": { "meta": { "count": 2, "next_page": null, "previous_page": null }, "data": [ { "url": "https://api.buttercms.com/blog/api-development-best-practices", "created": "2024-01-15T08:30:00.000Z", "published": "2024-01-15T10:00:00.000Z", "author": { "first_name": "John", "last_name": "Developer", "email": "john@buttercms.com", "slug": "john-developer", "bio": "Senior API Developer with 10+ years experience", "title": "Senior Developer", "linkedin_url": "https://linkedin.com/in/johndeveloper", "facebook_url": null, "twitter_handle": "johndev", "profile_image": "https://cdn.buttercms.com/authors/john-developer.jpg" }, "categories": [ { "name": "Development", "slug": "development" } ], "tags": [ { "name": "API", "slug": "api" }, { "name": "Best Practices", "slug": "best-practices" } ], "featured_image": "https://cdn.buttercms.com/featured/api-guide.jpg", "featured_image_alt": "API Development Guide", "slug": "api-development-best-practices", "title": "API Development Best Practices for 2024", "body": "

Introduction

Building robust APIs requires following established best practices...

", "summary": "Learn the essential best practices for building scalable and maintainable APIs in 2024.", "seo_title": "API Development Best Practices for 2024", "meta_description": "Complete guide to API development best practices including REST design, authentication, and documentation.", "status": "published", "rank": 0.8573 }, { "url": "https://api.buttercms.com/blog/rest-api-design-principles", "created": "2024-01-10T14:20:00.000Z", "published": "2024-01-12T09:00:00.000Z", "author": { "first_name": "Sarah", "last_name": "Architect", "email": "sarah@buttercms.com", "slug": "sarah-architect", "bio": "API Architect specializing in distributed systems", "title": "API Architect", "linkedin_url": "https://linkedin.com/in/saraharchitect", "facebook_url": null, "twitter_handle": "sarahapi", "profile_image": "https://cdn.buttercms.com/authors/sarah-architect.jpg" }, "categories": [ { "name": "Architecture", "slug": "architecture" } ], "tags": [ { "name": "REST", "slug": "rest" }, { "name": "API Design", "slug": "api-design" } ], "featured_image": "https://cdn.buttercms.com/featured/rest-design.jpg", "featured_image_alt": "REST API Design", "slug": "rest-api-design-principles", "title": "RESTful API Design Principles", "body": "

Core Principles

RESTful API design follows key principles that ensure scalability...

", "summary": "Master the fundamental principles of RESTful API design for better developer experience.", "seo_title": "RESTful API Design Principles", "meta_description": "Learn the core principles of REST API design for building intuitive and scalable web services.", "status": "published", "rank": 0.7234 } ] } }, "offset_search_results": { "summary": "Search results with offset-based pagination", "description": "Using ?limit=5&offset=0 parameters", "value": { "meta": { "count": 2, "next_offset": null, "previous_offset": null }, "data": [ { "url": "https://api.buttercms.com/blog/api-development-best-practices", "created": "2024-01-15T08:30:00.000Z", "published": "2024-01-15T10:00:00.000Z", "author": { "first_name": "John", "last_name": "Developer", "email": "john@buttercms.com", "slug": "john-developer", "bio": "Senior API Developer with 10+ years experience", "title": "Senior Developer", "linkedin_url": "https://linkedin.com/in/johndeveloper", "facebook_url": null, "twitter_handle": "johndev", "profile_image": "https://cdn.buttercms.com/authors/john-developer.jpg" }, "categories": [ { "name": "Development", "slug": "development" } ], "tags": [ { "name": "API", "slug": "api" }, { "name": "Best Practices", "slug": "best-practices" } ], "featured_image": "https://cdn.buttercms.com/featured/api-guide.jpg", "featured_image_alt": "API Development Guide", "slug": "api-development-best-practices", "title": "API Development Best Practices for 2024", "body": "

Introduction

Building robust APIs requires following established best practices...

", "summary": "Learn the essential best practices for building scalable and maintainable APIs in 2024.", "seo_title": "API Development Best Practices for 2024", "meta_description": "Complete guide to API development best practices including REST design, authentication, and documentation.", "status": "published", "rank": 0.8573 }, { "url": "https://api.buttercms.com/blog/rest-api-design-principles", "created": "2024-01-10T14:20:00.000Z", "published": "2024-01-12T09:00:00.000Z", "author": { "first_name": "Sarah", "last_name": "Architect", "email": "sarah@buttercms.com", "slug": "sarah-architect", "bio": "API Architect specializing in distributed systems", "title": "API Architect", "linkedin_url": "https://linkedin.com/in/saraharchitect", "facebook_url": null, "twitter_handle": "sarahapi", "profile_image": "https://cdn.buttercms.com/authors/sarah-architect.jpg" }, "categories": [ { "name": "Architecture", "slug": "architecture" } ], "tags": [ { "name": "REST", "slug": "rest" }, { "name": "API Design", "slug": "api-design" } ], "featured_image": "https://cdn.buttercms.com/featured/rest-design.jpg", "featured_image_alt": "REST API Design", "slug": "rest-api-design-principles", "title": "RESTful API Design Principles", "body": "

Core Principles

RESTful API design follows key principles that ensure scalability...

", "summary": "Master the fundamental principles of RESTful API design for better developer experience.", "seo_title": "RESTful API Design Principles", "meta_description": "Learn the core principles of REST API design for building intuitive and scalable web services.", "status": "published", "rank": 0.7234 } ] } }, "no_results": { "summary": "No search results found", "value": { "meta": { "count": 0, "next_page": null, "previous_page": null }, "data": [] } }, "excluded_body": { "summary": "Search results with body content excluded", "value": { "meta": { "count": 1, "next_page": null, "previous_page": null }, "data": [ { "url": "https://api.buttercms.com/blog/api-development-guide", "created": "2024-01-15T08:30:00.000Z", "published": "2024-01-15T10:00:00.000Z", "author": { "first_name": "John", "last_name": "Developer", "email": "john@buttercms.com", "slug": "john-developer", "bio": "Senior API Developer", "title": "Senior Developer", "linkedin_url": "https://linkedin.com/in/johndeveloper", "facebook_url": null, "twitter_handle": "johndev", "profile_image": "https://cdn.buttercms.com/authors/john.jpg" }, "categories": [ { "name": "Development", "slug": "development" } ], "tags": [ { "name": "API", "slug": "api" } ], "featured_image": "https://cdn.buttercms.com/featured/api.jpg", "featured_image_alt": "API Development", "slug": "api-development-guide", "title": "Complete API Development Guide", "summary": "Everything you need to know about API development.", "seo_title": "API Development Guide", "meta_description": "Complete guide to API development best practices.", "status": "published", "rank": 0.9012 } ] } } } } } }, "400": { "description": "Bad Request - Invalid search parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalid_pagination": { "summary": "Invalid pagination parameters", "value": { "page": [ "Ensure this value is greater than or equal to 1." ], "page_size": [ "Ensure this value is greater than or equal to 1." ] } }, "query_too_long": { "summary": "Search query too long", "value": { "query": [ "Ensure this field has no more than 100 characters." ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" } }, "security": [ { "readTokenAuthHeader": [] }, { "readTokenAuthQuery": [] } ] } }, "/feeds/rss/": { "get": { "tags": [ "Feeds and utilities" ], "summary": "RSS Feed", "description": "Generate a fully compliant RSS 2.0 XML feed for your blog content, perfect for syndication, feed readers, and content distribution. This endpoint automatically formats your blog posts into the standard RSS format with optional filtering capabilities.\n\n**RSS 2.0 Compliance**: Produces a standards-compliant RSS 2.0 XML feed that works with all major feed readers, news aggregators, and syndication services. The feed includes post titles, descriptions, publication dates, and permalinks.\n\n**Filtering Options**: Apply category or tag filters to create specialized feeds for specific content topics. This allows you to offer targeted RSS feeds for different audience segments or content verticals.\n", "x-mint": { "metadata": { "description": "Generate a compliant RSS 2.0 XML feed for blog content with filtering options for targeted content syndication." }, "content": "Generate a fully compliant RSS 2.0 XML feed for your blog content, perfect for syndication, feed readers, and content distribution. This endpoint automatically formats your blog posts into the standard RSS format with optional filtering capabilities.\n\n**RSS 2.0 Compliance**: Produces a standards-compliant RSS 2.0 XML feed that works with all major feed readers, news aggregators, and syndication services. The feed includes post titles, descriptions, publication dates, and permalinks.\n\n**Filtering Options**: Apply category or tag filters to create specialized feeds for specific content topics. This allows you to offer targeted RSS feeds for different audience segments or content verticals.\n" }, "operationId": "getRssFeed", "parameters": [ { "$ref": "#/components/parameters/auth_token" }, { "name": "category_slug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter the RSS feed to include only posts from a specific category.\n\nProvide the URL-friendly slug of the category. When specified, only blog posts assigned to this category will be included in the RSS feed.\n", "example": "announcements" }, { "name": "tag_slug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter the RSS feed to include only posts with a specific tag.\n\nProvide the URL-friendly slug of the tag. When specified, only blog posts tagged with this tag will be included in the RSS feed.\n", "example": "product-updates" }, { "name": "locale", "in": "query", "description": "Return only posts in the given locale (e.g. `en`, `es`) in the feed. When omitted, defaults to your organization's default locale.\n\nReturns `400` if the value is not a locale configured on your organization.\n", "required": false, "schema": { "type": "string", "maxLength": 10 }, "example": "en" } ], "responses": { "200": { "description": "RSS feed generated successfully", "content": { "application/xml": { "schema": { "type": "string", "format": "xml", "description": "Complete RSS 2.0 XML feed with blog posts" }, "examples": { "rss_feed": { "summary": "Standard RSS feed with blog posts", "value": "\n\n \n Latest blog posts\n https://example.buttercms.com/blog/rss/\n \n \n en-us\n Mon, 15 Jan 2024 10:00:00 +0000\n \n API Development Best Practices for 2024\n https://example.buttercms.com/blog/api-development-best-practices\n \n John Developer\n Mon, 15 Jan 2024 10:00:00 +0000\n https://example.buttercms.com/blog/api-development-best-practices\n Learn the essential best practices for building scalable and maintainable APIs in 2024.\n \n Introduction

Building robust APIs requires following established best practices. In this comprehensive guide, we'll explore the key principles that ensure your APIs are scalable, maintainable, and developer-friendly.

Key Principles

Modern API development focuses on consistency, documentation, and performance optimization...

]]>\n \n \n \n RESTful API Design Principles\n https://example.buttercms.com/blog/restful-api-design-principles\n \n Sarah Architect\n Fri, 12 Jan 2024 09:00:00 +0000\n https://example.buttercms.com/blog/restful-api-design-principles\n Master the fundamental principles of RESTful API design for better developer experience.\n \n Core Principles

RESTful API design follows key principles that ensure scalability and intuitive usage. Understanding these principles is crucial for creating APIs that developers love to use.

]]>\n \n \n \n\n" }, "filtered_by_category": { "summary": "RSS feed filtered by category", "value": "\n\n \n Latest blog posts\n https://example.buttercms.com/blog/rss/\n \n \n en-us\n Wed, 10 Jan 2024 15:30:00 +0000\n \n Product Launch: New API Features\n https://example.buttercms.com/blog/product-launch-new-api-features\n \n Product Team\n Wed, 10 Jan 2024 15:30:00 +0000\n https://example.buttercms.com/blog/product-launch-new-api-features\n Announcing exciting new API features and improvements in our latest release.\n \n What's New

We're excited to announce several new API features that will enhance your development experience...

]]>\n \n \n \n\n" } } } } }, "401": { "description": "Unauthorized - Invalid or missing API token", "content": { "application/xml": { "schema": { "type": "string", "format": "xml", "description": "Error response in XML format" }, "examples": { "missing_token": { "summary": "Missing API token", "value": "\nAuthentication credentials were not provided\n" }, "invalid_token": { "summary": "Invalid API token", "value": "\nInvalid token\n" } } } } }, "404": { "description": "Not Found - Invalid feed type or no posts found", "content": { "application/xml": { "schema": { "type": "string", "format": "xml", "description": "Error response when feed type is invalid" }, "examples": { "feed_not_found": { "summary": "Invalid feed type", "value": "\nFeed type not found\n" } } } } } }, "security": [ { "readTokenAuthHeader": [] }, { "readTokenAuthQuery": [] } ] } }, "/feeds/atom/": { "get": { "tags": [ "Feeds and utilities" ], "summary": "Atom Feed", "description": "Generate a fully compliant Atom 1.0 XML feed for your blog content, offering an alternative syndication format with rich metadata support. This endpoint is ideal for feed readers that prefer the Atom standard and applications requiring detailed content metadata.\n\n**Atom 1.0 Compliance**: Produces a standards-compliant Atom 1.0 XML feed with enhanced metadata support compared to RSS. The feed includes detailed author information, updated timestamps, content types, and rich linking relationships.\n\n**Filtering Capabilities**: Apply category or tag filters to generate specialized Atom feeds for specific content topics. This enables you to provide targeted content syndication for different audiences or subject areas.\n", "x-mint": { "metadata": { "description": "Generate a compliant Atom 1.0 XML feed for blog content with filtering capabilities for content syndication." }, "content": "Generate a fully compliant Atom 1.0 XML feed for your blog content, offering an alternative syndication format with rich metadata support. This endpoint is ideal for feed readers that prefer the Atom standard and applications requiring detailed content metadata.\n\n**Atom 1.0 Compliance**: Produces a standards-compliant Atom 1.0 XML feed with enhanced metadata support compared to RSS. The feed includes detailed author information, updated timestamps, content types, and rich linking relationships.\n\n**Filtering Capabilities**: Apply category or tag filters to generate specialized Atom feeds for specific content topics. This enables you to provide targeted content syndication for different audiences or subject areas.\n" }, "operationId": "getAtomFeed", "parameters": [ { "$ref": "#/components/parameters/auth_token" }, { "name": "category_slug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter the Atom feed to include only posts from a specific category.\n\nProvide the URL-friendly slug of the category. When specified, only blog posts assigned to this category will be included in the Atom feed.\n", "example": "announcements" }, { "name": "tag_slug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter the Atom feed to include only posts with a specific tag.\n\nProvide the URL-friendly slug of the tag. When specified, only blog posts tagged with this tag will be included in the Atom feed.\n", "example": "product-updates" }, { "name": "locale", "in": "query", "description": "Return only posts in the given locale (e.g. `en`, `es`) in the feed. When omitted, defaults to your organization's default locale.\n\nReturns `400` if the value is not a locale configured on your organization.\n", "required": false, "schema": { "type": "string", "maxLength": 10 }, "example": "en" } ], "responses": { "200": { "description": "Atom feed generated successfully", "content": { "application/xml": { "schema": { "type": "string", "format": "xml", "description": "Complete Atom 1.0 XML feed with blog posts" }, "examples": { "atom_feed": { "summary": "Standard Atom feed with blog posts", "value": "\n\n Latest blog posts\n \n \n https://example.buttercms.com/blog/rss/\n 2024-01-15T10:00:00Z\n \n API Development Best Practices for 2024\n \n 2024-01-15T10:00:00Z\n 2024-01-15T10:00:00Z\n \n John Developer\n \n https://example.buttercms.com/blog/api-development-best-practices\n Learn the essential best practices for building scalable and maintainable APIs in 2024.\n \n \n RESTful API Design Principles\n \n 2024-01-12T09:00:00Z\n 2024-01-12T09:00:00Z\n \n Sarah Architect\n \n https://example.buttercms.com/blog/restful-api-design-principles\n Master the fundamental principles of RESTful API design for better developer experience.\n \n\n" }, "filtered_by_tag": { "summary": "Atom feed filtered by tag", "value": "\n\n Latest blog posts\n \n \n https://example.buttercms.com/blog/rss/\n 2024-01-10T15:30:00Z\n \n New Features in Our API\n \n 2024-01-10T15:30:00Z\n 2024-01-10T15:30:00Z\n \n Product Team\n \n https://example.buttercms.com/blog/new-features-in-our-api\n Announcing exciting new API features and improvements in our latest release.\n \n\n" } } } } }, "401": { "$ref": "#/paths/~1feeds~1rss~1/get/responses/401" }, "404": { "description": "Not Found - Invalid feed type or no posts found", "content": { "application/xml": { "schema": { "type": "string", "format": "xml", "description": "Error response when feed type is invalid" }, "examples": { "feed_not_found": { "summary": "Invalid feed type", "value": "\nFeed type not found\n" } } } } } }, "security": [ { "readTokenAuthHeader": [] }, { "readTokenAuthQuery": [] } ] } }, "/feeds/sitemap/": { "get": { "tags": [ "Feeds and utilities" ], "summary": "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.\n\n**SEO Optimization**: Produces an XML sitemap following the sitemaps.org protocol that includes post URLs, last modification dates, and change frequency information. This helps search engines understand your content structure and prioritize crawling of updated content.\n\n**Filtering for Focused Sitemaps**: Apply category or tag filters to create specialized sitemaps for specific content sections. This is useful for large blogs where you want to submit targeted sitemaps to search engines or create separate indexing strategies for different content types.\n", "x-mint": { "metadata": { "description": "Generate a comprehensive XML sitemap for blog posts optimized for search engine discovery." }, "content": "Generate a comprehensive XML sitemap for your blog posts, optimized for search engine discovery and indexing. This endpoint creates a standards-compliant sitemap that helps search engines efficiently crawl and index your blog content.\n\n**SEO Optimization**: Produces an XML sitemap following the sitemaps.org protocol that includes post URLs, last modification dates, and change frequency information. This helps search engines understand your content structure and prioritize crawling of updated content.\n\n**Filtering for Focused Sitemaps**: Apply category or tag filters to create specialized sitemaps for specific content sections. This is useful for large blogs where you want to submit targeted sitemaps to search engines or create separate indexing strategies for different content types.\n" }, "operationId": "getSitemap", "parameters": [ { "$ref": "#/components/parameters/auth_token" }, { "name": "category_slug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter the sitemap to include only posts from a specific category.\n\nProvide the URL-friendly slug of the category. When specified, only blog posts assigned to this category will be included in the sitemap.\n", "example": "announcements" }, { "name": "tag_slug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter the sitemap to include only posts with a specific tag.\n\nProvide the URL-friendly slug of the tag. When specified, only blog posts tagged with this tag will be included in the sitemap.\n", "example": "seo-tips" }, { "name": "locale", "in": "query", "description": "Filter the sitemap to include only posts in the given locale (e.g. `en`, `es`). When omitted, defaults to your organization's default locale.\n\nReturns `400` if the value is not a locale configured on your organization.\n", "required": false, "schema": { "type": "string", "maxLength": 10 }, "example": "en" } ], "responses": { "200": { "description": "XML sitemap generated successfully", "content": { "application/xml": { "schema": { "type": "string", "format": "xml", "description": "Complete XML sitemap with blog post URLs" }, "examples": { "standard_sitemap": { "summary": "Standard XML sitemap with blog posts", "value": "\n\n \n https://example.buttercms.com/blog/api-development-best-practices\n 2024-01-15\n \n \n https://example.buttercms.com/blog/restful-api-design-principles\n 2024-01-12\n \n \n https://example.buttercms.com/blog/microservices-architecture-guide\n 2024-01-10\n \n \n https://example.buttercms.com/blog/database-optimization-techniques\n 2024-01-08\n \n\n" }, "filtered_by_category": { "summary": "Sitemap filtered by category", "value": "\n\n \n https://example.buttercms.com/blog/new-api-features-released\n 2024-01-10\n \n \n https://example.buttercms.com/blog/product-roadmap-update\n 2024-01-05\n \n\n" } } } } }, "401": { "$ref": "#/paths/~1feeds~1rss~1/get/responses/401" }, "404": { "description": "Not Found - Invalid feed type or no posts found", "content": { "application/xml": { "schema": { "type": "string", "format": "xml", "description": "Error response when feed type is invalid" }, "examples": { "feed_not_found": { "summary": "Invalid feed type", "value": "\nFeed type not found\n" } } } } } }, "security": [ { "readTokenAuthHeader": [] }, { "readTokenAuthQuery": [] } ] } } }, "components": { "securitySchemes": { "readTokenAuthQuery": { "type": "apiKey", "in": "query", "name": "auth_token", "description": "Pass your API token via the `auth_token` parameter on every request: `?auth_token=your_read_api_token`.\n\nYou can access your API token from your settings page.\n\nRequests made with a missing or invalid token will get a 401 Unauthorized response. All requests must be made over HTTPS.\n" }, "readTokenAuthHeader": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Set the `Authorization` header to `Token your_read_api_token`.\n\nExample: `Authorization: Token abc123def456`\n\nNote: The header value includes the `Token` prefix.\n\nYou can access your API token from your settings page.\n" }, "writeTokenAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Write-enabled API token required for creating content.\n\nThe API token you use for reading from the ButterCMS API will not allow you to create content in the API. For this you will need to use a different write-enabled token. Chat or email support@buttercms.com to get yours.\n\nSet the `Authorization` header to `Token your_write_api_token`.\n\nExample: `Authorization: Token abc123def456`\n\nYour write-enabled token should never be used anywhere it would be exposed, e.g. in client-side JavaScript.\n" } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message describing what went wrong", "example": "Authentication credentials were not provided" } } }, "SuccessResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending" ], "description": "Indicates that the page creation request has been accepted and is being processed asynchronously", "example": "pending" } } }, "ValidationErrorResponse": { "type": "object", "description": "Response for validation errors (400 Bad Request) - supports both field-specific errors and general error messages", "oneOf": [ { "type": "object", "description": "Field-specific validation errors (used by Pages, Blog Posts, and Collections)", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "title": [ "You must specify a page title." ], "slug": [ "You must specify a page slug." ] } }, { "type": "object", "description": "General error message (used for organization limits, etc.)", "properties": { "error": { "type": "string", "description": "Error message" } }, "example": { "error": "Cannot create a new Collection Item. Collection Item Limit Reached." } } ] }, "LimitErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message when subscription plan limits are exceeded", "example": "Page creation limit is over" } } }, "PaginationMeta": { "type": "object", "properties": { "previous_page": { "type": [ "integer", "null" ], "description": "Previous page number if it exists" }, "next_page": { "type": [ "integer", "null" ], "description": "Next page number if it exists" }, "count": { "type": "integer", "description": "Total number of items" } } }, "OffsetPaginationMeta": { "type": "object", "description": "Pagination metadata for limit/offset pagination", "properties": { "count": { "type": "integer", "description": "Total number of items", "example": 25 }, "next_offset": { "type": [ "integer", "null" ], "description": "Offset for the next page, null if no next page", "example": 20 }, "previous_offset": { "type": [ "integer", "null" ], "description": "Offset for the previous page, null if no previous page", "example": null } } }, "PageObject": { "type": "object", "description": "A single page object that can be either a Single Page or Page Type page", "properties": { "slug": { "type": "string", "description": "Unique identifier", "example": "example-news-page" }, "name": { "type": "string", "description": "Name of the Page", "example": "Example News Page" }, "page_type": { "type": [ "string", "null" ], "description": "API slug identifier of the page_type for the Page. null for Single Pages", "example": "news" }, "published": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of when the page was first published", "example": "2019-11-12T17:23:53.109696Z" }, "updated": { "type": "string", "format": "date-time", "description": "Timestamp of when the page was most recently published", "example": "2020-10-22T20:07:52.965850Z" }, "scheduled": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of when the page is scheduled to be published. If not scheduled, this field will be null", "example": null }, "status": { "type": "string", "enum": [ "published", "draft", "scheduled" ], "description": "Status of the current version of the page", "example": "published" }, "fields": { "type": "object", "description": "Contains all of the actual content for the Page - fields are customizable", "additionalProperties": true, "example": { "seo": { "title": "Example News Page", "description": "SEO Description", "keywords": "SEO, Keywords" }, "headline": "This is an example news page", "sections": [ { "fields": { "headline": "...", "subheadline": "...", "call_to_action": "..." }, "type": "hero" } ] } } } }, "SinglePage": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier", "example": "single-page-1" }, "page_type": { "type": [ "string", "null" ], "description": "Page type - null for single pages", "example": null }, "published": { "type": "string", "format": "date-time", "description": "Timestamp of when the page was first published", "example": "2019-11-12T17:23:53.109696Z" }, "updated": { "type": "string", "format": "date-time", "description": "Timestamp of when the page was most recently published", "example": "2020-10-22T20:07:52.965850Z" }, "fields": { "type": "object", "description": "Contains all of the actual content for the Page - fields are customizable", "additionalProperties": true, "example": { "title": "This is a single page", "body": "

Single PAGE!

" } } } }, "PageTypePage": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier", "example": "example-news-page" }, "name": { "type": "string", "description": "Name of the Page", "example": "Example News Page" }, "page_type": { "type": "string", "description": "API slug identifier of the page_type for the Page", "example": "news" }, "published": { "type": "string", "format": "date-time", "description": "Timestamp of when the page was first published", "example": "2019-11-12T17:23:53.109696Z" }, "updated": { "type": "string", "format": "date-time", "description": "Timestamp of when the page was most recently published", "example": "2020-10-22T20:07:52.965850Z" }, "fields": { "type": "object", "description": "Contains all of the actual content for the Page - fields are customizable", "additionalProperties": true, "example": { "seo": { "title": "Example News Page", "description": "SEO Description", "keywords": "SEO, Keywords" }, "headline": "This is an example news page", "tag": "example", "genre": "api" } } } }, "PageWebhookData": { "type": "object", "description": "Webhook data payload for page events", "properties": { "id": { "type": "string", "description": "Page slug", "example": "example-page-slug" }, "buttercms_id": { "type": "integer", "description": "Page numeric ID", "example": 1234 }, "page_type": { "type": "string", "description": "Page type key, or '*' for single pages", "example": "news" }, "editor": { "type": "string", "description": "Full name of the editor who made the change", "example": "John Doe" }, "name": { "type": "string", "description": "Human-readable page name", "example": "Example Page" }, "timestamp": { "type": "string", "description": "Current timestamp when webhook was generated", "example": "2024-01-15T18:11:09" }, "locale": { "type": [ "string", "null" ], "description": "Locale code for localized content, null for default locale", "example": "en" }, "status": { "type": "string", "description": "Current page status", "enum": [ "draft", "published", "scheduled", "deleted" ], "example": "published" }, "updated": { "type": "string", "format": "date-time", "description": "Last updated timestamp in ISO 8601 format", "example": "2024-01-15T18:11:09.791061Z" }, "published": { "type": [ "string", "null" ], "format": "date-time", "description": "Published timestamp in ISO 8601 format, null if not published", "example": "2024-01-15T18:10:00.000000Z" }, "scheduled": { "type": [ "string", "null" ], "format": "date-time", "description": "Scheduled publication timestamp in ISO 8601 format, null if not scheduled", "example": null } }, "required": [ "id", "buttercms_id", "page_type", "editor", "name", "timestamp", "status", "updated" ] }, "SinglePageResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PageObject" } } }, "SinglePagesResponse": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SinglePage" } } } }, "PageBasedPagesResponse": { "type": "object", "description": "Page type response using page-based pagination", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PageTypePage" } } }, "required": [ "meta", "data" ] }, "OffsetBasedPagesResponse": { "type": "object", "description": "Page type response using offset-based pagination", "properties": { "meta": { "$ref": "#/components/schemas/OffsetPaginationMeta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PageTypePage" } } }, "required": [ "meta", "data" ] }, "PageBasedPageSearchResponse": { "type": "object", "description": "Page search response using page-based pagination", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PageObject" }, "description": "Array of pages matching the search query, sorted by relevancy" } }, "required": [ "meta", "data" ] }, "OffsetBasedPageSearchResponse": { "type": "object", "description": "Page search response using offset-based pagination", "properties": { "meta": { "$ref": "#/components/schemas/OffsetPaginationMeta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PageObject" }, "description": "Array of pages matching the search query, sorted by relevancy" } }, "required": [ "meta", "data" ] }, "CollectionItemObject": { "type": "object", "description": "Individual collection item with dynamic field structure and metadata", "properties": { "meta": { "$ref": "#/components/schemas/CollectionItemMeta" } }, "additionalProperties": true, "example": { "meta": { "id": 123 }, "name": "The Beatles", "genre": "Rock", "formed_year": 1960, "members": [ "John Lennon", "Paul McCartney", "George Harrison", "Ringo Starr" ], "description": "Legendary British rock band" } }, "CollectionItemMeta": { "type": "object", "description": "Metadata for collection items containing unique identifier", "properties": { "id": { "type": "integer", "description": "Unique identifier for the collection item, used for updates and deletions", "example": 123 } }, "required": [ "id" ] }, "CollectionItemStatus": { "type": "string", "enum": [ "published", "draft" ], "default": "draft", "description": "Status of the collection item:\n\n- **draft**: Item is saved but not publicly available\n- **published**: Item is live and publicly accessible\n\nDefaults to \"draft\" if not specified.\n", "example": "published" }, "CollectionPaginationMeta": { "type": "object", "description": "Pagination metadata for collection retrieval", "properties": { "count": { "type": "integer", "description": "Total number of items in the collection (across all pages)", "example": 150 }, "next_page": { "type": [ "integer", "null" ], "description": "Next page number if more pages exist, null if this is the last page", "example": 3 }, "previous_page": { "type": [ "integer", "null" ], "description": "Previous page number if previous pages exist, null if this is the first page", "example": 1 } } }, "PageBasedCollectionResponse": { "type": "object", "description": "Collection response using page-based pagination", "properties": { "meta": { "$ref": "#/components/schemas/CollectionPaginationMeta" }, "data": { "type": "object", "description": "Collection data object with dynamic key based on collection name", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionItemObject" } } } }, "required": [ "meta", "data" ] }, "OffsetBasedCollectionResponse": { "type": "object", "description": "Collection response using offset-based pagination", "properties": { "meta": { "$ref": "#/components/schemas/OffsetPaginationMeta" }, "data": { "type": "object", "description": "Collection data object with dynamic key based on collection name", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionItemObject" } } } }, "required": [ "meta", "data" ] }, "BlogPostObject": { "type": "object", "description": "Complete blog post object with all fields and related data", "properties": { "url": { "type": "string", "format": "uri", "description": "Full URL to the blog post", "example": "http://www.example.com/blog/this-is-a-blog-post" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp when the blog post was created", "example": "2020-10-08T18:29:19.987936Z" }, "updated": { "type": "string", "format": "date-time", "description": "Timestamp when the blog post was last updated", "example": "2020-10-09T15:49:54.580309Z" }, "published": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the blog post was published", "example": "2020-10-08T18:08:00Z" }, "author": { "$ref": "#/components/schemas/BlogPostAuthorObject" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryObject" }, "description": "Array of categories assigned to the blog post" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/TagObject" }, "description": "Array of tags assigned to the blog post" }, "featured_image": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the featured image, null if no featured image", "example": null }, "featured_image_alt": { "type": "string", "description": "Alt text for the featured image", "example": "" }, "slug": { "type": "string", "description": "URL-friendly slug for the blog post", "example": "this-is-a-blog-post" }, "title": { "type": "string", "description": "Title of the blog post", "example": "This is a blog post" }, "body": { "type": "string", "description": "HTML content body of the blog post (excluded if exclude_body=true)", "example": "

This is a blog post to test the API.

" }, "summary": { "type": "string", "description": "Plain text summary of the blog post", "example": "This is a blog post to test the API." }, "seo_title": { "type": "string", "description": "SEO-optimized title for the blog post", "example": "This is a blog post" }, "meta_description": { "type": "string", "description": "Meta description for SEO and social sharing", "example": "This is a blog post to test the API." }, "status": { "type": "string", "enum": [ "draft", "published", "scheduled" ], "description": "Publication status of the blog post", "example": "published" }, "scheduled": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the blog post is scheduled to be published. If not scheduled, this field will be null", "example": null } } }, "BlogPostSearchResult": { "type": "object", "description": "Blog post object with search relevance ranking", "properties": { "url": { "type": "string", "format": "uri", "description": "Full URL to the blog post", "example": "https://api.buttercms.com/blog/api-development-best-practices" }, "created": { "type": "string", "format": "date-time", "description": "Creation date and time in ISO 8601 format", "example": "2024-01-15T08:30:00.000Z" }, "published": { "type": "string", "format": "date-time", "description": "Publication date and time in ISO 8601 format", "example": "2024-01-15T10:00:00.000Z" }, "author": { "$ref": "#/components/schemas/BlogPostAuthorObject", "description": "Author information" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryObject" }, "description": "Array of category objects" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/TagObject" }, "description": "Array of tag objects" }, "featured_image": { "type": [ "string", "null" ], "format": "uri", "description": "CDN URL of the featured image, null if no image", "example": "https://cdn.buttercms.com/featured/api-guide.jpg" }, "featured_image_alt": { "type": "string", "description": "Alt text for the featured image", "example": "API Development Guide" }, "slug": { "type": "string", "description": "URL-friendly slug identifier", "example": "api-development-best-practices" }, "title": { "type": "string", "description": "Blog post title", "example": "API Development Best Practices for 2024" }, "body": { "type": "string", "description": "Full HTML content of the blog post (excluded when exclude_body=true)", "example": "

Introduction

Building robust APIs requires following established best practices...

" }, "summary": { "type": "string", "description": "Summary or excerpt of the blog post", "example": "Learn the essential best practices for building scalable and maintainable APIs in 2024." }, "seo_title": { "type": "string", "description": "SEO-optimized title", "example": "API Development Best Practices for 2024" }, "meta_description": { "type": "string", "description": "Meta description for SEO", "example": "Complete guide to API development best practices including REST design, authentication, and documentation." }, "status": { "type": "string", "enum": [ "published" ], "description": "Publication status (only published posts appear in search results)", "example": "published" }, "rank": { "type": "number", "format": "float", "description": "Search relevance score (higher values indicate better matches)", "example": 0.8573, "minimum": 0, "maximum": 1 } } }, "PageBasedPostsResponse": { "type": "object", "description": "Blog posts response using page-based pagination (default)", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BlogPostObject" }, "description": "Array of blog post objects sorted by publish date (newest first)" } }, "required": [ "meta", "data" ] }, "OffsetBasedPostsResponse": { "type": "object", "description": "Blog posts response using offset-based pagination (alternative)", "properties": { "meta": { "$ref": "#/components/schemas/OffsetPaginationMeta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BlogPostObject" }, "description": "Array of blog post objects sorted by publish date (newest first)" } }, "required": [ "meta", "data" ] }, "RetrieveSinglePostResponse": { "type": "object", "description": "Response for retrieving a single blog post with navigation metadata", "properties": { "meta": { "$ref": "#/components/schemas/SinglePostMeta" }, "data": { "$ref": "#/components/schemas/BlogPostObject", "description": "Complete blog post object with all fields and related data" } } }, "PageBasedSearchResponse": { "type": "object", "description": "Blog post search response using page-based pagination", "properties": { "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BlogPostSearchResult" }, "description": "Array of blog post search results with relevance ranking" } }, "required": [ "meta", "data" ] }, "OffsetBasedSearchResponse": { "type": "object", "description": "Blog post search response using offset-based pagination", "properties": { "meta": { "$ref": "#/components/schemas/OffsetPaginationMeta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BlogPostSearchResult" }, "description": "Array of blog post search results with relevance ranking" } }, "required": [ "meta", "data" ] }, "PostNavigationObject": { "type": "object", "description": "Navigation object containing essential information for blog post links", "properties": { "slug": { "type": "string", "description": "URL-friendly slug of the post for navigation", "example": "google-analytics-is-now-integrated-with-your-butter-blog" }, "title": { "type": "string", "description": "Title of the post for display in navigation", "example": "Google Analytics is now integrated with your Butter blog" }, "featured_image": { "type": [ "string", "null" ], "format": "uri", "description": "URL to the featured image for navigation thumbnails, null if no featured image", "example": "https://d2devwt40at1e2.cloudfront.net/api/file/etSDYJUIFDADGEEAQ/" } } }, "SinglePostMeta": { "type": "object", "description": "Navigation metadata for single blog post responses", "properties": { "next_post": { "anyOf": [ { "$ref": "#/components/schemas/PostNavigationObject" }, { "type": "null" } ], "description": "Next blog post for navigation, null if no next post exists" }, "previous_post": { "anyOf": [ { "$ref": "#/components/schemas/PostNavigationObject" }, { "type": "null" } ], "description": "Previous blog post for navigation, null if no previous post exists" } } }, "AuthorObject": { "type": "object", "description": "Complete author information with optional recent posts", "properties": { "slug": { "type": "string", "description": "Unique identifier/slug for the author", "example": "api-test" }, "first_name": { "type": "string", "description": "Author's first name", "example": "API" }, "last_name": { "type": "string", "description": "Author's last name", "example": "Test" }, "email": { "type": "string", "format": "email", "description": "Author's email address", "example": "apitest@buttercms.com" }, "bio": { "type": "string", "description": "Author's biography/description", "example": "This is my bio." }, "title": { "type": "string", "description": "Author's professional title", "example": "API" }, "linkedin_url": { "type": [ "string", "null" ], "format": "uri", "description": "Author's LinkedIn profile URL", "example": "https://www.linkedin.com/in/API" }, "facebook_url": { "type": [ "string", "null" ], "format": "uri", "description": "Author's Facebook profile URL", "example": "https://www.facebook.com/API" }, "pinterest_url": { "type": [ "string", "null" ], "format": "uri", "description": "Author's Pinterest profile URL", "example": "https://www.pinterest.com/API" }, "instagram_url": { "type": [ "string", "null" ], "format": "uri", "description": "Author's Instagram profile URL", "example": "https://www.instagram.com/API" }, "twitter_handle": { "type": "string", "description": "Author's Twitter handle (without @ symbol)", "example": "buttercmsapi" }, "profile_image": { "type": [ "string", "null" ], "format": "uri", "description": "CDN URL of author's profile image", "example": "https://buttercms.com/api.png" }, "recent_posts": { "type": "array", "items": { "$ref": "#/components/schemas/AuthorRecentPost" }, "description": "Array of recent posts by this author (only included when include=recent_posts parameter is used)" } } }, "BlogPostAuthor": { "type": "object", "description": "Author reference for blog posts. Author must exist in your account prior to POST.\n\nYou can specify the author either by email or by slug. If no author is specified, defaults to the organization owner.\n", "oneOf": [ { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Email address of the existing author", "example": "your@author.com" } } }, { "type": "object", "required": [ "slug" ], "properties": { "slug": { "type": "string", "description": "Slug of the existing author", "example": "firstname-lastname" } } } ] }, "BlogPostAuthorObject": { "type": "object", "description": "Author information for blog posts", "properties": { "first_name": { "type": "string", "description": "Author's first name", "example": "API" }, "last_name": { "type": "string", "description": "Author's last name", "example": "Test" }, "email": { "type": "string", "format": "email", "description": "Author's email address", "example": "apitest@buttercms.com" }, "slug": { "type": "string", "description": "Author's URL-friendly slug", "example": "api-test" }, "bio": { "type": "string", "description": "Author's biography", "example": "This is my bio." }, "title": { "type": "string", "description": "Author's professional title", "example": "API" }, "linkedin_url": { "type": [ "string", "null" ], "format": "uri", "description": "Author's LinkedIn profile URL", "example": "https://www.linkedin.com/in/API" }, "facebook_url": { "type": [ "string", "null" ], "format": "uri", "description": "Author's Facebook profile URL", "example": "https://www.facebook.com/API" }, "twitter_handle": { "type": "string", "description": "Author's Twitter handle", "example": "buttercmsapi" }, "instagram_url": { "type": [ "string", "null" ], "format": "uri", "description": "Author's Instagram profile URL", "example": "https://www.instagram.com/API" }, "pinterest_url": { "type": [ "string", "null" ], "format": "uri", "description": "Author's Pinterest profile URL", "example": "https://www.pinterest.com/API" }, "profile_image": { "type": [ "string", "null" ], "format": "uri", "description": "URL to author's profile image", "example": "https://buttercms.com/api.png" } } }, "AuthorRecentPost": { "type": "object", "description": "Simplified blog post information for author's recent posts", "properties": { "slug": { "type": "string", "description": "Blog post slug/identifier", "example": "web-development-trends-2024" }, "title": { "type": "string", "description": "Blog post title", "example": "Web Development Trends in 2024" }, "published": { "type": "string", "format": "date-time", "description": "Publication date and time in ISO 8601 format", "example": "2024-01-15T10:00:00.000Z" } } }, "ListAuthorsResponse": { "type": "object", "description": "Response structure for listing all authors", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuthorObject" }, "description": "Array of author objects" } } }, "RetrieveAuthorResponse": { "type": "object", "description": "Response structure for retrieving a single author", "properties": { "data": { "$ref": "#/components/schemas/AuthorObject", "description": "Single author object" } } }, "CategoryObject": { "type": "object", "description": "Category information for blog posts", "properties": { "name": { "type": "string", "description": "Display name of the category", "example": "test category" }, "slug": { "type": "string", "description": "URL-friendly slug of the category", "example": "test-category" } } }, "CategoryObjectWithPosts": { "type": "object", "description": "Category information with optional recent posts", "properties": { "name": { "type": "string", "description": "Display name of the category", "example": "Product Updates" }, "slug": { "type": "string", "description": "URL-friendly slug of the category", "example": "product-updates" }, "recent_posts": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryRecentPost" }, "description": "Array of recent posts in this category (only included when include=recent_posts parameter is used)" } } }, "CategoryRecentPost": { "type": "object", "description": "Simplified blog post information for category's recent posts", "properties": { "slug": { "type": "string", "description": "Blog post slug/identifier", "example": "new-features-release" }, "title": { "type": "string", "description": "Blog post title", "example": "Exciting New Features in Our Latest Release" }, "published": { "type": "string", "format": "date-time", "description": "Publication date and time in ISO 8601 format", "example": "2024-01-20T10:00:00.000Z" } } }, "ListCategoriesResponse": { "type": "object", "description": "Response structure for listing all categories", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryObjectWithPosts" }, "description": "Array of category objects" } } }, "RetrieveCategoryResponse": { "type": "object", "description": "Response structure for retrieving a single category", "properties": { "data": { "$ref": "#/components/schemas/CategoryObjectWithPosts", "description": "Single category object" } } }, "TagObject": { "type": "object", "description": "Tag information for blog posts", "properties": { "name": { "type": "string", "description": "Display name of the tag", "example": "test tag" }, "slug": { "type": "string", "description": "URL-friendly slug of the tag", "example": "test-tag" } } }, "TagObjectWithPosts": { "type": "object", "description": "Tag information with optional recent posts", "properties": { "name": { "type": "string", "description": "Display name of the tag", "example": "API Development" }, "slug": { "type": "string", "description": "URL-friendly slug of the tag", "example": "api-development" }, "recent_posts": { "type": "array", "items": { "$ref": "#/components/schemas/TagRecentPost" }, "description": "Array of recent posts with this tag (only included when include=recent_posts parameter is used)" } } }, "TagRecentPost": { "type": "object", "description": "Simplified blog post information for tag's recent posts", "properties": { "slug": { "type": "string", "description": "Blog post slug/identifier", "example": "rest-api-best-practices" }, "title": { "type": "string", "description": "Blog post title", "example": "REST API Best Practices for Modern Development" }, "published": { "type": "string", "format": "date-time", "description": "Publication date and time in ISO 8601 format", "example": "2024-01-22T09:00:00.000Z" } } }, "ListTagsResponse": { "type": "object", "description": "Response structure for listing all tags", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TagObjectWithPosts" }, "description": "Array of tag objects" } } }, "RetrieveTagResponse": { "type": "object", "description": "Response structure for retrieving a single tag", "properties": { "data": { "$ref": "#/components/schemas/TagObjectWithPosts", "description": "Single tag object" } } } }, "responses": { "UnauthorizedResponse": { "description": "Unauthorized - Invalid or missing API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_token": { "summary": "Missing API token", "value": { "detail": "Authentication credentials were not provided" } }, "invalid_token": { "summary": "Invalid API token", "value": { "detail": "Invalid token" } } } } } }, "NoContentResponse": { "description": "Operation completed successfully - No content returned" } }, "parameters": { "auth_token": { "name": "auth_token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Your ButterCMS read API token\n", "example": "your_api_token" }, "preview": { "name": "preview", "in": "query", "description": "Set to 1 to return the latest draft version of a page. Useful for previewing changes before publishing live. i.e. `&preview=1`. If you are trying to view a scheduled page for which the most recent page version is published, you must pass the preview parameter to see the scheduled changes.\n\nSet to `1` to access unpublished/draft collection items. Useful for staging environments.\n", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "example": 1 }, "locale": { "name": "locale", "in": "query", "description": "Set to the api slug of your configured locale (e.g. `en` or `fr`). When omitted, this query parameter will default to your organization's default locale.\n", "required": false, "schema": { "type": "string", "maxLength": 10, "example": "en" }, "examples": { "english": { "value": "en", "description": "English locale" }, "spanish": { "value": "es", "description": "Spanish locale" }, "french": { "value": "fr", "description": "French locale" } } }, "levels": { "name": "levels", "in": "query", "description": "Depth of relationship serialization.\n\nControls how many levels of referenced content to include:\n- **1**: Direct fields only, references as URIs\n- **2**: Direct fields + one level of references (default)\n- **3-5**: Deeper relationship traversal\n\n**Important**: Higher levels increase response size. Maximum 10MB per response.\n\nValid range: 1-5 (inclusive). Values outside this range will be automatically capped.\n", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5, "default": 2 }, "examples": { "shallow": { "value": 1, "description": "Minimal depth (1 level)" }, "default": { "value": 2, "description": "Default depth (2 levels)" }, "deep": { "value": 5, "description": "Maximum depth (5 levels)" } } }, "alt_media_text": { "name": "alt_media_text", "in": "query", "description": "Media field response format.\n\nAffects only media-typed fields. Other field types are unchanged.\n\n- **0** (default): Media fields return simple URL strings\n- **1**: Media fields return objects with at least `url` and, when available,\n `alt`. If the stored media value is just a URL string, the object will\n include `url` only.\n", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "examples": { "url_only": { "value": 0, "description": "Return media as URL strings (default)" }, "object_format": { "value": 1, "description": "Return media as objects with at least url (alt included when available)" } } }, "page": { "name": "page", "in": "query", "description": "Page number for page-based pagination.\n\n**Mutually exclusive with limit/offset parameters.**\n", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 2 }, "page_size": { "name": "page_size", "in": "query", "description": "Number of items per page for page-based pagination.\n\n**Mutually exclusive with limit/offset parameters.**\n", "required": false, "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 100 }, "example": 5 }, "limit": { "name": "limit", "in": "query", "description": "Maximum number of items to return for offset-based pagination.\n\n**Mutually exclusive with page/page_size parameters.**\n\nValues above 100 are capped at 100; values below 1 or invalid fall back to the default of 10 (the request is not rejected).\n", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "example": 5 }, "offset": { "name": "offset", "in": "query", "description": "Number of items to skip before starting to return results.\n\n**Mutually exclusive with page/page_size parameters.**\n", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "example": 10 }, "order": { "name": "order", "in": "query", "description": "Can order by page level `published`, `updated`, or a content field of the Page Type. Defaults to ascending, prepend '-' to sort descending.\n\n**Note**: Only available for Page Type endpoints, not for Single Pages (`page_type=*`).\n", "required": false, "schema": { "type": "string" }, "examples": { "ascending_title": { "value": "title", "description": "Order by title ascending" }, "descending_published": { "value": "-published", "description": "Order by published date descending" }, "ascending_updated": { "value": "updated", "description": "Order by updated date ascending" } } } } }, "security": [ { "readTokenAuthHeader": [] }, { "readTokenAuthQuery": [] } ] }