GET /comments?projectId — fetch all comments

Use this endpoint to retrieve every comment left by reviewers on a given project. Each comment includes metadata such as status, priority, assignee, tags, and optional screenshot or attachment URLs. By default, comment text is returned as HTML; pass plainText=true if your integration works better with plain text. Pass locationMetadata=true to additionally receive the exact position of each comment — pin coordinates and DOM path for websites, HTML files, and email projects; page number, pin coordinates, annotation tool, shape data, and timestamp for images, PDFs, presentations, documents, widgets, apps, videos, and audio.

GET https://api.bugsmash.io/api/v2/comments?projectId={projectId}

Query parameters

string

required

UUID of the project whose comments you want to retrieve.

boolean

Pass true to receive comment text as plain text instead of HTML. Defaults to false.

boolean

Pass true to include location metadata (exact pixel or DOM location) on each comment. When omitted or false, location_metadata and comment_metadata are not returned. Defaults to false.

Request example

curl --location 'https://api.bugsmash.io/api/v2/comments?projectId={projectId}&plainText=true&locationMetadata=true' \
--header 'X-API-Key: YOUR_API_KEY'

Response example

{
  "status": true,
  "message": "Feedback data",
  "data": [
    {
      "comment_id": "{commentId}",
      "comment": "<p>This section needs more contrast</p>",
      "comment_number": 1,
      "status": "Active",
      "created_at": "2026-08-01T14:17:48.000000Z",
      "updated_at": "2026-08-01T14:17:48.000000Z",
      "is_private": true,
      "comment_by_name": "John Doe",
      "comment_by_email": "user@example.com",
      "assigned_to_name": null,
      "assigned_to_email": null,
      "priority": "Unset",
      "attachment_file_url": null,
      "audio_file_url": null,
      "comment_screenshot_file_url": null,
      "tags": [
        {
          "id": "{tagId}",
          "name": "UI-UX",
          "color": "#F3F4F6"
        },
        {
          "id": "{tagId}",
          "name": "Design",
          "color": "#FEF9C3"
        }
      ]
    }
  ]
}

Response fields

boolean

true when the request succeeded.

string

Human-readable description of the result.

array

Array of comment objects.

Show Comment object properties

string

UUID of the comment.

string

Comment text. Returned as HTML by default, or plain text when plainText=true.

number

Sequential number identifying this comment within the project.

string

Current status of the comment. Either "Active" or "Resolved".

string

ISO 8601 timestamp of when the comment was created.

string

ISO 8601 timestamp of the most recent update.

boolean

Whether the comment is private and visible only to the workspace.

string

Display name of the reviewer who posted the comment.

string

Email address of the reviewer who posted the comment.

string

Display name of the assignee. null if unassigned.

string

Email address of the assignee. null if unassigned.

string

Priority level. One of "Unset", "P1", "P2", "P3", or "P4".

string

URL of the file attached to the comment. null if no attachment.

string

URL of the audio note attached to the comment. null if the comment is not an audio comment.

string

URL of the context screenshot captured with the comment. null if not present.

array

Tags applied to the comment.

Show Tag object

string

UUID of the tag.

string

Display name of the tag.

string

Hex color code used to render the tag chip.

object

Only returned when locationMetadata=true. Browser/viewport context of the reviewer, or null for non-web project types. See the location metadata sections below for shape.

object

Only returned when locationMetadata=true. Shape depends on the project type — see the two sections below.

Location metadata: Website, HTML, and Email projects

When ?locationMetadata=true and the project is a website, HTML file, or email, each comment includes comment_metadata and a rich location_metadata block covering pin position, device breakpoint, and the annotated DOM node.

{
  "status": true,
  "message": "Feedback data",
  "data": [
    {
      "comment_id": "{commentId}",
      "comment": "<p>This section needs more contrast.</p>",
      "comment_number": 19,
      "status": "Active",
      "created_at": "2026-04-02T14:33:18.000000Z",
      "updated_at": "2026-04-02T14:33:18.000000Z",
      "is_private": false,
      "comment_by_name": "John Doe",
      "comment_by_email": "user@example.com",
      "assigned_to_name": null,
      "assigned_to_email": null,
      "priority": "Unset",
      "attachment_file_url": null,
      "comment_screenshot_file_url": "https://cdn.bugsmash.io/files/{workspaceId}/image/screenshot-example.png",
      "comment_metadata": {
        "browser": "Chrome",
        "view": "Desktop"
      },
      "location_metadata": {
        "page_url": "https://example.com/",
        "pin": {
          "x": "18.015625px",
          "y": "8.78125px"
        },
        "device": {
          "code": "L",
          "label": "Desktop",
          "viewport_width_range": {
            "min": 1280,
            "max": null
          }
        },
        "text_content": null,
        "is_screenshot_mode": false,
        "element_bounding_box": {
          "x": "18.015625px",
          "y": "8.78125px",
          "width": 150,
          "height": 33.38
        },
        "dom": {
          "closest_parent_selector": ".scroller > .brands-list:nth-child(1)",
          "dom_path": "main:nth-child(3) > section:nth-child(1) > div:nth-child(1) > div:nth-child(4) > div:nth-child(2) > ul:nth-child(1) > li:nth-child(10) > img:nth-child(1)",
          "fallback_path": ".brands-list > li:nth-child(10) > img:nth-child(1)",
          "element_tag": "img"
        }
      },
      "tags": [
        {
          "id": "{tagId}",
          "name": "UI-UX",
          "color": "#F3F4F6"
        }
      ]
    }
  ]
}

object

Reviewer’s browser context at the time of comment.

Show Properties

string

Browser name, e.g. "Chrome", "Firefox", "Safari".

string

Human-readable viewport class, e.g. "Desktop", "Tablet", "Mobile".

object

Position and DOM context of the comment.

Show Properties

string

URL of the page the comment was left on.

object

Pixel-space position of the comment pin.

Show Pin coordinates

string

Horizontal position from the left of the viewport, in pixels.

string

Vertical position from the top of the viewport, in pixels.

object

Device / breakpoint the reviewer was viewing.

Show Device properties

string

Single-letter device code. L = Desktop, M = Tablet, S = Mobile, I = Screenshot.

string

Human-readable label, e.g. "Desktop".

object

Viewport width range for the device breakpoint.

Show Range

number

Minimum width in pixels.

number

Maximum width in pixels. null when there is no upper bound (e.g. widescreen desktop).

string

Selected text content, if the reviewer highlighted text before commenting. null otherwise.

boolean

true if the comment was left on a captured screenshot rather than the live page. When true, element_bounding_box and dom are null.

object

Bounding box of the annotated DOM element. null when is_screenshot_mode is true.

Show Bounding box

string

Left edge in pixels.

string

Top edge in pixels.

number

Width in pixels.

number

Height in pixels.

object

DOM path to the annotated element. null when is_screenshot_mode is true.

Show DOM properties

string

CSS selector for the nearest identifiable parent element.

string

Full CSS selector path from the document root to the element.

string

Shorter fallback selector to use if dom_path fails to resolve after a page change.

string

HTML tag of the annotated element, e.g. "img", "div", "button".

When ?locationMetadata=true and the project type is image, PDF, PPT, doc, widget, app, video, or audio, each comment includes a simpler location_metadata block covering page number, pin coordinates, annotation tool, and timestamp. comment_metadata is null for these project types.

{
  "status": true,
  "message": "Feedback data",
  "data": [
    {
      "comment_id": "{commentId}",
      "comment": "<p>This section needs more contrast.</p>",
      "comment_number": 19,
      "status": "Active",
      "created_at": "2026-04-02T14:33:18.000000Z",
      "updated_at": "2026-04-02T14:33:18.000000Z",
      "is_private": false,
      "comment_by_name": "John Doe",
      "comment_by_email": "user@example.com",
      "assigned_to_name": null,
      "assigned_to_email": null,
      "priority": "Unset",
      "attachment_file_url": null,
      "comment_screenshot_file_url": "https://cdn.bugsmash.io/files/{workspaceId}/image/screenshot-example.png",
      "comment_metadata": null,
      "location_metadata": {
        "page_no": 1,
        "pin": {
          "x": "0.469",
          "y": "0.256"
        },
        "annotation_tool": "marker",
        "shape_type": null,
        "shape_data": null,
        "timestamp": null
      },
      "tags": [
        {
          "id": "{tagId}",
          "name": "UI-UX",
          "color": "#F3F4F6"
        }
      ]
    }
  ]
}

object

Position of the comment on the file.

Show Properties

number

Page number the comment sits on. For single-page assets (image, widget, video, audio) this is always 1.

object

Normalized pin coordinates (0.0 – 1.0 relative to the asset). null for audio comments.

Show Pin coordinates

string

Normalized horizontal position.

string

Normalized vertical position.

string

Tool used to place the annotation, e.g. "marker", "pen", "rectangle", "arrow".

string

Shape type when the annotation is a drawn shape (e.g. "rectangle", "circle"). null for pin markers.

object

Geometry payload describing the drawn shape. Shape depends on shape_type. null for pin markers.

number

Time offset in seconds within the media, for video and audio comments. null for image, PDF, PPT, doc, widget, and app projects.

Folders

Versions

Projects

Comments

Webhooks

GET /comments?projectId — fetch all comments

Query parameters

Request example

Response example

Response fields

Location metadata: Website, HTML, and Email projects

Location metadata: Image, PDF, PPT, Doc, Widget, App, Video, Audio projects

​Query parameters

​Request example

​Response example

​Response fields

​Location metadata: Website, HTML, and Email projects

​Location metadata: Image, PDF, PPT, Doc, Widget, App, Video, Audio projects

Query parameters

Request example

Response example

Response fields

Location metadata: Website, HTML, and Email projects

Location metadata: Image, PDF, PPT, Doc, Widget, App, Video, Audio projects