Comments

Add and manage discussion comments on reports.

Overview

Comments allow users to discuss and annotate reports. Comments support threaded replies and are associated with user accounts.

GET /api/reports/{id}/comments

Get all top-level comments for a report.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Report ID

Query Parameters:

Parameter	Type	Default	Description
sort	string	-createdAt	Sort order (prefix with - for descending)
limit	integer	-	Maximum number of comments to return

Response:

{
  "_links": {
    "self": { "href": "/api/reports/{id}/comments" }
  },
  "_embedded": {
    "inf:comment": [
      {
        "id": "comment-uuid",
        "message": "Great analysis! Can we add regional breakdowns?",
        "userId": "john.doe",
        "reportId": "team:sales-dashboard",
        "parentId": null,
        "createdAt": "2024-02-08T14:30:00Z",
        "updatedAt": "2024-02-08T14:30:00Z",
        "_links": {
          "self": { "href": "/api/comments/comment-uuid" },
          "inf:comments": { "href": "/api/comments/comment-uuid/replies" }
        },
        "_embedded": {
          "inf:user": {
            "username": "john.doe",
            "displayName": "John Doe",
            "_links": {
              "self": { "href": "/api/users/john.doe" }
            }
          }
        }
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 5
}

Response Fields:

Field	Type	Description
id	string	Comment UUID
message	string	Comment text
userId	string	Username of commenter
reportId	string	Associated report ID
parentId	string	Parent comment ID (null for top-level)
createdAt	string	Creation timestamp
updatedAt	string	Last update timestamp

HAL Links:

• inf:comments - Link to nested replies (if this comment has children)

HAL Query Template:

{?sort,limit}

---

POST /api/reports/{id}/comments

Add a new comment to a report.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Report ID

Request Body:

{
  "message": "This is a great report! Can we add more visualizations?"
}

Required Fields:

Field	Type	Description
message	string	Comment text

Response:

{
  "id": "comment-uuid",
  "message": "This is a great report! Can we add more visualizations?",
  "userId": "john.doe",
  "reportId": "team:sales-dashboard",
  "parentId": null,
  "createdAt": "2024-02-09T10:00:00Z",
  "updatedAt": "2024-02-09T10:00:00Z",
  "_links": {
    "self": { "href": "/api/comments/comment-uuid" }
  }
}

Status Code: 201 Created

Location Header: URL of the created comment

Behavior:

• Comment is associated with the authenticated user
• Creates a reportAddedComment activity entry
• Executes in a database transaction

Use Case:

Allow users to discuss report findings, request changes, or provide feedback.

---

Threaded Replies

To reply to an existing comment, use the comment API endpoints (not documented here):

POST /api/comments/{parentId}/replies

This creates a child comment with parentId set to the parent comment's ID.

---

Comment Management

Comments can be managed via the Comment API endpoints:

• GET /api/comments/\{id\} - Get a specific comment
• PUT /api/comments/\{id\} - Update comment text
• DELETE /api/comments/\{id\} - Delete a comment
• GET /api/comments/\{id\}/replies - Get nested replies

See the Comment API documentation for full details.