Documentation | 2025.1

# Comments: Swarm comments

## Get comments for a review, change, or job

### Summary

Get a list of comments for a review, change, or job.

GET /api/v11/comments/<topic_subject>/<topic_id>

### Description

Get a list of comments for a review, change, or job. Only comments for the specified topic_subject and topic_id are returned. Valid topic_subject values are reviews, changes, and jobs.

For example:

- `GET /api/v11/comments/reviews/1234`

- `GET /api/v11/comments/changes/1234`

- `GET /api/v11/comments/jobs/job001234`

### 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
ignoreArchived | Prevents archived comments from being returned. | boolean | query | No |
tasksOnly | Returns only comments that have been flagged as tasks. | boolean | query | No |
taskState | Limit the returned comments to ones that match the provided task state (one or more of `open`, `closed`, `verified`, or `comment`). | 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 |

### Example usage

#### Get all comments for a review

Get all of the comments for review 885:

curl -u "username:ticket" "https://my-swarm-host/api/v11/comments/reviews/885"

Swarm responds with the comments for the specified review:

By default, this is limited to the 100 most recent comments. This can be changed by adding a max parameter value to the request.

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "id": 51,
            "topic": "reviews/885",
            "context": [],
            "attachments": [],
            "flags": [],
            "taskState": "comment",
            "likes": [],
            "user": "bruno"
            "time": 1619823600,
            "updated": 1619823600,
            "edited": null,
            "body": "This is a really good comment."
            "readBy": []
          },
          {
            "id": 63,
            "topic": "reviews/885",
            "context": [],
            "attachments": [],
            "flags": [],
            "taskState": "comment",
            "likes": [],
            "user": "alice"
            "time": 1620799560,
            "updated": 1620799560,
            "edited": null,
            "body": "This is my comment.",
            "readBy": []
          },
          {
            "id": 95,
            "topic": "reviews/885",
            "context": [],
            "attachments": [],
            "flags": [],
            "taskState": "comment",
            "likes": [],
            "user": "bob"
            "time": 1620813784,
            "updated": 1620813784,
            "edited": null,
            "body": "This is another comment.",
            "readBy": []
          },
        ],
        "lastSeen": 95,
        "totalCount": 3
      }
    }

#### Get a list of the first two comments for a review

Get a list of the first two comments for review 885:

curl -u "username:ticket" "https://my-swarm-host/api/v11/comments/reviews/885&max=2"

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

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "id": 51,
            "topic": "reviews/885",
            "context": [],
            "attachments": [],
            "flags": [],
            "taskState": "comment",
            "likes": [],
            "user": "bruno"
            "time": 1619823600,
            "updated": 1619823600,
            "edited": null,
            "body": "This is a really good comment.",
            "readBy": []
          },
          {
            "id": 63,
            "topic": "reviews/885",
            "context": [],
            "attachments": [],
            "flags": [],
            "taskState": "comment",
            "likes": [],
            "user": "alice"
            "time": 1620799560,
            "updated": 1620799560,
            "edited": null,
            "body": "This is my comment.",
            "readBy": []
          },
        ],
        "lastSeen": 63,
        "totalCount": 2
      }
    }

#### Paginating a comment listing

To get the next page of a comments list (based on the example above):

curl -u "username:ticket" "https://my-swarm-host/api/v11/comments/reviews/885&max=2&after=63"

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

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "topic": "reviews/885",
            "context": [],
            "attachments": [],
            "flags": [],
            "taskState": "comment",
            "likes": [],
            "user": "bob"
            "time": 1620813784,
            "updated": 1620813784,
            "edited": null,
            "body": "This is another comment.",
            "readBy": []
          },
        ],
        "lastSeen": 95,
        "totalCount": 1
      }
    }

#### If a request fails

<error code>:

- 401 you are not authorized to view the comments in the specified review
- 404 one of the following:

  - the topic_subject specified is not valid, it must be a reviews, changes, or jobs

  - the topic_id id specified does not exist

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Get a comment by ID

### Summary

Get comment details by comment id.

GET /api/v11/comments/<id>

### Description

Get comment details by comment id if the user has permission to view it. If the comment is a reply, the parent comment id is also returned.

- 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.

### Example usage

#### Get comment id 1627

curl -u "username:ticket" "https://my-swarm-host/api/v11/comments/1627"

Swarm responds with the comment details:

    {
      "error": null,
      "messages": [],
      "data": {
        "comments":
          "id": 1627,
          "topic": "reviews/2004",
          "context": {
            "file": "//projects/acme/main/src/xml.c",
            "leftLine": 46,
            "rightLine": 48,
            "content": [
              " ",
              "   // Commodo magnis posuere lobortis.",
              "-  tincidunt = cumLigula * 100;",
              "-  data++;",
              "   int suspendisse = 0;"
            ],
            "type": "text",
            "review": 2004,
            "version": 1,
            "change": null,
            "md5": "e66e0d0d88b2f39fb721132adda7ecf5",
            "name": "xml.c",
            "line": 48
          },
          "attachments": [
            17,
            18,
            107,
            108,
            110,
            111
          ],
          "flags": [],
          "taskState": "comment",
          "likes": [],
          "user": "aaron.gleber",
          "time": 1649147498,
          "updated": 1650640678,
          "edited": 1650638878,
          "body": "This comment gives some examples of images you can use.",
          "readBy": []
        }
      }
    }

#### Get the parent comment of comment id 525

curl -u "username:ticket" "https://my-swarm-host/api/v11/comments/525"

Swarm responds with comment id 501 which is the parent of comment id 525:

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          "id": 525,
          "topic": "reviews/12373",
          "context": {
            "comment": 501,
            "version": 2
          },
          "attachments": [],
          "flags": [],
          "taskState": "comment",
          "likes": [],
          "user": "alice"
          "time": 1622712940,
          "updated": 1622712940,
          "edited": null,
          "body": "dao save test 1",
          "readBy": [],
          "notify": "delayed"
        }
      }
    }

#### If a request fails

<error code>:

- 401 you are not authorized to view the comments
- 404 the comment id specified does not exist

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Add a comment

### Summary

Add a comment to a review, change, or job.

POST /api/v11/comments/<topic_subject>/<topic_id>

### Description

Add a comment to a review, change, or job. The user that makes the API request is set as comment author.

Valid topic_subject values are reviews, changes, and jobs.

For example:

- `POST /api/v11/comments/reviews/1234`

- `POST /api/v11/comments/changes/1234`

- `POST /api/v11/comments/jobs/job001234`

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
body | The text content of the comment. | string | form | Yes
taskState | Optional task state of the comment. Valid values when adding a comment are comment (default) and open. This creates a plain comment or opens a task, respectively. If the taskState parameter is not in the request, the task state is set to comment. | string | form | No
notify | Comment notifications can be delayed, see Comment notification delay. The notify parameter enables you to set when the notification for the comment is sent. Valid options are: delayed (default): notifications for this comment are delayed by the time set in Comment notification delay immediate: the notification for this comment is sent immediately silent: no notification is sent for this comment | string | query | No
context | Used to add the comment to a file in the review. Valid fields are: file mandatory unless attribute or comment are set: File to comment on. Valid only for `changes` and `reviews` topics. For example, `//depot/main/README.txt`. leftline optional, but if specified, you must also specify the rightline and content parameters. Integer: Left-side diff line number to attach the inline comment to. Valid only for `changes` and `reviews` topics. rightline optional, but if specified, you must also specify the leftline and content parameters. Integer: Right-side diff line number to attach the inline comment to. Valid only for `changes` and `reviews` topics. content optional, but if specified, you must also specify the leftline and rightline parameters.Array of strings: Provide the content of the codeline the comment is on and the four preceding codelines. This is used to specify a short excerpt of context in case the lines being commented on change during the review. When set to null, Swarm makes an effort to build the content on its own. Because this involves file operations, it might be slow. version optional, integer: With a `reviews` topic, this field specifies which version to attach the comment to. attribute optional: Set to description to comment on the review description. comment optional, integer: Set to the comment id this comment is replying to. | array | form | No

### Example usage

#### Add a comment to a review

Add a comment to review 885, make the comment an open task, and send the notification immediately:

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://my-swarm-host/api/v11/comments/reviews/885?notify=immediate"

The "mybodyfilename.txt" file contains the authenticated user's comment and makes the comment an open task:

    {
      "body": "This is another comment.",
      "taskState": "open"
    }

Swarm responds the comment entity:

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "id": 95,
            "topic": "reviews/885",
            "context": [],
            "attachments": [],
            "flags": [],
            "taskState": "open",
            "likes": [],
            "user": "bob"
            "time": 1620813784,
            "updated": 1620813784,
            "edited": null,
            "body": "This is another comment.",
            "readBy": [],
            "notify": "immediate"
          },
        ],
        "userDelayedNotificationCount": 1
      }
    }

#### Add a comment to a file in a review

Add a comment to the end of the //depot/main/README.txt file on review 123:

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://my-swarm-host/api/v11/comments/reviews/123"

The "mybodyfilename.txt" file contains the authenticated user's comment for the file:

    {
      "body": "This is a comment on a file.",
      "context":{
        "file": "//depot/main/README.txt"
      }
    }

Swarm responds the comment entity:

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "id": 105,
            "topic": "reviews/123",
            "context": {
              "file": "//depot/main/README.txt",
              "leftLine": null,
              "rightLine": null,
              "content": [],
              "version": 1,
              "change": 122,
              "review": 123,
              "md5": "6af0e07c2d96afacaf2da234242c3cbd",
              "name": "README.txt"
              "line": null
            },
            "attachments": [],
            "flags": [],
            "taskState": "open",
            "likes": [],
            "user": "bob"
            "time": 1620813784,
            "updated": 1620813784,
            "edited": null,
            "body": "This is a comment on a file.",
            "readBy": [],
            "notify": "delayed"
          },
        ],
        "userDelayedNotificationCount": 1
      }
    }

#### Add a comment to a line in a file and include context for the comment

To populate the content field, you need to know the content of the line you are commenting on and the content of the four lines before the line you are commenting on

Add a comment to a line in a file on review 110 with the following information:

- Full filepath and filename of the file to comment on

- Left and right line numbers of the diff to comment on

- Text of the codeline you are commenting on and the four codelines before that to provide context for the comment

- Review version to add the comment to

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://my-swarm-host/api/v11/comments/reviews/110"

The "mybodyfilename.txt" file contains the details for the new comment:

    {
      "body": "This is a comment on a line in a file with context.",
      "context":{
        "file": "//depot/main/README.txt"
        "rightLine": 54,
        "leftLine": null,
        "content": {
          "FORTRAN default = \"\" ;\n",
          "LIBDIR default = /boot/develop/libraries ;\n",
          "-LINK default = $(CC) ;\n",
          "+LINK default = mwld ;\n",
          "+LINKFLAGS default = \"\" ;\n"
        },
        "version": 3
      }
    }

Swarm responds the comment entity:

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "id": 143,
            "topic": "reviews/110",
            "context": {
              "file": "//depot/main/README.txt"
              "leftLine": null,
              "rightLine": 54,
              "content": [
                "FORTRAN default = \"\" ;\n",
                "LIBDIR default = /boot/develop/libraries ;\n",
                "-LINK default = $(CC) ;\n",
                "+LINK default = mwld ;\n",
                "+LINKFLAGS default = \"\" ;\n"
              },
              "version": 3,
              "change": 109,
              "review": 110,
              "md5": "6af0e07c2d96afacaf2da234242c3cbd",
              "name": "README.txt",
              "line": 54
            }
            "attachments": [],
            "flags": [],
            "taskState": "open",
            "likes": [],
            "user": "bob"
            "time": 1620813784,
            "updated": 1620813784,
            "edited": null,
            "body": "This is a comment on a line in a file with context.",
            "readBy": [],
            "notify": "delayed"
          },
        ],
        "userDelayedNotificationCount": 1
      }
    }

#### Add a comment to a review description

Add a comment to the description of review 885 and delay the notification:

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://my-swarm-host/api/v11/comments/reviews/885?notify=delayed"

The "mybodyfilename.txt" file contains the authenticated user's comment and adds it to the review description:

    {
      "body": "This is a comment on the description.",
      "context":{
        "attribute": "description"
      },
    }

Swarm responds the comment entity:

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "id": 99,
            "topic": "reviews/885",
            "context": {
              "attribute": "description"
            },
            "attachments": [],
            "flags": [],
            "taskState": "comment",
            "likes": [],
            "user": "bob"
            "time": 1620813784,
            "updated": 1620813784,
            "edited": null,
            "body": "This is a comment on the description.",
            "readBy": [],
            "notify": "delayed"
          },
        ],
        "userDelayedNotificationCount": 1
      }
    }

#### Reply to a comment

You have two options when replying to a comment. Although the URLs for the options are different, they both do the same job:

- Reply to a comment using POST /api/v11/comments/<topic_subject>/<topic_id>

- Reply to a comment using POST /api/v11/comments/<id>

##### Reply to a comment using POST /api/v11/comments/<topic_subject>/<topic_id>

Add a reply to comment id 99 in review 885:

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://my-swarm-host/api/v11/comments/reviews/885"

The "mybodyfilename.txt" file contains the authenticated user's comment text and the comment the reply is for:

    {
      "body": "This is a reply to a comment.",
      "context": {
        "comment": 99
      }
    }

Swarm responds the comment entity:

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "id": 109,
            "topic": "reviews/885",
            "context": {
              "comment": 99,
              "version": 2
            },
            "attachments": [],
            "flags": [],
            "taskState": "comment",
            "likes": [],
            "user": "bruno"
            "time": 1622712940,
            "updated": 1622712940,
            "edited": null,
            "body": "This is a reply to a comment.",
            "readBy": [],
            "notify": "delayed"
          }
        ],
        "userDelayedNotificationCount": 1
      }
    }

##### Reply to a comment using POST /api/v11/comments/<id>

Add a reply to comment id 99 in review 885:

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://my-swarm-host/api/v11/comments/99"

The "mybodyfilename.txt" file contains the authenticated user's comment text and the comment the reply is for:

    {
      "body": "This is a reply to a comment.",
      "topic": "reviews/885"
    }

Swarm responds the comment entity:

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "id": 120,
            "topic": "reviews/885",
            "context": {
              "comment": 99,
              "version": 2
            },
            "attachments": [],
            "flags": [],
            "taskState": "comment",
            "likes": [],
            "user": "bruno"
            "time": 1622712940,
            "updated": 1622712940,
            "edited": null,
            "body": "This is another reply to a comment.",
            "readBy": [],
            "notify": "delayed"
          }
        ]
        "userDelayedNotificationCount": 1
      }
    }

#### If a request fails

<error code>:

- 400 one of the following:

  - the id specified must be an integer greater than 0

  - invalid context field specified, valid fields are file, leftline, rightline, content, version, attribute, and comment

  - invalid notify value specified, value must be delayed, immediate, or silent

  - invalid taskState value specified, value must be open or comment

- 403: you are not authorized to create this comment
- 404 the review, change, job, review version, file line number, or file specified does not exist
- 409 invalid topic_subject specified, value must be reviews, changes, or jobs
- 500 internal error, request failed

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Edit a comment

### Summary

Edit a comment.

POST /api/v11/comments/{comment_id}/edit

### Description

Only the author of the original comment can edit it. Users with admin or super permissions cannot edit a comment by another user.

Edit a comment. Only the parameters specified in the API request are updated for the comment, the rest of the comment parameters are left unchanged.

When a comment is edited:

- The comment time stamp is marked as (edited) to show that the comment has been changed.

- All of the likes for the comment are removed.

- If users have marked the comment as read, the comment read status is reset to unread for those users.

- Swarm sends a notification to everyone involved in the review, including the review author and the reviewers, but not the editor of the comment.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
body | The text content of the comment. | string | form | No
taskState | The task state of the comment. Valid values are comment, open, addressed, and verified. Certain transitions (such as moving from open to verified) are not possible without an intermediate step (addressed, in this case). | string | form | No
notify | Comment notifications can be delayed, see Comment notification delay. The notify parameter enables you to set when the notification for the comment is sent. Valid options are: delayed (default): notifications for this comment are delayed by the time set in Comment notification delay immediate: the notification for this comment is sent immediately silent: no notification is sent for this comment | string | query | No

#### Edit a comment

Edit the text of comment id 95, set its task state to addressed, and send the comment notification immediately:

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://my-swarm-host/api/v11/comments/95/edit?notify=immediate"

The "mybodyfilename.txt" file contains the comment author's edited text and the new task state value:

    {
      "body": "This is an edit to this comment.",
      "taskState": "addressed"
    }

Swarm responds with:

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "id": 95,
            "topic": "reviews/885",
            "context": [],
            "attachments": [],
            "flags": [],
            "taskState": "addressed",
            "likes": [],
            "user": "bob"
            "time": 1620813784,
            "updated": 1620813784,
            "edited": true,
            "body": "This is an edit to this comment.",
            "readBy": [],
            "notify": "immediate"
          },
        ],
        "userDelayedNotificationCount": 1
      }
    }

#### If a request fails

<error code>:

- 400 one of the following:

  - the comment-id specified must be an integer greater than 0

  - invalid notify value specified, value must be delayed, immediate, or silent

  - invalid taskState value specified, value must be open, comment, addressed, or verified

- 403: you are not authorized to edit this comment, you must be the comment author
- 404 the comment_id specified does not exist

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Mark a comment as read

### Summary

Mark a comment as read for the authenticated user.

POST /api/v11/comments/{id}/read

### Description

Mark a comment as read for the authenticated user.

### Example usage

Mark comment id 1626 as read for Bruno:

curl -X POST -u "bruno:ticket" "https://my-swarm-host/api/v11/comments/1626/read"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "id": 1626,
            "topic": "reviews/2004",
            "context": {
              "file": "//projects/acme/main/src/xml.c",
              "leftLine": null,
              "rightLine": 36,
              "version": 1,
              "content": [
                "/**",
                " * Fringilla duis feugiat natoque. Mauris fames cursus, adipiscing justo",
                " * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque",
                "+ * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque",
                "+ * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque"
              ],
              "change": null,
              "review": null,
              "md5": "e66e0d0d88b2f39fb721132adda7ecf5",
              "name": "xml.c",
              "line": 36
            },
            "attachments": [
              14,
              15,
              16
            ],
            "flags": [
              "closed"
            ],
            "taskState": "comment",
            "likes": [],
            "user": "aaron.gleber",
            "time": 1649147456,
            "updated": 1650981576,
            "edited": 1649147475,
            "body": "We have lots of repeated comments.",
            "readBy": [
              "bruno"
            ],
            "notify": "delayed"
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 400 the comment-id specified must be an integer greater than 0
- 404 the comment_id specified does not exist

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Mark a comment as unread

### Summary

Mark a comment as unread for the authenticated user.

POST /api/v11/comments/{id}/unread

### Description

Mark a comment as unread for the authenticated user.

### Example usage

Mark comment id 1626 as unread for Bruno:

curl -X POST -u "bruno:ticket" "https://my-swarm-host/api/v11/comments/1626/unread"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "id": 1626,
            "topic": "reviews/2004",
            "context": {
              "file": "//projects/acme/main/src/xml.c",
              "leftLine": null,
              "rightLine": 36,
              "version": 1,
              "content": [
                "/**",
                " * Fringilla duis feugiat natoque. Mauris fames cursus, adipiscing justo",
                " * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque",
                "+ * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque",
                "+ * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque"
              ],
              "change": null,
              "review": null,
              "md5": "e66e0d0d88b2f39fb721132adda7ecf5",
              "name": "xml.c",
              "line": 36
            },
            "attachments": [
              14,
              15,
              16
            ],
            "flags": [
              "closed"
            ],
            "taskState": "comment",
            "likes": [],
            "user": "aaron.gleber",
            "time": 1649147456,
            "updated": 1650981576,
            "edited": 1649147475,
            "body": "We have lots of repeated comments.",
            "readBy": [],
            "notify": "delayed"
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 400 the comment-id specified must be an integer greater than 0
- 404 the comment_id specified does not exist

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Mark all comments read

### Summary

Mark all comments on a review as read for the authenticated user.

POST /api/v11/reviews/{id}/comments/read

### Description

Mark all comments on a review as read for the authenticated user.

### Example usage

Mark comments on review 2004 as read for Vernon Renno:

curl -X POST -u "vernon.renno:ticket" "https://my-swarm-host/api/v11/reviews/2004/comments/read"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "id": 1626,
            "topic": "reviews/2004",
            "context": {
              "file": "//projects/acme/main/src/xml.c",
              "leftLine": null,
              "rightLine": 36,
              "version": 1,
              "content": [
                "/**",
                " * Fringilla duis feugiat natoque. Mauris fames cursus, adipiscing justo",
                " * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque",
                "+ * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque",
                "+ * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque"
              ],
              "change": null,
              "review": null,
              "md5": "e66e0d0d88b2f39fb721132adda7ecf5",
              "name": "xml.c",
              "line": 36
            },
            "attachments": [
              14,
              15,
              16
            ],
            "flags": [
              "closed"
            ],
            "taskState": "comment",
            "likes": [],
            "user": "aaron.gleber",
            "time": 1649147456,
            "updated": 1650981576,
            "edited": 1649147475,
            "body": "We have lots of repeated comments.",
            "readBy": [
              "vernon.renno"
            ],
            "notify": "delayed"
          },
          {
          ...
          <other comment ids formatted as above>
          ...
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 400 the review id specified must be an integer greater than 0
- 404 the review id specified does not exist

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Mark all comments unread

### Summary

Mark all comments on a review as unread for the authenticated user.

POST /api/v11/reviews/{id}/comments/unread

### Description

Mark all comments on a review as unread for the authenticated user.

### Example usage

Mark comments on review 2004 as unread for Vernon Renno:

curl -X POST -u "vernon.renno:ticket" "https://my-swarm-host/api/v11/reviews/2004/comments/unread"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "id": 1626,
            "topic": "reviews/2004",
            "context": {
              "file": "//projects/acme/main/src/xml.c",
              "leftLine": null,
              "rightLine": 36,
              "version": 1,
              "content": [
                "/**",
                " * Fringilla duis feugiat natoque. Mauris fames cursus, adipiscing justo",
                " * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque",
                "+ * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque",
                "+ * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque"
              ],
              "change": null,
              "review": null,
              "md5": "e66e0d0d88b2f39fb721132adda7ecf5",
              "name": "xml.c",
              "line": 36
            },
            "attachments": [
              14,
              15,
              16
            ],
            "flags": [
              "closed"
            ],
            "taskState": "comment",
            "likes": [],
            "user": "aaron.gleber",
            "time": 1649147456,
            "updated": 1650981576,
            "edited": 1649147475,
            "body": "We have lots of repeated comments.",
            "readBy": [],
            "notify": "delayed"
          },
          {
          ...
          <other comment ids formatted as above>
          ...
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 400 the review id specified must be an integer greater than 0
- 404 the review id specified does not exist

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Archive a comment

### Summary

Archive a comment.

POST /api/v11/comments/{id}/archive

### Description

Archive a comment. The Archive option is only available for top level comments, if the comment has replies they are archived with the parent comment.

### Example usage

Archive comment id 1626:

curl -X POST -u "bruno:ticket" "https://my-swarm-host/api/v11/comments/1626/archive"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "id": 1626,
            "topic": "reviews/2004",
            "context": {
              "file": "//projects/acme/main/src/xml.c",
              "leftLine": null,
              "rightLine": 36,
              "version": 1,
              "content": [
                "/**",
                " * Fringilla duis feugiat natoque. Mauris fames cursus, adipiscing justo",
                " * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque",
                "+ * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque",
                "+ * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque"
              ],
              "change": null,
              "review": null,
              "md5": "e66e0d0d88b2f39fb721132adda7ecf5",
              "name": "xml.c",
              "line": 36
            },
            "attachments": [
              14,
              15,
              16
            ],
            "flags": [
              "closed"
            ],
            "taskState": "comment",
            "likes": [],
            "user": "aaron.gleber",
            "time": 1649147456,
            "updated": 1650988005,
            "edited": 1649147475,
            "body": "We have lots of repeated comments.",
            "readBy": [
              "vernon.renno"
            ],
            "notify": "delayed"
          },
          {
            "id": 1628,
            "topic": "reviews/2004",
            "context": {
              "file": "//projects/acme/main/src/xml.c",
              "leftLine": null,
              "rightLine": 36,
              "version": 1,
              "content": [
                "/**",
                " * Fringilla duis feugiat natoque. Mauris fames cursus, adipiscing justo",
                " * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque",
                "+ * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque",
                "+ * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque"
              ],
              "change": null,
              "review": null,
              "md5": "e66e0d0d88b2f39fb721132adda7ecf5",
              "name": "xml.c",
              "line": 36,
              "comment": 1626
            },
            "attachments": [
              19
            ],
            "flags": [
              "closed"
            ],
            "taskState": "comment",
            "likes": [],
            "user": "aaron.gleber",
            "time": 1649147599,
            "updated": 1650988005,
            "edited": 1649147611,
            "body": "This is a reply comment,",
            "readBy": []
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 400 the comment-id specified must be an integer greater than 0
- 404 the comment_id specified does not exist

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Restore an archived comment

### Summary

Restore an archived comment.

POST /api/v11/comments/{id}/unarchive

### Description

Restore an archived comment. If the archived comment has replies, the replies are also restored.

### Example usage

Restore archived comment id 1626:

curl -X POST -u "bruno:ticket" "https://my-swarm-host/api/v11/comments/1626/unarchive"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
          {
            "id": 1626,
            "topic": "reviews/2004",
            "context": {
              "file": "//projects/acme/main/src/xml.c",
              "leftLine": null,
              "rightLine": 36,
              "version": 1,
              "content": [
                "/**",
                " * Fringilla duis feugiat natoque. Mauris fames cursus, adipiscing justo",
                " * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque",
                "+ * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque",
                "+ * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque"
              ],
              "change": null,
              "review": null,
              "md5": "e66e0d0d88b2f39fb721132adda7ecf5",
              "name": "xml.c",
              "line": 36
            },
            "attachments": [
              14,
              15,
              16
            ],
            "flags": [],
            "taskState": "comment",
            "likes": [],
            "user": "aaron.gleber",
            "time": 1649147456,
            "updated": 1650989315,
            "edited": 1649147475,
            "body": "We have lots of repeated comments.",
            "readBy": [],
            "notify": "delayed"
          },
          {
            "id": 1628,
            "topic": "reviews/2004",
            "context": {
              "file": "//projects/acme/main/src/xml.c",
              "leftLine": null,
              "rightLine": 36,
              "version": 1,
              "content": [
                "/**",
                " * Fringilla duis feugiat natoque. Mauris fames cursus, adipiscing justo",
                " * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque",
                "+ * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque",
                "+ * arcu consectetuer. Condimentum sed hymenaeos sit, pellentesque"
              ],
              "change": null,
              "review": null,
              "md5": "e66e0d0d88b2f39fb721132adda7ecf5",
              "name": "xml.c",
              "line": 36,
              "comment": 1626
            },
            "attachments": [
              19
            ],
            "flags": [],
            "taskState": "comment",
            "likes": [],
            "user": "aaron.gleber",
            "time": 1649147599,
            "updated": 1650989315,
            "edited": 1649147611,
            "body": "This is a reply comment,",
            "readBy": []
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 400 the comment-id specified must be an integer greater than 0
- 404 the comment_id specified does not exist

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Add a reaction

### Summary

Add a reaction.

POST /api/v11/comments/{id}/addReaction

### Description

Add a thumbs up to a comment.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
reactions | Used to add a reaction icon to a comment. Valid fields are: thumbsup mandatory, added to a comment. | array | form | Yes

### Example usage

Add a thumbs up to the comment id 28:

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://my-swarm-host/api/v11/comments/28/addReaction"

The "mybodyfilename.txt" file contains the username and reaction icon:

    {
      "reactions": {
          "thumbsup": "bruno"
          }
    }

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "id": 28,
            "topic": "reviews/12625",
            "context": {
              "file": "//jam/main/src/make.c",
              "version": 1,
              "leftLine": 5,
              "rightLine": 5,
              "content": [
                " * Copyright 1993, 1995 Christopher Seiwald.",
                " *",
                "- * This file is part of Jam - see jam.c for Copyright information. This is change 1 and this is change 2 and change 3 change 4",
                "+ * This file is part of Jam - see jam.c for Copyright information. This is change 1 and this is change 2 and change 3 change 4 and change 4",
                " */"
              ],
              "change": null,
              "review": null,
              "md5": "8e79caff1ae9cdbd21b1581b554331ba",
              "name": "make.c",
              "line": 5
            },
            "attachments": [],
            "flags": [],
            "taskState": "comment",
            "likes": [],
            "user": "bruno",
            "time": 1690801379,
            "updated": 1690801556,
            "edited": null,
            "body": "THis is test reaction comment",
            "readBy": [],
            "notify": "delayed",
            "reactions": {
              "thumbsup": [
                "bruno"
              ]
            }
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 400 the comment-id specified must be an integer greater than 0
- 404 the comment_id specified does not exist

## Remove a reaction

### Summary

Remove a reaction.

DELETE /api/v11/comments/{id}/removeReaction

### Description

Removes the thumbs up from a comment.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
reactions | Used to remove a reaction icon from a comment. Valid fields are: thumbsup mandatory, removed from a comment. | array | form | Yes

### Example usage

Remove the thumbs up from the comment id 28:

curl -X DELETE -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://my-swarm-host/api/v11/comments/28/removeReaction"

The "mybodyfilename.txt" file contains the username and the reaction icon to be removed from the comment:

    {
      "reactions": {
          "thumbsup": "bruno"
          }
    }

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "id": 28,
            "topic": "reviews/12625",
            "context": {
              "file": "//jam/main/src/make.c",
              "version": 1,
              "leftLine": 5,
              "rightLine": 5,
              "content": [
                " * Copyright 1993, 1995 Christopher Seiwald.",
                " *",
                "- * This file is part of Jam - see jam.c for Copyright information. This is change 1 and this is change 2 and change 3 change 4",
                "+ * This file is part of Jam - see jam.c for Copyright information. This is change 1 and this is change 2 and change 3 change 4 and change 4",
                " */"
              ],
              "change": null,
              "review": null,
              "md5": "8e79caff1ae9cdbd21b1581b554331ba",
              "name": "make.c",
              "line": 5
            },
            "attachments": [],
            "flags": [],
            "taskState": "comment",
            "likes": [],
            "user": "bruno",
            "time": 1690801379,
            "updated": 1690801556,
            "edited": null,
            "body": "THis is test reaction comment",
            "readBy": [],
            "reactions": [],
            "notify": "delayed"
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 400 the comment-id specified must be an integer greater than 0
- 404 the comment_id specified does not exist

## Add a comment with an attachment to a review

### Summary

Add a comment with an attachment to a review.

POST /api/v11/comments/reviews/{id}

### Description

Add a comment with an attachment to a review. This is a two-step process:

1. Create a stand-alone attachment.

   Once the attachment is created, Swarm assigns a unique id to the attachment. The unique attachment id is returned in the response. See Create an attachment.

2. Pass the unique attachment id as a parameter using the POST /api/v11/comments/reviews/{id} API endpoint.

   You have now successfully added a comment with an attachment to a review.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Review ID. | integer | path | Yes
body | The text content of the comment. | string | form | Yes
taskState | Optional task state of the comment. Valid values when adding a comment are comment (default) and open. This creates a plain comment or opens a task, respectively. If the taskState parameter is not in the request, the task state is set to comment. | string | form | No
notify | Comment notifications can be delayed, see Comment notification delay. The notify parameter enables you to set when the notification for the comment is sent. Valid options are: delayed (default): notifications for this comment are delayed by the time set in Comment notification delay immediate: the notification for this comment is sent immediately silent: no notification is sent for this comment | string | query | No
context | Used to add the comment to a file in the review. Valid fields are: file mandatory unless attribute or comment are set: File to comment on. Valid only for `changes` and `reviews` topics. For example, `//depot/main/README.txt`. type: the filetype of the file, text, binary, symlink, unicode, utf8, utf16, apple, or resource. For more information on filetypes, see the Base filetypes section of the Helix Core Command-Line (P4) Reference. version optional, integer: With a `reviews` topic, this field specifies which version to attach the comment to. leftline optional, but if specified, you must also specify the rightline and content parameters. Integer: Left-side diff line number to attach the inline comment to. Valid only for `changes` and `reviews` topics. rightline optional, but if specified, you must also specify the leftline and content parameters. Integer: Right-side diff line number to attach the inline comment to. Valid only for `changes` and `reviews` topics. content optional, but if specified, you must also specify the leftline and rightline parameters. Array of strings: Provide the content of the codeline the comment is on and the four preceding codelines. This is used to specify a short excerpt of context in case the lines being commented on change during the review. When set to null, Swarm makes an effort to build the content on its own. Because this involves file operations, it might be slow. | array | form | No
attachments | Attachment id generated using the Create an attachment API endpoint. | integer | form | Yes

### Example usage

Create a comment with attachment id 12, make the comment an open task, and delay sending the comment notification:

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://my-swarm-host/api/v11/comments/reviews/885"

The "mybodyfilename.txt" file contains the authenticated user's comment, the attachment id 12, and makes the comment an open task:

    {
      "body": "This is another comment.",
      "taskState": "open"
      "context" : {
        "file": "//depot/Jam/MAIN/src/jamgram.c",
        "type": "text",
        "version": 0,
        "leftLine": 13,
        "rightLine": 13,
        "content": [
            "#define yyerrok (yyerrflag=0)",
            "#define YYRECOVERING (yyerrflag!=0)",
            "-/* cfront 1.2 defines \"c_plusplus\" instead of \"__cplusplus\" */",
            "+/* cfront 1.2 defines \"c_plusplus\" instead of \"__cplusplus\" */ change 1",
            "#ifdef c_plusplus"
          ]
        },
       "attachments": [12]
      }
    }

Swarm responds the comment entity:

    {
      "error": null,
      "messages": [],
      "data": {
      "comments": [
        {
          "id": 123,
          "topic": "reviews/12923",
          "context": {
          "file": "//depot/Jam/MAIN/src/jamgram.c",
          "version": 0,
          "leftLine": 13,
          "rightLine": 13,
          "content": [
            "#define yyerrok (yyerrflag=0)",
            "#define YYRECOVERING (yyerrflag!=0)",
            "-/* cfront 1.2 defines \"c_plusplus\" instead of \"__cplusplus\" */",
            "+/* cfront 1.2 defines \"c_plusplus\" instead of \"__cplusplus\" */ change 1",
            "#ifdef c_plusplus"
           ]
         }
         "attachments": [
           12
         ],
         "flags": [],
         "taskState": "open",
         "likes": [],
         "user": "bruno",
         "time": 1699003426,
         "updated": 1699003426,
         "edited": null,
         "body": "This is another comment.",
         "readBy": [],
         "notify": "delayed"
        }
       ],
       "userDelayedNotificationCount": 2
      }
    }

#### If a request fails

<error code>:

- 400 one of the following:

  - the id specified must be an integer greater than 0

  - invalid context field specified, valid fields are file, leftline, rightline, content, version, attribute, and comment

  - invalid notify value specified, value must be delayed, immediate, or silent

  - invalid taskstate value specified, value must be open or comment

- 403: you are not authorized to create this comment
- 404 the attachment does not exist
- 500 internal error, request failed

Your search for returned results