Comments

Create, fetch, update, delete comments, and manage reactions from your server

The comments module provides full server-side control over comments on entities. Use it to seed content, build moderation pipelines, or integrate comment data into your backend logic.

---

createComment

Creates a new comment on an entity.

const comment = await sublay.comments.createComment({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
  content: "Great post!",
});

entityId · string · required

The Sublay entity ID to comment on.

userId · string · required

The Sublay user ID of the comment author.

content · string

The comment text content.

foreignId · string

Your application’s identifier for this comment.

gif · object

A GIF to attach to the comment (GifData), or null.

mentions · array

User mentions embedded in the comment.

parentId · string

The Sublay comment ID of the parent, for creating a reply.

referencedCommentId · string

A comment being directly quoted or referenced.

attachments · array

File or media attachments on the comment.

metadata · object

Arbitrary metadata attached to the comment.

createdAt · Date

A Date used to backdate the comment’s creation time.

updatedAt · Date

A Date used to backdate the comment’s last update time.

Returns — Promise<Comment>

---

fetchComment

Fetches a single comment by its Sublay ID.

const comment = await sublay.comments.fetchComment({ commentId: "cmt_abc123" });

commentId · string · required

The Sublay comment ID.

include · string

Comma-separated list of associations to populate.

spaceReputationId · string

Opts the returned comment’s author into a spaceReputation number. Accepts a space <uuid>, "none" (the project-general bucket), or "context" (the space derived from the request context). The empty string and the legacy general / null aliases are rejected. See Reputation.

spaceReputationDescendants · boolean

Only honored alongside an explicit space <uuid>. When true, spaceReputation is the subtree sum — the named space plus all of its descendants.

Returns — Promise<Comment>

---

fetchCommentByForeignId

Fetches a comment by your application’s own identifier.

const comment = await sublay.comments.fetchCommentByForeignId({
  foreignId: "my-comment-id-99",
});

foreignId · string · required

Your application’s comment identifier.

include · string

Comma-separated list of associations to populate.

Returns — Promise<Comment>

---

updateComment

Updates the content of an existing comment.

const comment = await sublay.comments.updateComment({
  commentId: "cmt_abc123",
  content: "Edited comment text",
});

commentId · string · required

The Sublay comment ID to update.

content · string · required

The new comment text.

Returns — Promise<Comment>

---

deleteComment

Permanently deletes a comment.

await sublay.comments.deleteComment({ commentId: "cmt_abc123" });

commentId · string · required

The Sublay comment ID to delete.

Returns — Promise<void>

---

fetchManyComments

Fetches a paginated list of comments on an entity. Supports top-level and reply-level fetching.

const { data, pagination } = await sublay.comments.fetchManyComments({
  entityId: "ent_xyz789",
  sortBy: "top",
  page: 1,
  limit: 20,
});

entityId · string

The Sublay entity ID to fetch comments for.

userId · string

Filter to comments authored by a specific user.

parentId · string

When provided, fetches replies to this specific comment ID instead of top-level comments.

sourceId · string

Filter comments by source ID.

page · number

Page number (1-indexed). Defaults to 1.

limit · number

Results per page. Defaults to 20.

sortBy · string

Sort order: "createdAt" (newest first; honors sortDir), "top" (highest scored), or "controversial". "new" (createdAt DESC) and "old" (createdAt ASC) are deprecated aliases for "createdAt" (removed in v8) — the server still accepts them but responds with a deprecation header.

include · string

Comma-separated list of associations to populate.

spaceReputationId · string

Opts each returned comment’s author into a spaceReputation number. Accepts a space <uuid>, "none" (the project-general bucket), or "context" (the space derived from the request context — resolved per-row from the space each comment belongs to). The empty string and the legacy general / null aliases are rejected. See Reputation.

spaceReputationDescendants · boolean

Only honored alongside an explicit space <uuid>. When true, spaceReputation is the subtree sum — the named space plus all of its descendants.

Returns — Promise<PaginatedResponse<Comment>>

---

addReaction

Adds a reaction from a user to a comment.

const reaction = await sublay.comments.addReaction({
  commentId: "cmt_abc123",
  userId: "usr_abc123",
  reactionType: "like",
});

commentId · string · required

The Sublay comment ID.

userId · string · required

The Sublay user ID of the reactor.

reactionType · ReactionType · required

One of: "upvote", "downvote", "like", "love", "wow", "sad", "angry", "funny".

Returns — Promise<Reaction>

---

removeReaction

Removes a user’s existing reaction from a comment.

await sublay.comments.removeReaction({
  commentId: "cmt_abc123",
  userId: "usr_abc123",
});

commentId · string · required

The Sublay comment ID.

userId · string · required

The Sublay user ID whose reaction to remove.

Returns — Promise<void>

---

fetchReactions

Fetches a paginated list of reactions on a comment, optionally filtered by reaction type.

const { data, pagination } = await sublay.comments.fetchReactions({
  commentId: "cmt_abc123",
  reactionType: "upvote",
  page: 1,
  limit: 20,
});

commentId · string · required

The Sublay comment ID.

reactionType · ReactionType

Filter to a specific reaction type.

page · number

Page number (1-indexed). Defaults to 1.

limit · number

Results per page. Defaults to 20.

sortDir · string

Sort direction: "asc" or "desc".

spaceReputationId · string

Opts each returned reactor into a spaceReputation number. Accepts a space <uuid>, "none" (the project-general bucket), or "context" (the space derived from the request context). The empty string and the legacy general / null aliases are rejected. See Reputation.

spaceReputationDescendants · boolean

Only honored alongside an explicit space <uuid>. When true, spaceReputation is the subtree sum — the named space plus all of its descendants.

Returns — Promise<PaginatedResponse<Reaction>>

---

getUserReaction

Checks what reaction (if any) a specific user has left on a comment.

const { reactionType } = await sublay.comments.getUserReaction({
  commentId: "cmt_abc123",
  userId: "usr_abc123",
});
// reactionType is "like" | "upvote" | ... | null

commentId · string · required

The Sublay comment ID.

userId · string · required

The Sublay user ID to check.

Returns — Promise<{ reactionType: ReactionType | null }>