Skip to main content
POST
/
content
curl --request POST \
  --url https://api.buttercms.com/v2/content/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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
    }
  ]
}
'
{
  "status": "pending"
}
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.

Authorizations

​
Authorization
string
header
required

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.

Body

application/json

Collection item data with dynamic field structure based on collection configuration and locale settings.

​
key
string
required

The unique identifier/slug of the Collection to create an item in.

Must match an existing collection in your organization.

Example:

"team_members"

​
fields
object[]
required

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.

Minimum array length: 1
Example:
[
  {
    "name": "John Smith",
    "position": "Senior Developer",
    "email": "john@company.com"
  }
]
​
status
enum<string>
default:draft

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.

Available options:
published,
draft
Example:

"published"

Response

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.

Response for successful collection item creation (202 Accepted)

​
status
enum<string>

Indicates that the collection item creation is being processed asynchronously

Available options:
pending
Example:

"pending"