Comments

Create and manage threaded comments and reactions

Comments are threaded discussions attached to entities. The comments module lets you create, fetch, update, and delete comments, and manage reactions on them. All actions are performed on behalf of the logged-in user.

---

createComment

Creates a comment on an entity. Optionally a reply, with a GIF, mentions, attachments, or metadata.

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

entityId · string · required

The Sublay entity ID the comment belongs to.

foreignId · string

Your application’s identifier for this comment.

content · string

The comment’s text content.

gif · GifData | null

An optional GIF attached to the comment.

mentions · Mention[]

User mentions embedded in the comment.

parentId · string | null

The ID of the parent comment when this is a reply.

referencedCommentId · string

The ID of another comment this comment references.

attachments · Record<string, any>[]

File or media attachments.

metadata · Record<string, any>

Arbitrary public metadata.

Returns — Promise<Comment>

---

fetchComment

Fetches a single comment by its 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: "comment-99",
});

foreignId · string · required

Your application’s comment identifier.

include · string

Comma-separated list of associations to populate.

Returns — Promise<Comment>

---

updateComment

Updates a comment’s content.

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 content for the comment.

Returns — Promise<Comment>

---

deleteComment

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, filterable by entity, user, or parent.

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

entityId · string

Filter to comments on a specific entity.

userId · string

Filter to comments authored by a given user.

parentId · string

Filter to replies of a specific parent comment.

page · number

Page number (1-indexed).

limit · number

Results per page.

sortBy · string

Sort order: "createdAt" (newest first; honors sortDir), "top", or "controversial". "new" and "old" 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.

sourceId · string

Filter by source ID.

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 the logged-in user’s reaction to a comment and returns the full populated comment.

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

commentId · string · required

The Sublay comment ID.

reactionType · ReactionType · required

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

Returns — Promise<Comment>

---

removeReaction

Removes the logged-in user’s reaction from a comment and returns the full populated comment.

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

commentId · string · required

The Sublay comment ID.

Returns — Promise<Comment>

---

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: "like",
  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).

limit · number

Results per page.

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<{ data: Reaction[]; pagination: { page: number; limit: number; total: number; totalPages: number; hasMore: boolean } }>

---

getUserReaction

Gets the logged-in user’s reaction on a comment. Returns null if there is no reaction.

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

commentId · string · required

The Sublay comment ID.

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