Comment

A comment represents a user-authored response to an entity. Comments support nested replies, reactions, GIF attachments, user mentions, and moderation.

Properties

Property	Type	Description
`id`	`string`	Unique comment identifier (UUID).
`foreignId`	`string \| null`	Your system’s ID for this comment, if applicable.
`entityId`	`string`	The entity this comment belongs to.
`spaceId`	`string \| null`	The space of the comment’s entity. `null` when the entity isn’t in a space.
`entity`	`CommentEntity \| null`	The entity the comment is on, as its stored record — see The included entity for which fields it carries. Populated when `include` contains `"entity"` or `"space"`. `null` when the entity isn’t available to the caller — for example, removed by a moderator, or on your own comment on an entity whose author blocked you. The comment is still returned, and `null` doesn’t say why.
`userId`	`string \| null`	The ID of the user who posted this comment. `null` on placeholders.
`user`	`User \| null`	The comment author. Populated when `include` contains `"user"`. `null` on placeholders.
`parentId`	`string \| null`	ID of the parent comment if this is a reply. `null` for top-level comments.
`parentComment`	`Comment \| null`	The parent comment, under the same placeholder and block rules as any comment. Populated when `include` contains `"parent"` (user history and single-comment fetches). `null` for top-level comments, when the parent no longer exists or is on another entity, and on your own comment on an unavailable entity.
`referencedCommentId`	`string \| null`	ID of the comment this one quotes, set with `referencedCommentId` when the comment is created. `null` when it quotes none, or the quoted comment no longer exists.
`content`	`string \| null`	Text content of the comment. `null` on placeholders.
`gif`	`GifData \| null`	Attached GIF, if any. `null` on placeholders.
`mentions`	`Mention[]`	Array of user mentions embedded in the comment. `[]` on placeholders.
`attachments`	`Record<string, any>[]`	Generic attachment objects. `[]` on placeholders.
`upvotes`	`string[]`	Legacy v6 field — array of user IDs that upvoted. Use `reactionCounts` in v8.
`downvotes`	`string[]`	Legacy v6 field — array of user IDs that downvoted. Use `reactionCounts` in v8.
`reactionCounts`	`ReactionCounts`	Counts for all 8 reaction types. See Reaction.
`userReaction`	`ReactionType \| null`	The current user’s reaction, populated when authenticated.
`repliesCount`	`number`	Number of direct replies to this comment, for display. See What `repliesCount` counts.
`grants`	`GrantSummary \| undefined`	Per-item reputation-grant summary — `{ total, count, viewerTotal }` over positive grants. Populated when `include` contains `"grants"`. Zero-filled rather than omitted on a project with no grants, so `undefined` always means “nobody asked”.
`metadata`	`Record<string, any> \| null`	Custom key-value data, up to 10 KB (10,240 bytes) as JSON. `null` on placeholders.
`moderationStatus`	`"approved" \| "removed" \| null`	Space moderation status. Visible to everyone.
`moderatedAt`	`Date \| null`	When the moderation action was taken.
`moderatedById`	`string \| null`	ID of the moderator. Visible only to moderators and keys — see Moderation fields; `null` for everyone else.
`moderatedByType`	`"client" \| "user" \| null`	Whether a client (admin) or user performed moderation. Visible only to moderators and keys — see Moderation fields; `null` for everyone else.
`moderationReason`	`string \| null`	Reason provided for moderation. Visible only to moderators, keys and the comment’s author — see Moderation fields; `null` for everyone else.
`userDeletedAt`	`Date \| null`	Set when the author deletes their own comment. The comment stays in threads as a placeholder, so the replies under it remain.
`createdAt`	`Date`	When the comment was created.
`updatedAt`	`Date`	When the comment was last updated.
`deletedAt`	`Date \| null`	Legacy field; always `null` in responses. A user-deleted comment is marked by `userDeletedAt`.
`parentDeletedAt`	`Date \| null`	Legacy field; always `null` in responses.
`isAuthorBlocked`	`boolean`	`true` when the requesting user blocked this comment’s author and the comment is returned in full. See Blocked authors.
`isUnavailable`	`boolean`	`true` when the comment exists but can’t be shown to the requesting user; it is returned as a placeholder. See Blocked authors.
`replies`	`{ data: Comment[]; pagination: { nextCursor: string \| null; hasMore: boolean } }`	Nested replies. Present only on thread fetches with `replyDepth` above `0`, and absent on comments at the last nested level.

Nested Types

GifData

Property	Type	Description
`id`	`string`	GIF provider identifier.
`url`	`string`	URL to the GIF page or canonical source.
`gifUrl`	`string`	Direct URL to the animated GIF file.
`gifPreviewUrl`	`string`	URL to a lower-quality preview of the GIF.
`altText`	`string`	Accessible description of the GIF. Required.
`aspectRatio`	`string`	Width-to-height ratio for rendering, as a string — e.g. `"1.5"`, not `1.5`.

All six fields are required when a GIF is attached.

Includes

Pass include to populate optional fields. What each endpoint accepts:

Include value	Populates	Thread fetch	User history and single-comment fetches
`"user"`	`user` — the comment author	✓	✓
`"grants"`	`grants` — the reputation-grant summary	✓	✓
`"entity"`	`entity` — the entity the comment is on		✓
`"space"`	`entity` with its `space` populated		✓
`"parent"`	`parentComment` — the parent comment, for replies		✓

On a thread fetch, include applies at every nested level.

The included entity

entity is the entity’s stored record. It carries every stored Entity field — id, shortId, foreignId, sourceId, spaceId, userId, title, content, mentions, attachments, keywords, upvotes, downvotes, reactionCounts, sharesCount, views, score, scoreUpdatedAt, location, metadata, nsfw, the moderation fields, isDraft, createdAt, updatedAt and deletedAt. The fields an entity fetch computes or joins are not included:

Not included	What to use instead
`commentsCount`	Fetch the entity.
`userReaction`	Fetch the entity.
`nsfwEffective`	`entity.nsfw`, combined with `entity.space.nsfwEffective` when `include` contains `"space"`.
`user`	`entity.userId`, or fetch the entity with `include=user`.
`files`	Fetch the entity with `include=files`.
`topComments`	Fetch the entity with `include=topComments`.
`isSaved`	Fetch the entity with `include=saved`.
`grants`	Fetch the entity with `include=grants`. The comment’s own `grants` is unaffected.

entity.space is present only when include contains "space", and is null when the entity isn’t in a space. It is the Space record with membersCount and childSpacesCount (and isMember for a signed-in caller), without the avatarFile and bannerFile objects.

Placeholders

A comment that can’t be shown in full stays in place as a placeholder, so the replies under it — other people’s conversation — aren’t lost. There are three kinds, and each keeps a marker so your app can tell them apart:

Kind	Marker	Who sees the full comment
Deleted by its author	`userDeletedAt` is set	Nobody
Removed by a moderator	`moderationStatus: "removed"`	Its author
Unavailable to this user	`isUnavailable: true`	—

On a placeholder, userId, user, content, gif and metadata are null, and mentions and attachments are []. Everything else is kept: id, entityId, parentId, foreignId, timestamps, reactionCounts, repliesCount and the markers. Markers can combine — for example, a deleted comment whose author blocked the requesting user carries both userDeletedAt and isUnavailable: true. Render isUnavailable first: show the neutral unavailable row, without reply or reaction controls. Nothing is written into content; render your own wording for each kind. A deleted or removed comment can’t take new direct replies, new reactions or quotes — including a removed comment its author sees in full — so hide the reply, reaction and quote controls on it. The replies already under it can still be replied to, and a reaction already on it can still be removed. See Deleted and removed parents and quotes and Add Comment Reaction. A placeholder’s moderation fields follow Moderation fields: moderationStatus is always kept, and moderationReason, moderatedById and moderatedByType are filled only for the requesters listed there.

Moderation fields

moderationStatus is returned to everyone. The other three moderation fields are returned only to some requesters, on every comment response; everyone else gets null:

Requester	`moderationReason`	`moderatedById`, `moderatedByType`
An active admin or moderator of the comment’s space	✓	✓
A user whose project `role` is `admin` or `moderator`	✓	✓
A request made with a service or master key	✓	✓
The comment’s author	✓	—
Anyone else, including signed-out requests	—	—

A comment on an entity with no space has no space moderators: only project-role admins and moderators, keys and the comment’s author qualify.

Blocked authors

When the requesting user is signed in and the moderation bundle is installed, comments returned by thread, user-history, single-comment, topComments, update-comment and add/remove-reaction responses carry two flags (both false by default):

The requesting user and the comment’s author	The comment is returned as	Flags
The requesting user blocked the author	the full comment	`isAuthorBlocked: true`
The author blocked the requesting user, or both blocked each other	a placeholder	`isUnavailable: true`, `isAuthorBlocked: false`
No block	usual	both `false`

isAuthorBlocked reflects only the requesting user’s own preference. Your app decides how to render it — collapse it, offer “show anyway”, or hide it. The user can still reply to and react to it.
isUnavailable is neutral: the comment exists, but can’t be shown to this user, and the reason isn’t disclosed. Replying to or reacting to it is refused, so hide those controls.

The other responses that return a comment — create comment and search — don’t include these flags.

What `repliesCount` counts

repliesCount is the number of a comment’s direct replies, and it counts everything the thread contains: deleted, removed and unavailable replies included, since they stay in the thread as placeholders. It’s the same number for every user, and it matches what paging through the comment’s replies returns. Use it for display (“12 replies”), and use pagination.hasMore to decide whether to show a “load more” button. An entity’s commentsCount counts its comments at every depth by the same rule.

Models

Properties

Nested Types

GifData

Includes

The included entity

Placeholders

Moderation fields

Blocked authors

What `repliesCount` counts

See Also

​Properties

​Nested Types

​GifData

​Includes

​The included entity

​Placeholders

​Moderation fields

​Blocked authors

​What repliesCount counts

​See Also

Properties

Nested Types

GifData

Includes

The included entity

Placeholders

Moderation fields

Blocked authors

What `repliesCount` counts

See Also