Documentation | 2025.1

# Reviews: Swarm reviews

## Get a list of reviews

### Summary

Get a list of reviews.

GET /api/v11/reviews

### Description

List the reviews the user has permission to view.

- 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
--- | --- | --- | --- | ---
max | Specify the maximum number of results to return as an integer greater than 0. If the max parameter is not specified, the 50 most recent reviews are returned. | integer | query | No
project[] | To limit the results to a list of reviews in a specific project or projects, specify the projects you want reviews returned for. | string or an array (of strings) | query | No
after | A review ID to seek to. Reviews 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. Reviews are returned in the order they were created in, starting with the most recently created review. You cannot use the after and afterUpdated parameters in the same request, they are mutually exclusive. | string | query | No
afterUpdated | Return reviews updated on the day before the date/time specified in the afterUpdated parameter. The parameter value must be set in seconds since epoch. The seconds since epoch value for the day reviews are returned for is included at the end of the response. Used by the Swarm team to step backwards one day at a time, loading reviews in an iterative process by using the value returned in a response as the afterUpdated parameter value for the next request. To return the most recently updated reviews on top, use the resultOrder parameter in conjunction with afterUpdated parameter. For example,resultOrder=updated For example: Requested: afterUpdated=1606233362 (Tuesday November 24th, 2020, 15:56:02) Response fetched for: any reviews updated on Monday November 23rd, 2020. 1606175999 (Monday, 23 November 2020 23:59:59) is added to the end of the response You cannot use the after and afterUpdated parameters in the same request, they are mutually exclusive. | string | query | No
resultOrder | Return most recently updated reviews on top. Valid value is updated. For example, resultOrder=updated When using resultOrder=updated, reviews will be retrieved for an entire day at a time. If there are hundreds or thousands of reviews updated that day, then all of them will be retrieved, regardless of the maximum number of reviews allowed to be displayed on the Swarm review page. | string | query | No
state[] | To limit the results to a list of reviews in a specific state or states, specify the states you want reviews returned for. Valid review states are: needsRevision review needs revision needsReview review needs review approved review is approved approved:isPending review is approved but not committed approved:commit review is approved and committed approved:notPending review is approved and committed rejected review is rejected archived review is archived | string or an array (of strings) | query | No
keywords | To limit the results to a list of reviews that contain a specified keyword in a specified review field, use the keywords parameter in conjunction with the keywordsFields parameter. Multiple keywordFields can be specified. | string | query | No but required if keywordsFields is used
keywordsFields[] | To limit the results to a list of reviews that contain a specified keyword in a specified review field, use the keywordsFields parameter in conjunction with the keywords parameter. Multiple keywordFields can be specified. Valid keywordFields indexed on a review are: changes author participants hasReviewer description updated projects state testStatus pending groups id | string or an array (of strings) | query | No but required if keywords is used
fields[] | To limit the fields returned for the reviews, add the fields parameter to the request. Multiple fields can be specified. | string or an array (of strings) | query | No

### Example usage

#### Get a list of reviews

curl -u "username:ticket" "https://myswarm-url/api/v11/reviews"

Swarm responds with the review entities:

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

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews": [{
            "id": 12345,
            "type": "default",
            "changes": [
              12344,
            ],
            "commits": [],
            "author": "bruno",
            "approvals": null,
            "participants": ["bruno"],
            "participantsData": {
              "bruno": []
            },
            "hasReviewer": 0,
            "description": "Review for my code change",
            "created": 1594265070,
            "updated": 1594266228,
            "projects": {
              "myproject": ["main"]
            },
            "state": "needsReview",
            "stateLabel": "Needs Review",
            "testStatus": "fail",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 1,
              "lines_deleted": 0
            },
          },
          ...
          <other review ids formatted as above>
          ...
        ],
        "totalCount": 1,
        "lastSeen": 12345
      }
    }

#### Get a list of the 25 most recent reviews

curl -u "username:ticket" "https://myswarm-url/api/v11/reviews?max=25"

Swarm responds with the 25 most recent review entities:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews": [{
            "id": 12345,
            "type": "default",
            "changes": [
              12344,
            ],
            "commits": [],
            "author": "bruno",
            "approvals": null,
            "participants": ["bruno"],
            "participantsData": {
              "bruno": []
            },
            "hasReviewer": 0,
            "description": "Review for my code change",
            "created": 1594265070,
            "updated": 1594266228,
            "projects": {
              "myproject": ["main"]
            },
            "state": "needsReview",
            "stateLabel": "Needs Review",
            "testStatus": "fail",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 1,
              "lines_deleted": 0
            },
          },
          ...
          <other review ids formatted as above>
          ...
        ],
        "totalCount": 1,
        "lastSeen": 12345
      }
    }

#### Get a list of reviews for the myproject project

curl -u "username:ticket" "https://myswarm-url/api/v11/reviews?project=myproject"

Swarm responds with the review entities for the myproject project:

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

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews": [{
            "id": 12345,
            "type": "default",
            "changes": [
              12344,
            ],
            "commits": [],
            "author": "bruno",
            "approvals": null,
            "participants": ["bruno"],
            "participantsData": {
              "bruno": []
            },
            "hasReviewer": 0,
            "description": "Review for my code change",
            "created": 1594265070,
            "updated": 1594266228,
            "projects": {
              "myproject": ["main"]
            },
            "state": "needsReview",
            "stateLabel": "Needs Review",
            "testStatus": "fail",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 1,
              "lines_deleted": 0
            },
          },
          ...
          <other review ids formatted as above>
          ...
        ],
        "totalCount": 1,
        "lastSeen": 12345
      }
    }

#### Get a list of reviews for the myproject and gemini projects

curl -u "username:ticket" "https://myswarm-url/api/v11/reviews?project[]=myproject&project[]=gemini"

Swarm responds with the review entities for the myproject and gemini projects:

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

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews": [{
            "id": 12345,
            "type": "default",
            "changes": [
              12344,
            ],
            "commits": [],
            "author": "bruno",
            "approvals": null,
            "participants": ["bruno"],
            "participantsData": {
              "bruno": []
            },
            "hasReviewer": 0,
            "description": "Review for my code change",
            "created": 1594265070,
            "updated": 1594266228,
            "projects": {
              "myproject": ["main"]
            },
            "state": "needsReview",
            "stateLabel": "Needs Review",
            "testStatus": "fail",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 1,
              "lines_deleted": 0
            },
          },
            "id": 12356,
            "type": "default",
            "changes": [
              12350,
            ],
            "commits": [],
            "author": "jsmith",
            "approvals": null,
            "participants": ["jsmith"],
            "participantsData": {
              "jsmith": []
            },
            "hasReviewer": 0,
            "description": "Another one of my reviews",
            "created": 1594265070,
            "updated": 1594266228,
            "projects": {
              "gemini": ["main"]
            },
            "state": "needsReview",
            "stateLabel": "Needs Review",
            "testStatus": "pass",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 1,
              "lines_deleted": 0
            },
          },
          ...
          <other review ids formatted as above>
          ...
        ],
        "totalCount": 2,
        "lastSeen": 12356
      }
    }

#### Get a list of reviews that have jam in the projects or description fields

curl -u "username:ticket" "https://myswarm-url/api/v11/reviews?keywords=jam&keywordsFields[]=projects&keywordsFields[]=description"

Swarm responds with the review entities with "jam" in either the projects or description fields:

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

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews": [{
            "id": 12340,
            "type": "default",
            "changes": [
              12339,
            ],
            "commits": [],
            "author": "bruno",
            "approvals": null,
            "participants": ["bruno"],
            "participantsData": {
              "bruno": []
            },
            "hasReviewer": 0,
            "description": "Review for my code change",
            "created": 1594265070,
            "updated": 1594266228,
            "projects": {
              "jam": ["main"]
            },
            "state": "needsReview",
            "stateLabel": "Needs Review",
            "testStatus": "fail",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 1,
              "lines_deleted": 0
            },
          },
            "id": 12360,
            "type": "default",
            "changes": [
              12359,
            ],
            "commits": [],
            "author": "jsmith",
            "approvals": null,
            "participants": ["jsmith"],
            "participantsData": {
              "jsmith": []
            },
            "hasReviewer": 0,
            "description": "Another one of my reviews and this one has jam in the description",
            "created": 1594265070,
            "updated": 1594266228,
            "projects": {
              "gemini": ["main"]
            },
            "state": "needsReview",
            "stateLabel": "Needs Review",
            "testStatus": "pass",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 1,
              "lines_deleted": 0
            },
          },
          ...
          <other review ids formatted as above>
          ...
        ],
        "totalCount": 2,
        "lastSeen": 12360
      }
    }

#### Get a review associated with a change

Get details of a review associated with a specific change 12345. The curl example is using the &fields=id parameter to reduce the size of the output.

curl https://mywarm-url/api/v11/reviews?keywords=12345&keywordsFields[]=changes&fields=id

Swarm responds with the review associated with the change 12345 which is 12346.

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
      "reviews": [
        {
          "id": 12346
        }
      ],
      "totalCount": 1,
      "lastSeen": 12344
     }
    }

#### Limit fields returned in a list of reviews

Get a list of reviews and limit the fields returned to id, author, and pending:

curl -u "username:ticket" "https://myswarm-url/api/v11/reviews?fields[]=id&fields[]=pending&fields[]=author"

Swarm responds with the review entities:

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

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews": [{
            "id": 12345,
            "author": "bruno",
            "pending": true,
          },
          ...
          <other review ids formatted as above>
          ...
        ],
        "totalCount": 7,
        "lastSeen": 12352
      }
    }

#### Get a list of reviews created after review 12344

curl -u "username:ticket" "https://myswarm-url/api/v11/reviews?after=12344"

Swarm responds with the review entities:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews": [{
            "id": 12345,
            "type": "default",
            "changes": [
              12345,
            ],
            "commits": [],
            "author": "bruno",
            "approvals": null,
            "participants": ["bruno"],
            "participantsData": {
              "bruno": []
            },
            "hasReviewer": 0,
            "description": "Review for my code change",
            "created": 1594265070,
            "updated": 1594266228,
            "projects": {
              "myproject": ["main"]
            },
            "state": "needsReview",
            "stateLabel": "Needs Review",
            "testStatus": "fail",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 1,
              "lines_deleted": 0
            },
          },
          ...
          <other review ids formatted as above>
          ...
        ],
        "totalCount": 7,
        "lastSeen": 12352
      }
    }

#### Get a list of reviews updated during the day before the set date

Request reviews updated on the day before 1606233362 (Tuesday November 24th, 2020, 15:56:02)

curl -u "username:ticket" "https://myswarm-url/api/v11/reviews?afterUpdated=1606233362"

Swarm return all reviews that were updated on the day before the date/time specified in your request. In this example, Swarm responds with any reviews that were updated on Monday November 23rd 2020. The seconds since epoch value Swarm used is added to the end of the response:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews": [{
            "id": 12345,
            "type": "default",
            "changes": [
              12345,
            ],
            "commits": [],
            "author": "bruno",
            "approvals": null,
            "participants": ["bruno"],
            "participantsData": {
              "bruno": []
            },
            "hasReviewer": 0,
            "description": "Review for my code change",
            "created": 1594265070,
            "updated": 1606119044,
            "projects": {
              "myproject": ["main"]
            },
            "state": "needsReview",
            "stateLabel": "Needs Review",
            "testStatus": "fail",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 1,
              "lines_deleted": 0
            },
          },
          ...
          <other review ids formatted as above>
          ...
        ],
        "totalCount": 25,
        "lastSeen": "0",
        "afterUpdated": "1606089600"
      }
    }

#### Get a list of reviews that need review

curl -u "username:ticket" "https://myswarm-url/api/v11/reviews?state=needsReview"

Swarm responds with the review entities in the needsReview state:

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

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews": [{
            "id": 12345,
            "type": "default",
            "changes": [
              12344,
            ],
            "commits": [],
            "author": "bruno",
            "approvals": null,
            "participants": ["bruno"],
            "participantsData": {
              "bruno": []
            },
            "hasReviewer": 0,
            "description": "Review for my code change",
            "created": 1594265070,
            "updated": 1594266228,
            "projects": {
              "myproject": ["main"]
            },
            "state": "needsReview",
            "stateLabel": "Needs Review",
            "testStatus": "fail",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 1,
              "lines_deleted": 0
            },
          },
          ...
          <other review ids formatted as above>
          ...
        ],
        "totalCount": 1,
        "lastSeen": 12345
      }
    }

#### Get a list of reviews that are open

Reviews are considered open when they are in any one of three states:

- needsReview
- needsRevision
- approved:isPending

curl -u "username:ticket" "https://myswarm-url/api/v11/reviews?state[]=approved:isPending&state[]=needsReview&state[]=needsRevision"

Swarm responds with the review entities for open reviews:

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

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews": [{
            "id": 12345,
            "type": "default",
            "changes": [
              12344,
            ],
            "commits": [],
            "author": "bruno",
            "approvals": null,
            "participants": ["bruno"],
            "participantsData": {
              "bruno": []
            },
            "hasReviewer": 0,
            "description": "Review for my code change",
            "created": 1594265070,
            "updated": 1594266228,
            "projects": {
              "myproject": ["main"]
            },
            "state": "needsReview",
            "stateLabel": "Needs Review",
            "testStatus": "fail",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 1,
              "lines_deleted": 0
            },
          },
            "id": 12356,
            "type": "default",
            "changes": [
              12350,
            ],
            "commits": [],
            "author": "jsmith",
            "approvals": null,
            "participants": ["jsmith"],
            "participantsData": {
              "jsmith": []
            },
            "hasReviewer": 0,
            "description": "Another one of my reviews",
            "created": 1594265070,
            "updated": 1594266228,
            "projects": {
              "gemini": ["main"]
            },
            "state": "needsRevision",
            "stateLabel": "Needs Revision",
            "testStatus": "pass",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 1,
              "lines_deleted": 0
            },
          },
          ...
          <other review ids formatted as above>
          ...
        ],
        "totalCount": 2,
        "lastSeen": 12356
      }
    }

#### Get a list of reviews updated during the day before the set date and get the most recently updated review on top

Request reviews updated on the day before 1606233362 (Tuesday November 24th, 2020, 15:56:02) and order with the most recently updated review on top.

curl -u "username:ticket" "https://myswarm-url/api/v11/reviews?afterUpdated=1606233362&resultOrder=updated"

Swarm return all reviews that were updated on the day before the date/time specified in your request and orders the most recently updated review on top. In this example, Swarm responds with any reviews that were updated on Monday November 23rd 2020. The seconds since epoch value Swarm used is added to the end of the response:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews": [
          {
            "id": 12130,
            "type": "default",
            "changes": [
              12129,
              12131
            ],
            "commits": [],
            "author": "bruno",
            "approvals": null,
            "participants": [
              "bruno"
            ],
            "participantsData": {
              "bruno": []
            },
            "hasReviewer": 0,
            "description": "Lorem Ipsum is simply dummy text of the printing and typesetting industry.",
            "created": 1713180845,
            "updated": 1713180849,
            "projects": [],
            "state": "needsReview",
            "stateLabel": "Needs Review",
            "testStatus": null,
            "previousTestStatus": "",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [
              "Administrators"
            ],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 0,
              "lines_deleted": 0
            }
          },
          {
            "id": 12127,
            "type": "default",
            "changes": [
              12126,
              12128
            ],
            "commits": [],
            "author": "bruno",
            "approvals": null,
            "participants": [
              "bruno"
            ],
            "participantsData": {
              "bruno": []
            },
            "hasReviewer": 0,
            "description": "New Review",
            "created": 1713180715,
            "updated": 1713180718,
            "projects": [],
            "state": "needsReview",
            "stateLabel": "Needs Review",
            "testStatus": null,
            "previousTestStatus": "",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [
              "Administrators"
            ],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 1,
              "lines_deleted": 0
            }
          },
          {
            "id": 12119,
            "type": "default",
            "changes": [
              12118,
              12120,
              12121
            ],
            "commits": [
              12121
            ],
            "author": "bruno",
            "approvals": {
              "mei": [
                1
              ]
            },
            "participants": [
              "bruno",
              "mei"
            ],
            "participantsData": {
            "bruno": [],
            "mei": {
              "vote": {
                "value": 1,
                "version": 1,
                "isStale": false
              }
             }
            },
            "hasReviewer": 1,
            "description": "Testttt",
            "created": 1713167013,
            "updated": 1713167061,
            "projects": [],
            "state": "approved",
            "stateLabel": "Approved",
            "testStatus": null,
            "previousTestStatus": "",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": false,
            "commitStatus": [],
            "groups": [
              "Administrators"
            ],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 1,
              "lines_deleted": 0
            }
           },
           {
             "id": 12115,
             "type": "default",
             "changes": [
               12114,
               12116,
               12117
             ],
             "commits": [
               12117
             ],
             "author": "bruno",
             "approvals": {
               "mei": [
                 1
               ]
             },
             "participants": [
               "bruno",
               "mei"
             ],
             "participantsData": {
               "bruno": [],
               "mei": {
                 "vote": {
                   "value": 1,
                   "version": 1,
                   "isStale": false
                 }
               }
             },
             "hasReviewer": 1,
             "description": "ANother new review",
             "created": 1713166904,
             "updated": 1713166936,
             "projects": [],
             "state": "approved",
             "stateLabel": "Approved",
             "testStatus": null,
             "previousTestStatus": "",
             "testDetails": [],
             "deployStatus": null,
             "deployDetails": [],
             "pending": false,
             "commitStatus": [],
             "groups": [
               "Administrators"
             ],
             "complexity": {
               "files_modified": 1,
               "lines_added": 0,
               "lines_edited": 1,
               "lines_deleted": 0
             }
           },
           {
             "id": 12111,
             "type": "default",
             "changes": [
               12110,
               12112,
               12113
             ],
             "commits": [
               12113
             ],
             "author": "bruno",
             "approvals": {
               "mei": [
                 1
               ]
             },
             "participants": [
               "bruno",
               "mei"
             ],
             "participantsData": {
               "bruno": [],
               "mei": {
                 "vote": {
                   "value": 1,
                   "version": 1,
                   "isStale": false
                 }
               }
             },
             "hasReviewer": 1,
             "description": "New Test Review",
             "created": 1713166672,
             "updated": 1713166740,
             "projects": [],
             "state": "approved",
             "stateLabel": "Approved",
             "testStatus": null,
             "previousTestStatus": "",
             "testDetails": [],
             "deployStatus": null,
             "deployDetails": [],
             "pending": false,
             "commitStatus": [],
             "groups": [
               "Administrators"
             ],
             "complexity": {
               "files_modified": 1,
               "lines_added": 0,
               "lines_edited": 1,
               "lines_deleted": 0
             }
            }
          ],
          "totalCount": 5,
          "lastSeen": null,
          "afterUpdated": 1713080340
       }
    }

#### If a request fails

<error code>:

- 400 one of the following:
  - the input specified must be an integer greater than 0
  - invalid keywordsFields field specified
- 401 you are not authorized to view reviews

    HTTP/1.1 <response error code>

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

## Get review information

### Summary

Get review information and metadata.

GET /api/v11/reviews/{id}

### Description

Retrieve all of the information and metadata for a review.

- 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 | Review ID | integer | path | Yes
transitions | To limit the results to a list of the state transitions that are allowed for the review, add the transitions parameter to the request. | query | path | No
fields | To limit the fields returned for the review, add the fields parameter to the request. Multiple fields can be specified. | string or an array (of strings) | query | No

### Example usage

#### Fetch information for review number 12345

curl -u "username:ticket" "https://myswarm-url/api/v11/reviews/12345"

Swarm responds with a review entity:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews": [{
          "id": 12345,
          "type": "default",
          "changes": [1,3],
          "commits": [],
          "author": "normal-user",
          "approvals": null,
          "participants": ["normal-user"],
          "participantsData": {
            "normal-user": []
          },
          "hasReviewer": 0,
          "description": "Added a file\n",
          "created": 1576595749,
          "updated": 1576595754,
          "projects": [],
          "state": "needsReview",
          "stateLabel": "Needs Review",
          "transitions": {
            "needsRevision": "Needs Revision",
            "approved": "Approve",
            "approved:commit": "Approve and Commit",
            "rejected": "Reject",
            "archived": "Archive"
          },
          "testStatus": null,
          "testDetails": [],
          "deployStatus": null,
          "deployDetails": [],
          "pending": true,
          "commitStatus": [],
          "groups": [],
          "versions": [
            {
              "difference": 1,
              "stream": "//jam/main",
              "streamSpecDifference": 0,
              "change": 2,
              "user": "normal-user",
              "time": 1576595752,
              "pending": true,
              "addChangeMode": "replace",
              "archiveChange": 3,
              "testRuns": [}
            },
            {
              ...
              <other "versions" formatted as above>
              ...
            }
          ],
          "description-markdown": "<span class=\"first-line\">Added a file</span>"
        }]
      }
    }

#### Fetch a list of the state transitions that are allowed for review 12345

curl -u "username:ticket" "https://myswarm-url/api/v11/reviews/12345/transitions"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "transitions": {
          "needsRevision": "Needs Revision",
          "approved": "Approve",
          "approved:commit": "Approve and Commit",
          "rejected": "Reject",
          "archived": "Archive"
        }
      }
    }

#### Limit fields returned for review number 12345

Limit the fields return for review 12345 to the review author and the committed status of the review.

curl -u "username:ticket" "https://myswarm-url/api/v11/reviews/12345?fields[]=commitStatus&fields[]=author"

Swarm responds with a review entity:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews": [
          {
            "author": "normal-user",
            "commitStatus": []
          }
        ]
      }
    }

#### If a request fails

<error code>:

404 Review does not exist

    HTTP/1.1 <response error code>

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

## Get read by status for files in a review

### Summary

Get the read by status for each file in a review for the authenticated user.

GET /api/v11/reviews/{id}/files/readby

### Description

Get the read by status for each file in a review for the authenticated user. This is the status the user sets when they select Mark file as read/Mark file as unread for a file.

- 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 a list of the read by status of each file in review 12345 for the authenticated user.

curl -u "bruno:ticket" "https://myswarm-url/api/v11/reviews/12345/files/readby"

With bruno is the authenticated user, Swarm responds with the following:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "filesInfo": [
          {
            "review": 12345,
            "depotFile": "//depot/jam/main/src/Build.com",
            "readBy": {
              "bruno": {
                "version": 1,
                "digest": "82D5161601D12DB46F184D3F0778A16D"
              }
            }
          }
        }
      ]
    }

#### If a request fails

<error code>:

404 Review does not exist

    HTTP/1.1 <response error code>

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

## Get transitions and items that are blocking approval for a review

### Summary

Get a list of transitions and items that are blocking approval for a review.

GET /api/v11/reviews/{{REVIEWID}}/transitions

### Description

Get a list of transitions and details about the items that are blocking approval for a review.

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

#### Pending moderator approvals required for a review

Provides a list of branch moderators that are blocking approval for a review. Depending on the configuration of moderator_approval configurable in the SWARM_ROOT/data/config.php file, the branch moderator approval is required.

Changing the state of any review associated with a moderated branch is restricted as follows:

- Only moderators can approve or reject the review. Moderators can also transition a review to any other state.

Moderators prevent the automatic approval of reviews, for more information about automatically approving reviews using workflow rules see Workflow rules.

By default, when a review spans multiple branches that have different moderators, only one moderator from any one of the branches needs to approve the review.

Swarm can be configured to require that one moderator from each branch must approve the review, this is a global setting. If a moderator belongs to more than one of the branches spanned by the review, their approval will count for each of the branches they belong to. For instructions on how to configure moderator behavior, see Moderator behavior when a review spans multiple branches.

- The review's author, when not a moderator, can change the review's state to Needs review, Needs revision, Archived, and can attach committed changelists.

  Normally, the review's author cannot change the review's state to Approved or Rejected on moderated branches. However, authors that are also moderators have moderator privileges, and may approve or reject their own review.

  When `disable_self_approve` is enabled, authors who are moderators (or even users with admin privileges) cannot approve their own reviews.

- Project members can change the review's state to Needs review or Needs revision, and can attach committed changelists. Project members cannot change the review's state to Approved, Rejected, or Archived.
- Users that are not project members, moderators, or the review's author cannot transition the review's state.
- For the review's author and project members, if a review is not in one of their permitted states, for example if the review's state is Rejected, they cannot transition the review to another state.

These restrictions have no effect on who can start a review.

#### Minimum Up votes required for a review

Provides the number of Minimum Up votes required for each project that you have access to. This includes the maximum number of Minimum Up votes required for all branches in a project blocking approval for a review.

For private project, the maximum number of Minimum Up votes for all private projects and their branches that is blocking approval for a review is returned.

A review cannot be approved until all of the Required reviewers have voted up the review and the Minimum up votes specified has been satisfied.

- If a review spans projects/branches, the Minimum up votes for each of the projects and branches must be satisfied before you can approve the review.
- Required reviewers are included when up votes are counted.
- When Count votes up from is set to Members for a workflow associated with a project/branch, only the up votes of members of the project contribute to satisfying the Minimum up votes for a project/branch. For more information about the Count votes up from rule, see Workflow rules.

If the Workflow feature is disabled, all votes are counted not just votes from project members.

If the Minimum up votes required is set higher than the number of reviewers that exist for a review, approval will be blocked for that review. This is true even if all the reviewers on the review have voted up the review.

#### Tests blocking approval for a review

Provides a list of workflow tests that have Failed or have an In progress status that is blocking approval for a review. For more information about a failed test, see Tests.

### Example usage

#### Example for review 12345 shows a list of transitions and pending moderator approvals for two projects

GET /api/v11/reviews/12345/transitions

Swarm responds with:

    HTTP/1.1 200 OK

    {
      error: null,
      messages: [ ],
      data: {
          transitions: {
             "needsRevision": "Needs Revision",
             "rejected": "Reject",
             "archived": "Archive"
          },
          blocked: {
              approved: {
                  moderators: {
                      projects: {
                          {
                              id: "project1",
                              name:  "Project1",
                              branches: {
                                  {
                                      id: "main",
                                      name: "Main Line",
                                      Users: {
                                          {
                                             id: "earl",
                                             name: "Earl Ashby",
                                             vote: 0,
                                          },
                                      },
                                  },
                              },
                          },
                          {
                              id: "project2",
                              name:  "Project2",
                              branches: {
                                  {
                                      id: "main",
                                      name: "Main Line",
                                      Users: {
                                          {
                                             id: "quinn",
                                             name: "Quinn Cass",
                                             vote: 0,
                                          },
                                      },
                                  },
                              },
                          },
                      },
                  },
              },
          },
       },
    }

#### Example for review 12345 shows a list of transitions and two Minimum Up votes that are blocking approval

GET /api/v11/reviews/12345/transitions

Swarm responds with:

    HTTP/1.1 200 OK

    {
      error: null,
      messages: [ ],
      data: {
          transitions: {
             "needsRevision": "Needs Revision",
             "rejected": "Reject",
             "archived": "Archive"
          },
          blocked: {
              approved: {
                  votes: {
                         projects: {
                             project1: {
                                 id: "project1",
                                 name: "Project1",
                                 minimumUpVotes: 2
                             }
                         }
                  }
              }
          }
       }
    }

#### Example for review 12345 shows a list of transitions and required Minimum Up votes that are blocking approval for a public project and a private project

GET /api/v11/reviews/12345/transitions

Swarm responds with:

    HTTP/1.1 200 OK

    {
      error: null,
      messages: [ ],
      data: {
          transitions: {
             "needsReview": "Needs Review",
             "rejected": "Reject",
             "archived": "Archive"
          },
          blocked: {
              approved: {
                  votes: {
                          projects: {
                              jam: {
                                  id: "jam",
                                  name: "Jam",
                                  minimumUpVotes: 2
                              }
                         },
                         privateProjects: 3
                   }
              }
          }
       }
    }

#### Example for review 12345 shows a list of transitions and three tests that are blocking approval

GET /api/v11/reviews/12345/transitions

Swarm responds with:

    HTTP/1.1 200 OK

    {
      error: null,
      messages: [ ],
      data: {
          transitions: {
             "needsReview": "Needs Review",
             "rejected": "Reject",
             "archived": "Archive"
          },
          blocked: {
              approved: {
                  tests: ["1","2","3"],
              },
          },
       },
    }

#### If a request fails

<error code>:

- 401 User must be authenticated

- 403 You do not have permission to view the review

- 404 Review does not exist

    HTTP/1.1 <response error code>

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

## Get list of files that changed in a review

### Summary

Get a list of files that changed between specified versions of a review.

GET /api/v11/reviews/{id}/files?from={x}&to={y}

### Description

Get a list of files that changed between specified versions of a review.

The GET request returns the following:

- root: the common root depot path of the files that changed between the specified versions of the review.
- limited: Swarm limits the number of files presented for changelists based on the max_changelist_files setting for the Helix Core Server connection. By default, a maximum of 1000 files are returned:
  - true: the number of files in the review is ≥ max_changelist_files. Some of the files changed in the specified review versions might not have been returned by this request.
  - false: the number of files in the review is < max_changelist_files. All of the files changed in the specified review versions have been returned by this request.
- For each file:
  - depotFile: the filename and path of the file.
  - action: how the file changed, Add, Edit, or Delete.
  - 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.

  - rev: the file revision number.
  - fileSize: the file size in bytes.
  - digest: the file digest.

- 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 | Review ID | integer | path | Yes
from | Specify a value for from: 0 specifies the base version of the review. -1 specifies the current #head version of the review files in the Helix Core Server. If omitted, from defaults to 0 which is the base version of the review. Must not be greater that the latest version of the review. | integer | query | No
to | Specify a value for to: If omitted, to defaults to the latest version of the review. Cannot be 0 or -1 Must not be greater that the latest version of the review. | integer | query | No

### Example usage

#### Get a list of files that changed between version 1 and 3 of review 12345

curl -u "username:ticket" "https://myswarm-url/api/v11/reviews/12345/files?from=1&to=3"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "root": "//jam/main/src",
        "limited": false,
        "files": [{
            "depotFile": "//jam/main/src/execvms.c",
            "action": "edit",
            "type": "text",
            "rev": "3",
            "fileSize": "3343",
            "digest": "82D5161601D12DB46F184D3F0778A16D"
          },
          {
            "depotFile": "//jam/main/src/jam.h",
            "action": "add",
            "type": "text",
            "rev": "2",
            "fileSize": "7364",
            "digest": "2E94B379F201AD02CF7E8EE33FB7DA99"
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 400 invalid review version number requested
- 403 Insufficient permissions to access the review
- 404 Review does not exist

    HTTP/1.1 <response error code>

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

## Get activity for a review

### Summary

Get a list of activities for the specified review id.

GET /api/v11/reviews/{id}/activity

### Description

Get a list of activities for the specified review id, filtered by permissions.

- 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
--- | --- | --- | --- | ---
after | An activity ID to seek to. Activity entries 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 activity entries to return. This does not guarantee that max entries are returned. It does guarantee that the number of entries returned won’t exceed max. Server-side filtering may exclude some activity entries for permissions reasons. If the max parameter is not included in the request, only the most recent 100 activities are returned. | integer | query | No
fields | An optional comma-separated list (or array) of fields to show. Omitting this parameter or passing an empty value shows all fields. | string | query | No

### Example usage

#### Get a list of activities for review 1236

curl -u "username:ticket" "https://my-swarm-host/api/v11/reviews/1236/activity"

Swarm responds with:

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

    {
      "error": null,
      "messages": null,
      "data": {
        "activity": [
          {
            "id": 1646,
            "type": "review",
            "link": [
              "review",
              {
                "review": "1236",
                "version": 4
              }
            ],
            "user": null
            "action": "Automated tests reported",
            "target": "review 1236",
            "preposition": "failed tests for",
            "description": "Make a review.",
            "details": [ ],
            "topic": "reviews/1236",
            "depotFile": null,
            "time": 1620228301,
            "behalfOf": null,
            "projects": [ ],
            "followers": [
              "bruno"
              "bob"
            ],
            "streams": {
              "review-1236",
              "user-",
              "personal-",
              "personal-macy.winter",
              "personal-super"
            },
            "change": 1235
          },
          {
            Other ids formatted as above
          }
        ],
        "totalCount": 100,
        "lastSeen": 1646
      }
    }

#### Activity pagination

To get the second page of activities for the review limited to a max of 1 and showing specified fields only (based on the previous example):

curl -u "username:ticket" "https://myswarm.url/api/v11/reviews/1236/activity?max=1&after=1646&fields=id,action,date,description,type"

Swarm responds with:

    {
      "error": null,
      "messages": null,
      "data": {
        "activity": [
          {
            "id": 1645,
            "type": "review",
            "action": "Automated tests reported",
            "description": "Make a review.",
            "time": 1626945417
          }
        ],
        "totalCount": 1,
        "lastSeen": 1645
      }
    }

#### If a request fails

<error code>:

- 400 One of the following:

  - The max parameter value must be an integer greater than 0

  - The after parameter must be an integer greater than 0

- 403 Insufficient permissions to access the review

- 404 Review does not exist

- 500 Internal error, request failed

    HTTP/1.1 <response error code>

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

## Get a list of comments on a review

### Summary

Get a list of comments on a review.

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

### Description

Get a list of comments on a review.

- 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 | Review ID | integer | path | Yes

### Example usage

#### Get a list of comments on a review

curl -u "username:ticket" "https://myswarm-url/api/v11/reviews/368/comments"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "comments": [
          {
            "84": {
              "id": 84,
              "topic": "reviews/368",
              "context": {
                "attribute": "description",
                "review": 368,
                "version": false
              },
              "attachments": [],
              "flags": [],
              "taskState": "comment",
              "likes": [],
              "user": "steve.russell",
              "time": 1594121651,
              "updated": 1594121651,
              "edited": null,
              "body": "@paula.boyle - can you take a look?",
              "readBy": []
            },
            "85": {
              "id": 85,
              "topic": "reviews/368",
              "context": {
                "file": "//projects/mercury/dev/src/api/client.cc",
                "leftLine": null,
                "rightLine": 7,
                "content": [
                  "  */",
                  " ",
                  " #include \"client.h\"",
                  " ",
                  "+#define OK \"OK\""
                ],
                "type": "text",
                "review": 368,
                "version": 1
              },
              "attachments": [],
              "flags": [],
              "taskState": "comment",
              "likes": [],
              "user": "paula.boyle",
              "time": 1594121935,
              "updated": 1594121935,
              "edited": null,
              "body": "Is this better? const char *OK=\"OK\";",
              "readBy": []
            },
              ...
              <other comments formatted as above>
              ...
            }
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 403 Insufficient permissions to access the review
- 404 Review does not exist

    HTTP/1.1 <response error code>

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

## Get the number of delayed notifications on a review

### Summary

Gets the number of delayed comment notifications for the authenticated user for a review.

GET /api/v11/reviews/{id}/notify

### Description

Gets the number of delayed comment notifications for the authenticated user for a review.

### Example usage

Get the number of delayed comment notifications for Bruno on review 12345:

curl -u "bruno:ticket" "https://myswarm-url/api/v11/reviews/12345/notify"

Swarm responds with the number of delayed comment notifications for Bruno on Review 12345:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "userDelayedNotificationCount": 3
      }
    }

#### If a request fails

<error code>:

404 Review does not exist

    HTTP/1.1 <response error code>

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

## Get Dashboard reviews for the authenticated user

### Summary

Gets a list of reviews for the authenticated user's dashboard

GET /api/v11/reviews/dashboard

### Description

Gets a list of reviews for the authenticated user's dashboard. For information about when reviews are displayed in the user dashboard, see My Dashboard.

In addition to he normal review information, the following information is returned for the dashboard filter:

- roles lists the roles the authenticated user has for the review.

- projectsForUser lists projectids the authenticated user is an owner, member, or moderator of.

### Example usage

Get the dashboard reviews for Bruno

curl -u "bruno:ticket" "https://myswarm-url/api/v11/reviews/dashboard"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews": [{
            "id": 12345,
            "type": "default",
            "changes": [
              12344,
            ],
            "commits": [],
            "author": "bruno",
            "approvals": null,
            "participants": ["bruno"],
            "participantsData": {
              "bruno": []
            },
            "hasReviewer": 0,
            "description": "Review for my code change",
            "created": 1594265070,
            "updated": 1594266228,
            "projects": {
              "myproject": ["main"]
            },
            "state": "needsRevision",
            "stateLabel": "Needs Revision",
            "testStatus": "fail",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 1,
              "lines_deleted": 0
            },
            "roles": [
              "author",
              "moderator"
            ],
          },
          ...
          <other review ids formatted as above>
          ...
        ],
        "totalCount": 1,
        "lastSeen": 12345,
        "projectsForUser": [
          "jam"
          "mercury",
        ]
      }
    }

#### If a request fails

<error code>:

401 User must be authenticated

    HTTP/1.1 <response error code>

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

## Get a .zip archive of files in a review

### Summary

Download a .zip archive of the files in the most recent version of a review.

GET /api/v11/reviews/{id}/archive

### Description

Get a .zip archive of the files in the most recent version of a review. Te zip command-line tool must be installed on the Swarm server to use this endpoint.

- 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

Download a .zip archive of the files in review 12345.

GET /api/v11/reviews/12345/archive

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "archive": {
          "phase": "initializing",
          "error": null,
          "success": false,
          "progress": 0
        }
      }
    }

If you repeat the request during the compression phase Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "archive": {
          "phase": "compressing",
          "error": null,
          "success": false,
          "progress": 50
        }
      }
    }

When .zip file has been created, Swarm downloads it.

#### If a request fails

<error code>:

- 401 User must be authenticated

- 404 Review does not exist

- .Zip command line tool not installed

    HTTP/1.1 <response error code>

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

## Refresh projects associated with a review

### Summary

Refresh the list of projects review files are associated with.

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

### Description

Use the refreshProjects API endpoint to check if the review files are associated with any projects created or updated after the review was last updated. If any projects are found that are not already associated with the review, the review is linked to them.

- 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

#### Refresh projects associated with review 12345

curl -X POST -u "username:ticket" "https://myswarm-url/api/v11/reviews/12345/refreshProjects"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews":[
          {
            "id": 12345,
            "type": "default",
            "changes": [
              12344
            ],
            "commits": [
              12344
            ],
            "author": "bruno",
            "approvals": null,
            "participants": [
              "bruno"
            ],
            "participantsData": {
              "bruno": []
            },
            "hasReviewer": 0,
            "description": "streamy",
            "created": 1608644775,
            "updated": 1612371881,
            "projects": [
              "bluebook",
              "jam",
              "mercury"
            ],
            "state": "needsRevision",
            "stateLabel": "Needs Revision",
            "testStatus": null,
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": false,
            "commitStatus": [],
            "groups": [
              "swarm-project-my-precious",
              "swarm-project-jam",
              "Administrators"
            ],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 0,
              "lines_deleted": 0
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 401 User must be authenticated
- 404 Review does not exist

    HTTP/1.1 <response error code>

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

## Set vote for the authenticated user

### Summary

Set the vote for the authenticated user to be up, down, or cleared

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

### Description

Set the vote for the authenticated user to be up, down, or cleared.

- 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 | Review ID | integer | path | Yes
vote | Specify the vote value you want to set on the review. Valid vote values are up, down, and clear. If the requested vote value already exists on the latest version of the review, the vote is not changed. | string | body | Yes
`version` | Votes can only be set on the latest version of a review. The version parameter is used to check that you are voting on the latest version of the review. If the specified version is not the latest version of the review, the vote is not applied to the review and a 400 error is returned. If the version parameter is not included, the vote is applied to the latest version of the review. | integer | body | No

### Example usage

#### Vote up version 1 of review 12345

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v11/reviews/12345/vote"

The "mybodyfilename.txt" file contains the authenticated user's vote and the version of the review they are voting on:

    {
      "vote": "up"
      "version": "1"
    }

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "vote": {
          "value": 1,
          "version": 1,
          "isStale": false
        }
      }
    }

#### If a request fails

<error code>:

- 400 Version specified is not the latest version of the review
- 401 User must be authenticated
- 403 Insufficient permissions to access the review
- 404 Review does not exist
- 409 Invalid vote specified, the response error message lists valid votes.

    HTTP/1.1 <response error code>

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

## Change review state

### Summary

Change the state of a review.

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

### Description

Change the state of a review. The state that a review can be changed to depends on a number of factors including its current state. You can check that the state change you want to make is allowed for the review by making a Get transitions and items that are blocking approval for a review request first. For more information on review states and restrictions on changing them, see States

- 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 | Review ID | integer | path | Yes
transition | Set the state transition to make to the review with the transition parameter. Review state transitions: needsRevision needsReview approved only available if the voting requirements for the review are satisfied committed only available for Pre-commit model reviews that have been approved approved:commit only available for unapproved Pre-commit model reviews when the voting requirements for the review are satisfied rejected archived | string | body | Yes
jobs | Optional, add Perforce jobs to the review when the state is changed with the jobs parameter. Multiple jobs can be added but they must be comma separated. For information on Perforce jobs, see Jobs. | array | body | No
fixedStatus | Optional, only used if the jobs parameter is used. Specify the Perforce job status when the state is changed with the fixedStatus parameter. Options depend on the configuration of your jobspec A form describing the fields and possible values for each job stored in the Helix Core Server machine. fields, see Jobs. The approved:commit state change updates the Perforce job description, all other state changes add the text as a comment on the job. | String | body | No
cleanup | Only used when the review is committed, options are: true Swarm will attempt to automatically clean up any changelists left behind after the review has been committed, including removing any shelved files. This option can be removed by an administrator, see Review cleanup for details. false Swarm will not try to automatically cleanup any changelists left behind after the review is committed. This is the default if the cleanup parameter is not present. | Boolean | body | No

### Example usage

Change the state of review 12345 to Approved and Committed, add Perforce jobs "job000001" and "job000015", set job status to closed, and get Swarm to attempt to cleanup any changelist that are left behind.

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v11/reviews/12345/transitions"

The "mybodyfilename.txt" file contains the state you want to change the review to and any other parameters you want to add:

    {
      "transition": "approved:commit",
      "jobs" : ["job000001","job000015"],
      "fixStatus" : "closed",
      "cleanup" : true
    }

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "state": "approved:commit",
        "stateLabel": "Approved and Committed"
      }
    }

#### If a request fails

<error code>:

- 400 Specified review state does not exist
- 401 Insufficient permissions to change review state
- 403 Insufficient permissions to access the review
- 404 Review does not exist
- 409 Specified state is not a valid transition for this review. API response message lists all valid transition states for the review

    HTTP/1.1 <response error code>

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

## Change review author

### Summary

Change review author.

PUT /api/v11/reviews/{id}/author

### Description

Change the review author.

By default you cannot change the author of a review, this option must be enabled by your Swarm administrator. See Allow author change for details.

- 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 | Review ID | integer | path | Yes

### Example usage

#### Change the author of review 12345

curl -X PUT -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v11/reviews/12345/author"

The "mybodyfilename.txt" file contains the new author username:

    {
      "author": "asmith"
    }

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "author": "asmith"
      }
    }

#### If a request fails

<error code>:

- 400 Author change not allowed, set allow_author_change to true
- 401 Insufficient permissions to change author
- 403 Insufficient permissions to access the review
- 404 Review does not exist

    HTTP/1.1 <response error code>

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

## Replace review description

### Summary

Replace review description.

PUT /api/v11/reviews/{id}/description

### Description

Replace the review description with a new description.

#### Optional: also replace pending changelist description

Only available if you are editing the description of a pre-commit review and you are the original author of the changelist that created the review.

To also apply your review description changes to the original changelist description, specify 'updateOriginalChangelist' : true.

- 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 | Review ID | integer | path | Yes

### Example usage

#### Replace the description for review 12345

curl -X PUT -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v11/reviews/12345/description"

The "mybodyfilename.txt" file contains the new description:

    {
      "description": "This is my replacement description text and it is better than the original description."
    }

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "description": "This is my replacement description text and it is better than the original description.",
        "description-markdown": "<span class=\"first-line\">This is my replacement description text and it is better than the original description.</span>"
      }
    }

#### If a request fails

<error code>:

- 401 Insufficient permissions to change description
- 404 Review does not exist

    HTTP/1.1 <response error code>

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

## Replace review participants

### Summary

Replace review participants.

PUT /api/v11/reviews/{id}/participants

### Description

Replace the review participants with a new set of participants.

- The text file used for your request must contain a complete list of all of the participants you want on the review (users and groups). The existing review participants are completely replaced by the participants in the text file. For example, if you already have some group participants on the review and you do not specify any group roles in the text file, all of the participant groups will be removed from the review.

- Default reviewers can be removed from a review but retained default reviewers cannot be removed from a review, see Default reviewers and Retain default reviewers.

  If your request tries to remove a retained default reviewer, your request will succeed but with a message in the response indicating that the retained default reviewer has not been removed.

- You cannot reduce the voting requirement of a retained default reviewer but you can increase it, see Retain default reviewers.

If your request tries to reduce the voting requirement of a retained default reviewer, your request will succeed but with a message in the response indicating that the retained default reviewer has not been changed.

- 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 | Review ID | integer | path | Yes

### Example usage

#### Replace participants for review 12345

curl -X PUT -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v11/reviews/12345/participants"

The "mybodyfilename.txt" file contains the new review participants and their voting requirements:

    {
      "participants": {
        "users": {
          "asmith": {
            "required": "yes"
          },
          "jbloggs": {
            "required": "no"
          },
          "molsen": {
            "required": "no"
          }
        },
        "groups": {
          "docs": {
            "required": "none"
          },
          "qa": {
            "required": "all"
          },
          "dev": {
            "required": "one"
          },
          "testers": {
            "required": "one"
          }
        }
      }
    }

Swarm responds with a list of all of the participants and their voting requirements:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": {
        "combinedReviewers": [
          "'molsen' must be a reviewer with a minimum requirement of 'required'",
          "'testers' must be a reviewer with a minimum requirement of 'require all'"
        ]
      },
      "data": {
        "participants": {
          "users": {
            "asmith": {
              "required": "yes"
            },
            "jbloggs": {
              "required": "no"
            },
            "molsen": {
              "required": "yes",
              "minimumRequired": "yes"
            }
          },
          "groups": {
            "dev": {
              "required": "one"
            },
            "docs": {
              "required": "none"
            },
            "qa": {
              "required": "all"
            },
            "testers": {
              "required": "all",
              "minimumRequired": "all"
            }
          }
        }
      }
    }

#### If a request fails

<error code>:

- 400 Invalid participant data, for example: unknown participant id or voting requirement
- 401 Insufficient permissions to replace participants
- 403 Insufficient permissions to edit reviewers
- 404 Review does not exist

    HTTP/1.1 <response error code>

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

## Append review participants

### Summary

Append review participants.

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

### Description

Append more participants to the existing review participants.

Only the users and groups specified in the request are appended to the review. For example, if you don't want to append any group participants to the review there is no need to include the groups role in the text file.

- 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 | Review ID | integer | path | Yes

### Example usage

#### Append participants to review 12345

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v11/reviews/12345/participants"

The "mybodyfilename.txt" file contains the new review participants and their voting requirements. In this example, bjones is an optional participant:

    {
      "participants": {
        "users": {
          "bjones": []
        }
      }
    }

Swarm responds with a list of all of the participants and their voting requirements:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "participants": {
          "users": {
            "asmith": {
              "required": "yes"
            },
            "jbloggs": {
              "required": "no"
            },
            "molsen": {
              "required": "yes",
              "minimumRequired": "yes"
            },
            "bjones": []
          },
          "groups": {
            "dev": {
              "required": "one"
            },
            "docs": {
              "required": "none"
            },
            "qa": {
              "required": "all"
            },
            "testers": {
              "required": "all",
              "minimumRequired": "all"
            }
          }
        }
      }
    }

#### If a request fails

<error code>:

- 400 Invalid participant data, for example: unknown participant id or voting requirement
- 401 Insufficient permissions to append participants
- 403 Insufficient permissions to edit reviewers
- 404 Review does not exist

    HTTP/1.1 <response error code>

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

## Add a comment to a review

### Summary

Add a comment to a review.

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

### Description

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

### 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 comment notification immediately:

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://my-swarm-host/api/v11/reviews/885/comments?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/reviews/123/comments"

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/reviews/110/comments"

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/reviews/885/comments?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/reviews/{id}/comments

- Reply to a comment using POST /api/v11/reviews/{id}/comments/{id}

##### Reply to a comment using POST /api/v11/reviews/{id}/comments

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/reviews/885/comments"

    {
      "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/reviews/{id}/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/reviews/885/comments/99"

    {
      "body": "This is another reply to a comment."
    }

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
    }

## Append change to a pre-commit review

### Summary

Append a changelist to the changelist in a pre-commit review.

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

### Description

Append a changelist to the changelist in a pre-commit review. Not available for post-commit reviews. For information about what happens when you append a changelist to a review, see Append a pending changelist to a review.

- 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 | Review ID | integer | path | Yes
change_id | Changelist number | integer | body | Yes

### Example usage

Append changelist 12456 to review 12345:

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

    {
      "changeId": 12456
    }

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews": [{
          "id": 12345,
          "type": "default",
          "changes": [12344,12346,12456],
          "commits": [],
          "author": "normal-user",
          "approvals": null,
          "participants": ["normal-user"],
          "participantsData": {
            "normal-user": []
          },
          "hasReviewer": 0,
          "description": "Added a file\n",
          "created": 1576595749,
          "updated": 1576595754,
          "projects": [],
          "state": "needsReview",
          "stateLabel": "Needs Review",
          "transitions": {
            "needsRevision": "Needs Revision",
            "approved": "Approve",
            "approved:commit": "Approve and Commit",
            "rejected": "Reject",
            "archived": "Archive"
          },
          "testStatus": null,
          "testDetails": [],
          "deployStatus": null,
          "deployDetails": [],
          "pending": true,
          "commitStatus": [],
          "groups": [],
          "versions": [
            {
              "difference": 1,
              "stream": "//jam/main",
              "streamSpecDifference": 0,
              "change": 2,
              "user": "normal-user",
              "time": 1576595752,
              "pending": true,
              "addChangeMode": "append",
              "archiveChange": 3,
              "testRuns": [}
            },
            {
          "description-markdown": "<span class=\"first-line\">Added a file</span>"
        }]
      }
    }

#### If a request fails

<error code>:

- 401 Insufficient permissions to add change
- 403 Insufficient permissions to access the review
- 404 Review or change does not exist

    HTTP/1.1 <response error code>

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

## Replace change on a review

### Summary

Replace the changelist on a review.

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

### Description

Replace the changelist on a review. Can be used for pre-commit and post-commit reviews. For information about what happens when you replace a changelist on a review, see Replace review with a pending changelist and Replace review with a committed changelist.

- 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 | Review ID | integer | path | Yes
change_id | Changelist number | integer | body | Yes

### Example usage

Replace changelist on review 12345 with changelist 12556:

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

    {
      "changeId": 12256
    }

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "reviews": [{
          "id": 12345,
          "type": "default",
          "changes": [12556],
          "commits": [],
          "author": "normal-user",
          "approvals": null,
          "participants": ["normal-user"],
          "participantsData": {
            "normal-user": []
          },
          "hasReviewer": 0,
          "description": "Added a file\n",
          "created": 1576595749,
          "updated": 1576595754,
          "projects": [],
          "state": "needsReview",
          "stateLabel": "Needs Review",
          "transitions": {
            "needsRevision": "Needs Revision",
            "approved": "Approve",
            "approved:commit": "Approve and Commit",
            "rejected": "Reject",
            "archived": "Archive"
          },
          "testStatus": null,
          "testDetails": [],
          "deployStatus": null,
          "deployDetails": [],
          "pending": true,
          "commitStatus": [],
          "groups": [],
          "versions": [
            {
              "difference": 1,
              "stream": "//jam/main",
              "streamSpecDifference": 0,
              "change": 2,
              "user": "normal-user",
              "time": 1576595752,
              "pending": true,
              "addChangeMode": "replace",
              "archiveChange": 3,
              "testRuns": [}
            },
            {
          "description-markdown": "<span class=\"first-line\">Added a file</span>"
        }]
      }
    }

#### If a request fails

<error code>:

- 401 Insufficient permissions to add change
- 403 Insufficient permissions to access the review
- 404 Review or change does not exist

    HTTP/1.1 <response error code>

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

## Send all delayed comment notifications on a review

### Summary

Send all of the delayed comment notifications for the authenticated user for a review.

POST /api/v11/reviews/{review_id}/notify

### Description

Send all of the delayed comment notifications for the authenticated user for a review.

### Example usage

Send all of the delayed comment notifications for Bruno on review 12345:

curl POST -u "bruno:ticket" "https://myswarm-url/api/v11/reviews/12345/notify"

Swarm responds with the number of delayed notifications sent:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "userDelayedNotificationCount": 3
      }
    }

#### If a request fails

<error code>:

404 Review does not exist

    HTTP/1.1 <response error code>

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

## Delete review participants

### Summary

Delete review participants.

DELETE /api/v11/reviews/{id}/participants

### Description

Delete review participants from a review.

- Only the users and groups specified in the request are deleted from the review. For example, if you don't want to delete any group participants from the review there is no need to include the groups role in the text file.

- Default reviewers can be removed from a review but retained default reviewers cannot be removed from a review, see Default reviewers and Retain default reviewers.

  If your request tries to remove a retained default reviewer, your request will succeed but with a message in the response indicating that the retained default reviewer has not been removed.

- 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 | Review ID | integer | path | Yes

### Example usage

#### Delete participants from review 12345

curl -X DELETE -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v11/reviews/12345/participants"

The "mybodyfilename.txt" file contains the participants you want to delete from the review:

    {
      "participants": {
        "users": {
          "jbloggs": [],
          "molsen": []
        },
        "groups": {
          "docs": []
        }
      }
    }

Swarm responds with a list of all of the participants and their voting requirements:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": {
        "combinedReviewers": [
          "'molsen' must be a reviewer with a minimum requirement of 'required'"
        ]
      },
      "data": {
        "participants": {
          "users": {
            "asmith": {
              "required": "yes"
            },
            "molsen": {
              "required": "yes",
              "minimumRequired": "yes"
            },
            "bjones": []
          },
          "groups": {
            "dev": {
              "required": "one"
            },
            "qa": {
              "required": "all"
            },
            "testers": {
              "required": "all",
              "minimumRequired": "all"
            }
          }
        }
      }
    }

#### If a request fails

<error code>:

- 400 Unknown participant id
- 401 Insufficient permissions to delete participants
- 403 Insufficient permissions to edit reviewers
- 404 Review does not exist

    HTTP/1.1 <response error code>

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

## Obliterate a review

### Summary

Obliterate a review.

DELETE /api/v11/reviews/{id}

### Description

Obliterate must be used with care, the review and all of its associated metadata are permanently deleted. An obliterated review cannot be reinstated, not even by Perforce Support.

- By default, you must be a user with admin or super user rights to obliterate a review.
- Optional: Swarm can be configured to allow users to obliterate reviews that they have authored. This can be configured by your Swarm administrator. See Allow author obliterate review.

Obliterate is used to permanently delete reviews that have been created by mistake. For instance, if a review is associated with the wrong changelist, or a review contains sensitive information that should not be openly available.

For information on what happens to a review when it is obliterated, see When you obliterate a review.

- 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 | Review ID | integer | path | Yes

### Example usage

#### Obliterate review number 12345

curl -X DELETE -u "username:ticket" "https://myswarm-url/api/v11/reviews/12345"

Swarm responds with a message informing you that it has successfully Obliterated the review:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [{
        "code": "review-obliterated",
        "text": "The review with id [12345] has been obliterated."
      }],
      "data": {
        "reviews": [{
          "id": 12345,
          "type": "default",
          "changes": [1, 3],
          "commits": [],
          "author": "normal-user",
          "approvals": null,
          "participants": ["normal-user"],
          "participantsData": {
            "normal-user": []
          },
          "hasReviewer": 0,
          "description": "Hello\n",
          "created": 1576579928,
          "updated": 1576579932,
          "projects": [],
          "state": "needsReview",
          "stateLabel": "Needs Review",
          "testStatus": null,
          "testDetails": [],
          "deployStatus": null,
          "deployDetails": [],
          "pending": true,
          "commitStatus": [],
          "groups": []
          "versions": [
            {
              "difference": 1,
              "stream": "//jam/main",
              "streamSpecDifference": 0
              "change": 2,
              "user": "normal-user",
              "time": 1576595752,
              "pending": true,
              "addChangeMode": "replace",
              "archiveChange": 3
              "testRuns": []
            },
            {
              ...
              <other "versions" formatted as above>
              ...
            }
          }
        }
      }
    }

#### Obliterate review number 56789 (with insufficient permission)

curl -X DELETE -u "username:ticket" "https://myswarm-url/api/v11/reviews/56789"

Swarm responds with a message informing you that you do not have permission to obliterate the review:

    HTTP/1.1 200 OK

    {
      "error":403,
      "messages":[{
        "code": "forbidden-exception",
        "text": "Failed to Obliterate the review, you need to have admin privileges or be the review author with 'allow_author_obliterate' set to true."
      }]
      "data": null
    }

#### If a request fails

<error code>":

- 403 Insufficient permissions to obliterate review
- 404 Review does not exist

    HTTP/1.1 <response error code>

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

## Enable notification for a review participant

### Summary

Enable notifications for a review participant.

DELETE /api/v11/reviews/{id}/participantNotifications

### Description

Enable notifications for a review participant. Once notifications are enabled, when you become a review participant, by joining the review or being @mentioned in a comment or in the review's description, you receive notifications for any events associated with the review.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Review ID | integer | path | Yes

### Example usage

curl -X DELETE -u "username:ticket" "https://myswarm-url/api/v11/reviews/12345/participantNotifications"

Swarm responds with a list of all the review participants.

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "participantsData": {
           "Aruna_Gupta": [],
    	"bruno": [],
           "mei": [],
           "Sunil_Patil": [],
           "swarm-group-developers": []
          }
       }
    }

#### If a request fails

<error code>":

- 401 Unauthorized
- 404 Review does not exist

    HTTP/1.1 <response error code>

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

## Disable notification for a review participant

### Summary

Disable notifications for a review participant.

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

### Description

Disable notifications for a review participant.

Once notifications are disabled, you no longer receive notifications. However, if you are @mentioned in a subsequent review comment, you do receive a notification for that comment; regular notifications remain disabled. This approach ensures that you don't miss anything that other reviewers or the review author deems important.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Review ID | integer | path | Yes

### Example usage

curl -X POST -u "username:ticket" "https://myswarm-url/api/v11/reviews/12345/participantNotifications"

Swarm responds with a list of all the review participants.

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "participantsData": {
           "Aruna_Gupta": [],
    	"bruno": {
    	  "notificationsDisabled": true
    	},
           "mei": [],
           "Sunil_Patil": [],
           "swarm-group-developers": []
          }
       }
    }

#### If a request fails

<error code>":

- 401 Unauthorized
- 404 Review does not exist

    HTTP/1.1 <response error code>

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

## Join a review

### Summary

Join a review.

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

### Description

The following individuals can be added as a reviewer:

- Users with admin or super privileges.
- If the review is moderated, the moderators.
- If the review is part of a project, but not moderated, all project members.
- If the review is not part of a project, any authenticated user.

An authenticated user can add themselves as a reviewer for a review.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Review ID | integer | path | Yes

### Example usage

Add vera to review 12345:

curl -X POST -u "vera:ticket" "https://myswarm-url/api/v11/reviews/12345/join"

Swarm responds with a list of all the review participants.

    HTTP/1.1 200 OK

     {
       "error": null,
       "messages": [],
       "data": {
         "participants": {
    	"users": {
    	  "Aruna_Gupta": {
    	    "vote": {
    	     "value": 1,
    	     "version": 2,
    	     "isStale": true
    	    }
    	   },
    	   "bruno": [],
    	   "earl": {
    	     "vote": {
    	       "value": -1,
    	       "version": 1,
    	       "isStale": true
    	      }
    	    },
    	    "mei": [],
    	    "vera": []
    	   },
    	   "groups": {
    	     "staletest": []
    	    }
    	 }
        }
     }

#### If a request fails

<error code>":

- 401 Unauthorized
- 404 Review does not exist

## Leave a review

### Summary

Leave a review.

DEL /api/v11/reviews/{id}/leave

### Description

You cannot leave a review if you are a retained default reviewer on the review or you are a member of a group that is a reviewer on the review.

An authenticated user can remove themselves as a reviewer from a review.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Review ID | integer | path | Yes

### Example usage

Remove vera from review 12345:

curl -X DEL -u "vera:ticket" "https://myswarm-url/api/v11/reviews/12345/leave"

Swarm responds with a list of all the review participants.

    HTTP/1.1 200 OK

     {
       "error": null,
       "messages": [],
       "data": {
         "participants": {
    	"users": {
    	  "Aruna_Gupta": {
    	    "vote": {
    	     "value": 1,
    	     "version": 2,
    	     "isStale": true
    	    }
    	   },
    	   "bruno": [],
    	   "earl": {
    	     "vote": {
    	       "value": -1,
    	       "version": 1,
    	       "isStale": true
    	      }
    	    },
    	    "mei": []
    	   },
    	   "groups": {
    	     "staletest": []
    	    }
    	 }
        }
     }

#### If a request fails

<error code>":

- 401 Unauthorized
- 404 Review does not exist

## Archive inactive reviews

### Summary

Archive inactive reviews.

POST /api/v11/reviews/archiveInactive

### Description

Archiving reviews not updated since a specific date.

- 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
--- | --- | --- | --- | ---
notUpdatedSince | Not updated since date. Requires the date to be in the format YYYY-mm-dd, for example 2023-06-06 | string | body | Yes
max | Optional, maximum number of reviews. | integer | body | No
description | Optional, a description that is posted as a comment for archiving. | string | body | No

### Example usage

Archive maximum 50 reviews inactive since 2023/06/06.

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v11/reviews/archiveInactive"

The "mybodyfilename.txt" file contains the not updated since date, the maximum number of reviews, and a description:

    {
      "notUpdatedSince": "2023-06-06",
      "max": 50,
      "description": "This is the description"
    }

Swarm responds with a list of all the inactive reviews that are archived.

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "archivedReviews": [
          {
            "id": 12450,
            "type": "default",
            "changes": [
              12443,
              12451
            ],
            "commits": [],
            "author": "bruno",
            "approvals": null,
            "participants": [
            "bruno"
            ],
            "participantsData": {
              "bruno": []
            },
            "hasReviewer": 0,
            "description": "pre commit review creation via swarm UI success",
            "created": 1678794209,
            "updated": 1683615474,
            "projects": {
              "project3": [
                "branch1",
                "branch2",
                "branch3"
              ]
            },
            "state": "archived",
            "stateLabel": "Archived",
            "testStatus": null,
            "previousTestStatus": "",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [
              "Administrators",
              "swarm-project-mod-project1",
              "swarm-project-mod-project2",
              "swarm-project-mod-project3",
              "swarm-project-mod-project4",
              "swarm-project-project-1",
              "swarm-project-project-2",
              "swarm-project-project-3",
              "swarm-project-project1",
              "swarm-project-project2",
              "swarm-project-project3",
              "swarm-project-project4",
              "swarm-project-project88",
              "swarm-project-project99",
              "swarm-project-test-project"
            ],
            "complexity": {
              "files_modified": 1,
              "lines_added": 0,
              "lines_edited": 2,
              "lines_deleted": 0
            }
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 401 Unauthorized
- 400 Transition of the review is not allowed

## Create a Review

### Summary

Create a review.

POST /api/v11/reviews/

### Description

Pass in a changelist ID to create a review. Optionally, you can also provide a description and a list of reviewers. For more information about reviewers, individual reviewers, and group reviewers, see Reviewers.

- 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
--- | --- | --- | --- | ---
change | Change ID to create a review from | integer | form | Yes
description | Description for the new review (defaults to change description) | string | form | No
reviewers | A list of reviewers for the new review | an array (of strings) | form | No
requiredReviewers | A list of required reviewers for the new review | an array (of strings) | form | No
reviewerGroups | A list of reviewer groups or required reviewer groups for the new review | an array (of strings) | form | No

When a group is a required reviewer, it can be set to operate in one of two ways:

- Require all: all members of the group must up-vote the review to allow the review to be approved. To do this, in the reviewerGroups parameter for a group, set "required":"true".
- Require one: at least one member of the group must up-vote the review to allow the review to be approved. If any member of the group down-votes the review, the review cannot be approved.

  To do this, in the reviewerGroups parameter for a group, set "required":"true" with `"quorum":"1"`.

### Example usage

Create a review for changelist 12345.

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v11/reviews/"

The "mybodyfilename.txt" file contains the changelist ID and a description:

    {
      "change": "12345",
      "description": "This is the review description."
      "reviewers": [
          "raj",
          "mei"
      ],
      "requiredReviewers": [
          "vera",
          "dai"
      ],
      "reviewerGroups": [
          {"name":"WebDesigners", "required":"true", "quorum":"1"},
          {"name":"Developers", "required":"true"},
          {"name":"Administrators"}
      ]
    }

Swarm responds with the new review entity:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "review": [
          {
            "id": 12346,
            "type": "default",
            "changes": [
              12345
            ],
            "commits": [],
            "author": "bruno",
            "approvals": null,
            "participants": [
              "bruno"
              "dai",
              "mei",
              "raj",
              "swarm-group-Administrators",
              "swarm-group-Developers",
              "swarm-group-WebDesigners",
              "vera"
            ],
            "participantsData": {
              "bruno": []
              "dai": {
                "required": true
              },
              "mei": [],
              "raj": [],
              "swarm-group-Administrators": [],
              "swarm-group-Developers": {
                "required": true
              },
              "swarm-group-WebDesigners": {
                "required": "1"
              },
              "vera": {
                "required": true
              }
            },
            "hasReviewer": 0,
            "description": "This is the review description.",
            "created": 1689244995,
            "updated": 1689244995,
            "projects": [],
            "state": "needsReview",
            "stateLabel": "Needs Review",
            "testStatus": null,
            "previousTestStatus": "",
            "testDetails": [],
            "deployStatus": null,
            "deployDetails": [],
            "pending": true,
            "commitStatus": [],
            "groups": [],
            "complexity": null,
            "versions": []
          }
        ]
      }
    }

#### If a request fails

<error code>:

- 400 The input specified must be an integer greater than 0

- 401 Unauthorized

- 404 Cannot fetch change. Record does not exist.

- 403 You don't have permission to access the specified change

Your search for returned results