Branches API

Branches are the drafts of an entry (root): each one is an independent line of commits you can edit, publish, and merge back. Methods live at cms.api.<collection>.<method> (use your collection name, e.g. cms.api.pages.listBranches) and mirror on the client with identical types. Every commit-producing mutation returns a commit envelope: { id, message, createdAt, createdBy }.

Methods

List Branches

List the branches of an entry, with pagination and filters for publication and merge-request state. Each item carries isDeletable and hasPublications, so you can tell at a glance which drafts are safe to remove.

const data = await cms.api.pages.listBranches({
  query: {
    rootId: 'root_123', // required
    limit: 50,
  },
});

const { data, error } = await client.pages.listBranches({
  query: {
    rootId: 'root_123', // required
    limit: 50,
  },
});

Get a Branch

Fetch a single branch with its metadata and isDeletable flag. Look it up either by branchId, or by its { rootId, name } pair (branch names are unique per root), so you can resolve a branch you only know by name without paging through listBranches.

const data = await cms.api.pages.getBranch({
  query: { rootId: 'root_123', name: 'draft' }, // or { branchId: 'br_main' }
});

const { data, error } = await client.pages.getBranch({
  query: { rootId: 'root_123', name: 'draft' }, // or { branchId: 'br_main' }
});

Create a Branch

Spin up a new branch by copying the head commit of a source branch. You get back the fresh branch, whose isDeletable is always true since it has no publications or open merge requests yet.

const data = await cms.api.pages.createBranch({
  body: {
    rootId: 'root_123', // required
    name: 'feature-hero', // required
    sourceBranchId: 'br_main', // required
  },
});

const { data, error } = await client.pages.createBranch({
  body: {
    rootId: 'root_123', // required
    name: 'feature-hero', // required
    sourceBranchId: 'br_main', // required
  },
});

Rename a Branch

Rename a branch and get the updated row back. Fails with CANNOT_RENAME_MAIN_BRANCH for the default branch, or BRANCH_NAME_ALREADY_EXISTS if the name is taken in the root.

const data = await cms.api.pages.renameBranch({
  body: {
    branchId: 'br_feature', // required
    newName: 'feature-hero', // required
  },
});

const { data, error } = await client.pages.renameBranch({
  body: {
    branchId: 'br_feature', // required
    newName: 'feature-hero', // required
  },
});

Revert a Branch

Roll a branch back to the snapshot at an earlier commit. This writes a new commit with that state onto the branch head (it never rewrites history), and is blocked while the branch is published.

const data = await cms.api.pages.revertBranch({
  body: {
    branchId: 'br_feature', // required
    targetCommitId: 'commit_abc', // required
  },
});

const { data, error } = await client.pages.revertBranch({
  body: {
    branchId: 'br_feature', // required
    targetCommitId: 'commit_abc', // required
  },
});

Check Divergence

Compare two branches of the same root to see how far they have diverged: their common ancestor, how many commits each is ahead, and whether the source can fast-forward onto the target. Fails with BRANCHES_NOT_SAME_ROOT if the branches belong to different roots.

const data = await cms.api.pages.checkDivergence({
  query: {
    sourceBranchId: 'br_feature', // required
    targetBranchId: 'br_main', // required
  },
});

const { data, error } = await client.pages.checkDivergence({
  query: {
    sourceBranchId: 'br_feature', // required
    targetBranchId: 'br_main', // required
  },
});

Delete a Branch

Delete a branch. Fails with CANNOT_DELETE_MAIN_BRANCH for the default branch, BRANCH_HAS_PUBLICATIONS if it has any publication, or BRANCH_HAS_OPEN_MERGE_REQUESTS if it is part of an open merge request.

const data = await cms.api.pages.deleteBranch({
  body: { branchId: 'br_feature' }, // required
});

const { data, error } = await client.pages.deleteBranch({
  body: { branchId: 'br_feature' }, // required
});