Jump to >

Review Request Resource

Provides information on review requests.

Review requests are one of the central concepts in Review Board. They represent code or files that are being placed up for review.

A review request has a number of fields that can be filled out, indicating the summary, description of the change, testing that was done, affected bugs, and more. These must be filled out through the associated Review Request Draft resource.

When a review request is published, it can be reviewed by users. It can then be updated, again through the Review Request Draft resource, or closed as submitted or discarded.

Details

Name review_request
URI /api/review-requests/{review_request_id}/
Token Policy ID review_request
HTTP Methods
  • DELETE - Deletes the review request permanently.
  • GET - Returns information on a particular review request.
  • PUT - Updates the status of the review request.
Parent Resource Review Request List Resource
Child Resources
Anonymous Access Yes, if anonymous site access is enabled

Fields

absolute_urlString

The absolute URL to the review request’s page on the site.

Added in 2.0

approval_failureString

The reason why the review request was not approved. This will be null if approved.

Added in 2.0

approvedBoolean

Whether the review request has been approved by reviewers.

On a default install, a review request is approved if it has at least one Ship It! and no open issues. Extensions may change these requirements.

Added in 2.0

blocksList of Review Request Resource

The list of review requests that this review request is blocking.

Added in 1.7.9

branchString The branch that the code was changed on or that the code will be committed to. This is a free-form field that can store any text.
bugs_closedList of String The list of bugs closed or referenced by this change.
changenumInteger Deprecated

The change number that the review request represents. These are server-side repository-specific change numbers, and are not supported by all types of repositories. It may be null.

This is deprecated in favor of the commit_id field.

Deprecated in 2.0

close_descriptionRich Text

The text describing the closing of the review request.

Added in 2.0.12

close_description_text_typeOne of plain, markdown, html

The current or forced text type for the close_description field.

Added in 2.0.12

commit_idString

The commit that the review request represents. This obsoletes the changenum field.

Added in 2.0

created_with_historyBoolean

Whether or not the review request was created with history support.

A value of true indicates that the review request will have commits attached.

Added in 4.0

depends_onList of Review Request Resource

The list of review requests that this review request depends on.

Added in 1.7.9

descriptionRich Text The review request’s description.
description_text_typeOne of plain, markdown, html

The current or forced text type for the description field.

Added in 2.0.12

extra_dataDictionary

Extra data as part of the review request. This can be set by the API or extensions.

Added in 2.0

idInteger The numeric ID of the review request.
issue_dropped_countInteger

The number of dropped issues on this review request

Added in 2.0

issue_open_countInteger

The number of open issues on this review request

Added in 2.0

issue_resolved_countInteger

The number of resolved issues on this review request

Added in 2.0

issue_verifying_countInteger

The number of issues waiting for verification to resolve or drop on this review request

Added in 3.0.3

last_updatedISO 8601 Date/Time The date and time that the review request was last updated.
publicBoolean Whether or not the review request is currently visible to other users.
repositoryRepository Resource The repository that the review request’s code is stored on.
ship_it_countInteger

The number of Ship Its given to this review request.

Added in 2.0

statusOne of discarded, pending, submitted The current status of the review request.
submitterUser Resource The user who submitted the review request.
summaryString The review request’s brief summary.
target_groupsList of Review Group Resource The list of review groups who were requested to review this change.
target_peopleList of User Resource The list of users who were requested to review this change.
testing_doneRich Text The information on the testing that was done for the change.
testing_done_text_typeOne of plain, markdown, html

The current or forced text type for the testing_done field.

Added in 2.0.12

text_typeOne of plain, markdown, html Deprecated

Formerly responsible for indicating the text type for text fields. Replaced by close_description_text_type, description_text_type, and testing_done_text_type in 2.0.12.

Added in 2.0

Deprecated in 2.0.12

time_addedISO 8601 Date/Time The date and time that the review request was added.
urlString Deprecated

The URL to the review request’s page on the site. This is deprecated and will be removed in a future version.

Added in 1.7.8

Deprecated in 2.0

HTTP DELETE

Deletes the review request permanently.

This is a dangerous call to make, as it will delete the review request, associated screenshots, diffs, and reviews. There is no going back after this call is made.

Only users who have been granted the reviews.delete_reviewrequest permission (which includes administrators) can perform a delete on the review request.

After a successful delete, this will return HTTP 204 No Content.

Errors

100 - Does Not ExistHTTP 404 - Not Found Object does not exist
101 - Permission DeniedHTTP 403 - Forbidden You don’t have permission for this
103 - Not Logged InHTTP 401 - Unauthorized You are not logged in
112 - OAuth2 Missing Scope ErrorHTTP 403 - Forbidden Your OAuth2 token lacks the necessary scopes for this request.
113 - OAuth2 Access Denied ErrorHTTP 403 - Forbidden OAuth2 token access for this resource is prohibited.

HTTP GET

Returns information on a particular review request.

This contains full information on the latest published review request.

If the review request is not public, then the client’s logged in user must either be the owner of the review request or must have the reviews.can_edit_reviewrequest permission set. Otherwise, an error will be returned.

Errors

100 - Does Not ExistHTTP 404 - Not Found Object does not exist
101 - Permission DeniedHTTP 403 - Forbidden You don’t have permission for this
103 - Not Logged InHTTP 401 - Unauthorized You are not logged in
112 - OAuth2 Missing Scope ErrorHTTP 403 - Forbidden Your OAuth2 token lacks the necessary scopes for this request.
113 - OAuth2 Access Denied ErrorHTTP 403 - Forbidden OAuth2 token access for this resource is prohibited.

HTTP PUT

Updates the status of the review request.

The only supported update to a review request’s resource is to change the status, the associated server-side, change number, or to update information from the existing change number.

The status can be set in order to close the review request as discarded or submitted, or to reopen as pending.

For Perforce, a change number can either be changed to a new number, or the current change number can be passed. In either case, a new draft will be created or an existing one updated to include information from the server based on the change number. This behavior is deprecated, and instead, the commit_id field should be set on the draft.

Changes to a review request’s fields, such as the summary or the list of reviewers, is made on the Review Request Draft resource. This can be accessed through the draft link. Only when that draft is published will the changes end up back in this resource.

Extra data can be stored later lookup. See Storing/Accessing Extra Data for more information.

Request Parameters

changenumInteger Deprecated

The optional change number to set or update.

This can be used to re-associate with a new change number, or to create/update a draft with new information from the current change number.

This only works with repositories that support server-side changesets.

This is deprecated. Instead, set commit_id and update_from_commit_id=1 on the draft.

Added in 1.5.4

Deprecated in 2.0

close_descriptionRich Text

The description of the update. Should only be used if the review request have been submitted or discarded.

This replaces the old description field.

Added in 2.0.9

close_description_text_typeOne of plain, markdown Deprecated

The text type for the close description of the update field.

Added in 2.0

Deprecated in 2.0.12

descriptionRich Text Deprecated

The description of the update. Should only be used if the review request have been submitted or discarded.

This is deprecated. Instead, set close_description.

Added in 1.6

Deprecated in 2.0.9

force_text_typeOne of plain, markdown, html

The text type, if any, to force for returned text fields. The contents will be converted to the requested type in the payload, but will not be saved as that type.

Added in 2.0.9

statusOne of discarded, pending, submitted The status of the review request. This can be changed to close or reopen the review request
text_typeOne of plain, markdown Deprecated

The text type for the close description of the update field.

This is deprecated. Please use close_description_text_type instead.

Added in 2.0

Deprecated in 2.0.12

Errors

100 - Does Not ExistHTTP 404 - Not Found Object does not exist
101 - Permission DeniedHTTP 403 - Forbidden You don’t have permission for this
103 - Not Logged InHTTP 401 - Unauthorized You are not logged in
105 - Invalid Form DataHTTP 400 - Bad Request One or more fields had errors
112 - OAuth2 Missing Scope ErrorHTTP 403 - Forbidden Your OAuth2 token lacks the necessary scopes for this request.
113 - OAuth2 Access Denied ErrorHTTP 403 - Forbidden OAuth2 token access for this resource is prohibited.

Examples

application/vnd.reviewboard.org.review-request+json

$ curl http://reviews.example.com/api10/ -H "Accept: application/json"
Vary: Accept, Cookie
ETag: 82003584edb000f6aaa7819b85cd330b31e9182b
Content-Type: application/vnd.reviewboard.org.review-request+json
X-Content-Type-Options: nosniff
{
  "review_request": {
    "absolute_url": "http://reviews.example.com/r/10/", 
    "approval_failure": "The review request has not been marked \"Ship It!\"", 
    "approved": false, 
    "blocks": [], 
    "branch": "", 
    "bugs_closed": [], 
    "changenum": null, 
    "close_description": null, 
    "close_description_text_type": "plain", 
    "commit_id": null, 
    "created_with_history": true, 
    "depends_on": [], 
    "description": "Test review request with history.", 
    "description_text_type": "markdown", 
    "extra_data": {
      "calculated_trophies": true, 
      "local_branch": "master"
    }, 
    "id": 10, 
    "issue_dropped_count": 0, 
    "issue_open_count": 0, 
    "issue_resolved_count": 0, 
    "issue_verifying_count": 0, 
    "last_updated": "2018-08-10T22:16:47Z", 
    "links": {
      "changes": {
        "href": "http://reviews.example.com/api/review-requests/10/changes/", 
        "method": "GET"
      }, 
      "delete": {
        "href": "http://reviews.example.com/api/review-requests/10/", 
        "method": "DELETE"
      }, 
      "diff_context": {
        "href": "http://reviews.example.com/api/review-requests/10/diff-context/", 
        "method": "GET"
      }, 
      "diffs": {
        "href": "http://reviews.example.com/api/review-requests/10/diffs/", 
        "method": "GET"
      }, 
      "draft": {
        "href": "http://reviews.example.com/api/review-requests/10/draft/", 
        "method": "GET"
      }, 
      "file_attachments": {
        "href": "http://reviews.example.com/api/review-requests/10/file-attachments/", 
        "method": "GET"
      }, 
      "last_update": {
        "href": "http://reviews.example.com/api/review-requests/10/last-update/", 
        "method": "GET"
      }, 
      "latest_diff": {
        "href": "http://example.com/api/review-requests/10/diffs/2/", 
        "method": "GET"
      }, 
      "repository": {
        "href": "http://reviews.example.com/api/repositories/3/", 
        "method": "GET", 
        "title": "Git Repo"
      }, 
      "reviews": {
        "href": "http://reviews.example.com/api/review-requests/10/reviews/", 
        "method": "GET"
      }, 
      "screenshots": {
        "href": "http://reviews.example.com/api/review-requests/10/screenshots/", 
        "method": "GET"
      }, 
      "self": {
        "href": "http://reviews.example.com/api/review-requests/10/", 
        "method": "GET"
      }, 
      "status_updates": {
        "href": "http://reviews.example.com/api/review-requests/10/status-updates/", 
        "method": "GET"
      }, 
      "submitter": {
        "href": "http://reviews.example.com/api/users/doc/", 
        "method": "GET", 
        "title": "doc"
      }, 
      "update": {
        "href": "http://reviews.example.com/api/review-requests/10/", 
        "method": "PUT"
      }
    }, 
    "public": true, 
    "ship_it_count": 0, 
    "status": "pending", 
    "summary": "Review request with history", 
    "target_groups": [
      {
        "href": "http://reviews.example.com/api/groups/devgroup/", 
        "method": "GET", 
        "title": "devgroup"
      }
    ], 
    "target_people": [], 
    "testing_done": "", 
    "testing_done_text_type": "markdown", 
    "text_type": null, 
    "time_added": "2018-08-10T22:16:22Z", 
    "url": "/r/10/"
  }, 
  "stat": "ok"
}