#summary Documentation for the public Review Board API #labels Featured =Review Board API Documentation= All web services return JSON formatted data. See http://json.org for a full description of JavaScript Object Notation. You must request all methods marked with "POST Required" with an HTTP POST method rather than GET. i.e. This will fail and return an HTTP status of 405: http://demo.review-board.org/api/json/accounts/login/?username=jay&password=password All methods marked with Login Required require you to send a login cookie to verify your credentials. Use the accounts/login method to get this cookie. All JSON responses contain a "stat" field that either has a value of "ok" on success or "fail" on failure. ==Error Handling== On error "stat" will be set to "fail" and there will be an "err" field that contains "msg" and "code". ===Error Response Example:=== {{{ { "stat": "fail", "err": { "msg": "You are not logged in", "code": 103 } } }}} ===List of possible error codes=== * 0: "If you see this, yell at the developers" * 100: "Object does not exist" * 101: "You don't have permission for this" * 102: "Invalid attribute" * 103: "You are not logged in" * 104: "The username or password was not correct" * 105: "One or more fields had errors" * 200: "Diff revision not specified" * 201: "Invalid diff revision" * 202: "Invalid action specified" * 203: "The change number specified could not be found" * 204: "The change number specified has already been used" * 205: "A repository path must be specified" * 206: "The repository path specified is not in the list of known repositories" * 207: "The file was not found in the repository" * 208: "User does not exist" =Methods= ==/api/json/accounts/login/== POST Required Login to reviewboard. Sets an HTTP cookie that must be presented all most other API calls. ===Required Arguments=== * username * password ===Example Response=== {{{ {"stat": "ok"} }}} ==/api/json/repositories/== Login Required Returns a list of all known repositories. ===Arguments=== None ===Example Response=== {{{ { "stat":"ok", "repositories":[ { "path":"http:\/\/reviewboard.googlecode.com\/svn", "tool":"Subversion", "id":1, "name":"Review Board SVN" }, { "path":"http:\/\/svn.navi.cx\/misc", "tool":"Subversion", "id":2, "name":"Navi" } ] } }}} ==/api/json/users/== Login Required Returns a list of all users. If the query parameter is passed, users with a username beginning with the query value will be returned. Note that query must be passed in as a GET parameter, not with a POST ===Optional Arguments=== * query ===Example Response=== {{{ { "stat":"ok", "users": [ { "username":"bovik", "first_name":"Harold", "last_name":"Bovik" }, { "username":"chkr", "first_name":"Christian", "last_name":"Krause" }, ] } }}} ==/api/json/groups/== Login Required Returns a list of all review groups. If the query parameter is passed, groups with a name beginning with the query value will be returned. Note that query must be passed in as a GET parameter, not with a POST ===Optional Arguments=== * query ===Example Response=== {{{ { "stat":"ok", "groups":[ { "display_name":"Review Board", "name":"reviewboard" } ] } }}} ==/api/json/groups/``/star/== Login Required. Adds a group to the user's watched groups list. ===Arguments=== None ===Example Response=== {{{ {"stat": "ok"} }}} ==/api/json/groups/``/unstar/== Login Required. Removes a group from the user's watched groups list. ===Arguments=== None ===Example Response=== {{{ {"stat": "ok"} }}} ==/api/json/reviewrequests/all/== ==/api/json/reviewrequests/to/group/``/== ==/api/json/reviewrequests/to/user/``/== ==/api/json/reviewrequests/from/user/``/== ==/api/json/reviewrequests/repository/``/changenum/``/== Login Required GET Required Return a list of reviews that match: * all * a group * to a user * from a user * have a changenum in specified repository ===Optional Arguments=== * status: filter on the status of the returned review requests. This defaults to "pending". ===Example Response=== {{{ { "stat":"ok", "review_requests":[ { "status":"pending", "bugs_closed":"", "last_updated":"2007-12-03 10:00:11", "description":"foo bar", "repository":{ "path":"http:\/\/reviewboard.googlecode.com\/svn", "tool":"Subversion", "id":1, "name":"Review Board SVN" }, "target_groups":[ { "url":"\/groups\/reviewboard\/", "id":1, "mailing_list":"reviewboard-reviews@googlegroups.com", "name":"reviewboard" } ], "public":1, "changenum":null, "target_people":[ ], "testing_done":"", "branch":"", "submitter":{ "username":"senthil", "first_name":"senthil", "last_name":"gandhi", "url":"\/users\/senthil\/", "email":"gsn.coldfire@gmail.com", "fullname":"senthil gandhi", "id":1354 }, "time_added":"2007-11-30 12:06:04", "summary":"Screen shot for problem diff", "id":148 }, ] } }}} ==/api/json/reviewrequests/all/count/== ==/api/json/reviewrequests/to/group/``/count/== ==/api/json/reviewrequests/to/user/``/count/== ==/api/json/reviewrequests/from/user/``/count/== Login Required GET Required Returns the number review requests that are outstanding for all, in a group, to or from a user. ===Optional Arguments=== * status: filter on the status of the returned review requests. This defaults to "pending". ===Example Response=== {{{ { "count":13, "stat":"ok" } }}} ==/api/json/reviewrequests/new/== Login Required. Requires POST Creates a new review request. ===Required Arguments=== * repository_path: The repository to create the review request against. If not specified, the DEFAULT_REPOSITORY_PATH setting will be used. If both this and repository_id are set, repository_path's value takes precedence. * repository_id: The ID of the repository to create the review request against. ===Optional Arguments=== * submit_as: The optional user to submit the review request as. This requires that the actual logged in user is either a superuser or has the "reviews.can_submit_as_another_user" property. * changenum: The optional changenumber to look up for the review request details. This only works with repositories that support changesets. ===Example Response=== {{{ { "stat":"ok", "review_request":{ "status":"pending", "bugs_closed":"", "last_updated":"2008-02-24 10:27:38", "description":"", "repository":{ "path":"http:\/\/reviewboard.googlecode.com\/svn", "tool":"Subversion", "id":1, "name":"Review Board SVN" }, "target_groups":[ ], "public":false, "changenum":null, "target_people":[ ], "testing_done":"", "branch":"", "submitter":{ "username":"jay", "first_name":"Jay", "last_name":"Buffington", "url":"\/users\/jay\/", "email":"jaybuffington@gmail.com", "fullname":"Jay Buffington", "id":2299 }, "time_added":"2008-02-24 10:27:38", "summary":"", "id":201 } } }}} ==/api/json/reviewrequests/``/== Login Required. Returns a review request with the specified changenum. ===Arguments=== None ===Example Response=== {{{ { "stat":"ok", "review_request":{ "status":"submitted", "bugs_closed":[ "138" ], "last_updated":"2007-06-26 11:44:44", "description":"When bugs_closed is blank and a ReviewRequest is encoded by the JSON encoder, the following line throws an error:\nbugs_closed = [int(b.strip()) for b in o.bugs_closed.split(',')]\n''.split(',') returns (as documented) the original string in a list, being ['']. This is iterated (it contains an item) and is passed to int, thus int('') is called, throwing an error.\n\nThe fix shown works, but does add a little extra cruft to the line. Perhaps this could be split over multiple lines or otherwise abstracted.", "repository":{ "path":"http:\/\/reviewboard.googlecode.com\/svn", "tool":"Subversion", "id":1, "name":"Review Board SVN" }, "target_groups":[ { "url":"\/groups\/reviewboard\/", "id":1, "mailing_list":"reviewboard-reviews@googlegroups.com", "name":"reviewboard" } ], "public":1, "changenum":null, "target_people":[ ], "testing_done":"", "branch":"", "submitter":{ "username":"testuser", "first_name":"Test", "last_name":"User", "url":"\/users\/testuser\/", "email":"testuser@example.com", "fullname":"Test User", "id":572 }, "time_added":"2007-06-26 07:58:40", "summary":"fix int() error when list of bugs is blank", "id":100 } } }}} ==/api/json/reviewrequests/``/star/== Login Required Mark this review request stared to put it under the logged in user's "starred reviews" ===Arguments=== None ===Example Response=== {{{ {"stat": "ok"} }}} ==/api/json/reviewrequests/``/unstar/== Login Required Remove the star from this review request so it no longer shows up in the logged in user's "starred reviews" ===Arguments=== None ===Example Response=== {{{ {"stat": "ok"} }}} ==/api/json/reviewrequests/``/delete/== Login Required Permission Required Delete this review request. ===Arguments=== None ===Example Response=== {{{ {"stat": "ok"} }}} ==/api/json/reviewrequests/``/update_from_changenum/== Login Required Requires POST ===Arguments=== None ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/draft/save/== Login Required Requires POST ===Required Arguments=== * shipit * body_top * body_bottom ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/draft/discard/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/draft/set/``/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/draft/set/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/reviews/draft/save/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/reviews/draft/publish/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/reviews/draft/delete/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/reviews/draft/comments/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/diff/== ===Arguments=== None ===Example Response=== {{{ { "stat": "ok", "diffsets": [ { "timestamp": "2009-07-12 14:05:34", "revision": 1, "id": 1, "repository": { "path": "file:///path/to/repos", "tool": "Subversion", "id": 1, "name": "Test" }, "name": "test.diff" } ] } }}} ==/api/json/reviewrequests/``/reviews/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/reviews/count/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/reviews/``/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/reviews/``/comments/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/reviews/``/comments/count/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/reviews/``/replies/draft/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/reviews/``/replies/draft/save/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/reviews/``/replies/draft/discard/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/reviews/``/replies/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/reviews/``/replies/count/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/diff/new/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/screenshot/new/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/diff/``/file/``/line/``/comments/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/diff/``-``/file/``-``/line/``/comments/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}} ==/api/json/reviewrequests/``/s/``/comments/``x``+``+``/== Login Required Requires POST ===Arguments=== ===Example Response=== {{{ }}}