Documentation | 2025.1

# Comments : Swarm Comments

From Swarm 2022.2, Swarm no longer supports APIs older than v9.

## Get List of Comments

GET /api/v9/comments/

### Summary

Get List of Comments

### Description

List comments.

- Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Core Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
- Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

### Parameters

Parameter | Description | Type | Parameter Type | Required | Default Value
--- | --- | --- | --- | --- | ---
after | A comment ID to seek to. Comments up to and including the specified ID are excluded from the results and do not count towards `max`. Useful for pagination. Commonly set to the `lastSeen` property from a previous query. | integer | query | No |
max | Maximum number of comments to return. This does not guarantee that `max` comments are returned. It does guarantee that the number of comments returned won’t exceed `max`. | integer | query | No | 100
topic | Only comments for given topic are returned. Examples: `reviews/1234`, `changes/1234` or `jobs/job001234`. | string | query | No |
context[version] | If a `reviews/1234` topic is provided, limit returned comments to a specific version of the provided review. | integer | query | No |
ignoreArchived | Prevents archived comments from being returned. (v5+) | boolean | query | No |
tasksOnly | Returns only comments that have been flagged as tasks. (v5+) | boolean | query | No |
taskStates | Limit the returned comments to ones that match the provided task state (one or more of `open`, `closed`, `verified`, or `comment`). (v5+) | array (of strings) | query | No |
fields | An optional comma-separated list (or array) of fields to show for each comment. Omitting this parameter or passing an empty value shows all fields. | string | query | No |

### Examples of successful responses

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "topic": "",
      "comments": {
        "51": {
          "id": 51,
          "attachments": [],
          "body": "Short loin ground round sin reprehensible, venison west participle triple.",
          "context": [],
          "edited": null,
          "flags": [],
          "likes": [],
          "taskState": "comment",
          "time": 1461164347,
          "topic": "reviews/885",
          "updated": 1461164347,
          "user": "bruno"
        }
      },
      "lastSeen": 51
    }

lastSeen can often be used as an offset for pagination, by using the value in the `after` parameter of subsequent requests.

#### When no results are found, the `comments` array is empty:

    HTTP/1.1 200 OK

    {
      "topic": "jobs/job000011",
      "comments": [],
      "lastSeen": null
    }

### Examples of usage

#### Listing comments

To list comments:

    curl -u "username:password" "https://my-swarm-host/api/v9/comments?topic=reviews/911&max=2&fields=id,body,time,user"

Swarm responds with a list of the first two comments for review 911 and a `lastSeen` value for pagination:

    HTTP/1.1 200 OK

    {
      "topic": "reviews/911",
      "comments": {
        "35": {
          "id": 35,
          "body": "Excitation thunder cats intelligent man braid organic bitters.",
          "time": 1461164347,
          "user": "bruno"
        },
        "39": {
          "id": 39,
          "body": "Chamber tote bag butcher, shirk truffle mode shabby chic single-origin coffee.",
          "time": 1461164347,
          "user": "swarm_user"
        }
      },
      "lastSeen": 39
    }

#### Paginating a comment listing

To obtain the next page of a comments list (based on the previous example):

    curl -u "username:password" "https://my-swarm-host/api/v9/comments?topic=reviews/911&max=2&fields=id,body,time,user&after=39"

Swarm responds with the second page of results, if any comments are present after the last seen comment:

    HTTP/1.1 200 OK

    {
      "topic": "reviews/911",
      "comments": {
        "260": {
          "id": 260,
          "body": "Reprehensible do lore flank ham hock.",
          "time": 1461164349,
          "user": "bruno"
        },
        "324": {
          "id": 324,
          "body": "Sinter lo-fi temporary, nihilist tote bag mustache swag consequence interest flexible.",
          "time": 1461164349,
          "user": "bruno"
        }
      },
      "lastSeen": 324
    }

## Send notification for comments

### Summary

Sends notification for comments

POST /api/v9/comments/notify

### Description

Sends notification for comments.

- Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Core Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
- Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
topic | This is going to send a single notification for any comments that were not notified immediately for the user authenticated for a given topic they are posting for. Example: `reviews/1234`. | string | form | Yes
preview | Set to true to check if there are comments waiting for a notification to be sent, the notification is not sent. | string | form | No

### Examples of successful responses

#### Comment notification sent.

    HTTP/1.1 200 OK

    {
      "isValid": true,
      "message": "Sending a notification for 3 comments",
      "code": 200
    }

#### No comments are waiting for a notification.

    HTTP/1.1 200 OK

    {
       "isValid": true,
       "message": "No comment notifications to send",
       "code": 200
    }

### Examples of usage

#### Sending notification for comments

To send a notification for all delayed comments:

    curl -u "username:password" \
         -X POST \
         -d "topic=reviews/911" \
         "https://my-swarm-host/api/v9/comments/notify"

Swarm responds with a message detailing a notification sent with the number of comments it applied to.

    HTTP/1.1 200 OK

    {
      "isValid": true,
      "message": "Sending a notification for 3 comments",
      "code": 200
    }

#### Checking to see if any comments are waiting for a notification to be sent

To check if there are any comments awaiting a notification without sending the notification, include "preview=true" in your request.

    curl -u "username:password" \
         -X POST \
         -d "topic=reviews/911" \
         -d "preview=true" \
         "https://my-swarm-host/api/v9/comments/notify"

Swarm responds with a message without sending a notification.

    HTTP/1.1 200 OK

    {
      "isValid": true,
      "message": "Sending a notification for 3 comments",
      "code": 200
      "preview": true
    }

## Add a Comment

### Summary

Add a Comment

POST /api/v9/comments/

### Description

Add a comment to a topic (such as a review or a job).

- Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Core Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
- Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

### Parameters

Parameter | Description | Type | Parameter Type | Required | Default Value
--- | --- | --- | --- | --- | ---
topic | Topic to comment on. Examples: `reviews/1234`, `changes/1234` or `jobs/job001234`. | string | form | Yes |
body | Content of the comment. | string | form | Yes |
silenceNotification | If set to 'true' no notifications will ever be sent for this created comment | string | form | No |
delayNotification | If set to 'true' notifications will be delayed | string | form | No |
taskState | Optional task state of the comment. Valid values when adding a comment are `comment` and `open`. This creates a plain comment or opens a task, respectively. | string | form | No | comment
flags[] | Optional flags on the comment. Typically set to `closed` to archive a comment. | array (of strings) | form | No |
context[file] | File to comment on. Valid only for `changes` and `reviews` topics. Example: `//depot/main/README.txt`. | string | form | No |
context[leftLine] | Left-side diff line to attach the inline comment to. Valid only for `changes` and `reviews` topics. If this is specified, `context[file]` must also be specified. | integer | form | No |
context[rightLine] | Right-side diff line to attach the inline comment to. Valid only for `changes` and `reviews` topics. If this is specified, `context[file]` must also be specified. | integer | form | No |
context[content] | Optionally provide content of the specified line and its four preceding lines. This is used to specify a short excerpt of context in case the lines being commented on change during the review. When not provided, Swarm makes an effort to build the content on its own - as this involves file operations, it could become slow. | array (of strings) | form | No |
context[version] | With a `reviews` topic, this field specifies which version to attach the comment to. | integer | form | No |

### Example of response

#### Successful Response contains Comment entity:

    HTTP/1.1 200 OK

    {
      "comment": {
        "id": 42,
        "attachments": [],
        "body": "Best. Comment. EVER!",
        "context": [],
        "edited": null,
        "flags": [],
        "likes": [],
        "taskState": "comment",
        "time": 123456789,
        "topic": "reviews/2",
        "updated": 123456790,
        "user": "bruno"
      }
    }

### Examples of usage

#### Create a comment on a review

To create a comment on a review:

    curl -u "username:password" \
         -X POST \
         -d "topic=reviews/2" \
         -d "body=This is my comment. It is an excellent comment. It contains a beginning, a middle, and an end." \
         "https://my-swarm-host/api/v9/comments"

JSON Response:

    HTTP/1.1 200 OK

    {
      "comment": {
        "id": 42,
        "attachments": [],
        "body": "This is my comment. It is an excellent comment. It contains a beginning, a middle, and an end.",
        "context": [],
        "edited": null,
        "flags": [],
        "likes": [],
        "taskState": "comment",
        "time": 123456789,
        "topic": "reviews/2",
        "updated": 123456790,
        "user": "username"
      }
    }

#### Open a task on a review

To create a comment on a review, and flag it as an open task:

    curl -u "username:password" \
         -X POST \
         -d "topic=reviews/2" \
         -d "taskState=open" \
         -d "body=If you could go ahead and attach a cover page to your TPS report, that would be great." \
         "https://my-swarm-host/api/v9/comments"

JSON Response:

    HTTP/1.1 200 OK

    {
      "comment": {
        "id": 43,
        "attachments": [],
        "body": "If you could go ahead and attach a cover page to your TPS report, that would be great.",
        "context": [],
        "edited": null,
        "flags": [],
        "likes": [],
        "taskState": "open",
        "time": 123456789,
        "topic": "reviews/2",
        "updated": 123456790,
        "user": "username"
      }
    }

## Edit a Comment

### Summary

Edit a Comment

PATCH /api/v9/comments/{id}

### Description

Edit a comment.

- Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Core Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
- Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | ID of the comment to be edited | integer | path | Yes
topic | Topic to comment on. Examples: `reviews/1234`, `changes/1234` or `jobs/job001234`. | string | form | No
body | Content of the comment. | string | form | Yes
taskState | Optional task state of the comment. Note that certain transitions (such as moving from `open` to `verified`) are not possible without an intermediate step (`addressed`, in this case). Examples: `comment` (not a task), `open`, `addressed`, `verified`. | string | form | No
flags[] | Optional flags on the comment. Typically set to `closed` to archive a comment. | array (of strings) | form | No
silenceNotification | If set to 'true' no notifications will ever be sent for this edited comment | string | form | No
delayNotification | If set to 'true' notifications will be delayed | string | form | No

### Example response

#### Successful Response contains Comment entity:

    HTTP/1.1 200 OK

    {
      "comment": {
        "id": 1,
        "attachments": [],
        "body": "Best. Comment. EVER!",
        "context": [],
        "edited": 123466790,
        "flags": [],
        "likes": [],
        "taskState": "comment",
        "time": 123456789,
        "topic": "reviews/42",
        "updated": 123456790,
        "user": "bruno"
      }
    }

### Examples of usage

#### Edit and archive a comment on a review

To edit and archive a comment on a review:

    curl -u "username:password" \
         -X PATCH \
         -d "flags[]=closed" \
         -d "body=This comment wasn't as excellent as I may have lead you to believe. A thousand apologies." \
         "https://my-swarm-host/api/v9/comments/42"

JSON Response:

    HTTP/1.1 200 OK

    {
      "comment": {
        "id": 42,
        "attachments": [],
        "body": "This comment wasn't as excellent as I may have lead you to believe. A thousand apologies.",
        "context": [],
        "edited": 123466790,
        "flags": ["closed"],
        "likes": [],
        "taskState": "comment",
        "time": 123456789,
        "topic": "reviews/2",
        "updated": 123456790,
        "user": "username"
      }
    }

#### Flag a task as addressed on a review

To flag an open task as addressed on a review:

    curl -u "username:password" \
         -X PATCH \
         -d "taskState=addressed" \
         "https://my-swarm-host/api/v9/comments/43"

JSON Response:

    HTTP/1.1 200 OK

    {
      "comment": {
        "id": 43,
        "attachments": [],
        "body": "If you could go ahead and attach a cover page to your TPS report, that would be great.",
        "context": [],
        "edited": 123466790,
        "flags": ["closed"],
        "likes": [],
        "taskState": "addressed",
        "time": 123456789,
        "topic": "reviews/2",
        "updated": 123456790,
        "user": "username"
      }
    }

Your search for returned results