Blocks API

Block methods live at cms.api.<collection>.<method> and read or mutate the block tree of a single entry on a branch. The same methods are available on the client with identical types. Every commit-producing mutation returns commit: { id, message, createdAt, createdBy }, the new branch head.

Read a Block Tree

Load an entry's block tree for editing, at a branch head or a specific commit. You get back the nested tree with each block's typed properties, ready to render in your editor.

const data = await cms.api.pages.getBlockTree({
  query: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
  },
});

const { data, error } = await client.pages.getBlockTree({
  query: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
  },
});

The tree is a discriminated union over type, and the top node is type: 'root'. reconstructed is true when the commit was rebuilt from a partial snapshot. With includeReferencePreviews: true, references is a Record<storedReferenceValue, tree> holding the published render tree of every reference embedded in the entry, resolved through the active scope.

Resolve an Unsaved Tree

Run the same resolution getBlockTree applies to a stored tree — variables substituted, links resolved to their current href, references as a published-preview sidecar or inlined — on a tree you post. Nothing is written: this is how an editor previews its unsaved working copy (live canvas, HTML/PDF preview, e-mail send-preview). The tree is not validated against the schema; unknown block types and undeclared properties pass through untouched.

const data = await cms.api.pages.resolveTree({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    tree, // required: the (edited) tree, root node first
    includeReferencePreviews: true,
  },
});

const { data, error } = await client.pages.resolveTree({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    tree, // required: the (edited) tree, root node first
    includeReferencePreviews: true,
  },
});

resolveTree never persists anything and creates no commit; save with updateBlocks when you are done. Roots outside your scope (or of another collection) are rejected with ROOT_NOT_FOUND, exactly like getBlockTree.

Add a Block

Add a block as a child of a parent block. The body is a discriminated union over type: each block type accepts its own typed properties. You get back the new commit and the id of the block you just created.

const data = await cms.api.pages.createBlock({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    parentBlockId: 'root_home', // required (pass the rootId to attach at the top level)
    type: 'Hero', // required
    properties: { heading: 'Welcome' }, // required
  },
});

const { data, error } = await client.pages.createBlock({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    parentBlockId: 'root_home', // required (pass the rootId to attach at the top level)
    type: 'Hero', // required
    properties: { heading: 'Welcome' }, // required
  },
});

Update a Block

Edit one block with patch semantics: the fields you send overwrite, omitted fields stay, and a null value deletes a key.

const data = await cms.api.pages.updateBlock({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    blockId: 'blk_hero', // required
    type: 'Hero', // required (must match the stored type)
    properties: { heading: 'Updated heading' }, // required
  },
});

const { data, error } = await client.pages.updateBlock({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    blockId: 'blk_hero', // required
    type: 'Hero', // required (must match the stored type)
    properties: { heading: 'Updated heading' }, // required
  },
});

Save a Block Tree

Save a whole tree in one commit: createCMS diffs the tree you send against the branch head and creates, updates, and deletes blocks to match. This is the batch save path your editor calls after local edits, instead of one call per change.

const data = await cms.api.pages.updateBlocks({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    tree, // required: the edited tree from getBlockTree, root node included
    expectedHeadCommitId: headCommitId,
  },
});

const { data, error } = await client.pages.updateBlocks({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    tree, // required: the edited tree from getBlockTree, root node included
    expectedHeadCommitId: headCommitId,
  },
});

changed is false when the tree already matches the head (no commit is written and the current head commit is returned), and true when a real commit was created. Every created or updated node is validated before the commit (known block type, valid properties, legal placement), so any violation rejects the whole batch with no partial write.

Move a Block

Move a block (and its subtree) to a new parent and/or a new position within a parent's children.

const data = await cms.api.pages.moveBlock({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    blockId: 'blk_hero', // required
    newParentBlockId: 'blk_section', // required
    newIndex: 0, // required
  },
});

const { data, error } = await client.pages.moveBlock({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    blockId: 'blk_hero', // required
    newParentBlockId: 'blk_section', // required
    newIndex: 0, // required
  },
});

Moving into itself, into one of its own descendants, or moving the root block is rejected (CANNOT_MOVE_INTO_SELF, CANNOT_MOVE_INTO_DESCENDANT, CANNOT_MOVE_ROOT).

Duplicate a Block

Clone a block subtree under an existing parent. targetParentBlockId is required — this endpoint only ever duplicates into a parent. To spin a subtree off into a brand-new top-level entry instead, use duplicateRoot.

const data = await cms.api.pages.duplicateBlock({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    blockId: 'blk_hero', // required
    targetParentBlockId: 'blk_section', // required: duplicate under this parent
  },
});

const { data, error } = await client.pages.duplicateBlock({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    blockId: 'blk_hero', // required
    targetParentBlockId: 'blk_section', // required: duplicate under this parent
  },
});

mode is always 'child'. The response also carries blockId, the new copy's id.

Delete a Block

Soft-delete a block and all its descendants (tombstones), and remove it from its parent's children. You get back the ids of everything that was tombstoned.

const data = await cms.api.pages.deleteBlock({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    blockId: 'blk_hero', // required
  },
});

const { data, error } = await client.pages.deleteBlock({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    blockId: 'blk_hero', // required
  },
});

deletedBlockIds lists every block tombstoned in the commit (the target plus its descendants).

List Reference Usages

List the pages that embed this reusable block, so you can see where it's used before you change or remove it. Under i18n the inspected entry's translation group expands to all sibling entries, so usage is reported across languages.

const data = await cms.api.pages.getReferenceUsages({
  query: { rootId: 'root_home' }, // required
});

const { data, error } = await client.pages.getReferenceUsages({
  query: { rootId: 'root_home' }, // required
});

This endpoint checks root:read, not block:read, because it reports usage of an entry across the collection.