---
title: "Update a field"
method: PATCH
path: "/cms/fields/{fieldId}"
tags: ["CMS fields"]
---

# Update a field

`PATCH /cms/fields/{fieldId}`

## Request

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

Updates `displayName`, `description`, `required`, `isUnique`, `example`, and (for `option` fields only) `config`; `type` and `targetCollectionId` are immutable. Setting `required: true` is rejected until every active item has a valid value for the field. Setting `isUnique: true` enforces uniqueness on all future writes and fails with a conflict when existing values already collide; unique is not supported for `plain_text`, `markdown`, `multi_reference`, `image`, `gallery`, or `file` fields. Pass `key` to rename the field’s key: the key is atomically migrated in every stored item’s `data` in the same transaction (no values are lost), a conflict is returned when the new key is already used in the collection, and when the website has a published version the rename is validated against the published site’s content queries. Pass `position: "first"` or `"last"`, or `"before"` / `"after"` together with `anchorFieldId`, to move the field within the collection’s display order.

## Path parameters

- `fieldId` string, required

## Request body

- object
  - `displayName` string
  - `description` string, nullable
  - `required` boolean
  - `isUnique` boolean
  - `example` unknown
  - `config` object
    - `choices` object[], required
      - `id` string, required
      - `label` string, required
    - `multiple` boolean
  - `key` string: New key for the field — a rename. Omit to keep the current key. Atomically migrates the key in every stored item’s `data`, so no values are lost.
  - `position` 'before' | 'after' | 'first' | 'last': Moves the field within the collection’s display order. Omit to leave the order unchanged. `"before"` / `"after"` require `anchorFieldId`.
  - `anchorFieldId` string: Sibling field to move against when `position` is `"before"` or `"after"`.

## Response `200`

The updated 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)