Documentation | 2025.1

# Reviews : Swarm Reviews

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

## Get reviews for action dashboard

### Summary

Get reviews for action dashboard

GET /api/v9/dashboards/action

### Description

Gets reviews for the action dashboard for the authenticated user.

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

#### Successful Commit contains Review and Commit Entities:

    HTTP/1.1 200 OK

    {
      "lastSeen": 120,
      "reviews": [
        {
          "id": 7,
          "author": "swarm_admin",
          "changes": [6],
          "comments": [0,0],
          "commits": [6],
          "commitStatus": [],
          "created": 1485793976,
          "deployDetails": [],
          "deployStatus": null,
          "description": "test\n",
          "groups": ["swarm-project-test"],
          "participants": {"swarm_admin":[]},
          "pending": false,
          "projects": {"test":["test"]},
          "roles": ["moderator|reviewer|required_reviewer|author"],
          "state": "needsReview",
          "stateLabel": "Needs Review",
          "testDetails": [],
          "testStatus": null,
          "type": "default",
          "updated": 1485958875,
          "updateDate": "2017-02-01T06:21:15-08:00"
        }
      ],
      "totalCount": null
    }

### Example usage

#### Getting reviews for the action dashboard

To list reviews:

    curl -u "username:password" "http://my-swarm-host/api/v9/dashboards/action"

Swarm responds with a list of the latest reviews, a `totalCount` field, and a `lastSeen` value for pagination:

    HTTP/1.1 200 OK

    {
      "lastSeen": 120,
      "reviews": [
        {
          "id": 7,
          "author": "swarm_admin",
          "changes": [6],
          "comments": [0,0],
          "commits": [6],
          "commitStatus": [],
          "created": 1485793976,
          "deployDetails": [],
          "deployStatus": null,
          "description": "test\n",
          "groups": ["swarm-project-test"],
          "participants": {"swarm_admin":[]},
          "pending": false,
          "projects": {"test":["test"]},
          "roles": ["moderator|reviewer|required_reviewer|author"],
          "state": "needsReview",
          "stateLabel": "Needs Review",
          "testDetails": [],
          "testStatus": null,
          "type": "default",
          "updated": 1485958875,
          "updateDate": "2017-02-01T06:21:15-08:00"
        }
      ],
      "totalCount": null
    }

## Get List of Reviews

### Summary

Get List of Reviews

GET /api/v9/reviews/

### Description

List and optionally filter reviews.

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

### Parameters

Parameter | Description | Type | Parameter Type | Required | Default Value
--- | --- | --- | --- | --- | ---
after | A 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. | integer | query | No |
max | Maximum number of reviews to return. This does not guarantee that `max` reviews are returned. It does guarantee that the number of reviews returned won’t exceed `max`. Server-side filtering may exclude some reviews for permissions reasons. | integer | query | No | 1000
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 |
author[] | One or more authors to limit reviews by. Reviews with any of the specified authors are returned. (v1.2+) | array (of strings) | query | No |
change[] | One or more change IDs to limit reviews by. Reviews associated with any of the specified changes are returned. | array (of integers) | query | No |
hasReviewers | Boolean option to limit to reviews to those with or without reviewers. Use `true` or `false` for JSON-encoded data, `1` for true and or `0` for false for form-encoded data. The presence of the parameter without a value is evaluated as true. | boolean | query | No |
ids[] | One or more review IDs to fetch. Only the specified reviews are returned. This filter cannot be combined with the `max` parameter. | array (of integers) | query | No |
keywords | Keywords to limit reviews by. Only reviews where the description, participants list or project list contain the specified keywords are returned. | string | query | No |
participants[] | One or more participants to limit reviews by. Reviews with any of the specified participants are returned. | array (of strings) | query | No |
project[] | One or more projects to limit reviews by. Reviews affecting any of the specified projects are returned. | array (of strings) | query | No |
state[] | One or more states to limit reviews by. Reviews in any of the specified states are returned. | array (of strings) | query | No |
passesTests | Boolean option to limit reviews by tests passing or failing. Use `true` or `false` for JSON-encoded data, `1` for true and `0` for false for form-encoded data. The presence of the parameter without a value is evaluated as true. | string | query | No |
notUpdatedSince | Option to fetch unchanged reviews. Requires the date to be in the format YYYY-mm-dd, for example 2017-01-01. Reviews to be returned are determined by looking at the last updated date of the review. | string | query | No |
hasVoted | Should have the value 'up' or 'down' to filter reviews that have been voted up or down by the current authenticated user. | string | query | No |
myComments | True or false to support filtering reviews that include comments by the current authenticated user. | boolean | query | No |

### Examples responses

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "lastSeen": 12209,
      "reviews": [
        {
          "id": 12206,
          "author": "swarm",
          "changes": [12205],
          "comments": 0,
          "commits": [],
          "commitStatus": [],
          "created": 1402507043,
          "deployDetails": [],
          "deployStatus": null,
          "description": "Review Description\n",
          "participants": {
            "swarm": []
          },
          "pending": true,
          "projects": [],
          "state": "needsReview",
          "stateLabel": "Needs Review",
          "testDetails": [],
          "testStatus": null,
          "type": "default",
          "updated": 1402518492
        }
      ],
      "totalCount": 1
    }

Swarm returns `null` for `totalCount` if no search filters were provided. `lastSeen` can often be used as an offset for pagination, by using the value in the `after` parameter of subsequent requests.

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

    HTTP/1.1 200 OK

    {
      "lastSeen": null,
      "reviews": [],
      "totalCount": 0
    }

### Example usage

#### Listing reviews

To list reviews:

    curl -u "username:password" "https://my-swarm-host/api/v9/reviews?max=2&fields=id,description,author,state"

Swarm responds with a list of the latest reviews, a `totalCount` field, and a `lastSeen` value for pagination:

    HTTP/1.1 200 OK

    {
      "lastSeen": 120,
      "reviews": [
        {
          "id": 123,
          "author": "bruno",
          "description": "Adding .jar that should have been included in r110\n",
          "state": "needsReview"
        },
        {
          "id": 120,
          "author": "bruno",
          "description": "Fixing a typo.\n",
          "state": "needsReview"
        }
      ],
      "totalCount": null
    }

The `totalCount` field is populated when keywords are supplied. It indicates how many total matches there are. If keywords are not supplied the `totalCount` field remains `null`, indicating that the list of all reviews is being queried.

#### Paginating a review listing

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

    curl -u "username:password" "https://my-swarm-host/api/v9/reviews?max=2&fields=id,description,author,state&after=120"

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

    HTTP/1.1 200 OK

    {
      "lastSeen": 100,
      "reviews": [
        {
          "id": 110,
          "author": "bruno",
          "description": "Updating Java files\n",
          "state": "needsReview"
        },
        {
          "id": 100,
          "author": "bruno",
          "description": "Marketing materials for our new cutting-edge product\n",
          "state": "needsReview"
        }
      ],
      "totalCount": null
    }

#### Finding reviews for a change or a list of changes

Given a list of change IDs (5, 6, 7), here is how to check if any of them have reviews attached:

    curl -u "username:password" "https://my-swarm-host/api/v9/reviews?max=2&fields=id,changes,description,author,state&change\[\]=5&change\[\]=6&change\[\]=7"

Swarm responds with a list of reviews that include these changes:

    HTTP/1.1 200 OK

    {
      "lastSeen": 100,
      "reviews": [
        {
          "id": 110,
          "author": "bruno",
          "changes": [5],
          "description": "Updating Java files\n",
          "state": "needsReview"
        },
        {
          "id": 100,
          "author": "bruno",
          "changes": [6,7],
          "description": "Marketing materials for our new cutting-edge product\n",
          "state": "needsReview"
        }
      ],
      "totalCount": 2
    }

If no corresponding reviews are found, Swarm responds with an empty reviews list:

    HTTP/1.1 200 OK

    {
      "lastSeen": null,
      "reviews": [],
      "totalCount": 0
    }

#### Finding inactive reviews (by checking the last updated date)

    curl -u "username:password" "https://my-swarm-host/api/v9/reviews?max=2&fields=id,changes,description,author,state&notUpdatedSince=2017-01-01"

Swarm responds with a list of reviews that have not been updated since the notUpdatedSince date:

    HTTP/1.1 200 OK

    {
      "lastSeen": 100,
      "reviews": [
        {
          "id": 110,
          "author": "bruno",
          "changes": [5],
          "description": "Updating Java files\n",
          "state": "needsReview"
        },
        {
          "id": 100,
          "author": "bruno",
          "changes": [6,7],
          "description": "Marketing materials for our new cutting-edge product\n",
          "state": "needsReview"
        }
      ],
      "totalCount": 2
    }

#### Finding reviews I have voted up

    curl -u "username:password" "https://my-swarm-host/api/v9/reviews?max=2&fields=id,changes,description,author,state&hasVoted=up"

Swarm responds with a list of reviews that include these changes:

    HTTP/1.1 200 OK

    {
      "lastSeen": 100,
      "reviews": [
        {
          "id": 110,
          "author": "bruno",
          "changes": [5],
          "description": "Updating Java files\n",
          "state": "needsReview"
        },
        {
          "id": 100,
          "author": "bruno",
          "changes": [6,7],
          "description": "Marketing materials for our new cutting-edge product\n",
          "state": "needsReview"
        }
      ],
      "totalCount": 2
    }

If no corresponding reviews are found, Swarm responds with an empty reviews list:

    {
      "lastSeen": null,
      "reviews": [],
      "totalCount": 0
    }

#### Finding reviews I have commented on (current authenticated user)

    curl -u "username:password" "https://my-swarm-host/api/v9/reviews?max=2&fields=id,changes,description,author,state&myComments=true"

Swarm responds with a list of reviews that include these changes:

    HTTP/1.1 200 OK

    {
      "lastSeen": 100,
      "reviews": [
        {
          "id": 110,
          "author": "bruno",
          "changes": [5],
          "description": "Updating Java files\n",
          "state": "needsReview"
        },
        {
          "id": 100,
          "author": "bruno",
          "changes": [6,7],
          "description": "Marketing materials for our new cutting-edge product\n",
          "state": "needsReview"
        }
      ],
      "totalCount": 2
    }

If no corresponding reviews are found, Swarm responds with an empty reviews list:

    HTTP/1.1 200 OK

    {
      "lastSeen": null,
      "reviews": [],
      "totalCount": 0
    }

## Get Review Information

### Summary

Get Review Information

GET /api/v9/reviews/{id}

### Description

Retrieve information about 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
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

#### Fetching a review

To fetch a review:

    curl -u "username:password" "https://my-swarm-host/api/v9/reviews/123"

Swarm responds with a review entity:

    HTTP/1.1 200 OK

    {
      "review": {
        "id": 123,
        "author": "bruno",
        "changes": [122,124],
        "commits": [124],
        "commitStatus": [],
        "created": 1399325913,
        "deployDetails": [],
        "deployStatus": null,
        "description": "Adding .jar that should have been included in r110\n",
        "groups": [],
        "participants": {
          "alex_qc": [],
          "bruno": {
            "vote": 1,
            "required": true
          },
          "vera": []
        },
        "reviewerGroups": {
          "group1" : [],
          "group2" : {
            "required" : true
          },
          "group3" : {
            "required" : true,
            "quorum": "1"
          }
        },
        "pending": false,
        "projects": {
          "swarm": ["main"]
        },
        "state": "archived",
        "stateLabel": "Archived",
        "testDetails": {
          "url": "http://jenkins.example.com/job/project_ci/123/"
        },
        "testStatus": null,
        "type": "default",
        "updated": 1399325913,
        "versions": [
          {
            "difference": 1,
            "stream": "//jam/main",
            "streamSpecDifference": 0,
            "change": 124,
            "user": "bruno",
            "time": 1568115902,
            "pending": true,
            "addChangeMode": "replace",
            "testRuns": [
              8
            ]
          },
          {
            "difference": 1,
            "stream": "//jam/main",
            "streamSpecDifference": 0,
            "change": 12157,
            "user": "bruno",
            "time": 1568115918,
            "pending": true,
            "addChangeMode": "replace",
            "archiveChange": 122,
            "testRuns": [
              1,
              2,
              3,
              4,
              5,
              6,
              7
            ]
          }
        ]
      }
    }

#### Fetching a review that does not exist

If you try to fetch a review that does not exist:

    curl -u "username:password" "https://my-swarm-host/api/v9/reviews/999999"

Swarm responds with a 404 resonse:

    HTTP/1.1 404 Not Found

    {
      "error": "Not Found"
    }

## Get transitions for a review

### Summary

Get transitions for a review

GET /api/v9/reviews/{id}/transitions

### Description

Get the allowed transitions 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
--- | --- | --- | --- | ---
upVoters | A list of users whose vote up will be assumed when determining the transitions. For example if a user has not yet voted but would be the last required vote and asked for possible transitions we would want to include 'approve' | string | query | No

### Example response

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "isValid": "true",
      "transitions": {
          "needsRevision": "Needs Revision",
          "approved": "Approve",
          "approved:commit": "Approve and Commit",
          "rejected": "Reject",
          "archived": "Archive"
      }
    }

### Example usage

#### Getting transitions that a review with id 1 can transition to:

    curl -u "username:password" "https://my-swarm-host/api/v9/reviews/1/transitions?upVoters=bruno"

The transitions that are returned depend on the current review state, Swarm setup and the configuration of associated projects and branches

    HTTP/1.1 200 OK

    {
      "isValid": "true"
      "transitions": {
          "needsRevision": "Needs Revision",
          "approved": "Approve",
          "approved:commit": "Approve and Commit",
          "rejected": "Reject",
          "archived": "Archive"
      }
    }

## Create a Review

### Summary

Create a Review

POST /api/v9/reviews/

### Description

Pass in a changelist ID to create a review. Optionally, you can also provide a description and a list of 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 | array (of strings) | form | No
requiredReviewers | A list of required reviewers for the new review (v1.1+) | array (of strings) | form | No
reviewerGroups | A list of required reviewers for the new review (v7+) | array | form | No

### Example response

#### Successful Response contains Review Entity:

    HTTP/1.1 200 OK

    {
      "review": {
        "id": 12205,
        "author": "bruno",
        "changes": [10667],
        "commits": [10667],
        "commitStatus": [],
        "created": 1399325913,
        "deployDetails": [],
        "deployStatus": null,
        "description": "Adding .jar that should have been included in r10145\n",
        "participants": {
          "bruno": []
        },
        "reviewerGroups": {
          "group1" : [],
          "group2" : {
            "required" : true
          },
          "group3" : {
            "required" : true,
            "quorum": "1"
          }
        },
        "pending": false,
        "projects": [],
        "state": "archived",
        "stateLabel": "Archived",
        "testDetails": [],
        "testStatus": null,
        "type": "default",
        "updated": 1399325913
      }
    }

### Example usage

#### Starting a review

To start a review for a committed change or a non-empty shelved changelist specifying reviewer groups:

    curl -u "username:password" \
         -X POST \
         -d "change=122" \
         -d "reviewerGroups[0][name]=group1" \
         -d "reviewerGroups[1][name]=group2" \
         -d "reviewerGroups[1][required]=true" \
         -d "reviewerGroups[2][name]=group3" \
         -d "reviewerGroups[2][required]=true" \
         -d "reviewerGroups[2][quorum]=1" \
         "https://my-swarm-host/api/v9/reviews/"

Swarm responds with the new review entity:

    HTTP/1.1 200 OK

    {
      "review": {
        "id": 123,
        "author": "bruno",
        "changes": [122],
        "commits": [],
        "commitStatus": [],
        "created": 1399325913,
        "deployDetails": [],
        "deployStatus": null,
        "description": "Adding .jar that should have been included in r110\n",
        "groups": [],
        "participants": {
          "bruno": []
        },
        "reviewerGroups": {
          "group1" : [],
          "group2" : {
            "required" : true
          },
          "group3" : {
            "required" : true,
            "quorum": "1"
          }
        },
        "pending": true,
        "projects": [],
        "state": "needsReview",
        "stateLabel": "Needs Review",
        "testDetails": [],
        "testStatus": null,
        "type": "default",
        "updated": 1399325913,
        "versions": []
      }
    }

## Archiving the inactive reviews

### Summary

Archiving the inactive reviews (v6+)

POST /api/v9/reviews/archive/

### Description

Archiving reviews not updated since the date (v6+).

- 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 | Updated since date. Requires the date to be in the format YYYY-mm-dd, for example 2017-01-01 | string | form | Yes
description | A description that is posted as a comment for archiving. | string | form | Yes

### Example response

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "archivedReviews": [
        {
          "id": 836,
          "author": "swarm",
          "changes": [789],
          "commits": [],
          "commitStatus": [],
          "created": 1461164339,
          "deployDetails": [],
          "deployStatus": null,
          "description": "Review description\n",
          "groups": [],
          "participants": {
            "swarm": []
          },
          "pending": false,
          "projects": [],
          "state": "archived",
          "stateLabel": "Archived",
          "testDetails": [],
          "testStatus": null,
          "type": "default",
          "updated": 1478191607
        }
      ],
      "failedReviews": []
    }

### Example usage

#### Archiving reviews inactive since 2016/06/30

To archive reviews not updated since 2016/06/30 inclusive:

    curl -u "username:password" \
         -X POST \
         -d "notUpdatedSince=2016-06-30" \
         "https://my-swarm-host/api/v9/reviews/archive/"

Swarm responds with the list of archived reviews and failed reviews if there are any:

    HTTP/1.1 200 OK

    {
      "archivedReviews":[
        {
          "id": 911,
          "author": "swarm",
          "changes": [601],
          "commits": [],
          "commitStatus": [],
          "created": 1461164344,
          "deployDetails": [],
          "deployStatus": null,
          "description": "Touch up references on html pages.\n",
          "groups": [],
          "participants": {
            "swarm":[]
          },
          "pending": false,
          "projects": [],
          "state": "archived",
          "stateLabel": "Archived",
          "testDetails": [],
          "testStatus": null,
          "type": "default",
          "updated": 1478191605
        },
        {
          "id": 908,
          "author": "earl",
          "changes": [605],
          "commits": [],
          "commitStatus": [],
          "created": 1461947794,
          "deployDetails": [],
          "deployStatus": null,
          "description": "Remove (attempted) installation of now deleted man pages.\n",
          "groups": [],
          "participants": {
            "swarm": []
          },
          "pending": false,
          "projects": [],
          "state": "archived",
          "stateLabel": "Archived",
          "testDetails": [],
          "testStatus": null,
          "type": "default",
          "updated": 1478191605
        }
      ],
      "failedReviews":[
        {
        }
      ]
    }

If no reviews are archived, Swarm responds with an empty reviews list:

    HTTP/1.1 200 OK

    {
      "archivedReviews": [],
      "failedReviews": []
    }

## Add Change to Review

### Summary

Add Change to Review

POST /api/v9/reviews/{id}/changes/

### Description

Links the given change to the review and schedules an update.

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

### Parameters

Parameter | Description | Type | Parameter Type | Required | Default Value
--- | --- | --- | --- | --- | ---
id | Review ID | integer | path | Yes |
change | Change ID | integer | form | Yes |
mode | The mode of operation, currently 'replace' or 'append' | string | form | No | replace

### Example response

#### Successful Response contains Review Entity:

    HTTP/1.1 200 OK

    {
      "review": {
        "id": 12206,
        "author": "bruno",
        "changes": [10667, 12000],
        "commits": [10667, 12000],
        "commitStatus": [],
        "created": 1399325913,
        "deployDetails": [],
        "deployStatus": null,
        "description": "Adding .jar that should have been included in r10145\n",
        "participants": {
          "bruno": []
        },
        "pending": false,
        "projects": [],
        "state": "archived",
        "stateLabel": "Archived",
        "testDetails": [],
        "testStatus": null,
        "type": "default",
        "updated": 1399325913
      }
    }

### Example usage

#### Adding a change to a review

You may want to update a review from a shelved or committed change that is different from the initiating change. This is done by adding a change to the review.

To replace a changelist:

    curl -u "username:password" \
         -X POST \
         -d "change=124" \
         "https://my-swarm-host/api/v9/reviews/123/changes/"

To append a changelist:

    curl -u "username:password" -X POST -d "change=124" -d "mode=append" https://my-swarm-host/api/v9/reviews/123/changes/"

Swarm responds with the updated review entity:

    HTTP/1.1 200 OK

    {
      "review": {
        "id": 123,
        "author": "bruno",
        "changes": [122, 124],
        "commits": [],
        "commitStatus": [],
        "created": 1399325913,
        "deployDetails": [],
        "deployStatus": null,
        "description": "Adding .jar that should have been included in r110\n",
        "groups": [],
        "participants": {
          "bruno": []
        },
        "pending": true,
        "projects": [],
        "state": "needsReview",
        "stateLabel": "Needs Review",
        "testDetails": [],
        "testStatus": null,
        "type": "default",
        "updated": 1399325913,
        "versions": [
          {
            "difference": 1,
            "stream": null,
            "change": 124,
            "user": "bruno",
            "time": 1399330003,
            "pending": true,
            "archiveChange": 124
          }
        ]
      }
    }

## Clean up a review

### Summary

Clean up a review (v6+)

POST /api/v9/reviews/{id}/cleanup

### Description

Clean up a review for the given id.

- 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
--- | --- | --- | --- | ---
reopen | Expected to be a boolean (defaulting to false). If true then an attempt will be made to reopen files into a default changelist | boolean | form | No

### Example response

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "complete": [
        {
          "1": ["2"]
        }
      ],
      "incomplete": []
    }

### Example usage

#### Cleaning up a review with id 1

Cleanup review number 1, reopening any files into the default changelist.

    curl -u "username:password" \
         -X POST \
         -d "reopen=true" \
         "https://my-swarm-host/api/v9/reviews/1/cleanup"

Swarm responds with the review and the changelists cleaned. Depending on the completion they will be either detailed in 'complete' or 'incomplete'. Incomplete changelists will have messages indicating why it was not possible to complete:

    HTTP/1.1 200 OK

    {
      "complete": [
        {
          "1": ["2"]
        }
      ],
      "incomplete": []
    }

## Obliterate a review

### Summary

Obliterate a review

POST /api/v9/reviews/{id}/obliterate

### Description

Obliterate a review for the given id.

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

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "isValid": true,
      "message": "The review with id [1] has been obliterated.",
      "code": 200
    }

### Example usage

#### Obliterating a review with id 1

Obliterating review number 1.

    curl -u "username:password" \
         -X POST \
         "https://my-swarm-host/api/v9/reviews/1/obliterate"

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

    HTTP/1.1 200 OK

    {
      "isValid": true,
      "message": "The review with id [1] has been obliterated.",
      "code": 200
    }

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

### Summary

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

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

### Description

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

- 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
--- | --- | --- | --- | ---
version | Expected to be a valid review version to vote on if supplied, ignored if the version does not exist and the vote will apply to the latest version | string | form | No
vote | Expected to be a valid vote. Valid votes are 'up', 'down' and 'clear | string | form | Yes

### Example response

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "isValid": "true",
      "messages": ["User username set vote to up on review 1"]
    }

### Example usage

#### Voting up for review with id 1

    curl -u "username:password" \
         -X POST \
         -d "vote[value]=up" -d "vote[version]=1" \
         "https://my-swarm-host/api/v9/reviews/1/vote/"

Swarm responds with

    HTTP/1.1 200 OK

    {
      "isValid": "true",
      "messages": ["User username set vote to up on review 1"]
    }

## Transition the Review State

### Summary

Transition the Review State (v2+)

PATCH /api/v9/reviews/{id}/state/

### Description

Transition the review to a new state. When transitioning to approved, you can optionally commit the review. (v2+).

- 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
state | Review State. Valid options: needsReview, needsRevision, approved, archived, rejected | string | form | Yes
description | An optional description that is posted as a comment for non-commit transitions. Commits that do not include a description default to using the Review description in the resulting change description. | string | form | No
commit | Set this flag to true and provide a state of `approved` in order to trigger the Approve and Commit action in Swarm. | boolean | form | No
wait | Instruct Swarm to wait for a commit to finish before returning. | boolean | form | No
jobs[] | When performing an 'Approve and Commit', one or more jobs can be attached to the review as part of the commit process. | stringArray | form | No
fixStatus | Provide a fix status for the attached job(s) when performing an 'Approve and Commit'. Possible status values vary by job specification, but often include: open, suspended, closed, review, fixed. | string | form | No

### Example responses

#### Successful Response contains Review Entity:

    HTTP/1.1 200 OK

    {
      "review": {
        "id": 12207,
        "author": "bruno",
        "changes": [10667, 12000],
        "commits": [],
        "commitStatus": [],
        "created": 1399325913,
        "deployDetails": [],
        "deployStatus": null,
        "description": "Adding .jar that should have been included in r10145\n",
        "participants": {
          "bruno": []
        },
        "pending": false,
        "projects": [],
        "state": "needsRevision",
        "stateLabel": "Needs Revision",
        "testDetails": [],
        "testStatus": null,
        "type": "default",
        "updated": 1399325913
      },
      "transitions": {
        "needsReview": "Needs Review",
        "approved": "Approve",
        "rejected": "Reject",
        "archived": "Archive"
      }
    }

#### Successful Commit contains Review and Commit Entities:

    HTTP/1.1 200 OK

    {
      "review": {
        "id": 12208,
        "author": "bruno",
        "changes": [10667, 12000, 12006],
        "commits": [12006],
        "commitStatus": {
          "start": 1399326910,
          "change": 12006,
          "status": "Committed",
          "committer": "bruno",
          "end": 1399326911
        },
        "created": 1399325900,
        "deployDetails": [],
        "deployStatus": null,
        "description": "Adding .jar that should have been included in r10145\n",
        "participants": {
          "bruno": []
        },
        "pending": false,
        "projects": [],
        "state": "needsRevision",
        "stateLabel": "Needs Revision",
        "testDetails": [],
        "testStatus": null,
        "type": "default",
        "updated": 1399325905
      },
      "transitions": {
        "needsReview": "Needs Review",
        "needsRevision": "Needs Revision",
        "rejected": "Reject",
        "archived": "Archive"
      },
      "commit": 12006
    }

### Example usage

#### Committing a review

To commit a review:

    curl -u "username:password" \
         -X PATCH \
         -d "state=approved" -d "commit=1" \
         "https://my-swarm-host/api/v9/reviews/123/state/"

Swarm responds with the updated review entity, as well as a list of possible transitions for the review:

    HTTP/1.1 200 OK

    {
      "review": {
        "id": 123,
        "author": "bruno",
        "changes": [122, 124],
        "commits": [124],
        "commitStatus": {
            "start": 1399326910,
            "change": 124,
            "status": "Committed",
            "committer": "bruno",
            "end": 1399326911
          },
        "created": 1399325913,
        "deployDetails": [],
        "deployStatus": null,
        "description": "Adding .jar that should have been included in r110\n",
        "groups": [],
        "participants": {
          "bruno": []
        },
        "pending": false,
        "projects": [],
        "state": "approved",
        "stateLabel": "Approved",
        "testDetails": [],
        "testStatus": null,
        "type": "default",
        "updated": 1399325913,
        "versions": []
      },
        "transitions": {
          "needsReview": "Needs Review",
          "approved": "Approve",
          "rejected": "Reject",
          "archived": "Archive"
        }
    }

## Update Review Description

### Summary

Update Review Description

PATCH /api/v9/reviews/{review_id}

### Description

Update the description field of 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
--- | --- | --- | --- | ---
review_id | Review ID | integer | path | Yes
author | The new author for the specified review. (At least one of Author or Description are required.) | string | form | No
description | The new description for the specified review. (At least one of Description or Author are required.) | string | form | No
_method | Method Override. If your client cannot submit HTTP PATCH, use an HTTP POST with the parameter ?_method=PATCH to override. | string | query | No

### Example responses

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "review": {
          "id": 12306,
          "author": "swarm",
          "changes": [12205],
          "comments": 0,
          "commits": [],
          "commitStatus": [],
          "created": 1402507043,
          "deployDetails": [],
          "deployStatus": null,
          "description": "Updated Review Description\n",
          "participants": {
            "swarm": []
          },
          "pending": true,
          "projects": [],
          "state": "needsReview",
          "stateLabel": "Needs Review",
          "testDetails": [],
          "testStatus": null,
          "type": "default",
          "updated": 1402518492
      },
      "transitions": {
          "needsRevision": "Needs Revision",
          "approved": "Approve",
          "rejected": "Reject",
          "archived": "Archive"
      },
      "canEditAuthor": true
    }

Swarm returns `null` for `totalCount` if no search filters were provided. `lastSeen` can often be used as an offset for pagination, by using the value in the `after` parameter of subsequent requests.

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

    HTTP/1.1 200 OK

    {
      "lastSeen": null,
      "reviews": [],
      "totalCount": 0
    }

Your search for returned results