Skip to content
WhiteBeard

Register variants from a manifest

PUT
/cms/pagebuilder/variants

Creates or updates the variants listed in a frontend’s pagebuilder-variants.json manifest. Entries with status: "disable" disable an existing variant, and status: "planned" entries are skipped. Variants not listed are left untouched; nothing is deleted. Validation is all-or-nothing: if any entry is invalid, the response is 422 and nothing is written. Use ?dry_run=1 to see what would change without writing. Thumbnails are uploaded separately (POST …/{blockType}/{key}/thumbnail). Requires an API key linked to a CMS user who can create and update Page Builder variants.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
dry_run
string
Allowed values: 1

Validate and report without writing

Request Bodyrequired

Section titled “Request Bodyrequired”
PageBuilderVariantManifest

A frontend’s pagebuilder-variants.json: variants grouped by block type. Other top-level fields (site, generatedAt, …) are ignored. In GET responses, entries also carry thumbnail (image URL or null) and usedBy (number of published layouts using the variant).

object
blocks
required

Block type → variants

object
key
additional properties
Array<object>
PageBuilderVariantEntry

A display variant a frontend implements. Unknown fields (e.g. component, note, thumbnail in a manifest) are ignored when importing.

object
key
required

Variant key, ^[a-z0-9_]{1,64}$. Never changes once registered.

string
Example
lead_grid
label

Name editors see (required unless status is “disable” or “planned”)

string
Example
Lead story + grid
description

When editors should use it

string
nullable
isDefault

Make this the block type’s default (fallback) variant. Only one per block type; must have breakpoints null.

boolean
status

implemented (create or update), disable (disable an existing variant), planned (skipped)

string
Allowed values: implemented disable planned
Example
implemented
allowedSources

Content_list only: source kinds this variant supports; null = all

Array<string>
nullable
Allowed values: section query mostread mostcommented external
breakpoints

Screen sizes the variant can be used on; null = all (must be null for the default variant)

Array<string>
nullable
Allowed values: lg md xs
limit

List blocks only: number of items the design shows well (whole numbers ≥ 1, min ≤ default ≤ max)

object
min
integer
default
integer
max
integer
options

Fields editors fill in per block; read by the frontend from variantOptions[key]

Array<object>
object
name
required

Label editors see

string
key

Option key, ^[A-Za-z0-9_-]+$ (generated from the name when omitted)

string
type
required
string
Allowed values: boolean text number list
values
One of:
string
multiple

List only: allow several values

boolean
default
One of:
string
Example
{
  "key": "lead_grid",
  "label": "Lead story + grid",
  "description": "One large lead story followed by a grid of smaller stories.",
  "isDefault": false,
  "status": "implemented",
  "allowedSources": [
    "section",
    "query"
  ],
  "breakpoints": null,
  "limit": {
    "min": 3,
    "default": 7,
    "max": 13
  },
  "options": [
    {
      "name": "Lead badge",
      "key": "leadBadge",
      "type": "text",
      "default": "TOP STORY"
    },
    {
      "name": "Show byline",
      "key": "showByline",
      "type": "boolean",
      "default": "true"
    }
  ]
}
Example
{
  "blocks": {
    "content_list": [
      {
        "key": "lead_grid",
        "label": "Lead story + grid",
        "limit": {
          "min": 3,
          "default": 7,
          "max": 13
        }
      }
    ],
    "ad_slot": [
      {
        "key": "default",
        "label": "Default",
        "isDefault": true
      }
    ]
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

Import report

PageBuilderVariantImportReport

What a variant import did (or would do, with dry_run). When ok is false nothing was written.

object
ok

False when any entry is invalid; nothing is written then

boolean
dryRun

True when called with dry_run=1 (nothing written)

boolean
applied

Number of database operations applied

integer
errors

All validation errors, prefixed with blockType.key

Array<string>
results

One result per manifest entry

Array<object>
object
blockType
string
key
string
action
string
Allowed values: created updated unchanged disabled skipped invalid
changed

Updated: the fields that changed

Array<string>
becomesDefault

This variant becomes the block type’s default

boolean
reason

Skipped: why

string
errors
Array<string>
warnings
Array<string>
Example
{
  "ok": true,
  "dryRun": false,
  "applied": 2,
  "errors": [],
  "results": [
    {
      "blockType": "content_list",
      "key": "lead_grid",
      "action": "created"
    },
    {
      "blockType": "content_list",
      "key": "thumb_list",
      "action": "updated",
      "changed": [
        "label",
        "optionsSchema"
      ]
    },
    {
      "blockType": "content_list",
      "key": "image_only",
      "action": "disabled"
    },
    {
      "blockType": "content_list",
      "key": "video_rail",
      "action": "skipped",
      "reason": "status is \"planned\""
    }
  ]
}

403

Section titled “403”

API key not linked to a CMS user with the required permission

422

Section titled “422”

Invalid manifest; nothing was written

PageBuilderVariantImportReport

What a variant import did (or would do, with dry_run). When ok is false nothing was written.

object
ok

False when any entry is invalid; nothing is written then

boolean
dryRun

True when called with dry_run=1 (nothing written)

boolean
applied

Number of database operations applied

integer
errors

All validation errors, prefixed with blockType.key

Array<string>
results

One result per manifest entry

Array<object>
object
blockType
string
key
string
action
string
Allowed values: created updated unchanged disabled skipped invalid
changed

Updated: the fields that changed

Array<string>
becomesDefault

This variant becomes the block type’s default

boolean
reason

Skipped: why

string
errors
Array<string>
warnings
Array<string>
Example
{
  "ok": true,
  "dryRun": false,
  "applied": 2,
  "errors": [],
  "results": [
    {
      "blockType": "content_list",
      "key": "lead_grid",
      "action": "created"
    },
    {
      "blockType": "content_list",
      "key": "thumb_list",
      "action": "updated",
      "changed": [
        "label",
        "optionsSchema"
      ]
    },
    {
      "blockType": "content_list",
      "key": "image_only",
      "action": "disabled"
    },
    {
      "blockType": "content_list",
      "key": "video_rail",
      "action": "skipped",
      "reason": "status is \"planned\""
    }
  ]
}