Skip to content
WhiteBeard

Register one variant

PUT
/cms/pagebuilder/variants/{blockType}/{key}

Creates or updates a single variant. The body is one manifest entry; key is taken from the path. Same rules and report as PUT /cms/pagebuilder/variants.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
blockType
required
string
Example
content_list
key
required
string
Example
lead_grid

Query Parameters

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

Validate and report without writing

Request Bodyrequired

Section titled “Request Bodyrequired”
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"
    }
  ]
}

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 entry; 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\""
    }
  ]
}