Approvals API

Approval methods let you request sign-off from reviewers and record their approve or reject decisions on a merge request or a direct publication. They live at cms.api.<collection>.<method> and mirror on the client at client.<collection>.<method> with identical types. Examples below use pages as the sample collection. An approval targets either a merge request or a direct publication (a branch's head commit); the targetType field reflects which.

These methods record approvals against an existing commit, they don't produce content commits, so none returns the commit: { id, message, createdAt, createdBy } envelope that commit-producing mutations elsewhere in the API return.

Request Approval

Ask one or more reviewers to sign off on a merge request or a branch's head commit (a direct publication). Each reviewer gets their own pending approval and a notification. Provide exactly one of mergeRequestId or branchId.

const data = await cms.api.pages.requestApproval({
  body: {
    branchId: 'br_9f2a1c', // required (or mergeRequestId, exactly one)
    requestedReviewers: ['user_editor', 'user_legal'], // required
    message: 'Ready for review before publishing.',
  },
});

const { data, error } = await client.pages.requestApproval({
  body: {
    branchId: 'br_9f2a1c', // required (or mergeRequestId, exactly one)
    requestedReviewers: ['user_editor', 'user_legal'], // required
    message: 'Ready for review before publishing.',
  },
});

List Approvals

Page through approvals, filtered by status, target, requester, or reviewer, so you can build a review queue or an audit trail. Approvals on archived entries are left out, and every query field is optional.

const data = await cms.api.pages.listApprovals({
  query: { status: 'pending', requestedReviewer: 'user_editor', limit: 20 },
});

const { data, error } = await client.pages.listApprovals({
  query: { status: 'pending', requestedReviewer: 'user_editor', limit: 20 },
});

Get an Approval

Fetch a single approval by id, with its requester, requested reviewer, and reviewer enriched as full user profiles (when user enrichment is enabled), so you can render who asked and who signed off.

const data = await cms.api.pages.getApproval({
  query: { approvalId: 'apr_1a2b3c' }, // required
});

const { data, error } = await client.pages.getApproval({
  query: { approvalId: 'apr_1a2b3c' }, // required
});

Approve a Request

Approve a pending approval as its requested reviewer. Only that reviewer may approve it, and for a direct-publication approval it fails if the branch head has moved since the request went out.

const data = await cms.api.pages.submitApproval({
  body: { approvalId: 'apr_1a2b3c' }, // required
});

const { data, error } = await client.pages.submitApproval({
  body: { approvalId: 'apr_1a2b3c' }, // required
});

Reject a Request

Reject a pending approval, optionally recording why. The same requested-reviewer and staleness rules as submitApproval apply.

const data = await cms.api.pages.submitRejection({
  body: {
    approvalId: 'apr_1a2b3c', // required
    rejectionReason: 'Needs revision before publishing.',
  },
});

const { data, error } = await client.pages.submitRejection({
  body: {
    approvalId: 'apr_1a2b3c', // required
    rejectionReason: 'Needs revision before publishing.',
  },
});

Cancel a Request

Cancel a pending approval, deleting the request outright. Only pending approvals can be canceled; an already-approved or rejected one can't be undone this way.

const data = await cms.api.pages.cancelApproval({
  body: { approvalId: 'apr_1a2b3c' }, // required
});

const { data, error } = await client.pages.cancelApproval({
  body: { approvalId: 'apr_1a2b3c' }, // required
});