CMS

Every website has a built-in headless CMS: collections define a schema of fields, and items hold the content your pages query.

The model

Primitive	What it is	Identity
Collection	A typed bucket of content, like a spreadsheet schema	Stable `slug` (e.g. `posts`) plus a mutable `displayName`
Field	One typed column of a collection	Stable `key` (the JSON key in item `data`) plus a mutable `displayName`
Item	One record in a collection	Stable `slug`, unique within the collection

Create a collection with POST /v1/cms/collections, add fields with POST /v1/cms/collections/{collectionId}/fields, then create items with POST /v1/cms/collections/{collectionId}/items. GET /v1/cms/collections returns each collection’s active item count. GET /v1/cms/schema returns the whole schema, including collections and fields, in one call. Slugs and keys are load-bearing: page code queries collections by slug and reads values by field key. Renames go through the normal update endpoints — slug on PATCH /v1/cms/collections/{collectionId}, key on PATCH /v1/cms/fields/{fieldId}, and slug on PATCH /v1/cms/items/{itemId} — and migrate stored data atomically.

Fields

A field has a type (immutable after create), required, and isUnique flags, an optional description, an optional example value (any JSON, a design-phase placeholder that reads back as null when unset), and a position you change by passing position (with anchorFieldId for before/after) to PATCH /v1/cms/fields/{fieldId}. Reference fields also declare an immutable targetCollectionId. To change a field’s type, create a new field, migrate the data, and delete the old one. isUnique is not available on plain_text, markdown, or the multi-valued and asset-backed types. Field keys match ^[a-z][a-z0-9_]{0,63}$. The keys id, slug, publishedAt, publishAt, createdAt, updatedAt, and position are reserved for item metadata.

Field types

All 14 field types, with write-time validation and exact limits:

Type	Value	Limits and semantics
`plain_text`	string	Unformatted text; maximum 1,048,576 bytes (1 MiB)
`markdown`	string	Markdown source; maximum 1,048,576 bytes; raw HTML is rejected
`number`	number	Integers and decimals
`boolean`	boolean	`true` or `false`
`date`	string	ISO 8601 datetime with timezone (`Z` or explicit offset)
`link`	string	Must parse as a URL
`email`	string	Must be a valid email address
`color`	string	Any concrete CSS color; stored normalized to hex
`option`	string or string[]	Stored as choice id(s); up to 1,000 choices per field; `multiple` config allows arrays
`reference`	item id	Single link to an item in the field’s target collection
`multi_reference`	item ids	Ordered links; maximum 1,000 per item
`image`	asset	One ready image asset from the same website; supports `altText`
`gallery`	assets	Ordered image assets; maximum 25 per item
`file`	asset	One ready file asset from the same website

Scalar values live in the item’s data object. Reference and asset values are stored relationally and written through dedicated request properties: references, images, and files on POST .../items and PATCH /v1/cms/items/{itemId}. Image writes accept an asset id, { "assetId": "...", "altText": "..." }, or null to clear. See Assets.

Items: drafts, scheduling, publishing, ordering

An item has one of three publication states:

Draft: publishedAt and publishAt are both null.
Scheduled: publishedAt is null and publishAt is a future timestamp. Cactal promotes the item shortly after that time, clears publishAt, and records the actual time in publishedAt.
Published: publishedAt is set and publishAt is null.

Call POST /v1/cms/items/{itemId}/set-published with { "published": true } to publish immediately, { "publishAt": "2026-08-10T15:00:00Z" } to schedule a draft, or { "published": false } to unpublish or cancel a schedule. Published items must be unpublished before scheduling because scheduled publication promotes the latest saved item rather than a frozen revision. Item data remains patchable in every state. DELETE /v1/cms/items/{itemId} soft-deletes: the item leaves all reads and backreference results, but POST /v1/cms/items/{itemId}/restore brings it back with its references intact. Items order by a position you change on PATCH /v1/cms/items/{itemId} using { "position": "first" | "last" | "before" | "after", "anchorItemId": "..." }.

Published websites render only items with publishedAt set. Draft, scheduled, unpublished-again, and soft-deleted items never appear on the live site. API reads include every state by default; filter with published=true or published=false on GET /v1/cms/collections/{collectionId}/items. Scheduled items match published=false until promotion.

References and hydration

Reference fields link items across collections. Reads return them by id at depth=0 (the default): a single reference is an item id string, a multi-reference is an array of ids. Pass depth up to 3 to hydrate referenced items in place, one level per unit.

curl "https://api.cactal.ai/v1/cms/items/find?itemId=9FbQ2xLwPz8kTn4rWv6Ma&depth=1" \
  -H "Authorization: Bearer $CACTAL_API_KEY"

{
  "id": "9FbQ2xLwPz8kTn4rWv6Ma",
  "slug": "hello-world",
  "publishedAt": "2026-07-01T08:00:00.000Z",
  "publishAt": null,
  "data": {
    "title": "Hello world",
    "author": { "id": "aQ7pXk2LmC9sVe5tYb1Rn", "slug": "jane", "data": { "name": "Jane Doe" } },
    "tags": ["tRz4Nc8KvB2mXq6PdY3Ws"]
  }
}

A hydrated reference to a missing or soft-deleted item reads as null (single) or is omitted from the array (multi). GET /v1/cms/items/{itemId}/backreferences returns the active items that point at an item. It uses the standard { items, nextCursor } envelope; follow every cursor before deleting content that other items link to. Deleting a collection is refused with 409 while reference fields in other collections target it; the error lists the blocking fields. Reads never break on schema drift: unknown keys are stripped and missing values read as null.

Schema changes are gated by the published site. Collection and field mutations run the published version’s framework validation against the candidate schema; a change that would break the live site — for example deleting a field a published page queries — is rejected with a validation error. Update the source, publish, then change the schema.

Querying items

GET /v1/cms/collections/{collectionId}/items supports cursor/limit pagination plus:

Parameter	Shape	Example
`filter`	JSON map of `{ field: { op: value } }`	`filter={"views":{"gt":10},"author":{"eq":"aQ7p..."}}`
`filterLogic`	`and` (default) or `or`	`filterLogic=or`
`search`	string, or JSON `{ "query": "...", "fields": [...] }`	`search=pricing`
`sort`	JSON `{ "kind": "field" \| "meta", "field": "...", "direction": "asc" \| "desc" }`	`sort={"kind":"meta","field":"publishedAt","direction":"desc"}`
`published`	`true` or `false`	`published=true`
`depth`	`0`–`3`	`depth=1`

Field operators: eq, neq, in, nin, exists on all types; gt/gte/lt/lte on number and date; contains, startsWith, endsWith on text-like types. Reference fields also accept slug for one-level equality matching, such as {"author":{"slug":"jane"}}. Metadata keys accept a narrower set: id and slug take eq, in, and startsWith; publishedAt and publishAt take exists, gt, gte, lt, and lte; createdAt and updatedAt take gt, gte, lt, and lte. Any other operator on a metadata key returns 400. GET /v1/cms/items/find fetches one item by itemId, or by collectionId plus slug.

Limits

Limit	Value
Collections per website	100
Fields per collection	100
Items per collection	Unlimited
Collection slug	`^[a-z][a-z0-9-]{0,63}$`, unique per website
Field key	`^[a-z][a-z0-9_]{0,63}$`, unique per collection
Item slug	`^[a-z0-9][a-z0-9-]{0,255}$`, unique per collection
`displayName`	1–200 characters
List page size	default `20`, maximum `100`
Hydration depth	maximum `3`

Get started

Core concepts

Guides

Build with agents

Platform

The model

Fields

Field types

Items: drafts, scheduling, publishing, ordering

References and hydration

Querying items

Limits

Next steps

Manage CMS content

Assets

​The model

​Fields

​Field types

​Items: drafts, scheduling, publishing, ordering

​References and hydration

​Querying items

​Limits

​Next steps

Manage CMS content

Assets

The model

Fields

Field types

Items: drafts, scheduling, publishing, ordering

References and hydration

Querying items

Limits

Next steps