CMS fields

Add a field to a collection

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.

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

Path parameters

collectionIdstring required

Request body

keystring required
displayNamestring required
descriptionstring nullable
type'plain_text' | 'markdown' | 'number' | 'boolean' | 'date' | 'link' | 'email' | 'color' | 'option' | 'reference' | 'multi_reference' | 'image' | 'gallery' | 'file' required
requiredboolean
isUniqueboolean
exampleunknown
targetCollectionIdstring

Response

The created 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.