---
title: "Create an item"
method: POST
path: "/cms/collections/{collectionId}/items"
tags: ["CMS items"]
---

# Create an item

`POST /cms/collections/{collectionId}/items`

## Request

- Base URL: `https://api.cactal.ai/v1`
- URL: `https://api.cactal.ai/v1/cms/collections/{collectionId}/items`
- Auth: HTTP bearer

Creates an item at the end of the collection’s manual order. Scalar values go in `data` keyed by field key and are validated against the field types — unknown keys are rejected, required fields must be present, `plain_text` and `markdown` are capped at 1,048,576 bytes (markdown must not contain raw HTML), `date` values are ISO 8601 with timezone, and `color` values are normalized to hex. Relationship and asset values go in the side maps: `references` (`reference`: an item id; `multi_reference`: an ordered array of up to 1,000 ids), `images` (`image`: an asset id or `{ assetId, altText }`; `gallery`: an ordered array of up to 25 of those), and `files` (`file`: an asset id or `{ assetId }`). `slug` is optional — it is derived from `data.title` or `data.name` when omitted. Set a non-future `publishedAt` to create an already-published item, or a future `publishAt` to schedule it; the two fields are mutually exclusive.

## Path parameters

- `collectionId` string, required

## Request body

- object
  - `slug` string
  - `publishedAt` unknown
  - `publishAt` unknown
  - `data` object
  - `references` object
  - `images` object
  - `files` object

## Response `200`

Identity of the created item. Read the full item back with the get-item endpoint.

- object
  - `id` string, required: Id of the created item.
  - `slug` string, required: Slug of the created item, derived from `data.title` or `data.name` when not provided.
  - `publishedAt` string, date-time, nullable, required: `null` when the item was created as a draft; the publish timestamp otherwise.
  - `publishAt` string, date-time, nullable, required: Future publication time when the item was created as scheduled; `null` otherwise.

## Other responses

- `400`: Validation failed. The response `message` names the first invalid field.
- `401`: Missing, invalid, expired, or revoked API key.
- `403`: The authenticated principal lacks the required capability.
- `404`: The resource does not exist or is outside the principal’s access scope.
- `409`: The request conflicts with the current state of the resource.
- `429`: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.

---

[API](https://skmtc.dev/cactal/apis/cactal-api.md) · [All operations](https://skmtc.dev/cactal/apis/cactal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cactal/apis/cactal-api/revisions/9cd0fb5eacdd?raw)