Notifications

Notifications are the per-user inbox. The CMS raises them on @mentions in comments, approval decisions, merge-request activity, and publishing. Methods live under cms.api.notifications and mirror on the client as client.notifications.<method> with identical types.

These endpoints operate on the recipient's inbox, not on content commits, so no method returns a commit envelope. Every endpoint scopes to the authenticated user: reads and mutations only ever touch the current user's own notifications, and acting on another user's notification fails with NOTIFICATION_RECIPIENT_MISMATCH.

Methods

List Notifications

Fetch a page of your notifications (newest first, archived ones excluded) so you can render an inbox. Filter by type, collection, or read status, or leave every query field off to pull the latest across the board.

const data = await cms.api.notifications.list({
  query: { unreadOnly: true, limit: 10 },
});

const { data, error } = await client.notifications.list({
  query: { unreadOnly: true, limit: 10 },
});

unreadCount is the count of all unread notifications for the user, independent of the current page or filters. Each item carries id, recipientId, actorId, type, title, body, resourceType, resourceId, collection, meta, readAt, and createdAt. Pass the transport-level withUser: true flag to also include actorUser (the acting user, limited to your user config's exposeColumns allowlist) on each item.

Mark Notifications Read

Mark a notification as read once you've seen it. Pass a notificationId to clear a single one, or omit it entirely to mark your whole unread inbox as read in one call. You get back how many were actually flipped.

const data = await cms.api.notifications.markNotificationsRead({
  body: { notificationId: 'notif_8fd21c' }, // omit body to mark all unread as read
});

const { data, error } = await client.notifications.markNotificationsRead({
  body: { notificationId: 'notif_8fd21c' }, // omit body to mark all unread as read
});

Mark Notifications Unread

Flag a notification as unread so it resurfaces for later. Pass a notificationId to reopen one, or omit it to mark all of your read notifications unread. You get back how many were flipped.

const data = await cms.api.notifications.markNotificationsUnread({
  body: { notificationId: 'notif_8fd21c' }, // omit body to mark all read as unread
});

const { data, error } = await client.notifications.markNotificationsUnread({
  body: { notificationId: 'notif_8fd21c' }, // omit body to mark all read as unread
});

Archive a Notification

Archive a notification to drop it from your active inbox, so it stops showing up in list. Use it to clear out items you're done with without losing the underlying record.

const data = await cms.api.notifications.archiveNotification({
  body: { notificationId: 'notif_8fd21c' }, // required
});

const { data, error } = await client.notifications.archiveNotification({
  body: { notificationId: 'notif_8fd21c' }, // required
});

Types

type is one of: mention, comment, threadResolved, threadReopened, approvalRequested, approvalApproved, approvalRejected, mergeRequestOpened, mergeRequestMerged, mergeRequestClosed, mergeRequestReopened, published, custom.