> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Collection Item

> Create a new item within a Collection via the Write API with support for locales and media uploads.

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.

**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.

**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.

**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.

**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.
See also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices.


## OpenAPI

````yaml /api/openapi/write_api.yaml post /content/
openapi: 3.1.0
info:
  title: ButterCMS Write API
  version: 2.0.0
  description: >
    Write endpoints for the ButterCMS API — create, update, and delete Pages,
    Collections, and Blog Posts.
  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
security:
  - writeTokenAuth: []
tags:
  - name: Pages
    description: >
      Create new pages using ButterCMS Write API. Programmatically create
      content to enable powerful use cases and scale your content faster.


      Note: For Pages, PUT behaves like PATCH (partial update). Use either
      method to perform partial updates.
  - name: Collections
    description: >
      Create, update, and delete Collection items using ButterCMS Write API.
      Collections are user-defined content structures with completely
      customizable field schemas.
  - name: Blog posts
    description: >
      Create, update, and delete blog posts using ButterCMS Write API. Blog
      posts support rich content including HTML body, categories, tags, featured
      images, and SEO metadata.
paths:
  /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.


        **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.


        **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.


        **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.


        **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.

        See also: Architecture & Performance for guidance on `levels`,
        pagination, and performance best practices.
      operationId: createCollectionItem
      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
                value:
                  key: products
                  status: draft
                  fields:
                    - name: Premium Widget
                      description: High-quality widget for professional use
                      main_image: https://cdn.example.com/products/widget-main.jpg
                      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**


            The collection item has passed initial validation and creation has
            been queued for asynchronous processing.


            **Important**: The item may not be immediately available in
            collection queries. Background processing includes:


            - Field validation against collection schema

            - Media download and upload to Butter Media Library

            - Reference field resolution

            - Search index updates


            If creation fails during background processing, contact support for
            assistance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCollectionItemResponse'
              example:
                status: pending
        '400':
          description: >
            **Bad Request - Validation Failed**


            The request failed initial validation. Common causes:


            - **Missing Required Fields**: `key` or `fields` not provided

            - **Invalid Status**: Status must be 'published' or 'draft'

            - **Invalid Collection Key**: Collection doesn't exist or access
            denied

            - **Field Validation**: Missing required fields or invalid field
            values

            - **Invalid Media URLs**: Remote URLs are not accessible or return
            404

            - **Locale Errors**: Invalid locale codes or mismatched locale
            format

            - **Organization Limits**: Collection item limit reached for
            subscription plan
          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 <script> tag in the SVG files.
        '401':
          $ref: '#/components/responses/UnauthorizedWriteResponse'
        '403':
          description: >
            **Forbidden - Insufficient Permissions or Subscription Limits**


            This error occurs when the provided token doesn't have write
            permissions or the collection item limit has been reached for your
            subscription plan.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - $ref: '#/components/schemas/LimitErrorResponse'
              examples:
                write_permission:
                  summary: Token lacks write permissions
                  value:
                    detail: Token does not have write permissions
                organization_limit:
                  summary: Collection item limit reached
                  value:
                    error: >-
                      Cannot create a new Collection Item. Collection Item Limit
                      Reached.
      security:
        - writeTokenAuth: []
components:
  schemas:
    CreateCollectionItemRequest:
      type: object
      required:
        - key
        - fields
      properties:
        key:
          type: string
          description: |
            The unique identifier/slug of the Collection to create an item in.

            Must match an existing collection in your organization.
          example: team_members
        status:
          type: string
          enum:
            - published
            - draft
          default: draft
          description: |
            Status of the collection item:

            - **draft**: Item is saved but not publicly available
            - **published**: Item is live and publicly accessible

            Defaults to "draft" if not specified.
          example: published
        fields:
          type: array
          description: >
            Array of collection item data. Structure varies based on locale
            configuration:


            - **Without Locales**: Array of objects with direct field key-value
            pairs

            - **With Locales**: Array of objects with locale codes as keys,
            containing field data


            **Dynamic Nature**: Field names and types are defined by your
            collection schema and can vary completely between collections.
          items:
            type: object
            description: >
              **Flexible collection item data - supports both single-locale and
              multi-locale formats.**


              System automatically detects the format based on the structure of
              the object:


              **Without Locales Format**: Direct field properties (e.g., `name`,
              `position`, `bio`)

              **With Locales Format**: Locale codes as keys (e.g., `en`, `es`,
              `fr`)


              **Dynamic Schema**: Field names and types are completely
              user-defined based on your collection configuration.
            additionalProperties: true
          minItems: 1
          example:
            - name: John Smith
              position: Senior Developer
              email: john@company.com
    CreateCollectionItemResponse:
      type: object
      description: Response for successful collection item creation (202 Accepted)
      properties:
        status:
          type: string
          enum:
            - pending
          description: >-
            Indicates that the collection item creation 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.
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message describing what went wrong
          example: Authentication credentials were not provided
    LimitErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message when subscription plan limits are exceeded
          example: Page creation limit is over
  responses:
    UnauthorizedWriteResponse:
      description: >
        **Unauthorized - Invalid or Missing Write API Token**


        No valid write API key provided. The API token you use for reading from
        the ButterCMS API

        will not allow you to create content. You need a different write-enabled
        token.

        Contact support@buttercms.com to get yours.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            detail: Authentication credentials were not provided
  securitySchemes:
    writeTokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >
        Write-enabled API token required for creating content.


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


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


        Example: `Authorization: Token abc123def456`


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

````