Comments API

Comment methods let reviewers open threads on a merge request or a block, reply, mention users, and resolve or reopen the discussion. 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.

These endpoints operate on comment threads and messages, not on content commits, so no method returns a commit envelope.

Open a Comment Thread

Open a new review thread with an initial message, so reviewers can flag something on a merge request or a block. targetType picks the anchor: 'mergeRequest' requires mergeRequestId, 'block' requires blockId. Anyone you list in mentions gets a notification.

const data = await cms.api.pages.createCommentThread({
  body: {
    targetType: 'mergeRequest', // required
    mergeRequestId: 'mr_8fd21c', // required when targetType is 'mergeRequest'
    body: 'Can we tighten the hero copy before merging?', // required
    mentions: ['user_editor'],
  },
});

const { data, error } = await client.pages.createCommentThread({
  body: {
    targetType: 'mergeRequest', // required
    mergeRequestId: 'mr_8fd21c', // required when targetType is 'mergeRequest'
    body: 'Can we tighten the hero copy before merging?', // required
    mentions: ['user_editor'],
  },
});

Reply to a Thread

Reply to an existing thread, optionally nested under a parent message. The thread's creator and every mentioned user get notified.

const data = await cms.api.pages.createCommentMessage({
  body: {
    threadId: 'thr_1a2b3c', // required
    body: 'Updated, ready for another look.', // required
  },
});

const { data, error } = await client.pages.createCommentMessage({
  body: {
    threadId: 'thr_1a2b3c', // required
    body: 'Updated, ready for another look.', // required
  },
});

List Comment Threads

Page through comment threads, filtered by what they're attached to (merge request, block, commit, root), by status, or by who was mentioned. Each thread comes back with its message count and first/latest message, so you can render a list without a second round-trip. Every query field is optional.

const data = await cms.api.pages.listCommentThreads({
  query: {
    status: 'open',
    limit: 50,
  },
});

const { data, error } = await client.pages.listCommentThreads({
  query: {
    status: 'open',
    limit: 50,
  },
});

Get a Thread with Its Messages

Load a single thread together with all of its messages in chronological order, so you can render the full discussion. Deleted messages still come back, but with their body masked to null.

const data = await cms.api.pages.getCommentThread({
  query: { threadId: 'thr_1a2b3c' }, // required
});

const { data, error } = await client.pages.getCommentThread({
  query: { threadId: 'thr_1a2b3c' }, // required
});

Edit a Message

Edit the text of a message you wrote, and optionally replace its mentions. Only the original author may edit, and system messages cannot be edited.

const data = await cms.api.pages.updateCommentMessage({
  body: {
    messageId: 'msg_9f8e7d', // required
    body: 'Revised: tightened the hero copy.', // required
  },
});

const { data, error } = await client.pages.updateCommentMessage({
  body: {
    messageId: 'msg_9f8e7d', // required
    body: 'Revised: tightened the hero copy.', // required
  },
});

Resolve a Thread

Mark a thread as resolved once its discussion is settled. A system message is appended recording who resolved it, and you get both the updated thread and that message back.

const data = await cms.api.pages.resolveCommentThread({
  body: { threadId: 'thr_1a2b3c' }, // required
});

const { data, error } = await client.pages.resolveCommentThread({
  body: { threadId: 'thr_1a2b3c' }, // required
});

Reopen a Thread

Reopen a resolved thread when the discussion isn't finished after all. A system message is appended recording the reopening, and you get both the updated thread and that message back.

const data = await cms.api.pages.reopenCommentThread({
  body: { threadId: 'thr_1a2b3c' }, // required
});

const { data, error } = await client.pages.reopenCommentThread({
  body: { threadId: 'thr_1a2b3c' }, // required
});

Delete a Thread

Soft-delete a thread so it drops out of list and get. Its messages and mentions stay in the database and are removed only when the owning root is pruned.

const data = await cms.api.pages.deleteCommentThread({
  body: { threadId: 'thr_1a2b3c' }, // required
});

const { data, error } = await client.pages.deleteCommentThread({
  body: { threadId: 'thr_1a2b3c' }, // required
});

Delete a Message

Soft-delete a single message so its body is masked on retrieval. Only the original author may delete, and system messages cannot be deleted.

const data = await cms.api.pages.deleteCommentMessage({
  body: { messageId: 'msg_9f8e7d' }, // required
});

const { data, error } = await client.pages.deleteCommentMessage({
  body: { messageId: 'msg_9f8e7d' }, // required
});

List a User's Mentions

Page through the mentions a user has received, each with the message and thread it came from, so you can build a mentions inbox. Filter to a single thread with threadId.

const data = await cms.api.pages.listMentions({
  query: {
    mentionedUserId: 'usr_1', // required
    limit: 50,
  },
});

const { data, error } = await client.pages.listMentions({
  query: {
    mentionedUserId: 'usr_1', // required
    limit: 50,
  },
});