{ "openapi": "3.1.0", "info": { "title": "ButterCMS API", "version": "2.0.0", "description": "This OpenAPI specification covers the complete ButterCMS API, including read and write operations for Pages, Blog Posts, Collections, and more.\n\n### New Documentation Version\nThis is a new version of our API documentation built with OpenAPI standards. If you encounter any issues, inaccuracies, or have suggestions for improvement, please report them to [support@buttercms.com](mailto:support@buttercms.com).\n## API Overview\nThe ButterCMS API is organized around REST principles with predictable, resource-oriented URLs and uses HTTP response codes to indicate API errors. JSON is returned by all API responses, including errors.\n\nOur API provides comprehensive content management capabilities through both read and write operations. Content is served through a global CDN with 150+ edge locations, ensuring fast delivery worldwide.\n---\nThe API supports creating, updating, and deleting items of three main content types:\n\n**Pages**: Fully customizable, reusable schemas that are supercharged with features like structured local and global components, form integrations, and repeaters. These can be individually fetched via a slug and are ideal for complex web content requiring flexible layouts and advanced functionality.\n\n**Collections**: Lighter-weight, customizable, reusable schemas for tables of data that are fetched via ID. Perfect for structured content like categories, team members, or product catalogs that primarily serve as reference data.\n\n**Blog Posts**: Built-in content type from our blog engine, which comes out-of-the-box with categorization, tagging, predefined SEO, and authors. Designed for chronological content with standardized blog functionality.\n---\nAuthentication is handled through an access token; read operations can use either header-based authentication or a query parameter (`auth_token`) while write operations require header-based authentication for enhanced security.\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": "Create, retrieve, and update pages using the ButterCMS API.\n\nNote: For Pages, PUT behaves like PATCH (partial update). Use either method to perform partial updates.\n" }, { "name": "Collections", "description": "Create, retrieve, update, and delete Collection items using the ButterCMS API. Collections are user-defined content structures with completely customizable field schemas.\n" }, { "name": "Blog posts", "description": "Create, retrieve, update, and delete blog posts using the ButterCMS API. Blog posts support rich content including HTML body, categories, tags, featured images, and SEO metadata.\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": "Page events", "description": "Webhook event notifications sent by ButterCMS when page content changes occur in your account.\n" }, { "name": "Post events", "description": "Webhook event notifications sent by ButterCMS when blog post changes occur in your account.\n" }, { "name": "Collection events", "description": "Webhook event notifications sent by ButterCMS when collection item changes occur in your account.\n" }, { "name": "Media events", "description": "Webhook event notifications sent by ButterCMS when media changes occur in your account.\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/": { "post": { "tags": [ "Pages" ], "summary": "Create Page via Write API", "description": "Create a new page using the ButterCMS Write API with support for multiple locales and automatic media uploads. This endpoint allows you to programmatically generate content that follows your predefined page type structure.\n\n**Page Type Requirement**: The page type schema must already exist in your ButterCMS account before creating pages. Page types define the structure and field requirements for your content. You cannot create new Page Types through the API - they must be configured through the dashboard first.\n\n**Field Requirements**: When creating a page, all field keys defined in your page type schema must be included in the request, even if they're marked as optional in your schema. For optional fields that you don't want to populate, provide empty strings (e.g., `\"hero_image\": \"\"`). This ensures your content structure remains consistent.\n\n**Locale Formats**: Define all page content inside of a single `fields` object for accounts that do not have localization set up. For accounts with localization, all page content for each individual language should be defined inside of an object whose key is the locale slug. Nest these objects inside of the `fields` object. The locale codes must match those configured in your account.\n\n**Media Upload**: If `Media` is the field_type for a chosen field, any URL can be provided as the field's value. The media corresponding to this URL will be automatically downloaded and uploaded to your ButterCMS media library. This ensures your media is hosted reliably and integrates with ButterCMS's CDN for optimal performance.\n\n**Media Alt Text**: A Media field also accepts an object `{\"url\": \"https://...\", \"alt\": \"Descriptive alt text\"}`. Alt text is optional, up to 255 characters, and is returned by the Read API when you pass `alt_media_text=1`. Sending a plain URL string replaces any existing alt text.\n\n**Publication & Scheduling**: Pages are created as `draft` by default. You can set `status=published` to publish immediately. Scheduling future publication is not supported via the Write API.\n", "x-mint": { "metadata": { "description": "Create a new page via the Write API with support for multiple locales, media uploads, and draft status." }, "content": "Create a new page using the ButterCMS Write API with support for multiple locales and automatic media uploads. This endpoint allows you to programmatically generate content that follows your predefined page type structure.\n\n**Page Type Requirement**: The page type schema must already exist in your ButterCMS account before creating pages. Page types define the structure and field requirements for your content. You cannot create new Page Types through the API - they must be configured through the dashboard first.\n\n**Field Requirements**: When creating a page, all field keys defined in your page type schema must be included in the request, even if they're marked as optional in your schema. For optional fields that you don't want to populate, provide empty strings (e.g., `\"hero_image\": \"\"`). This ensures your content structure remains consistent.\n\n**Locale Formats**: Define all page content inside of a single `fields` object for accounts that do not have localization set up. For accounts with localization, all page content for each individual language should be defined inside of an object whose key is the locale slug. Nest these objects inside of the `fields` object. The locale codes must match those configured in your account.\n\n**Media Upload**: If `Media` is the field_type for a chosen field, any URL can be provided as the field's value. The media corresponding to this URL will be automatically downloaded and uploaded to your ButterCMS media library. This ensures your media is hosted reliably and integrates with ButterCMS's CDN for optimal performance.\n\n**Media Alt Text**: A Media field also accepts an object `{\"url\": \"https://...\", \"alt\": \"Descriptive alt text\"}`. Alt text is optional, up to 255 characters, and is returned by the Read API when you pass `alt_media_text=1`. Sending a plain URL string replaces any existing alt text.\n\n**Publication & Scheduling**: Pages are created as `draft` by default. You can set `status=published` to publish immediately. Scheduling future publication is not supported via the Write API.\n" }, "operationId": "createPage", "security": [ { "writeTokenAuth": [] } ], "parameters": [ { "name": "locale", "in": "query", "description": "Set to the API slug of a pre-configured locale (e.g., 'en' or 'fr').\n\n**Usage:** Only applicable when using the single-locale request format (WITHOUT Locales format).\nIf you are using the single-locale format to create only a single locale's version of a page, you must specify the locale via this query param, e.g., `?locale=en`.\n\n**Not applicable** when using the multi-locale format (WITH Locales format), as locale codes are specified within the request body under the `fields` object.\n\nWhen omitted and using single-locale format, defaults to your organization's default locale.\n", "required": false, "schema": { "type": "string", "example": "en" }, "examples": { "english": { "value": "en", "description": "English locale" }, "spanish": { "value": "es", "description": "Spanish locale" }, "french": { "value": "fr", "description": "French locale" } } } ], "requestBody": { "required": true, "description": "Page data in either single-locale or multi-locale format.\n\n**Request Body Formats**:\n- **WITHOUT Locales or Single Locale**: If you don't have locales, or if you are only creating a single locale's version of a page, format your request body as a JSON object where `fields` is an object with each property representing a content field. Note: if creating only a single locale's version, you must specify the locale via query param, e.g., `?locale=en`.\n- **WITH Locales (Multi-Locale)**: The multi-locale format can be used to create one or more locales of a page at the same time. In this format, the `fields` object has an extra level and must be first mapped to the locale code. The locale codes must already be configured in your account; however, you can pick and choose which locales to create.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePageRequest" }, "examples": { "without_locales": { "summary": "Create Page WITHOUT Locales or with a Single Locale", "description": "Example of creating a page without locale support or for a single locale.\n\nIf you don't have locales, or if you are only creating a single locale's version of a page, you can format your request body into a JSON object where `fields` is an object in which each property represents a content field with its key and value.\n\nNote: If you are using this format to create only a single locale's version of a page, you must specify the locale via query param, e.g., `?locale=en`.\n", "value": { "title": "Frequently Asked Questions", "slug": "faq", "page_type": "questions", "status": "draft", "fields": { "headline": "Frequently Asked Questions", "hero_image": "", "body": "

We love questions

", "questions": [ { "question": "Are dogs allowed?", "answer": "Leashed dogs are allowed.", "picture": { "url": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg", "alt": "A leashed dog on a park trail" } }, { "question": "Are wallabies allowed?", "answer": "Yes, leashed wallabies are allowed", "picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg" } ] } } }, "with_locales": { "summary": "Create Page WITH Locales", "description": "Example of creating a page with multiple locales at the same time.\n\nThis is our multi-locale format, which can be used to create one or more locales of a page at the same time. In this format, the `fields` object has an extra level and must be first mapped to the locale code to use. The locale codes must already be configured in your account; however, you can pick and choose which locales to create.\n", "value": { "title": "Frequently Asked Questions", "slug": "faq", "page_type": "questions", "status": "draft", "fields": { "en": { "headline": "Frequently Asked Questions", "body": "

We love questions

", "questions": [ { "question": "Are dogs allowed?", "answer": "Leashed dogs are allowed.", "picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg" } ] }, "es": { "headline": "Preguntas frecuentes", "body": "

Nos encantan las preguntas

", "questions": [ { "question": "Se admiten perros?", "answer": "Se permiten perros con correa.", "picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg" } ] } } } } } } } }, "responses": { "202": { "description": "**Accepted - Page creation started successfully**\n\nThe request has been accepted for processing. Full page creation occurs asynchronously,\nmeaning the successfully created page may not show immediately. Pages are validated\nprior to returning this response, but it is possible that page creation may fail\nafter returning a `202` response. If this happens, please contact support.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "status": "pending" } } } }, "400": { "description": "**Bad Request - Validation Error**\n\nYour data did not pass the initial validation stage. This may happen if you are:\n- Missing a required field\n- Missing a field that's required in your page type\n- Providing a remote URL for a media field that returns a 404\n\nError explanations will be returned in a JSON array.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missing_page_type": { "summary": "Missing page type", "value": { "page_type": [ "You must specify a page type." ] } }, "invalid_page_type": { "summary": "Invalid page type", "value": { "page_type": [ "The write API cannot be used to create single pages." ] } }, "missing_title": { "summary": "Missing title", "value": { "title": [ "You must specify a page title." ] } }, "missing_slug": { "summary": "Missing slug", "value": { "slug": [ "You must specify a page slug." ] } }, "slug_already_exists": { "summary": "Slug already exists", "value": { "slug": [ "A page with slug 'faq' already exists." ] } }, "invalid_status": { "summary": "Invalid status", "value": { "status": [ "Valid status values are 'draft' and 'published'" ] } }, "scheduling_not_supported": { "summary": "Scheduling not supported", "value": { "scheduled": [ "Scheduling a page during page creation is not supported by the write API at this time." ] } }, "locale_validation_error": { "summary": "Locale validation error", "value": { "fields": [ "You must specify one or more locales from your account." ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedWriteResponse" }, "403": { "description": "**Forbidden - Page Creation Limit Exceeded**\n\nThe organization has exceeded its page creation limit. This can happen when you've reached\nthe maximum number of pages allowed for your plan.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitErrorResponse" }, "example": { "error": "Page creation limit is over" } } } } } } }, "/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": "#/paths/~1posts~1/get/parameters/2" }, { "$ref": "#/paths/~1posts~1/get/parameters/3" }, { "$ref": "#/components/parameters/locale" }, { "$ref": "#/paths/~1pages~1search~1/get/parameters/3" }, { "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)" } } }, { "$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": "#/paths/~1pages~1search~1/get/parameters/3" }, { "$ref": "#/paths/~1pages~1%7Bpage_type%7D~1/get/parameters/8" }, { "$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." } } } } } } } }, "patch": { "tags": [ "Pages" ], "summary": "Update Page via Write API", "description": "Update existing pages using PATCH requests with support for partial updates and multi-locale content. This endpoint provides flexible page modification capabilities while preserving unchanged content.\n\n**PUT Support**: PUT requests are supported for backwards compatibility. PATCH is the recommended method going forward. Both methods perform partial updates — only the fields you include in the request body will be modified.\n\n**Page Type Flexibility**: Use `*` to update pages across all page types when you know the slug but not the specific type, or specify the particular page type slug for optimized queries.\n\n**Partial Update Behavior**: Include only the fields you want to modify in your request body. All other fields will retain their current values, making this ideal for targeted content updates without affecting the entire page structure.\nNote: PUT behaves like PATCH (partial update) for Pages. Use either method to perform partial updates.\n\n**Locale Handling**: For single-locale updates, use the direct field format. For multi-locale organizations, nest your field changes under the appropriate locale codes. You can update specific locales without affecting others.\n\n**Status Control**: Control page visibility by setting `status` to \"draft\" (keeps the page unpublished) or \"published\" (makes changes live immediately). Draft status is useful for staging content changes.\n\n**Immutable Fields**: Page `title` and `slug` cannot be modified via PATCH requests to maintain URL consistency and prevent broken links. These core identifiers must remain stable after page creation.\n\n**Repeater Field Behavior**: When updating repeater fields, you must include the complete array contents in your request. Partial repeater updates are not supported - the entire repeater will be replaced with your provided data.\n\n**Scheduling Limitation**: Page scheduling is not available through the Write API. Any scheduled parameters in your request will be ignored, allowing you to safely update pages that are currently scheduled without affecting their publication timing.\n", "x-mint": { "metadata": { "description": "Update an existing page via PATCH request with support for locale handling and status control." }, "content": "Update existing pages using PATCH requests with support for partial updates and multi-locale content. This endpoint provides flexible page modification capabilities while preserving unchanged content.\n\n**PUT Support**: PUT requests are supported for backwards compatibility. PATCH is the recommended method going forward. Both methods perform partial updates — only the fields you include in the request body will be modified.\n\n**Page Type Flexibility**: Use `*` to update pages across all page types when you know the slug but not the specific type, or specify the particular page type slug for optimized queries.\n\n**Partial Update Behavior**: Include only the fields you want to modify in your request body. All other fields will retain their current values, making this ideal for targeted content updates without affecting the entire page structure.\nNote: PUT behaves like PATCH (partial update) for Pages. Use either method to perform partial updates.\n\n**Locale Handling**: For single-locale updates, use the direct field format. For multi-locale organizations, nest your field changes under the appropriate locale codes. You can update specific locales without affecting others.\n\n**Status Control**: Control page visibility by setting `status` to \"draft\" (keeps the page unpublished) or \"published\" (makes changes live immediately). Draft status is useful for staging content changes.\n\n**Immutable Fields**: Page `title` and `slug` cannot be modified via PATCH requests to maintain URL consistency and prevent broken links. These core identifiers must remain stable after page creation.\n\n**Repeater Field Behavior**: When updating repeater fields, you must include the complete array contents in your request. Partial repeater updates are not supported - the entire repeater will be replaced with your provided data.\n\n**Scheduling Limitation**: Page scheduling is not available through the Write API. Any scheduled parameters in your request will be ignored, allowing you to safely update pages that are currently scheduled without affecting their publication timing.\n" }, "operationId": "updatePage", "security": [ { "writeTokenAuth": [] } ], "parameters": [ { "name": "page_type", "in": "path", "description": "The type of page to update.\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": "Update page across all page types" }, "specific_type": { "value": "news", "description": "Update page within news page type only" } } }, { "name": "page_slug", "in": "path", "description": "The slug of the page to update.\n", "required": true, "schema": { "type": "string" }, "example": "faq" }, { "name": "locale", "in": "query", "description": "Set to the API slug of a pre-configured locale (e.g., 'en' or 'fr').\n\n**Usage:** Only applicable when using the single-locale request format (WITHOUT Locales format).\nIf you are using the single-locale format to update only a single locale's version of a page, you can specify the locale via this query param, e.g., `?locale=en`.\n\n**Not applicable** when using the multi-locale format (WITH Locales format), as locale codes are specified within the request body under the `fields` object.\n\nWhen omitted and using single-locale format, updates the organization's default locale.\n", "required": false, "schema": { "type": "string", "example": "en" }, "examples": { "english": { "value": "en", "description": "English locale" }, "spanish": { "value": "es", "description": "Spanish locale" }, "french": { "value": "fr", "description": "French locale" } } } ], "requestBody": { "required": true, "description": "Page update data in either single-locale or multi-locale format.\n\n**Partial Updates**: Unlike creating pages, you only need to specify the fields you want to update. You don't need to include all fields.\n\n**Format Flexibility**: The API accepts data wrapped in a top-level \"data\" key (Read API format). For example: `{\"data\": {\"status\": \"draft\", \"fields\": {...}}}` will be automatically unwrapped. You can use either `title` or `name` - both are accepted and `name` will be automatically converted to `title`.\n\n**Request Body Formats**:\n- **WITHOUT Locales or Single Locale**: One format mirrors the read API response and can be used for pages without locales or updating a single, specified locale.\n- **WITH Locales (Multi-Locale)**: The second format can be used for updating multiple locales at once. In this format, the `fields` object has an extra level and must be first mapped to the locale code to use.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePageRequest" }, "examples": { "without_locales": { "summary": "Update Page WITHOUT Locales or with a Single Locale", "description": "Example of updating a page without locale support or for a single locale.\n\nNote: You only need to specify the fields you want to update, not all fields.\n", "value": { "status": "draft", "fields": { "headline": "Frequently Asked Questions Updated", "questions": [ { "question": "Are dogs allowed?", "answer": "Leashed dogs are allowed.", "picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg" }, { "question": "Another dog question", "answer": "Another dog answer", "picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg" } ] } } }, "with_locales": { "summary": "Update Page WITH Locales", "description": "Example of updating a page with multiple locales at the same time.\n\nNote: You only need to specify the fields you want to update for each locale.\n", "value": { "status": "draft", "fields": { "en": { "headline": "Frequently Asked Questions Updated", "questions": [ { "question": "Are dogs allowed?", "answer": "Leashed dogs are allowed.", "picture": { "url": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg", "alt": "A leashed dog on a park trail" } }, { "question": "Another dog question", "answer": "Another dog answer", "picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg" } ] } } } } } } } }, "responses": { "202": { "description": "**Accepted - Page update started successfully**\n\nThe request has been accepted for processing. Full page update occurs asynchronously,\nmeaning the successfully updated page may not show changes immediately. Page updates are validated\nprior to returning this response, but it is possible that page update may fail\nafter returning a `202` response. If this happens, please contact support.\n\n**Warning Messages**: If you include fields that cannot be updated (like `scheduled` timestamp or `scheduled` status),\nthe API will return warning messages explaining which fields were ignored.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSuccessResponse" }, "examples": { "basic_success": { "summary": "Standard successful update", "value": { "status": "pending" } }, "success_with_warnings": { "summary": "Successful update with ignored fields", "value": { "status": "pending", "warning: scheduled field": "Scheduled timestamps cannot be created or altered via write API. This field will be ignored.", "warning: status field": "A page's status cannot be set as `scheduled` via write API at this time. This field will be ignored." } } } } } }, "400": { "description": "**Bad Request - Validation Error**\n\nYour data did not pass the initial validation stage. This may happen if you are:\n- Missing a required field for the specific page type\n- Providing a remote URL for a media field that returns a 404\n- Trying to update immutable fields (title, slug)\n- Providing invalid field values\n\nError explanations will be returned in a JSON array.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missing_required_field": { "summary": "Missing required field", "value": { "headline": [ "This field is required for this page type." ] } }, "invalid_status": { "summary": "Invalid status", "value": { "status": [ "Valid status values are 'draft' and 'published'" ] } }, "immutable_field_attempt": { "summary": "Attempted to update immutable field", "value": { "title": [ "Page title cannot be updated via PATCH." ] } }, "locale_validation_error": { "summary": "Locale validation error", "value": { "fields": [ "You must specify one or more locales from your account." ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedWriteResponse" }, "403": { "description": "**Forbidden - Permission Denied**\n\nYou don't have permission to update this page. This could be due to:\n- Page update limits exceeded\n- Insufficient permissions for the page type\n- Organization-level restrictions\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Permission denied" } } } }, "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" }, { "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)" } } }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/paths/~1posts~1/get/parameters/2" }, { "$ref": "#/paths/~1posts~1/get/parameters/3" }, { "$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/": { "post": { "tags": [ "Collections" ], "summary": "Create Collection Item", "description": "Create new items within a Collection using the Write API. Collections support completely dynamic schemas and multi-locale content, making them ideal for flexible content types like team members, products, or testimonials.\n\n**Dynamic Schema Flexibility**: Collection fields are entirely user-defined through your dashboard configuration. The field structure in your request must match the schema you've configured for the specific collection, including field types, validation rules, and any required fields.\n\n**Locale Structure**: For organizations without locales configured, provide field values directly in a flat structure. For multi-locale organizations, nest your field data under the appropriate locale codes (e.g., \"en\", \"es\") to create content in multiple languages simultaneously.\n\n**Media Integration**: If `Media` is the field_type for a chosen field, any URL can be provided as the field's value. The media corresponding to this URL will be automatically downloaded and uploaded to your ButterCMS media library, ensuring reliable hosting and CDN integration.\n\n**Media Alt Text**: A Media field also accepts an object `{\"url\": \"https://...\", \"alt\": \"Descriptive alt text\"}`. Alt text is optional, up to 255 characters, and is returned by the Read API when you pass `alt_media_text=1`. Sending a plain URL string replaces any existing alt text.\n\n**Asynchronous Processing**: This endpoint returns `202 Accepted` immediately to ensure fast response times for your application. The actual item creation, including media uploads, validation, and any configured webhooks, happens in the background processing queue.\nSee also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.\n", "x-mint": { "metadata": { "description": "Create a new item within a Collection via the Write API with support for locales and media uploads." }, "content": "Create new items within a Collection using the Write API. Collections support completely dynamic schemas and multi-locale content, making them ideal for flexible content types like team members, products, or testimonials.\n\n**Dynamic Schema Flexibility**: Collection fields are entirely user-defined through your dashboard configuration. The field structure in your request must match the schema you've configured for the specific collection, including field types, validation rules, and any required fields.\n\n**Locale Structure**: For organizations without locales configured, provide field values directly in a flat structure. For multi-locale organizations, nest your field data under the appropriate locale codes (e.g., \"en\", \"es\") to create content in multiple languages simultaneously.\n\n**Media Integration**: If `Media` is the field_type for a chosen field, any URL can be provided as the field's value. The media corresponding to this URL will be automatically downloaded and uploaded to your ButterCMS media library, ensuring reliable hosting and CDN integration.\n\n**Media Alt Text**: A Media field also accepts an object `{\"url\": \"https://...\", \"alt\": \"Descriptive alt text\"}`. Alt text is optional, up to 255 characters, and is returned by the Read API when you pass `alt_media_text=1`. Sending a plain URL string replaces any existing alt text.\n\n**Asynchronous Processing**: This endpoint returns `202 Accepted` immediately to ensure fast response times for your application. The actual item creation, including media uploads, validation, and any configured webhooks, happens in the background processing queue.\nSee also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.\n" }, "operationId": "createCollectionItem", "security": [ { "writeTokenAuth": [] } ], "requestBody": { "required": true, "description": "Collection item data with dynamic field structure based on collection configuration and locale settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCollectionItemRequest" }, "examples": { "without_locales": { "summary": "Create item without locales (single language)", "description": "Use this format when your organization has no locales configured", "value": { "key": "team_members", "status": "published", "fields": [ { "name": "John Doe", "position": "Software Engineer", "bio": "Experienced developer with expertise in web technologies", "profile_image": "https://example.com/images/john-doe.jpg", "years_experience": 5 } ] } }, "with_locales": { "summary": "Create item with locales (multi-language)", "description": "Use this format when your organization has locales configured (e.g., English and Spanish)", "value": { "key": "team_members", "status": "published", "fields": [ { "en": { "name": "John Doe", "position": "Software Engineer", "bio": "Experienced developer with expertise in web technologies", "profile_image": "https://example.com/images/john-doe.jpg", "years_experience": 5 }, "es": { "name": "John Doe", "position": "Ingeniero de Software", "bio": "Desarrollador experimentado con experiencia en tecnologías web", "profile_image": "https://example.com/images/john-doe.jpg", "years_experience": 5 } } ] } }, "media_upload_example": { "summary": "Create item with remote media URLs", "description": "Demonstrates automatic media upload from remote URLs, with optional alt text", "value": { "key": "products", "status": "draft", "fields": [ { "name": "Premium Widget", "description": "High-quality widget for professional use", "main_image": { "url": "https://cdn.example.com/products/widget-main.jpg", "alt": "Premium Widget on a white background" }, "gallery_images": [ "https://cdn.example.com/products/widget-1.jpg", "https://cdn.example.com/products/widget-2.jpg" ], "price": 99.99 } ] } } } } } }, "responses": { "202": { "description": "**Accepted - Collection Item Creation Queued**\n\nThe collection item has passed initial validation and creation has been queued for asynchronous processing.\n\n**Important**: The item may not be immediately available in collection queries. Background processing includes:\n\n- Field validation against collection schema\n- Media download and upload to Butter Media Library\n- Reference field resolution\n- Search index updates\n\nIf creation fails during background processing, contact support for assistance.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCollectionItemResponse" }, "example": { "status": "pending" } } } }, "400": { "description": "**Bad Request - Validation Failed**\n\nThe request failed initial validation. Common causes:\n\n- **Missing Required Fields**: `key` or `fields` not provided\n- **Invalid Status**: Status must be 'published' or 'draft'\n- **Invalid Collection Key**: Collection doesn't exist or access denied\n- **Field Validation**: Missing required fields or invalid field values\n- **Invalid Media URLs**: Remote URLs are not accessible or return 404\n- **Locale Errors**: Invalid locale codes or mismatched locale format\n- **Organization Limits**: Collection item limit reached for subscription plan\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missing_fields": { "summary": "Missing required fields", "value": { "key": [ "Missing parameter" ], "fields": [ "Missing parameter" ] } }, "invalid_status": { "summary": "Invalid status value", "value": { "status": [ "Valid status values are 'draft' and 'published'" ] } }, "invalid_media_url": { "summary": "Invalid remote media URL", "value": { "fields": [ "Remote URL for media field is not a valid URL" ] } }, "unsupported_media_type": { "summary": "Unsupported media file type", "value": { "fields": [ "We don't support 'text/plain' files, please contact us about possible support." ] } }, "video_enterprise_required": { "summary": "Video uploads require enterprise plan", "value": { "fields": [ "Video upload is not allowed with your current plan. Please contact support." ] } }, "svg_security_error": { "summary": "SVG security validation failed", "value": { "fields": [ "We don't allow