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	Status Update Resource
Anonymous Access	Yes, if anonymous site access is enabled

Links¶

Name	Method	Resource
create	POST	Status Update List Resource
self	GET	Status Update List Resource

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`, `not-yet-run`, `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
}