Cactal CMS fields API
Manage the typed fields that make up a collection schema.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/cactal-ai:cactal-ai-cms-fields-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Cactal Ai CMS fields API
version: 1.0.0
description: 'Operations tagged CMS fields across 2 of this provider''s published API definitions: openapi.json, cactal-ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.cactal.ai/v1
security:
- apiKey: []
tags:
- name: CMS fields
description: Manage the typed fields that make up a collection schema.
paths:
/cms/collections/{collectionId}/fields:
post:
operationId: cms.fields.create
summary: Add a field to a collection
description: '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.'
tags:
- CMS fields
parameters:
- name: collectionId
in: path
required: true
schema:
type: string
minLength: 1
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
key:
type: string
pattern: ^[a-z][a-z0-9_]{0,63}$
displayName:
type: string
minLength: 1
maxLength: 200
description:
anyOf:
- type: string
maxLength: 2000
- type: 'null'
type:
type: string
enum:
- plain_text
- markdown
- number
- boolean
- date
- link
- email
- color
- option
- reference
- multi_reference
- image
- gallery
- file
required:
type: boolean
isUnique:
type: boolean
example: {}
targetCollectionId:
type: string
minLength: 1
config:
type: object
properties:
choices:
minItems: 1
maxItems: 1000
type: array
items:
type: object
properties:
id:
type: string
minLength: 1
maxLength: 100
label:
type: string
minLength: 1
maxLength: 200
required:
- id
- label
multiple:
type: boolean
required:
- choices
required:
- key
- displayName
- type
responses:
'200':
description: The created field.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Unique field id.
collectionId:
type: string
description: Id of the owning collection.
key:
type: string
description: 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:
type: string
description: Human-readable name, 1–200 characters.
description:
description: Optional description, up to 2,000 characters.
type:
- string
- 'null'
type:
type: string
enum:
- plain_text
- markdown
- number
- boolean
- date
- link
- email
- color
- option
- reference
- multi_reference
- image
- gallery
- file
description: Value type. Immutable after creation.
required:
type: boolean
description: Whether every item must carry a non-null value for this field. Enforced on write.
isUnique:
type: boolean
description: 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:
type: string
description: Fractional ordering key; fields sort lexicographically by this value.
example:
description: Optional example value used as a design-phase placeholder. Any JSON value; `null` when unset.
config:
anyOf:
- type: object
properties:
choices:
type: array
items:
type: object
properties:
id:
type: string
description: Stable choice id stored as the field value.
label:
type: string
description: Human-readable choice label.
required:
- id
- label
additionalProperties: false
description: Selectable choices, 1–1,000.
multiple:
type: boolean
description: Whether items may select multiple choices.
required:
- choices
- multiple
additionalProperties: false
- type: 'null'
description: Type-specific configuration. Present for `option` fields only; `null` for all other types.
targetCollectionId:
description: For `reference` and `multi_reference` fields, the id of the collection referenced items must belong to (same website). `null` otherwise. Immutable.
type:
- string
- 'null'
required:
- id
- collectionId
- key
- displayName
- description
- type
- required
- isUnique
- position
- example
- config
- targetCollectionId
additionalProperties: false
'400':
description: Validation failed. The response `message` names the first invalid field.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'401':
description: Missing, invalid, expired, or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'403':
description: The authenticated principal lacks the required capability.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'404':
description: The resource does not exist or is outside the principal’s access scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'409':
description: The request conflicts with the current state of the resource.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'429':
description: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
x-cactal-required-capability: cms.fields.create
x-cactal-read-only: false
x-cactal-destructive: false
x-cactal-idempotent: false
servers:
- url: https://api.cactal.ai/v1
/cms/fields/{fieldId}:
patch:
operationId: cms.fields.update
summary: Update a field
description: '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.'
tags:
- CMS fields
parameters:
- name: fieldId
in: path
required: true
schema:
type: string
minLength: 1
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
displayName:
type: string
minLength: 1
maxLength: 200
description:
anyOf:
- type: string
maxLength: 2000
- type: 'null'
required:
type: boolean
isUnique:
type: boolean
example: {}
config:
type: object
properties:
choices:
minItems: 1
maxItems: 1000
type: array
items:
type: object
properties:
id:
type: string
minLength: 1
maxLength: 100
label:
type: string
minLength: 1
maxLength: 200
required:
- id
- label
multiple:
type: boolean
required:
- choices
key:
description: 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.
type: string
pattern: ^[a-z][a-z0-9_]{0,63}$
position:
description: Moves the field within the collection’s display order. Omit to leave the order unchanged. `"before"` / `"after"` require `anchorFieldId`.
type: string
enum:
- before
- after
- first
- last
anchorFieldId:
description: Sibling field to move against when `position` is `"before"` or `"after"`.
type: string
minLength: 1
responses:
'200':
description: The updated field.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Unique field id.
collectionId:
type: string
description: Id of the owning collection.
key:
type: string
description: 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:
type: string
description: Human-readable name, 1–200 characters.
description:
description: Optional description, up to 2,000 characters.
type:
- string
- 'null'
type:
type: string
enum:
- plain_text
- markdown
- number
- boolean
- date
- link
- email
- color
- option
- reference
- multi_reference
- image
- gallery
- file
description: Value type. Immutable after creation.
required:
type: boolean
description: Whether every item must carry a non-null value for this field. Enforced on write.
isUnique:
type: boolean
description: 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:
type: string
description: Fractional ordering key; fields sort lexicographically by this value.
example:
description: Optional example value used as a design-phase placeholder. Any JSON value; `null` when unset.
config:
anyOf:
- type: object
properties:
choices:
type: array
items:
type: object
properties:
id:
type: string
description: Stable choice id stored as the field value.
label:
type: string
description: Human-readable choice label.
required:
- id
- label
additionalProperties: false
description: Selectable choices, 1–1,000.
multiple:
type: boolean
description: Whether items may select multiple choices.
required:
- choices
- multiple
additionalProperties: false
- type: 'null'
description: Type-specific configuration. Present for `option` fields only; `null` for all other types.
targetCollectionId:
description: For `reference` and `multi_reference` fields, the id of the collection referenced items must belong to (same website). `null` otherwise. Immutable.
type:
- string
- 'null'
required:
- id
- collectionId
- key
- displayName
- description
- type
- required
- isUnique
- position
- example
- config
- targetCollectionId
additionalProperties: false
'400':
description: Validation failed. The response `message` names the first invalid field.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'401':
description: Missing, invalid, expired, or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'403':
description: The authenticated principal lacks the required capability.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'404':
description: The resource does not exist or is outside the principal’s access scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'409':
description: The request conflicts with the current state of the resource.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'429':
description: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
x-cactal-required-capability: cms.fields.update
x-cactal-read-only: false
x-cactal-destructive: true
x-cactal-idempotent: false
delete:
operationId: cms.fields.delete
summary: Delete a field
description: 'Permanently deletes the field and its stored values: the key is stripped from every item’s `data`, and reference or asset attachments made through the field are removed. This cannot be undone. If the website has a published version, the deletion is validated against the published site’s content queries and rejected when the site still depends on the field.'
tags:
- CMS fields
parameters:
- name: fieldId
in: path
required: true
schema:
type: string
minLength: 1
responses:
'200':
description: Deletion acknowledgement.
content:
application/json:
schema:
type: object
properties:
deleted:
type: boolean
const: true
description: Always `true` once the field and its stored values are removed.
required:
- deleted
additionalProperties: false
'400':
description: Validation failed. The response `message` names the first invalid field.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'401':
description: Missing, invalid, expired, or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'403':
description: The authenticated principal lacks the required capability.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'404':
description: The resource does not exist or is outside the principal’s access scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
'429':
description: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
x-cactal-required-capability: cms.fields.delete
x-cactal-read-only: false
x-cactal-destructive: true
x-cactal-idempotent: false
servers:
- url: https://api.cactal.ai/v1
components:
schemas:
ServiceError:
type: object
required:
- kind
- message
description: Canonical error body returned by every non-2xx response. Extra fields carry error-specific details.
properties:
kind:
type: string
enum:
- validation
- unauthorized
- forbidden
- not_found
- conflict
- rate_limited
- internal
description: Stable, machine-readable error category.
message:
type: string
description: Human-readable explanation of the failure.
suggestion:
type: string
description: What to do next when the failure has a known fix; may name the exact operation to call.
validValues:
type: array
items:
type: string
description: The acceptable values for the failing field, when the set is closed.
additionalProperties: true
securitySchemes:
apiKey:
type: http
scheme: bearer
description: Cactal API key. Create one in the dashboard or via `POST /apiKeys`. The plaintext key is shown once at creation.
x-refined-from:
- openapi.json
- cactal-ai-openapi.json