Roots API

Roots are the top-level entries of a collection (a page, a post, a product). These methods live at cms.api.<collection>.<method> and mirror on the client as client.<collection>.<method> with identical types. Every commit-producing mutation (createRoot, updateRoot, duplicateRoot) returns a commit: { id, message, createdAt, createdBy } envelope.

Create an Entry

Create a new entry (root) in a collection. You get back a fresh entry with its own draft branch and initial commit, ready for you to start adding blocks to.

const data = await cms.api.pages.createRoot({
  body: {
    slug: 'welcome', // required on slug-enabled collections
    properties: { title: 'Welcome' }, // required
  },
});

const { data, error } = await client.pages.createRoot({
  body: {
    slug: 'welcome', // required on slug-enabled collections
    properties: { title: 'Welcome' }, // required
  },
});

List Entries

Page through the entries of a collection with search, filter, and sort. Every field is optional, so a bare call hands you the most recent entries. Each row comes back enriched with its publication, branch, and open-merge-request counts.

const data = await cms.api.pages.listRoots({
  query: { limit: 20, sortBy: 'createdAt', sortDirection: 'desc' },
});

const { data, error } = await client.pages.listRoots({
  query: { limit: 20, sortBy: 'createdAt', sortDirection: 'desc' },
});

Get an Entry

Fetch a single entry by id, with its current properties, metadata, and publication counts. Use this when you already hold the entry's id; to look one up by slug, reach for getRootBySlug instead.

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

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

Get an Entry by Slug

Look up an entry by its draft slug (and optional parent). It matches the per-branch __slug, not the published slug, so you can find an unpublished entry by the slug it is about to publish.

const data = await cms.api.pages.getRootBySlug({
  query: { slug: 'welcome' }, // required
});

const { data, error } = await client.pages.getRootBySlug({
  query: { slug: 'welcome' }, // required
});

Get an Entry's History

Walk the full commit history of an entry across all its branches, newest first, so you can render a timeline or an activity feed. Opt into per-commit change counts with withChanges.

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

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

Each commit carries id, message, createdBy, createdAt, branch (the branch it was created on), parents (one commit id, two for a merge), type ('initial' | 'commit' | 'merge'), and isPublished. With withChanges: true, the counts are version-level (from a cheap version-id comparison against the parent snapshot, no properties loaded), coarser than getDiff: a pure move counts as modified on the parent whose children array changed, an initial commit counts every block as added, and a merge commit is diffed against its first parent only. The field is omitted (not zeroed) on commits whose snapshot was pruned by retention.

Update an Entry

Edit an entry's properties and/or slug on a branch. You get back the new commit and, on slug-enabled collections, the server-normalized draft slug; redirects are auto-created when a published slug changes.

const data = await cms.api.pages.updateRoot({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    properties: { title: 'Welcome home' }, // required
  },
});

const { data, error } = await client.pages.updateRoot({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    properties: { title: 'Welcome home' }, // required
  },
});

Move an Entry

Reparent an entry (or promote it to top-level) and reorder it among its siblings. Nesting must be enabled and circular references are rejected; redirects are auto-created when the parent actually changes.

const data = await cms.api.pages.moveRoot({
  body: {
    rootId: 'root_home', // required
    newParentRootId: 'root_docs', // required (or null for top-level)
  },
});

const { data, error } = await client.pages.moveRoot({
  body: {
    rootId: 'root_home', // required
    newParentRootId: 'root_docs', // required (or null for top-level)
  },
});

Duplicate an Entry

Deep-copy an entire entry's block tree into a brand-new top-level entry. To copy a subtree under an existing parent instead, reach for duplicateBlock.

const data = await cms.api.pages.duplicateRoot({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    blockId: 'root_home', // required (the entry's root block id)
    targetProperties: { title: 'Welcome (copy)' }, // required
    targetSlug: 'welcome-copy',
  },
});

const { data, error } = await client.pages.duplicateRoot({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    blockId: 'root_home', // required (the entry's root block id)
    targetProperties: { title: 'Welcome (copy)' }, // required
    targetSlug: 'welcome-copy',
  },
});

Archive an Entry

Soft-archive an entry (its history is preserved) and auto-create a redirect from its old path to its parent. You cannot archive an entry that still has live child pages or is embedded as a reusable block on live content.

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

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