--- title: ButterCMS API Integration on Truto slug: buttercms category: Knowledge Management canonical: "https://truto.one/integrations/detail/buttercms/" --- # ButterCMS API Integration on Truto **Category:** Knowledge Management **Status:** Beta ## MCP-ready AI tools Truto exposes 25 tools for ButterCMS that AI agents can call directly. - **list_all_butter_cms_pages** — Retrieve a paginated list of ButterCMS pages for a given page type, or all Single Pages when page_type is `*`. Returns: slug, name, page_type, published, updated, fields. Field filtering and ordering apply to Page Type endpoints, not Single Pages. Required: page_type. - **create_a_butter_cms_page** — Create a new ButterCMS page via the Write API with support for multiple locales and automatic media uploads. The page type schema must already exist in your account; pages are created as draft by default and processing is asynchronous. Returns: status. Required: title, slug, page_type, fields. - **update_a_butter_cms_page_by_id** — Update an existing ButterCMS page via the Write API using a partial PATCH (PUT is supported for backwards compatibility). Only included fields are modified; title and slug are immutable. Page updates are asynchronous; scheduling is not supported. Returns: status, examples, name. Required: id, page_type. - **get_single_butter_cms_page_by_id** — Retrieve a specific ButterCMS page by page type and slug (id). Use `*` as page_type to look up a Single Page when the type is unknown. Returns: slug, name, page_type, published, updated, fields. Required: page_type, id. - **list_all_butter_cms_pages_searches** — Search ButterCMS pages by text query, returning matching pages sorted by relevancy. Only direct page content is searched; references are excluded from search but still included in the response based on levels. Returns: slug, name, page_type, published, updated, fields. Required: query. - **list_all_butter_cms_contents** — Retrieve items from a ButterCMS Collection with filtering, pagination, and relationship serialization. Collection fields are user-defined in the dashboard and vary by collection. Returns: meta. Required: collection_key. - **create_a_butter_cms_content** — Create a new item in a ButterCMS Collection via the Write API. Field structure must match the collection schema configured in the dashboard. Processing is asynchronous (202 Accepted). Returns: status. Required: key, fields. - **update_a_butter_cms_content_by_id** — Fully update (PUT) a ButterCMS Collection item, replacing the item with the provided data. Use PUT when you need complete field synchronization; processing is asynchronous (202 Accepted). Returns: status. Required: id, collection_key, fields. - **delete_a_butter_cms_content_by_id** — Soft-delete a ButterCMS Collection item by id, marking it deleted while preserving data for potential recovery. The item no longer appears in collection listings or standard API responses. Returns an empty 204 response on success. Required: id, collection_key. - **butter_cms_contents_partial_update** — Partially update (PATCH) a ButterCMS Collection item, modifying only the specified fields while preserving all other content. Processing is asynchronous (202 Accepted). Returns: status. Required: id, collection_key. - **list_all_butter_cms_posts** — Retrieve a paginated list of published ButterCMS blog posts sorted by publication date (newest first). Use exclude_body to reduce payload size on listing pages; filter by author_slug, category_slug, or tag_slug. Returns: url, id, _id. - **create_a_butter_cms_post** — Create a new ButterCMS blog post via the Write API with support for author assignment, categories, tags, and media integration. Posts default to draft; processing is asynchronous (202 Accepted). Scheduling is not supported on create. Returns: status, example. Required: title. - **update_a_butter_cms_post_by_id** — Partially update an existing ButterCMS blog post by id, modifying only the provided fields while preserving omitted ones. Use locale to update or create a specific locale variant. Scheduling parameters may be ignored with warning fields in the response. Returns: status, example. Required: id. - **delete_a_butter_cms_post_by_id** — Soft-delete a ButterCMS blog post by id, removing it from public listings, search, and feeds while preserving content for potential recovery. Use locale to target a specific locale variant. Returns an empty 204 response on success. Required: id. - **get_single_butter_cms_post_by_id** — Retrieve a specific ButterCMS blog post by slug (id), including content regardless of publication status (published, draft, or scheduled). Ideal for individual post pages and preview workflows. Returns: url, id, _id. Required: id. - **list_all_butter_cms_authors** — Retrieve all ButterCMS blog post authors with profile information. Pass include=recent_posts to enrich each author with recent posts; use locale to filter those posts. Returns: slug, first_name, last_name, email, bio, title, profile_image. - **get_single_butter_cms_author_by_id** — Retrieve a ButterCMS author by slug (id), including profile details and optional recent posts. Returns: slug, first_name, last_name, email, bio, title, profile_image. Required: id. - **list_all_butter_cms_categories** — Retrieve all ButterCMS blog post categories that contain published posts. Pass include=recent_posts to attach recent posts per category; use locale to filter those posts. Returns: name, slug, recent_posts. - **get_single_butter_cms_category_by_id** — Retrieve a ButterCMS blog post category by slug (id), optionally including recent posts. Returns: name, slug, recent_posts. Required: id. - **list_all_butter_cms_tags** — Retrieve all ButterCMS blog post tags that contain published posts. Pass include=recent_posts to attach recent posts per tag; use locale to filter those posts. Returns: name, slug, recent_posts. - **get_single_butter_cms_tag_by_id** — Retrieve a ButterCMS blog post tag by slug (id), optionally including recent posts. Returns: name, slug, recent_posts. Required: id. - **list_all_butter_cms_posts_searches** — Search ButterCMS blog posts with full-text search across titles and body content, ranked by relevance. An empty query returns no results; use exclude_body to omit the body field and reduce response size. Returns: url, id, _id. - **list_all_butter_cms_feeds_rses** — Generate a standards-compliant RSS 2.0 XML feed of ButterCMS blog posts for syndication and feed readers. Filter with category_slug, tag_slug, or locale. Returns the complete RSS 2.0 XML feed string. - **list_all_butter_cms_feeds_atoms** — Generate a standards-compliant Atom 1.0 XML feed of ButterCMS blog posts for syndication, with richer metadata than RSS. Filter with category_slug, tag_slug, or locale. Returns the complete Atom 1.0 XML feed string. - **list_all_butter_cms_feeds_sitemaps** — Generate a standards-compliant XML sitemap of ButterCMS blog posts for search engine discovery (sitemaps.org protocol). Filter with category_slug, tag_slug, or locale. Returns the complete XML sitemap string with loc and lastmod entries. ## How it works 1. **Link your customer's ButterCMS account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach ButterCMS.** The Proxy API is a 1-to-1 mapping of the ButterCMS API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Embed ButterCMS in marketing automation platforms** — Email and campaign SaaS tools can let users pull published blog posts, landing pages, and featured images directly from ButterCMS into newsletters and drip campaigns, eliminating manual copy-paste workflows. - **Power AI knowledge agents and site search** — RAG chatbots and enterprise search platforms can ingest clean, structured content from ButterCMS pages and posts on a schedule, producing higher-quality embeddings than web scraping and keeping answers current with the customer's published content. - **Automate localization pipelines** — Translation management systems can detect new ButterCMS pages and posts, translate them externally, and push localized variants back with the correct locale parameter — turning a manual CSV process into a two-way sync. - **Syndicate content to external channels** — Social media schedulers, partner portals, and content distribution tools can consume ButterCMS posts and RSS/Atom feeds to auto-publish content across channels the moment it goes live in the CMS. - **Enrich commerce and CDP experiences** — E-commerce platforms and customer data platforms can map product IDs or audience segments to ButterCMS content collections, letting marketers attach editorial copy, banners, or personalized variants without engineering involvement. ## What you can build - **Blog post importer with author and category enrichment** — List ButterCMS posts and hydrate each record with author, category, and tag metadata using the dedicated lookup endpoints for a fully structured content object. - **Two-way page and post sync** — Read pages and posts from ButterCMS, apply external edits or translations, and write updates back via create, update, or partial-update operations on pages, posts, and content collections. - **Content search widget** — Expose ButterCMS's page and post search endpoints inside your product so end users can query their own CMS content directly from your UI. - **RSS, Atom, and sitemap ingestion** — Consume the standards-compliant feed endpoints to power syndication, SEO monitoring, or feed-based content distribution features without parsing HTML. - **Collections-based structured data manager** — Use the contents endpoints to let end users manage reusable structured records like FAQs, testimonials, or product specs from inside your application. - **Bulk content migration and backfill** — Use the write endpoints for pages, posts, and contents to run programmatic imports from legacy systems, taking advantage of ButterCMS's asynchronous 202 Accepted processing for large jobs. ## FAQs ### How does authentication work for the ButterCMS integration? ButterCMS uses API key authentication. Truto handles the secure storage and injection of each end user's API key, so you don't have to build a credential vault or key rotation logic for the integration. ### Which ButterCMS resources can I read and write through Truto? You can read and write pages, posts, and content collections; read authors, categories, and tags; and read RSS, Atom, and sitemap feeds. Search endpoints are available for both pages and posts. ### Does the integration support ButterCMS's write API for bulk updates? Yes. Create, update, partial update (PATCH), and delete operations are supported on posts and content collections, and create/update are supported on pages. ButterCMS processes write operations asynchronously and returns 202 Accepted, which makes it suitable for bulk imports. ### How do we handle localization and multi-locale content? ButterCMS accepts a locale parameter on its content endpoints, so you can read and write locale-specific variants of pages and posts. This is what powers two-way sync workflows with translation management systems. ### How fresh is the data — is there webhook support? The integration is currently polling-based against ButterCMS's REST API. You can schedule sync jobs at whatever cadence your product needs to keep content current, and use the search endpoints to efficiently detect new or updated records. ### Can we filter posts by tag, category, or author? Yes. The list posts endpoint supports filtering by author slug, category slug, tag slug, and locale, so you can build features like tag-based newsletters or author-specific content feeds without pulling the full dataset.