Add a field to a collection

curl --request POST \
  --url https://api.cactal.ai/v1/cms/collections/{collectionId}/fields \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "key": "<string>",
  "displayName": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({key: '<string>', displayName: '<string>'})
};

fetch('https://api.cactal.ai/v1/cms/collections/{collectionId}/fields', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.cactal.ai/v1/cms/collections/{collectionId}/fields"

payload = {
    "key": "<string>",
    "displayName": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "<string>",
  "collectionId": "<string>",
  "key": "<string>",
  "displayName": "<string>",
  "description": "<string>",
  "type": "plain_text",
  "required": true,
  "isUnique": true,
  "position": "<string>",
  "example": "<unknown>",
  "config": {
    "choices": [
      {
        "id": "<string>",
        "label": "<string>"
      }
    ],
    "multiple": true
  },
  "targetCollectionId": "<string>"
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

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

Add a field to a collection

curl --request POST \
  --url https://api.cactal.ai/v1/cms/collections/{collectionId}/fields \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "key": "<string>",
  "displayName": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({key: '<string>', displayName: '<string>'})
};

fetch('https://api.cactal.ai/v1/cms/collections/{collectionId}/fields', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.cactal.ai/v1/cms/collections/{collectionId}/fields"

payload = {
    "key": "<string>",
    "displayName": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "<string>",
  "collectionId": "<string>",
  "key": "<string>",
  "displayName": "<string>",
  "description": "<string>",
  "type": "plain_text",
  "required": true,
  "isUnique": true,
  "position": "<string>",
  "example": "<unknown>",
  "config": {
    "choices": [
      {
        "id": "<string>",
        "label": "<string>"
      }
    ],
    "multiple": true
  },
  "targetCollectionId": "<string>"
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

{
  "kind": "validation",
  "message": "<string>",
  "suggestion": "<string>",
  "validValues": [
    "<string>"
  ]
}

Authorizations

Authorization

string

header

required

Cactal API key. Create one in the dashboard or via POST /apiKeys. The plaintext key is shown once at creation.

Path Parameters

collectionId

string

required

Minimum string length: 1

Body

application/json

key

string

required

Pattern: ^[a-z][a-z0-9_]{0,63}$

displayName

string

required

Required string length: 1 - 200

type

enum<string>

required

Available options:

plain_text,

markdown,

number,

boolean,

date,

link,

email,

color,

option,

reference,

multi_reference,

image,

gallery,

file

description

string | null

Maximum string length: 2000

required

boolean

isUnique

boolean

example

any

targetCollectionId

string

Minimum string length: 1

config

object

Show child attributes

Response

The created field.

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 | null

required

Optional description, up to 2,000 characters.

type

enum<string>

required

Value type. Immutable after creation.

Available options:

plain_text,

markdown,

number,

boolean,

date,

link,

email,

color,

option,

reference,

multi_reference,

image,

gallery,

file

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

any

required

Optional example value used as a design-phase placeholder. Any JSON value; null when unset.

config

object | null

required

Type-specific configuration. Present for option fields only; null for all other types.

Show child attributes

targetCollectionId

string | null

required

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

Getting started

Documentation

Feedback

Websites

Website editors

API keys

Source code

Publishing

CMS collections

CMS fields

CMS items

Domains

Assets

Project context

Analytics

Organizations

Audit log

Billing

Add a field to a collection

Authorizations

Path Parameters

Body

Response