# Create a new comment

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

Endpoint: POST /v2/comments
Version: 2026-01-01.nova
Security: bearerAuth

## Header parameters:

  - `Featurebase-Version` (string)
    API version for this request. Defaults to your organization's configured API version if not specified.
    Example: "2026-01-01.nova"

## Request fields (application/json):

  - `content` (string, required)
    Comment content in HTML format
    Example: "<p>This is a great idea!</p>"

  - `postId` (string)
    Post ID to comment on (accepts ObjectId or slug)
    Example: "507f1f77bcf86cd799439011"

  - `changelogId` (string)
    Changelog ID to comment on (accepts ObjectId or slug)
    Example: "507f1f77bcf86cd799439012"

  - `parentCommentId` (string)
    Parent comment ID if this is a reply
    Example: "507f1f77bcf86cd799439013"

  - `isPrivate` (boolean,null)
    Whether the comment is private (only visible to admins)

  - `sendNotification` (boolean,null)
    Whether to notify voters of the submission about the comment
    Example: true

  - `author` (object)
    Author to attribute the post to. If not provided, uses the authenticated user. Supports multiple identification methods: id (Featurebase ID), userId (external SSO ID), or email.

  - `author.id` (string)
    Featurebase user ID to attribute content to
    Example: "507f1f77bcf86cd799439011"

  - `author.userId` (string)
    External user ID from your system (matched via SSO)
    Example: "usr_12345"

  - `author.email` (string)
    Author email (used to find or create user)
    Example: "john@example.com"

  - `author.name` (string)
    Author display name
    Example: "John Doe"

  - `author.profilePicture` (string)
    Author profile picture URL
    Example: "https://example.com/avatar.png"

  - `createdAt` (string,null)
    Set the date when the comment was created. Useful for importing comments from other platforms.
    Example: "2025-01-15T10:30:00.000Z"

  - `upvotes` (integer,null)
    Initial upvotes count. Useful for importing comments from other platforms. Score will be calculated as upvotes - downvotes.
    Example: 5

  - `downvotes` (integer,null)
    Initial downvotes count. Useful for importing comments from other platforms. Score will be calculated as upvotes - downvotes.

## Response 201 fields (application/json):

  - `object` (string, required)
    Object type identifier
    Enum: "comment"

  - `id` (string, required)
    Unique identifier
    Example: "507f1f77bcf86cd799439011"

  - `postId` (string,null, required)
    Post ID this comment belongs to
    Example: "507f1f77bcf86cd799439012"

  - `changelogId` (string,null, required)
    Changelog ID this comment belongs to
    Example: "507f1f77bcf86cd799439013"

  - `parentCommentId` (string,null, required)
    Parent comment ID for replies, null for root comments
    Example: "507f1f77bcf86cd799439014"

  - `content` (string, required)
    Comment content in HTML format
    Example: "<p>This is a great idea!</p>"

  - `author` (object,null, required)

  - `author.id` (string,null, required)
    Author unique identifier
    Example: "507f1f77bcf86cd799439011"

  - `author.name` (string, required)
    Author display name
    Example: "John Doe"

  - `author.profilePicture` (string,null, required)
    Author profile picture URL
    Example: "https://cdn.example.com/avatars/john.png"

  - `author.type` (string, required)
    Type of user who authored the comment
    Enum: "admin", "customer", "guest", "integration", "bot", "lead"

  - `upvotes` (number, required)
    Number of upvotes
    Example: 5

  - `downvotes` (number, required)
    Number of downvotes

  - `score` (number, required)
    Net score (upvotes - downvotes)
    Example: 5

  - `isPrivate` (boolean, required)
    Whether the comment is private

  - `isDeleted` (boolean, required)
    Whether the comment is deleted

  - `isPinned` (boolean, required)
    Whether the comment is pinned

  - `inReview` (boolean, required)
    Whether the comment is in review

  - `isSpam` (boolean, required)
    Whether the comment is spam

  - `createdAt` (string, required)
    ISO 8601 timestamp when created
    Example: "2023-12-12T00:00:00.000Z"

  - `updatedAt` (string, required)
    ISO 8601 timestamp when updated
    Example: "2023-12-13T00:00:00.000Z"

## Response 400 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "invalid_request_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "invalid_request"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 400

## Response 403 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "authorization_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "feature_disabled"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 403

## Response 404 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "invalid_request_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "post_not_found", "comment_not_found"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 404