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 |
integer |
query |
No |
|
|
max |
Maximum number of comments to return. This does not guarantee that |
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 |
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:
|
string |
query |
No |
|
context |
Used to add the comment to a file in the review. Valid fields are:
|
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>
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:
|
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:
|
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:
|
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
