CMS fields

Update a field

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.

patch/cms/fields/{fieldId}

Request

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

Path parameters

fieldIdstring required

Request body

displayNamestring
descriptionstring nullable
requiredboolean
isUniqueboolean
exampleunknown
keystring

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.

anchorFieldIdstring

Sibling field to move against when position is "before" or "after".

Response

The updated field.

idstring required

Unique field id.

collectionIdstring required

Id of the owning collection.

keystring 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.

displayNamestring required

Human-readable name, 1–200 characters.

descriptionstring 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.

requiredboolean required

Whether every item must carry a non-null value for this field. Enforced on write.

isUniqueboolean 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.

positionstring required

Fractional ordering key; fields sort lexicographically by this value.

exampleunknown required
targetCollectionIdstring nullable required

For reference and multi_reference fields, the id of the collection referenced items must belong to (same website). null otherwise. Immutable.

Changes

No recorded changes to this operation across all 1 revision of this API.