Comments

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!",
});

string

required

The Sublay entity ID to comment on.

string

required

The Sublay user ID of the comment author.

string

The comment text content.

string

Your application’s identifier for this comment.

object

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

array

User mentions embedded in the comment.

string

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

string

A comment being directly quoted or referenced.

array

File or media attachments on the comment.

object

Arbitrary metadata attached to the comment.

Date

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

Date

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

Returns — Promise<Comment> When the server refuses the comment, the call rejects with its error — among them 403 comment/parent-deleted and 403 comment/parent-removed for a reply to a deleted or removed comment, 403 comment/referenced-deleted and 403 comment/referenced-removed for a quote of one, and 409 comment/foreign-id-taken for a foreignId already in use. See Create Comment → Error Responses for the full list.

fetchComment

Fetches a single comment by its Sublay ID.

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

string

required

The Sublay comment ID.

string

Comma-separated list of associations to populate.

Returns — Promise<Comment>

fetchCommentByForeignId

Fetches a comment by your application’s own identifier.

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

string

required

Your application’s comment identifier.

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",
});

string

required

The Sublay comment ID to update.

string

required

The new comment text.

Returns — Promise<Comment>

deleteComment

Permanently deletes a comment.

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

string

required

The Sublay comment ID to delete.

Returns — Promise<void>

fetchManyComments

Fetches one level of a comment thread, cursor-paginated: an entity’s top-level comments (entityId) or a comment’s direct replies (parentId). One of the two is required. Optionally nests a few levels of replies inside each returned comment. See Fetch Many Comments for the full contract — placeholders, block flags and the request size limit.

const { data, pagination } = await sublay.comments.fetchManyComments({
  entityId: "ent_xyz789",
  sortBy: "top",
  limit: 20,
  include: "user",
  replyDepth: 2, // also bring 2 levels of replies…
  replyLimit: 3, // …up to 3 per comment
});

// Next page
const next = await sublay.comments.fetchManyComments({
  entityId: "ent_xyz789",
  sortBy: "top",
  limit: 20,
  cursor: pagination.nextCursor,
});

For a user’s comments across entities, use users.fetchCommentsByUserId.

Service-key reads have no signed-in viewer, so they are anonymous: isAuthorBlocked and isUnavailable are always false, userReaction isn’t populated, and no block rule applies. Moderator-removed comments come back as placeholders.

string

Fetch this entity’s top-level comments. Required unless parentId is passed.

string

Fetch this comment’s direct replies. Required unless entityId is passed.

number

How many comments at the level being fetched. Server default 10, max 100.

string | null

pagination.nextCursor from the previous response, passed as returned. Omit it, or pass null, for the first page. Send the same sortBy, sortDir and sortByReaction as the request that returned it.

"createdAt" | "top" | "controversial"

Sort for the level being fetched. "top" ranks by the raw count of sortByReaction. Server default "createdAt". "new" / "old" are deprecated aliases for "createdAt" — the server still accepts them but responds with a deprecation header.

"asc" | "desc"

Applies to every sort. Server default "desc".

ReactionType

With sortBy: "top" only: the reaction to rank by. Server default "upvote".

number

Levels of replies to nest under each returned comment (0–5). Server default 0.

number

Replies per comment in the nested levels (at least 1). Server default 3.

"createdAt" | "top" | "controversial"

Sort for the nested levels. Defaults to sortBy.

"asc" | "desc"

Sort direction for the nested levels. Defaults to sortDir.

ReactionType

The reaction the nested levels rank by, when their sort is "top".

"user" | "grants" | ("user" | "grants")[]

Related data to populate, at every level.

Returns — Promise<CursorPaginatedResponse<Comment>> — { data, pagination: { nextCursor, hasMore } }. With replyDepth above 0, each comment carries nested replies in the same shape.

addReaction

Adds a reaction from a user to a comment.

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

string

required

The Sublay comment ID.

string

required

The Sublay user ID of the reactor.

ReactionType

required

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

Returns — Promise<Comment> — the updated comment, as the reacting user sees it: userReaction and reactionCounts reflect the new reaction.

removeReaction

Removes a user’s existing reaction from a comment.

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

string

required

The Sublay comment ID.

string

required

The Sublay user ID whose reaction to remove.

Returns — Promise<Comment> — the updated comment, as that user sees it. When the user has no reaction on the comment, the comment comes back unchanged.

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,
});

string

required

The Sublay comment ID.

ReactionType

Filter to a specific reaction type.

number

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

number

Results per page. Defaults to 20.

string

Sort direction: "asc" or "desc".

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

string

required

The Sublay comment ID.

string

required

The Sublay user ID to check.

Returns — Promise<{ reactionType: ReactionType | null }>. Rejects with 404 comment/not-found when the comment doesn’t exist, or is on an entity whose author has blocked the user (the user’s own comments excepted).

Getting Started

Modules

createComment

fetchComment

fetchCommentByForeignId

updateComment

deleteComment

fetchManyComments

addReaction

removeReaction

fetchReactions

getUserReaction

​createComment

​fetchComment

​fetchCommentByForeignId

​updateComment

​deleteComment

​fetchManyComments

​addReaction

​removeReaction

​fetchReactions

​getUserReaction

createComment

fetchComment

fetchCommentByForeignId

updateComment

deleteComment

fetchManyComments

addReaction

removeReaction

fetchReactions

getUserReaction