# Comments

Threaded discussions on posts and changelogs. Comments support voting, moderation, and privacy controls.

## List comments

 - [GET /v2/comments](https://docs.featurebase.app/rest-api/comments/listcomments.md): Returns comments for your organization.

Comments are threaded discussions. Each comment can have:
- Author information
- Voting (upvotes/downvotes)
- Privacy settings (public/private)
- Moderation status
- Parent comment reference for threading

### Filtering

Optionally filter by:
- postId - Get comments for a specific post
- changelogId - Get comments for a specific changelog

If no filter is provided, returns all comments across the organization.

### Pagination

This endpoint uses cursor-based pagination:

- limit - Number of comments to return (1-100, default 10)
- cursor - Opaque cursor from a previous response's nextCursor field

Example: To paginate through results:
1. First request: GET /v2/comments?postId={id}&limit=10
2. If nextCursor is not null, use it for the next page
3. Next request: GET /v2/comments?postId={id}&limit=10&cursor={nextCursor}

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of comment objects (flat structure with parentCommentId for threading)
- nextCursor - Cursor for the next page (null if no more results)

### Comment Structure

Each comment includes:
- id - Unique comment identifier
- postId / changelogId - Reference to the parent content
- parentCommentId - Reference to parent comment (null for root comments)
- content - Comment content in HTML format
- author - Author information (id, name, profilePicture, type)
- upvotes / downvotes / score - Voting metrics
- isPrivate - Whether comment is only visible to admins
- inReview - Whether comment is pending moderation
- created / updated - Unix timestamps

### Additional Filters

- privacy - Filter by privacy: "public", "private", or "all"
- inReview - Filter by moderation status (true/false)

### Sorting

Use sortBy to sort results:
- best - Sort by confidence score (default, like Reddit)
- top - Sort by net score (upvotes - downvotes)
- new - Sort by creation date, newest first
- old - Sort by creation date, oldest first

## Create a new comment

 - [POST /v2/comments](https://docs.featurebase.app/rest-api/comments/createcomment.md): Creates a new comment or reply to an existing comment.

You can create a comment for a post or changelog. Comments support:
- HTML content (images are automatically uploaded to our storage)
- Threading (replies via parentCommentId)
- Privacy controls (private comments visible only to admins)
- Author attribution (post on behalf of users)

### Required Fields

- content - Comment content in HTML format
- postId OR changelogId - One is required to specify the target

### Optional Fields

- parentCommentId - Create a reply to an existing comment
- isPrivate - Make comment visible only to admins (default: false)
- sendNotification - Notify voters about the comment (default: true)
- author - Post comment under a specific user (uses authenticated user if not provided)
- createdAt - Backdate creation (useful for imports)

### Author Object

The author field supports multiple identification methods:
- id - Featurebase user ID (direct reference)
- userId - External user ID from your system (via SSO)
- email - Email address (finds existing or creates new user)
- name - Display name (used with email for new users)
- profilePicture - Profile picture URL

If no author is provided, the comment is posted under the authenticated user.

### Content Format

Content should be formatted as HTML. For images:
- External URLs in img src attributes are automatically pulled into our storage
- Base64 encoded data URIs (data:image/...) are also supported and processed

### Response

Returns the created comment object with all fields populated, including:
- id - Unique comment identifier
- author - Author information
- Voting stats and timestamps

### Errors

- 400 - Invalid input (missing required fields, invalid IDs)
- 403 - Commenting disabled or not authorized
- 404 - Post/changelog not found or parent comment not found

## Get a comment by ID

 - [GET /v2/comments/{id}](https://docs.featurebase.app/rest-api/comments/getcomment.md): Retrieves a single comment by its unique identifier.

Returns the full comment object including:
- Author information
- Voting stats (upvotes, downvotes, score)
- Privacy and moderation status
- Threading information (parentCommentId)
- Timestamps

### Response

Returns a comment object with all fields populated.

### Errors

- 400 - Invalid comment ID format
- 404 - Comment not found or doesn't belong to your organization

## Update a comment

 - [PATCH /v2/comments/{id}](https://docs.featurebase.app/rest-api/comments/updatecomment.md): Updates an existing comment by its unique identifier.

You can update:
- content - Comment text (HTML format)
- isPrivate - Privacy status (admin-only visibility)
- isPinned - Pinned status (displayed at top)
- inReview - Moderation status

### Content Format

Content should be formatted as HTML. For images:
- External URLs in img src attributes are automatically pulled into our storage
- Base64 encoded data URIs (data:image/...) are also supported and processed

### Permissions

- Comment authors can update their own comment content
- Admin permissions required for:
  - isPrivate - Requires manage_comments_private permission
  - isPinned - Requires set_comment_pinned permission
  - inReview - Requires moderate_comments permission
  - Updating other users' comments - Requires moderate_comments permission

### Response

Returns the updated comment object with all fields populated.

### Errors

- 400 - Invalid comment ID format or input
- 403 - Not authorized to update this comment
- 404 - Comment not found

## Delete a comment

 - [DELETE /v2/comments/{id}](https://docs.featurebase.app/rest-api/comments/deletecomment.md): Deletes a comment by its unique identifier.

### Deletion Behavior

- Comments with replies: Soft delete
  - Content is replaced with "[deleted]"
  - Author information is anonymized
  - Comment remains visible to maintain conversation context
  - Votes and scores are reset to 0

- Comments without replies: Hard delete
  - Comment is permanently removed from the database
  - All associated data is deleted

### Permissions

- Comment authors can delete their own comments
- Admins can delete any comment (subject to permissions)
- Lite seat admins can only delete their own comments
- Non-authors require manage_comments or manage_comments_private permission

### Response

Returns a deletion confirmation:

json
{
  "id": "507f1f77bcf86cd799439011",
  "object": "comment",
  "deleted": true
}


### Errors

- 400 - Invalid comment ID format
- 403 - Not authorized to delete this comment
- 404 - Comment not found or doesn't belong to your organization

## Delete a comment

 - [DELETE /v2/comment](https://docs.featurebase.app/rest-api/comments/deletecommentclover.md): Deletes a comment using the legacy Clover API format.

This endpoint accepts the comment ID in the request body instead of the route parameter.

### Request Body

json
{
  "id": "507f1f77bcf86cd799439011"
}


### Deletion Behavior

- Comments with replies: Soft delete
  - Content is replaced with "[deleted]"
  - Author information is anonymized
  - Comment remains visible to maintain conversation context
  - Votes and scores are reset to 0

- Comments without replies: Hard delete
  - Comment is permanently removed from the database
  - All associated data is deleted

### Permissions

- Comment authors can delete their own comments
- Admins can delete any comment (subject to permissions)
- Lite seat admins can only delete their own comments
- Non-authors require manage_comments or manage_comments_private permission

### Response

Returns a success confirmation (Clover format):

json
{
  "success": true
}


Note: Nova API returns { id, object: "comment", deleted: true }, but Clover transformer converts it to { success: true } for backwards compatibility.

### Errors

- 400 - Invalid comment ID format or missing ID in body
- 403 - Not authorized to delete this comment
- 404 - Comment not found or doesn't belong to your organization