{"openapi":"3.1.0","info":{"title":"Butter CMS (BYOK) API","version":"0.1.0","description":"Butter CMS (BYOK) lets an AI assistant read your own Butter CMS data through the Butter CMS API with a key you supply (ButterCMS read API token). Read-only: 10 tools (list_posts, get_post, search_posts, list_pages, get_page, search_pages, get_collection, list_authors, list_categories, list_tags). The BYOK key travels with each request, is used for that one call only and is never stored, logged or...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-buttercms.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-buttercms/docs"},"termsOfService":"https://connectorbay.com/byok-buttercms/terms"},"servers":[{"url":"https://byok-buttercms.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-buttercms/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_posts":{"post":{"operationId":"list_posts","summary":"List blog posts with title, slug, summary, status, dates, author, categories and tags. Body is left out by default. Filt","description":"List blog posts with title, slug, summary, status, dates, author, categories and tags. Body is left out by default. Filter by author, category or tag slug. Use for \"What are the latest published blog posts in ButterCMS\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"author_slug":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only posts by this author slug.","title":"Author Slug"},"category_slug":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only posts in this category slug.","title":"Category Slug"},"tag_slug":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only posts with this tag slug.","title":"Tag Slug"},"locale":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Locale API slug such as en or fr; the organization's default locale when omitted.","title":"Locale"},"exclude_body":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to leave out the full post body (smaller answers).","title":"Exclude Body"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page (1 to 100).","title":"Page Size"}},"title":"list_postsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_post":{"post":{"operationId":"get_post","summary":"Get one blog post by slug, including its full body, author, categories, tags and SEO fields. Use for \"Show the ButterCMS","description":"Get one blog post by slug, including its full body, author, categories, tags and SEO fields. Use for \"Show the ButterCMS post with slug hello-world\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Post slug, for example hello-world.","maxLength":200,"title":"Slug","type":"string"},"locale":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Locale API slug such as en or fr; the organization's default locale when omitted.","title":"Locale"}},"required":["slug"],"title":"get_postArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_posts":{"post":{"operationId":"search_posts","summary":"Search blog posts by title and body text; returns the same summary fields as the post list. Use for \"Search my ButterCMS","description":"Search blog posts by title and body text; returns the same summary fields as the post list. Use for \"Search my ButterCMS posts for 'pricing'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Search text (up to 100 characters).","maxLength":100,"title":"Query","type":"string"},"locale":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Locale API slug such as en or fr; the organization's default locale when omitted.","title":"Locale"},"exclude_body":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to leave out the full post body (smaller answers).","title":"Exclude Body"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page (1 to 100).","title":"Page Size"}},"required":["query"],"title":"search_postsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_pages":{"post":{"operationId":"list_pages","summary":"List pages of one page type (or Single Pages with *) with slug, name, dates and content fields. Use for \"List the landin","description":"List pages of one page type (or Single Pages with *) with slug, name, dates and content fields. Use for \"List the landing pages in ButterCMS\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_type":{"description":"Page type slug, or * for Single Pages (pages without a type).","maxLength":200,"title":"Page Type","type":"string"},"order":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Order by published, updated or a content field; prefix with - for descending.","title":"Order"},"locale":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Locale API slug such as en or fr; the organization's default locale when omitted.","title":"Locale"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page (1 to 100).","title":"Page Size"}},"required":["page_type"],"title":"list_pagesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_page":{"post":{"operationId":"get_page","summary":"Get one page by page type and slug with its content fields. Use * as the type to search all page types. Use for \"Show th","description":"Get one page by page type and slug with its content fields. Use * as the type to search all page types. Use for \"Show the ButterCMS page 'example-news-page'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_type":{"description":"Page type slug, or * to search all types.","maxLength":200,"title":"Page Type","type":"string"},"page_slug":{"description":"Page slug.","maxLength":200,"title":"Page Slug","type":"string"},"locale":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Locale API slug such as en or fr; the organization's default locale when omitted.","title":"Locale"}},"required":["page_type","page_slug"],"title":"get_pageArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_pages":{"post":{"operationId":"search_pages","summary":"Search page content for text, optionally within one page type. Use for \"Find ButterCMS pages that mention 'warranty'\".","description":"Search page content for text, optionally within one page type. Use for \"Find ButterCMS pages that mention 'warranty'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Search text (up to 100 characters).","maxLength":100,"title":"Query","type":"string"},"page_type":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Limit to this page type slug (* for Single Pages).","title":"Page Type"},"locale":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Locale API slug such as en or fr; the organization's default locale when omitted.","title":"Locale"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page (1 to 100).","title":"Page Size"}},"required":["query"],"title":"search_pagesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_collection":{"post":{"operationId":"get_collection","summary":"Get the items of one Collection (custom structured content) by its key, paged. Use for \"Show the 'artists' collection fr","description":"Get the items of one Collection (custom structured content) by its key, paged. Use for \"Show the 'artists' collection from ButterCMS\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"collection_key":{"description":"Collection key (slug), for example artists.","maxLength":200,"title":"Collection Key","type":"string"},"order":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Order by a collection field; prefix with - for descending.","title":"Order"},"locale":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Locale API slug such as en or fr; the organization's default locale when omitted.","title":"Locale"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page (1 to 100).","title":"Page Size"}},"required":["collection_key"],"title":"get_collectionArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_authors":{"post":{"operationId":"list_authors","summary":"List blog authors with slug, name, title, bio and profile image. Email and social links are left out. Use for \"Who are t","description":"List blog authors with slug, name, title, bio and profile image. Email and social links are left out. Use for \"Who are the blog authors in ButterCMS\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_authorsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_categories":{"post":{"operationId":"list_categories","summary":"List blog categories with name and slug. Use for \"What blog categories exist in ButterCMS\".","description":"List blog categories with name and slug. Use for \"What blog categories exist in ButterCMS\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_categoriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tags":{"post":{"operationId":"list_tags","summary":"List blog tags with name and slug. Use for \"What blog tags exist in ButterCMS\".","description":"List blog tags with name and slug. Use for \"What blog tags exist in ButterCMS\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}