---
title: "Add a field to a collection"
method: POST
path: "/cms/collections/{collectionId}/fields"
tags: ["CMS fields"]
---

# Add a field to a collection

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

## Request

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

Adds a typed field at the end of the collection’s field order. `key` is lowercase snake_case (max 64 characters), must be unique in the collection, and cannot use the reserved metadata names `id`, `slug`, `publishedAt`, `publishAt`, `createdAt`, `updatedAt`, or `position`; `type` is immutable after creation. `reference` and `multi_reference` fields require a `targetCollectionId` in the same website, and `option` fields require `config.choices` (1–1,000 choices). A collection can hold at most 100 fields, and `required: true` is rejected while the collection has active items — add the field as optional, backfill every item, then mark it required.

## Path parameters

- `collectionId` string, required

## Request body

- object
  - `key` string, required
  - `displayName` string, required
  - `description` string, nullable
  - `type` 'plain_text' | 'markdown' | 'number' | 'boolean' | 'date' | 'link' | 'email' | 'color' | 'option' | 'reference' | 'multi_reference' | 'image' | 'gallery' | 'file', required
  - `required` boolean
  - `isUnique` boolean
  - `example` unknown
  - `targetCollectionId` string
  - `config` object
    - `choices` object[], required
      - `id` string, required
      - `label` string, required
    - `multiple` boolean

## Response `200`

The created field.

- object
  - `id` string, required: Unique field id.
  - `collectionId` string, required: Id of the owning collection.
  - `key` string, required: JSON key under item `data`. Lowercase snake_case, max 64 characters, unique per collection. Changed only via `key` on the update-field endpoint, which migrates stored data.
  - `displayName` string, required: Human-readable name, 1–200 characters.
  - `description` string, nullable, required: Optional description, up to 2,000 characters.
  - `type` 'plain_text' | 'markdown' | 'number' | 'boolean' | 'date' | 'link' | 'email' | 'color' | 'option' | 'reference' | 'multi_reference' | 'image' | 'gallery' | 'file', required: Value type. Immutable after creation.
  - `required` boolean, required: Whether every item must carry a non-null value for this field. Enforced on write.
  - `isUnique` boolean, required: Whether values must be unique across the collection’s active items. Not supported for `plain_text`, `markdown`, `multi_reference`, `image`, `gallery`, or `file` fields.
  - `position` string, required: Fractional ordering key; fields sort lexicographically by this value.
  - `example` unknown, required
  - `config` object, nullable, required: Type-specific configuration. Present for `option` fields only; `null` for all other types.
    - `choices` object[], required: Selectable choices, 1–1,000.
      - `id` string, required: Stable choice id stored as the field value.
      - `label` string, required: Human-readable choice label.
    - `multiple` boolean, required: Whether items may select multiple choices.
  - `targetCollectionId` string, nullable, required: For `reference` and `multi_reference` fields, the id of the collection referenced items must belong to (same website). `null` otherwise. Immutable.

## 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)