## List comments

**get** `/v2/comments`

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`
1. If `nextCursor` is not null, use it for the next page
1. 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

### Query Parameters

- `changelogId: optional string`

  Filter comments by changelog ID

- `cursor: optional string`

  Cursor for pagination. Use nextCursor from previous response.

- `inReview: optional boolean`

  Filter by review status

- `limit: optional number`

  Maximum number of comments to return

- `postId: optional string`

  Filter comments by post ID

- `privacy: optional "public" or "private" or "all"`

  Filter comments by privacy

  - `"public"`

  - `"private"`

  - `"all"`

- `sortBy: optional "best" or "top" or "new" or "old"`

  Sort order for comments

  - `"best"`

  - `"top"`

  - `"new"`

  - `"old"`

### Header Parameters

- `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"`

  - `"2026-01-01.nova"`

  - `"2025-12-12.clover"`

### Returns

- `data: array of Comment`

  Array of comments

  - `id: string`

    Unique identifier

  - `author: object { id, name, profilePicture, type }`

    - `id: string`

      Author unique identifier

    - `name: string`

      Author display name

    - `profilePicture: string`

      Author profile picture URL

    - `type: "admin" or "customer" or "guest" or 3 more`

      Type of user who authored the comment

      - `"admin"`

      - `"customer"`

      - `"guest"`

      - `"integration"`

      - `"bot"`

      - `"lead"`

  - `changelogId: string`

    Changelog ID this comment belongs to

  - `content: string`

    Comment content in HTML format

  - `createdAt: string`

    ISO 8601 timestamp when created

  - `downvotes: number`

    Number of downvotes

  - `inReview: boolean`

    Whether the comment is in review

  - `isDeleted: boolean`

    Whether the comment is deleted

  - `isPinned: boolean`

    Whether the comment is pinned

  - `isPrivate: boolean`

    Whether the comment is private

  - `isSpam: boolean`

    Whether the comment is spam

  - `object: "comment"`

    Object type identifier

    - `"comment"`

  - `parentCommentId: string`

    Parent comment ID for replies, null for root comments

  - `postId: string`

    Post ID this comment belongs to

  - `score: number`

    Net score (upvotes - downvotes)

  - `updatedAt: string`

    ISO 8601 timestamp when updated

  - `upvotes: number`

    Number of upvotes

- `nextCursor: string`

  Cursor for fetching the next page (cursor-based pagination)

- `object: "list"`

  Object type identifier

  - `"list"`

- `pagination: optional object { limit, page, total, totalPages }`

  Pagination metadata for page-based requests

  - `limit: number`

    Items per page

  - `page: number`

    Current page number

  - `total: number`

    Total number of items

  - `totalPages: number`

    Total number of pages

### Example

```http
curl https://do.featurebase.app/v2/comments \
    -H "Authorization: Bearer $FEATUREBASE_API_KEY"
```

#### Response

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "author": {
        "id": "507f1f77bcf86cd799439011",
        "name": "John Doe",
        "profilePicture": "https://cdn.example.com/avatars/john.png",
        "type": "customer"
      },
      "changelogId": "507f1f77bcf86cd799439013",
      "content": "<p>This is a great idea!</p>",
      "createdAt": "2023-12-12T00:00:00.000Z",
      "downvotes": 0,
      "inReview": false,
      "isDeleted": false,
      "isPinned": false,
      "isPrivate": false,
      "isSpam": false,
      "object": "comment",
      "parentCommentId": "507f1f77bcf86cd799439014",
      "postId": "507f1f77bcf86cd799439012",
      "score": 5,
      "updatedAt": "2023-12-13T00:00:00.000Z",
      "upvotes": 5
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9",
  "object": "list",
  "pagination": {
    "limit": 10,
    "page": 1,
    "total": 42,
    "totalPages": 5
  }
}
```