Reviews: Swarm reviews

Get a list of reviews

Summary

Get a list of reviews.

GET /api/v10/reviews

Description

List the reviews the user has permission to view.

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix 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

query

No

after

Return reviews created after the reviewid specified in the after parameter. Reviews are returned in the order they were created in.

Note

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. Reviews are returned in the order they were updated in, most recent first.

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.

For example:

  • Requested: afterUpdated=1606233362 (Tuesday November 24th, 2020, 15:56:02)
  • Response fetched for: any reviews updated on Monday November 23rd, 2020. 1606089600 (Monday, 23 November 2020 00:00:00) is added to the end of the response
Note

You cannot use the after and afterUpdated parameters in the same request, they are mutually exclusive.

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
  • committed review is committed
  • approved:commit review is approved and committed
  • approved:notPending review is approved and committed
  • rejected review is rejected
  • archived review is archived

string

query

No

Example usage

Get a list of reviews

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

Swarm responds with the review entities:

Tip

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/v10/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/v10/reviews?project=myproject"

Swarm responds with the review entities for the myproject project:

Tip

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/v10/reviews?project[]=myproject&project[]=gemini"

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

Tip

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 created after review 12344

curl -u "username:ticket" "https://myswarm-url/api/v10/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/v10/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/v10/reviews?state=needsReview"

Swarm responds with the review entities in the needsReview state:

Tip

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/v10/reviews?state[]=approved:isPending&state[]=needsReview&state[]=needsRevision"

Swarm responds with the review entities for open reviews:

Tip

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

If a request fails

<error code>:

  • 400 the input specified must be an integer greater than 0
  • 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/v10/reviews/{id}

Description

Retrieve all of the information and metadata for a review.

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix 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

Example usage

Fetch information for review number 12345

curl -u "username:ticket" "https://myswarm-url/api/v10/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/v10/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"
    }
  }
}

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 list of files that changed in a review

Summary

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

GET /api/v10/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 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 P4 Command Reference.

    • rev: the file revision number.
    • fileSize: the file size in bytes.
    • digest: the file digest.
Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix 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 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/v10/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
} 

Set vote for the authenticated user

Summary

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

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

Description

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

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix 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/v10/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/v10/reviews/{id}/transition

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 review information request first. For more information on review states and restrictions on changing them, see States

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
Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix 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 state of review 12345 to approved

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

The "mybodyfilename.txt" file contains the state you want to change the review to:

{
  "transition": "approved"
}

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "state": "approved",
    "stateLabel": "Approved"
  }
}

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/v10/reviews/{id}/author

Description

Change the review author.

Important

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.

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix 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/v10/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/v10/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.

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix 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/v10/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/v10/reviews/{id}/participants

Description

Replace the review participants with a new set of participants.

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

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix 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/v10/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/v10/reviews/{id}/participants

Description

Append more participants to the existing review participants.

Note

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.

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix 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/v10/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
} 

Delete review participants

Summary

Delete review participants.

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

Description

Delete review participants from a review.

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

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix 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/v10/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/v10/reviews/{id}

Description

Important

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.

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

Tip
  • Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix 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/v10/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/v10/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
}