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.

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

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

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/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:

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/v11/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 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:

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

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:

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,
        "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:

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

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

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

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

    • Important

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

    Note

    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.

    • Important

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

Important

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

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

Tip

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.

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

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

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

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

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

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

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

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

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

Tip

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

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.

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

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

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

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

Important

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

Tip

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.

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

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