Releases API

A release bundles several entries (roots), each pinned to one of its branches, so they can be published together in a single atomic operation. These methods live on the system namespace at cms.api.releases.<method> and mirror on the client as client.releases.<method> with identical types. A release is not per-collection: one release may span entries from different collections.

A release starts as a draft you build up with items, then flips to published when publishRelease succeeds. Item mutations only work while the release is a draft. Publishing points each item at its branch's existing head commit rather than creating new ones, so none of these methods returns a commit envelope.

Create a Release

Start a new, empty draft release and get it back to work with. Fill it with entries using addToRelease or setReleaseItems, then ship them together with publishRelease.

const data = await cms.api.releases.createRelease({
  body: { title: 'Spring launch' }, // required
});

const { data, error } = await client.releases.createRelease({
  body: { title: 'Spring launch' }, // required
});

The returned release carries id, title, status: 'draft', createdBy, createdAt, and publishedAt (null until published).

Add an Entry to a Release

Add one entry to a draft release, pinned to the branch you want it to publish from. It upserts on (releaseId, rootId), so re-adding a root that's already in the release just swaps which branch it will publish, and the root and branch are validated up front. Fails with RELEASE_NOT_FOUND, RELEASE_NOT_DRAFT, ROOT_NOT_FOUND, or BRANCH_NOT_FOUND.

const data = await cms.api.releases.addToRelease({
  body: {
    releaseId: 'rel_abc123', // required
    rootId: 'root_home', // required
    branchId: 'br_main', // required
  },
});

const { data, error } = await client.releases.addToRelease({
  body: {
    releaseId: 'rel_abc123', // required
    rootId: 'root_home', // required
    branchId: 'br_main', // required
  },
});

The returned item carries id, releaseId, rootId, and branchId.

Remove an Entry from a Release

Drop one entry (by rootId) from a draft release. Fails with RELEASE_NOT_FOUND or RELEASE_NOT_DRAFT.

const data = await cms.api.releases.removeFromRelease({
  body: {
    releaseId: 'rel_abc123', // required
    rootId: 'root_home', // required
  },
});

const { data, error } = await client.releases.removeFromRelease({
  body: {
    releaseId: 'rel_abc123', // required
    rootId: 'root_home', // required
  },
});

The returned removed is true when a matching item was deleted, false otherwise.

Set a Release's Items

Replace a draft release's entire member list in one shot. Every item is validated first, then the old items are cleared and the new set inserted in a single transaction. Duplicate roots are rejected with RELEASE_DUPLICATE_ROOT; it also fails with RELEASE_NOT_FOUND, RELEASE_NOT_DRAFT, ROOT_NOT_FOUND, or BRANCH_NOT_FOUND.

const data = await cms.api.releases.setReleaseItems({
  body: {
    releaseId: 'rel_abc123', // required
    items: [{ rootId: 'root_home', branchId: 'br_main' }], // required
  },
});

const { data, error } = await client.releases.setReleaseItems({
  body: {
    releaseId: 'rel_abc123', // required
    items: [{ rootId: 'root_home', branchId: 'br_main' }], // required
  },
});

Get a Release

Fetch a single release together with its items. Fails with RELEASE_NOT_FOUND.

const data = await cms.api.releases.getRelease({
  query: { releaseId: 'rel_abc123' }, // required
});

const { data, error } = await client.releases.getRelease({
  query: { releaseId: 'rel_abc123' }, // required
});

List Releases

Page through your releases, newest first, optionally narrowed to one status. Every query field is optional.

const data = await cms.api.releases.listReleases({
  query: { status: 'draft', limit: 20 },
});

const { data, error } = await client.releases.listReleases({
  query: { status: 'draft', limit: 20 },
});

Publish a Release

Publish every entry in the release atomically. Each item runs the same publish machinery as pages.publishBranch, all inside one database transaction: if any item fails (for example an unapproved branch under a policy that requires approval), the whole set rolls back and nothing goes live. On success the release flips to published. Fails with RELEASE_NOT_FOUND, RELEASE_NOT_DRAFT, RELEASE_EMPTY, ROOT_NOT_FOUND, BRANCH_NOT_FOUND, or PUBLICATION_APPROVAL_REQUIRED.

const data = await cms.api.releases.publishRelease({
  body: { releaseId: 'rel_abc123' }, // required
});

const { data, error } = await client.releases.publishRelease({
  body: { releaseId: 'rel_abc123' }, // required
});

The updated release has status: 'published' and a set publishedAt; publications holds one publication per item.