Publications API

Publications control what content is publicly live. Every method lives at cms.api.<collection>.<method> (use your collection name, e.g. cms.api.pages) and mirrors on the client as client.<collection>.<method> with identical types.

Publishing points a publication at the branch's existing head commit rather than creating a new one, so unlike the entry and block mutation APIs these methods do not return a commit envelope.

Publishing

Publish a Branch

Publish a branch, making its head commit the version your readers see live. You get back the resulting publication (publishing points at the existing head commit, so there is no new commit). Fails with PUBLICATION_APPROVAL_REQUIRED if the branch has open approval requests that are not all approved.

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

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

The returned publication carries rootId, branchId, commitId, publishedBy, publishedAt, and branchName.

Unpublish a Branch

Take a branch's content offline by removing its publication. You get back which commit was live and when it came down. Fails with PUBLICATION_NOT_FOUND when no active publication exists for the root-branch pair.

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

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

Scheduling

Schedule a Publish

Queue a branch to publish itself at a future time. Nothing goes live until the cron-driven admin.runScheduled processes the due row; the root (in scope) and branch are validated up front, so you catch bad ids now rather than at run time.

const data = await cms.api.pages.schedulePublication({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    scheduledAt: '2026-01-01T00:00:00Z', // required
  },
});

const { data, error } = await client.pages.schedulePublication({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    scheduledAt: '2026-01-01T00:00:00Z', // required
  },
});

The returned scheduled row carries id, rootId, branchId, action: 'publish', scheduledAt, and processedAt (null until run).

Schedule an Unpublish

Queue a branch's content to go offline at a future time. The content is taken down when admin.runScheduled processes the due row, so reach for this to expire content on a schedule.

const data = await cms.api.pages.scheduleUnpublish({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    scheduledAt: '2026-02-01T00:00:00Z', // required
  },
});

const { data, error } = await client.pages.scheduleUnpublish({
  body: {
    rootId: 'root_home', // required
    branchId: 'br_main', // required
    scheduledAt: '2026-02-01T00:00:00Z', // required
  },
});

The returned scheduled row is identical in shape to schedulePublication, with action: 'unpublish'.

Reading

Read Published Content

Fetch the live, published content for an entry, looked up by rootId, slug, or path (pass at least one). References are resolved inline and variables substituted unless you set raw. It runs the full auth chain (so plugin scope stays enforced) but is conventionally anonymous-readable.

const data = await cms.api.pages.getPublishedContent({
  query: { slug: 'welcome' }, // one of rootId, slug, or path required
});

const { data, error } = await client.pages.getPublishedContent({
  query: { slug: 'welcome' }, // one of rootId, slug, or path required
});

Each variants item carries branchId, branchName, commitId, publishedAt, publishedBy, and a resolved block tree. ancestors is present only for nested-slug collections.

List Publications

List the publications in a collection, so you can see what is currently live and when it went out. Filter by root, branch, or date range. Publications of soft-deleted roots are excluded.

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

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

Each publications item includes rootId, branchId, commitId, publishedBy, publishedAt, branchName, rootProperties, and (when user enrichment is enabled) publishedByUser.