Jump to >

Status Update List Resource

Added in 3.0

Provides status updates on review requests.

A status update is a way for a third-party service or extension to mark some kind of status on a review request. Examples of this could include static analysis tools or continuous integration services.

Status updates may optionally be associated with a change description, in which case they will be shown in that change description box on the review request page. Otherwise, the status update will be shown in a box immediately below the review request details.

Important

Using this resource requires extra features to be enabled on the server. See “Required Features” below.

Details

Name status_updates
URI /api/review-requests/{review_request_id}/status-updates/
Required Features
  • reviews.status_updates
Token Policy ID status_update
HTTP Methods
  • GET - Returns a list of status updates on a review request.
  • POST - Creates a new status update.
Parent Resource Review Request Resource
Child Resources
Anonymous Access Yes, if anonymous site access is enabled

HTTP GET

Returns a list of status updates on a review request.

By default, this returns all status updates for the review request.

Request Parameters

changeInteger The change description to get status updates for.
counts-onlyBoolean If specified, a single count field is returned with the number of results, instead of the results themselves.
max-resultsInteger The maximum number of results to return in this list. By default, this is 25. There is a hard limit of 200; if you need more than 200 results, you will need to make more than one request, using the “next” pagination link.
service-idString The service ID to query for.
startInteger The 0-based index of the first result in the list. The start index is usually the previous start index plus the number of previous results. By default, this is 0.
stateOne of pending, done-success, done-failure, error The state to query for.

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.

HTTP POST

Creates a new status update.

At a minimum, the service ID and a summary must be provided.

If desired, the new status update can be associated with a change description and/or a review. If a change description is included, this status update will be displayed in the review request page within that change description’s box. If a review is attached, once that review is published, it will appear alongside the status update.

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

Request Parameters

service_idString Required

A unique identifier for the service providing the status update.

summaryString Required

A user-visible short summary of the status update.

change_idInteger The change to a review request which this status update applies to (for example, the change adding a diff that was built by CI). If this is blank, the status update is for the review request as initially published.
descriptionString A user-visible description of the status update.
review_idInteger A review which corresponds to this status update.
stateOne of pending, done-success, done-failure, error The current state of the status update.
timeoutInteger An optional timeout for pending status updates, measured in seconds.
urlString A URL to link to for more details about the status update.
url_textString The text to use for the link.

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.status-updates+json

$ curl http://reviews.example.com/api/review-requests/8/status-updates/ -H "Accept: application/json"
Vary: Accept, Cookie
Item-Content-Type: application/vnd.reviewboard.org.status-update+json
Content-Type: application/vnd.reviewboard.org.status-updates+json
X-Content-Type-Options: nosniff
{
  "links": {
    "create": {
      "href": "http://reviews.example.com/api/review-requests/8/status-updates/", 
      "method": "POST"
    }, 
    "self": {
      "href": "http://reviews.example.com/api/review-requests/8/status-updates/", 
      "method": "GET"
    }
  }, 
  "stat": "ok", 
  "status_updates": [
    {
      "description": "running...", 
      "extra_data": {}, 
      "id": 1, 
      "links": {
        "change": {
          "href": "http://reviews.example.com/api/review-requests/8/changes/1/", 
          "method": "GET", 
          "title": "Added a second diff for the interdiff test."
        }, 
        "delete": {
          "href": "http://reviews.example.com/api/review-requests/8/status-updates/1/", 
          "method": "DELETE"
        }, 
        "self": {
          "href": "http://reviews.example.com/api/review-requests/8/status-updates/1/", 
          "method": "GET"
        }, 
        "update": {
          "href": "http://reviews.example.com/api/review-requests/8/status-updates/1/", 
          "method": "PUT"
        }
      }, 
      "review": null, 
      "service_id": "reviewbot.pep8", 
      "state": "timed-out", 
      "summary": "PEP-8", 
      "timeout": 20, 
      "url": "", 
      "url_text": ""
    }
  ], 
  "total_results": 1
}