ButterCMS API (2.0.0)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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.

Perform a full update (PUT) of an existing Collection item, completely replacing the item with the provided data. This operation is ideal when you need to ensure all fields are synchronized with your source data or when making comprehensive changes.

Update Method: PUT replaces the entire item with your request data, similar to recreating the item from scratch. This differs from PATCH operations, which only update specific fields. Use PUT when you want to ensure complete data consistency or when your workflow involves regenerating entire items.

Important: The URL must include a trailing slash after the item ID (e.g., /v2/content/my-collection/123/). This is required for the endpoint to function correctly.

Item Identification: The unique item ID can be found in the meta field of any collection item when retrieved through GET requests. This identifier remains constant throughout the item's life cycle and is required for all update and delete operations.

Reference Field Updates: When updating reference fields, use page slugs for Page references and item IDs for Collection references. To remove existing references, provide empty strings (""), empty arrays ([]), or null values depending on the field type and whether it's a single or multi-reference field.

Asynchronous Processing: This endpoint returns 202 Accepted immediately to ensure fast response times. The actual update processing, including media uploads, reference resolution, validation, and webhook triggers, happens in the background processing queue.

Perform a partial update (PATCH) of an existing Collection item, updating only the fields you specify while preserving all other content. This method is ideal for targeted updates without affecting the entire item structure.

Update Method: PATCH updates only the fields included in your request body, leaving all other fields unchanged. This differs from PUT operations, which replace the entire item. Use PATCH when you want to modify specific fields while preserving existing content, relationships, and metadata.

Partial Update Intelligence: Reference fields, status, timestamps, and any omitted content fields automatically retain their current values. This allows you to safely update specific content without worrying about accidentally clearing other important data.

Important: The URL must include a trailing slash after the item ID (e.g., /v2/content/my-collection/123/). This is required for the endpoint to function correctly.

Item Identification: The unique item ID can be found in the meta field of any collection item when retrieved through GET requests. This identifier remains constant throughout the item's life cycle.

Reference Field Handling: When updating reference fields, use page slugs for Page references and item IDs for Collection references. If you omit reference fields from your request, existing references remain completely unchanged, making it safe to update other content without affecting relationships.

Asynchronous Processing: This endpoint returns 202 Accepted immediately to ensure fast response times. The actual update processing, including media uploads, reference validation, and webhook triggers, happens in the background processing queue.

Delete an existing Collection item using a soft delete operation, which marks the item as deleted while preserving the data for potential recovery. This approach ensures data safety while removing items from public API responses.

Soft Delete Behavior: The item is marked as deleted in the system and will no longer appear in collection listings, search results, or standard API responses. However, the actual data is preserved in the database, allowing for potential recovery through support channels if needed.

Important: The URL must include a trailing slash after the item ID (e.g., /v2/content/my-collection/123/). This is required for the endpoint to function correctly.

Item Identification: The unique item ID can be found in the meta field of any collection item when retrieved through GET requests. This identifier is required to specify which item to delete.

Request Body: DELETE requests should not include any request body data - send an empty body or omit the body entirely. The item ID in the URL path is sufficient to identify the target item.

Asynchronous Processing: This endpoint returns 204 No Content immediately upon successful request validation. The actual deletion processing, including webhook notifications and reference cleanup, happens in the background processing queue.