Cookie Notice

Crucible REST API

This is the reference section of the Crucible REST API.

For information about Crucible Plugin Development, visit the Development Hub.

This documentation was automatically generated from the WADL.

REST Client Examples

Please have a look at python examples that demonstrate the capabilities of Fisheye & Crucible REST API: bitbucket.org/atlassian/fecru-rest-examples/src

Paged APIs

Fisheye uses paging to conserve server resources and limit response size for resources that return potentially large collections of items. A request to a paged API will result in a values array wrapped in a JSON object with some paging metadata, like this: 


                    {
                    "start": 3,
                    "size": 3,
                    "limit": 100,
                    "lastPage": true,
                    "values": [
                        { /* result 0 */ },
                        { /* result 1 */ },
                        { /* result 2 */ }
                    ]
                    }

Clients can use the limit and start query parameters to retrieve the desired number of results.

The limit parameter indicates how many results to return per page. Most APIs default to returning 100 if the limit is left unspecified. A resource can have a hard limit. It's always best practice to check the limit attribute on the response to see what limit has been applied. The request to get a page with desired size should look like this: 


                    http://host:port/context/rest/api/api-version/path/to/resource?limit={desired size of page}

For example: 


                    http://fecru.atlassian.com/rest/api/1.0/rest-service-fecru/users?limit=50

The start parameter indicates which item should be used as the first item in the page of results. All paged responses contain a lastPage attribute indicating whether another page of items exists. If a paged response has a property lastPage set to false, the next page start should be calculated by adding current page start and size. The request to get a subsequent page should look like this: 


                    http://host:port/context/path/to/resource?start={start of last page}+{size of last page}&limit={desired size of page}

For example: 


                    http://fecru.atlassian.com/rest/api/1.0/rest-service-fecru/users?size=50&limit=50

Resources

Resource providing information about available reviewers.

/rest-service/reviewer-search/{reviewId}/search?q=<value>&includeUsers=<value>&includeGroups=<value>&limit=<value>

resource-wide template parameters
parameter value description

reviewId

string

review id determining allowed reviewers
Methods

GET

Get review participants (users and groups) which are allowed to participate in given review and match a query.

request query parameters
parameter value description

q

string

the query string to search groups containing the string in the name, and to search users containing the string in username, name and email

includeUsers

boolean

Default: true

true if it should search users by username, displayname and email

includeGroups

boolean

Default: true

true if it should search groups by name

limit

int

Default: 25

the maximum number of results to be returned

available response representations:

  • 200 - application/json [expand]
  • 403 - application/json [expand]
  • 404 - application/json [expand]

/rest-service/reviewer-search/{reviewId}/group-members/{groupName:.+}?start=<value>&limit=<value>

resource-wide template parameters
parameter value description

groupName

string

group name whose members should be returned, if the group doesn't exists, empty results will be returned

reviewId

string

review id determining allowed reviewers
Methods

GET

Get members of groups being allowed to participate in given review. Note that this path doesn't follow the REST standard, like {reviewId}/groups/{groupName}/members, because there is a chance to have ambiguous path for different resources. For example if the group is 'department/members' and you want to GET this entity, you call GET {reviewId}/groups/department/members but this could be treated as GET entity of group 'department/members' or GET members of group 'department'

request query parameters
parameter value description

start

int

Default: 0

the number of first result to be returned

limit

int

Default: 50

the maximum number of results to be returned

available response representations:

  • 200 - application/json [expand]
  • 403 - application/json [expand]
  • 404 - application/json [expand]

/rest-service/auth-v1

This resource offers the ability for client applications to authenticate with Crucible and use the returned session identifier to make further calls without the need to send the caller's username and password every time.

The received token should be used as a FEAUTH query parameter for subsequent REST requests.

Usage of this resource is not required, as Crucible's REST API also supports basic HTTP authentication whereby the caller embeds the username and password in the HTTP request headers of every call, making the process completely stateless.

See https://developer.atlassian.com/display/FECRUDEV/Authenticating+REST+Requests for more details.

/rest-service/auth-v1/login

Methods

POST

Deprecated since FishEye 3.5.0 for removal in 4.0. Use POST /rest-service-fecru/auth/login instead.

Get the user authentication token.

acceptable request representations:

request form value parameters
parameter value description

userName

string

the username of the user to get the token for

password

string

the password for the user to get the token for
  • application/x-www-form-urlencoded [expand]

available response representations:

  • 200 - application/xml (loginResult) [expand]
  • 200 - application/json (loginResult) [expand]
  • 403 - application/xml [expand]
  • 403 - application/json [expand]

GET

Deprecated since FishEye 3.5.0 for removal in 4.0. Use POST /rest-service-fecru/auth/login instead.

Get the user authentication token.
This is a legacy version of the login request. Using GET is deprecated as your password is likely to appear in logs which record request URLs. Use the POST version instead.
request query parameters
parameter value description

userName

string

the username of the user to get the token for

password

string

the password for the user to get the token for

available response representations:

  • 200 - application/xml (loginResult) [expand]
  • 200 - application/json (loginResult) [expand]
  • 403 - application/xml [expand]
  • 403 - application/json [expand]

/rest-service

Endpoint for accessing review activity items. List of supported activity items: {@link com.atlassian.fecru.activityitem.ActivityItemDataService.Type} {@see ActivityItemDataService}

/rest-service/reviews/{permId}/activityitems?type=<value>&createdAfter=<value>

resource-wide template parameters
parameter value description

permId

string
Methods

GET

request query parameters
parameter value description

type

string

createdAfter

string

available response representations:

/rest-service/users-v1?username=<value>

Methods

GET

Get a list of all the users. You can also ask for a set of users.

request query parameters
parameter value description

username

string

a username (or a few) to limit the number of returned entries. It will return only existing users.

available response representations:

  • 200 - application/xml (users) [expand]
  • 200 - application/json (users) [expand]
  • 403 - application/xml [expand]
  • 403 - application/json [expand]

/rest-service/users-v1/{repository}/{username}

resource-wide template parameters
parameter value description

repository

string

the key of the repository

username

string

the name of the committer
Methods

GET

Returns the user details of the user mapped to a committer in a repository.

available response representations:

  • 200 - application/xml (userData) [expand]
  • 200 - application/json (userData) [expand]
  • 403 - application/xml [expand]
  • 403 - application/json [expand]
  • 404 - application/xml [expand]
  • 404 - application/json [expand]

/rest-service/users-v1/{username}

resource-wide template parameters
parameter value description

username

string

the username of the user
Methods

GET

Returns the user's profile details.

available response representations:

  • 200 - application/xml (restUserProfileData) [expand]
  • 200 - application/json (restUserProfileData) [expand]
  • 403 - application/xml [expand]
  • 403 - application/json [expand]
  • 404 - application/xml [expand]
  • 404 - application/json [expand]

/rest-service/search-v1

Provides an API for searching reviews.

/rest-service/search-v1/reviews?term=<value>&maxReturn=<value>

Methods

GET

Search for reviews where the name, description, state or permaId contain the specified term.

request query parameters
parameter value description

term

string

a search term.

maxReturn

string

the maximum number of reviews to return.

available response representations:

  • 200 - application/xml (reviews) [expand]
  • 200 - application/json (reviews) [expand]

/rest-service/search-v1/reviewsForIssue?jiraKey=<value>&maxReturn=<value>

Methods

GET

Get a list of all reviews that have been linked to the specified Jira issue key.

request query parameters
parameter value description

jiraKey

string

a Jira issue key (e.g. "FOO-3453")

maxReturn

string

the maximum number of reviews to return.

available response representations:

  • 200 - application/xml (reviews) [expand]
  • 200 - application/json (reviews) [expand]

/rest-service/reviews-v1?state=<value>

Methods

GET

Get all reviews as a list of ReviewData structures. Note that this may return a lot of data, so using /reviews-v1/filter/<filter> is usually better.

The state parameter is a comma separated list of state names from the set Draft, Approval, Review, Summarize, Closed, Dead, Rejected, Unknown.

request query parameters
parameter value description

state

string

only return reviews that are in these states.

available response representations:

  • 200 - application/xml (reviews) [expand]
  • 200 - application/json (reviews) [expand]

POST

Create a review from the given createReview element.

The sub-elements of the createReview element determine what type of review is created and how it is populated. The following rules govern which sub-elemnts can be present and how they are used in the review creation process

  • If the snippet element is specified a reviewData element must be supplied and no other elements may be supplied.
  • At least one of reviewData and detailedReviewData must be supplied. If both are supplied, the reviewers element of the detailedReviewData element is used. All other elements of detailedReviewData are ignored.
  • If the state element is present and has the value of "Review" in the reviewData (or detailedReviewData if used), then the review will be approved at creation, where allowed
  • The changesets and path elements can be supplied with either the reviewData or detailedReviewData elements.

The response includes the Location header that contains the URL of the newly created entity.

acceptable request representations:

  • application/xml (createReview) [expand]
  • application/json (createReview) [expand]

available response representations:

  • 200 - application/xml (reviewData) [expand]
  • 200 - application/json (reviewData) [expand]
  • 409 - application/xml (conflict) [expand]
  • 409 - application/json (conflict) [expand]

/rest-service/reviews-v1/{id}/comments/{cId}?render=<value>

resource-wide template parameters
parameter value description

id

string

the review perma id

cId

string

the comment perma id
Methods

GET

Gets the given comment.

request query parameters
parameter value description

render

boolean

Default: false

true if the wiki text should be rendered into html, into the field <messageAsHtml>.

available response representations:

  • 200 - application/xml (comment) [expand]
  • 200 - application/json (comment) [expand]
  • 400 - application/xml (error) [expand]
  • 400 - application/json (error) [expand]
  • 403 - application/xml (error) [expand]
  • 403 - application/json (error) [expand]
  • 404 - application/xml (error) [expand]
  • 404 - application/json (error) [expand]

POST

Updates the comment given by the perma id to the new comment posted.

acceptable request representations:

  • application/xml (newComment) [expand]
  • application/json (newComment) [expand]

DELETE

Deletes the given comment.

/rest-service/reviews-v1/{id}/addFile

resource-wide template parameters
parameter value description

id

string

the review perma id to add the file
Methods

POST

Adds a file to the review, optionally diff'ed to a second file.

In contrast to a patch, files can be either binary or text. Depending on the filetype, size and contents, Crucible may be able to display either parts, or the entire file in the review. It is possible to upload two versions of the file, in which case Crucible will display a diff and report that the file was modified. When only a single file is uploaded, Crucible treats the file as newly added.

This action returns the ReviewData document on success.

This resources uses multipart form-data to receive the file(s), character set indication and optional comments (it does not expect an XML document with embedded files, as that would require the client to first encode the files in Base64). Making a multipart form-data request can be done manually, but you will probably want to use a library.

During testing it is convenient to let your browser generate the requests using the test html form below: 

 <html>
 <head><title>Rest File Upload Test</title></head>
 <body>
     <form action="http://localhost:8060/rest-service/reviews-v1/CR-4/addFile" enctype="multipart/form-data" method="POST">
         <table>
             <tr>
                 <td>File (required):</td>
                 <td><input name="file" type="file"/></td>
             </tr>
 

             <tr>
                 <td>Diff to (optional):</td>
                 <td><input name="diffFile" type="file"/></td>
             </tr>
             <tr>
                 <td>Character Set (optional):</td>
                 <td><input name="charset" type="text" value="UTF-8"/></td>
             </tr>
 

             <tr>
                 <td>Comments (optional):</td>
                 <td><input type="text" name="comments"/></td>
             </tr>
             <tr><td><input type="submit" value="Upload"/></td></tr>
         </table>
     </form>
 </body>
 </html>

available response representations:

  • 200 - application/xml (reviewItem) [expand]
  • 200 - application/json (reviewItem) [expand]
  • 409 - application/xml (error) [expand]
  • 409 - application/json (error) [expand]

/rest-service/reviews-v1/metrics/{version}

resource-wide template parameters
parameter value description

version

string

a metrics version.
Methods

GET

Get comment metrics metadata for the specified metrics version.

available response representations:

  • 200 - application/xml [expand]
  • 200 - application/json [expand]

/rest-service/reviews-v1/versionInfo

Methods

GET

Returns Crucible version information.

available response representations:

  • 200 - application/xml (versionInfo) [expand]
  • 200 - application/json (versionInfo) [expand]

/rest-service/reviews-v1/details?state=<value>

Methods

GET

Retrieves all reviews that are in one of the the specified states. For each review all details are included (review items + comments). The wiki rendered comments will be available via the <messageAsHtml> element

request query parameters
parameter value description

state

string

the review states to match.

available response representations:

  • 200 - application/xml (detailedReviews) [expand]
  • 200 - application/json (detailedReviews) [expand]

/rest-service/reviews-v1/filter/{filter}

resource-wide template parameters
parameter value description

filter

string

a predefined filter type.

Available filter names are:

  • allReviews - All reviews for everyone.
  • allOpenReviews - Open reviews for everyone.
  • allClosedReviews - Closed reviews for everyone.
  • draftReviews - Draft reviews for everyone.
  • toReview - Reviews on which the current user is an uncompleted reviewer.
  • requireMyApproval - Reviews waiting to be approved by the current user.
  • toSummarize - Completed reviews which are ready for the current user to summarize.
  • outForReview - Reviews with uncompleted reviewers, on which the current reviewer is the moderator.
  • drafts - Draft reviews created by the current user.
  • open - Open reviews created by the current user.
  • completed - Open reviews where the current user is a completed reviewer.
  • closed - Closed reviews created by the current user.
  • trash - Abandoned reviews created by the current user.

Methods

GET

Get all the reviews which match the given filter, for the current user.

available response representations:

  • 200 - application/xml (reviews) [expand]
  • 200 - application/json (reviews) [expand]

/rest-service/reviews-v1/filter/{filter}/details

resource-wide template parameters
parameter value description

filter

string

a predefined filter type.

Available filter names are:

  • allReviews - All reviews for everyone.
  • allOpenReviews - Open reviews for everyone.
  • allClosedReviews - Closed reviews for everyone.
  • draftReviews - Draft reviews for everyone.
  • toReview - Reviews on which the current user is an uncompleted reviewer.
  • requireMyApproval - Reviews waiting to be approved by the current user.
  • toSummarize - Completed reviews which are ready for the current user to summarize.
  • outForReview - Reviews with uncompleted reviewers, on which the current reviewer is the moderator.
  • drafts - Draft reviews created by the current user.
  • open - Open reviews created by the current user.
  • closed - Closed reviews created by the current user.
  • trash - Abandoned reviews created by the current user.

Methods

GET

Gets a list of all the reviews that match the specified filter criteria.

For each review all details are included (review items + comments).

available response representations:

  • 200 - application/xml (filter) [expand]
  • 200 - application/json (filter) [expand]

/rest-service/reviews-v1/filter?title=<value>&author=<value>&moderator=<value>&creator=<value>&states=<value>&reviewer=<value>&orRoles=<value>&complete=<value>&allReviewersComplete=<value>&project=<value>&fromDate=<value>&toDate=<value>

Methods

GET

Returns all reviews that satisfy the specified filter parameters and are accessible under the provided credentials.

To ignore a property, omit it from the query string.
request query parameters
parameter value description

title

string

a string that will be searched for in review titles.

author

string

reviews authored by this user.

moderator

string

reviews moderated by this user.

creator

string

reviews created by this user.

states

string

comma-separated list of amy of the following strings: (Draft, Approval, Review, Summarize, Closed, Dead, Rejected, Unknown).

reviewer

string

reviews reviewed by this user.

orRoles

boolean

whether the value of author, creator, moderator and reviewer should be OR'd (orRoles=true) or AND'd (orRoles=false) together.

complete

boolean

reviews that the specified reviewer has completed.

allReviewersComplete

boolean

Reviews that all reviewers have completed.

project

string

reviews for the specified project.

fromDate

long

reviews with last activity date after the specified timestamp, in milliseconds. Inclusive.

toDate

long

reviews with last activity date before the specified timestamp, in milliseconds. Inclusive.

available response representations:

  • 200 - application/xml [expand]
  • 200 - application/json [expand]

POST

This method should no longer be used, as it uses a POST for a read-only retrieval operation and is provided for backward compatibility only.

Do a GET instead.

acceptable request representations:

  • application/xml (customFilterData) [expand]
  • application/json (customFilterData) [expand]

available response representations:

  • 200 - application/xml (reviews) [expand]
  • 200 - application/json (reviews) [expand]

/rest-service/reviews-v1/filter/details?title=<value>&author=<value>&moderator=<value>&creator=<value>&states=<value>&reviewer=<value>&orRoles=<value>&complete=<value>&allReviewersComplete=<value>&project=<value>&fromDate=<value>&toDate=<value>

Methods

GET

Returns all (detailed) information of all reviews that satisfy the specified filter parameters and are accessible under the provided credentials.

To ignore a property, omit it from the query string.
request query parameters
parameter value description

title

string

a string that will be searched for in review titles.

author

string

reviews authored by this user.

moderator

string

reviews moderated by this user.

creator

string

reviews created by this user.

states

string

comma-separated list of amy of the following strings: (Draft, Approval, Review, Summarize, Closed, Dead, Rejected, Unknown).

reviewer

string

reviews reviewed by this user.

orRoles

boolean

whether the value of author, creator, moderator and reviewer should be OR'd (orRoles=true) or AND'd (orRoles=false) together.

complete

boolean

reviews that the specified reviewer has completed.

allReviewersComplete

boolean

Reviews that all reviewers have completed.

project

string

reviews for the specified project.

fromDate

long

reviews with last activity date after the specified timestamp, in milliseconds. Inclusive.

toDate

long

reviews with last activity date before the specified timestamp, in milliseconds. Inclusive.

available response representations:

  • 200 - application/xml (detailedReviews) [expand]
  • 200 - application/json (detailedReviews) [expand]

/rest-service/reviews-v1/search/{repository}?path=<value>

resource-wide template parameters
parameter value description

repository

string

the key of the repository to search for file
Methods

GET

Return a list of Reviews which include a particular file.

The path parameter must be the full path name of a file in repository, with no leading slash.

request query parameters
parameter value description

path

string

path to find in reviews

available response representations:

  • 200 - application/xml (reviews) [expand]
  • 200 - application/json (reviews) [expand]

/rest-service/reviews-v1/search/{repository}/details?path=<value>

resource-wide template parameters
parameter value description

repository

string

the key of the repository to search for file.
Methods

GET

Return a list of Reviews which include a particular file.

The path parameter must be the full path name of a file in repository, with no leading slash.

For each review all details are included (review items + comments).

request query parameters
parameter value description

path

string

path to find in reviews.

available response representations:

  • 200 - application/xml (detailedReviews) [expand]
  • 200 - application/json (detailedReviews) [expand]

/rest-service/reviews-v1/{id}

resource-wide template parameters
parameter value description

id

string

the permId of the review to delete (e.g. "CR-45").
Methods

GET

Get a single review by its permId (e.g. "CR-45"). If the review does not exist, a 404 is returned.

The moderator element may not exist if the review does not have a Moderator.

available response representations:

  • 200 - application/xml (reviewData) [expand]
  • 200 - application/json (reviewData) [expand]
  • 404 - application/xml (error) [expand]
  • 404 - application/json (error) [expand]

DELETE

Permanently deletes the specified review. The review must have been abandoned.

/rest-service/reviews-v1/{id}/details

resource-wide template parameters
parameter value description

id

string

the permId of the review (e.g. "CR-45").
Methods

GET

Returns the specified review.

All details are included (review items + comments).

available response representations:

  • 200 - application/xml (detailedReviewData) [expand]
  • 200 - application/json (detailedReviewData) [expand]

/rest-service/reviews-v1/{id}/actions

resource-wide template parameters
parameter value description

id

string

the permId of the a review (e.g. "CR-45").
Methods

GET

Get a list of the actions which the current user is allowed to perform on the review.

This shows actions the user has permission to perform - the review may not be in a suitable state for all these actions to be performed.

available response representations:

  • 200 - application/xml (actions) [expand]
  • 200 - application/json (actions) [expand]

/rest-service/reviews-v1/{id}/transitions

resource-wide template parameters
parameter value description

id

string

the permId of the a review (e.g. "CR-45").
Methods

GET

Get a list of the actions which the current user can perform on this review, given its current state and the user's permissions.

available response representations:

  • 200 - application/xml (transitions) [expand]
  • 200 - application/json (transitions) [expand]

/rest-service/reviews-v1/{id}/addChangeset

resource-wide template parameters
parameter value description

id

string

the perm id of the review to add the changeset to
Methods

POST

acceptable request representations:

  • application/xml (addChangeset) [expand]
  • application/json (addChangeset) [expand]

available response representations:

  • 200 - application/xml (reviewData) [expand]
  • 200 - application/json (reviewData) [expand]
  • 400 (error) [expand]
  • 409 (error) [expand]

/rest-service/reviews-v1/{id}/patch

resource-wide template parameters
parameter value description

id

string

the review id to get the patches for
Methods

POST

Add the revisions in a patch to an existing review.

If the anchor field is filled Crucible will attempt to anchor the patch to the specified repository/path

If the source field is filled Crucible will attempt to add the patch to the existing patch with the given source name. Both patches need to be anchored to the same repository. Use GET reviews-v1/{id}/patch to get a list of valid sources.

acceptable request representations:

  • application/xml [expand]
  • application/json [expand]

available response representations:

  • 200 - application/xml (reviewData) [expand]
  • 200 - application/json (reviewData) [expand]
  • 409 - application/xml (error) [expand]
  • 409 - application/json (error) [expand]

GET

Get a list of patches and their details for the given review

available response representations:

  • 200 - application/xml (patchGroups) [expand]
  • 200 - application/json (patchGroups) [expand]

/rest-service/reviews-v1/{id}/patch/{patchId}

resource-wide template parameters
parameter value description

patchId

int

the id of the patch (as returned by the '{id}/patch' resource)

id

string

the permaId of the review
Methods

DELETE

Removes the patch with the given id from the review. All of the revisions provided by the patch will be removed as well.

available response representations:

  • 200 - application/xml (patchGroups) [expand]
  • 200 - application/json (patchGroups) [expand]

/rest-service/reviews-v1/{id}/addPatch

resource-wide template parameters
parameter value description

id

string
Methods

POST

Old, non-restful name. Kept for backwards compatibility. Exactly the same as POSTing to /{id}/patch

acceptable request representations:

  • application/xml [expand]
  • application/json [expand]

available response representations:

  • 200 [expand]
  • 409 - application/xml (error) [expand]
  • 409 - application/json (error) [expand]

/rest-service/reviews-v1/{id}/reviewers

resource-wide template parameters
parameter value description

id

string

the id of the review to add to
Methods

GET

Get a list of reviewers in the review given by the permaid id.

available response representations:

  • 200 - application/xml (reviewers) [expand]
  • 200 - application/json (reviewers) [expand]

POST

Adds the given list of reviewers to the review.

acceptable request representations:

  • application/xml (reviewers) [expand]
  • application/json (reviewers) [expand]

/rest-service/reviews-v1/{id}/reviewers/completed

resource-wide template parameters
parameter value description

id

string

the review perma id to retrieve reviewers
Methods

GET

Gets a list of completed reviewers.

available response representations:

  • 200 - application/xml (reviewers) [expand]
  • 200 - application/json (reviewers) [expand]

/rest-service/reviews-v1/{id}/reviewers/uncompleted

resource-wide template parameters
parameter value description

id

string

the review perma id to retrieve reviewers
Methods

GET

Gets a list of reviewers that have not completed the review.

available response representations:

  • 200 - application/xml (reviewers) [expand]
  • 200 - application/json (reviewers) [expand]

/rest-service/reviews-v1/{id}/reviewers/{username}

resource-wide template parameters
parameter value description

id

string

the perma id of the review

username

string

the name of the reviewer.
Methods

DELETE

Removes the reviewer from the review.

/rest-service/reviews-v1/{id}/reviewitems

resource-wide template parameters
parameter value description

id

string

the id of the review (e.g. "CR-362").
Methods

GET

Returns a list of all the items in a review.

available response representations:

  • 200 - application/xml (reviewItems) [expand]
  • 200 - application/json (reviewItems) [expand]

POST

Add the changes between two files in a fisheye repository to the review.

This call includes the Location repsonse header that contains the URL of the newly created entity.

acceptable request representations:

  • application/xml (reviewItem) [expand]
  • application/json (reviewItem) [expand]

available response representations:

  • 200 - application/xml (reviewItem) [expand]
  • 200 - application/json (reviewItem) [expand]
  • 409 - application/xml (error) [expand]
  • 409 - application/json (error) [expand]

/rest-service/reviews-v1/{id}/reviewitems/revisions

resource-wide template parameters
parameter value description

id

string

the id of the review (e.g. "CR-362").
Methods

POST

Adds a review item for each of the supplied crucibleRevisionData elements.

Provide a list of crucibleRevisionData elements, each one containing the desired shape of the review item. If a crucibleRevisionData element contains a path that already exists (i.e., an existing review item with the same path is in the review), then the crucibleRevisionData element given here will merge the revisions with the existing review item revisions instead of creating a new review item.

acceptable request representations:

  • application/xml (revisions) [expand]
  • application/json (revisions) [expand]

available response representations:

  • 200 - application/xml (detailedReviewData) [expand]
  • 200 - application/json (detailedReviewData) [expand]
  • 400 - application/xml (error) [expand]
  • 400 - application/json (error) [expand]
  • 401 - application/xml (error) [expand]
  • 401 - application/json (error) [expand]
  • 409 - application/xml (error) [expand]
  • 409 - application/json (error) [expand]

/rest-service/reviews-v1/{id}/reviewitems/details

resource-wide template parameters
parameter value description

id

string

the id of the review (e.g. "CR-362").
Methods

POST

Adds the given review item to the review. This will always create a new review item, even if there is an existing one with the same data in the review (in which case the existing item will be replaced).

The response includes the Location HTTP header.

acceptable request representations:

  • application/xml (reviewItem) [expand]
  • application/json (reviewItem) [expand]

available response representations:

  • 200 - application/xml (reviewItem) [expand]
  • 200 - application/json (reviewItem) [expand]
  • 409 - application/xml (error) [expand]
  • 409 - application/json (error) [expand]

/rest-service/reviews-v1/{id}/reviewitems/{riId}/details

resource-wide template parameters
parameter value description

riId

string

a valid review item id (e.g. "CFR-5622").

id

string

a valid review id (e.g. "CR-345").
Methods

PUT

Sets the review item specified by itemId with the given reviewItem. The old review item is discarded. Can only perform this operation if the old review item specified by itemId can be deleted. The old review item's permId is not changed.

acceptable request representations:

  • application/xml (fisheyeReviewItemData) [expand]
  • application/json (fisheyeReviewItemData) [expand]

available response representations:

  • 200 - application/xml [expand]
  • 200 - application/json [expand]
  • 409 - application/xml (error) [expand]
  • 409 - application/json (error) [expand]

/rest-service/reviews-v1/{id}/reviewitems/{riId}/revisions;rev=...

resource-wide template parameters
parameter value description

riId

string

the id of the review item from which to remove the list of revisions (e.g. "CFR-5622").

id

string

the PermId of the review to remove the item from (e.g. "CR-345").
resource-wide matrix parameters
parameter value description

rev

string

a list of revisions to remove. If the revision does not exist in the review item, it is ignored.
Methods

POST

Adds the given list of revisions to the supplied review item, merging if required. For example, if the review item for a.txt contains revisions 3 to 6, and if:

  • revisions to add is 4 and 5, then a.txt will have revisions 3--4--5--6
  • revisions to add is 2 and 7, then a.txt will have revisions 2--3--6--7
  • revisions to add is just 2, then a.txt will have revisions 2--3--6
  • revisions to add is just 7, then a.txt will have revisions 3--6--7
  • revisions to add is 2 and 4, then a.txt will have revisions 2--3--4--6
  • revisions to add is 4 and 7, then a.txt will have revisions 3--4--6--7

available response representations:

  • 200 - application/xml [expand]
  • 200 - application/json [expand]
  • 409 - application/xml (error) [expand]
  • 409 - application/json (error) [expand]

DELETE

Removes the revisions given from the review item in the review specified by the id. If the review item has no more revisions left, it is automatically deleted.

/rest-service/reviews-v1/{id}/reviewitems/{riId}

resource-wide template parameters
parameter value description

riId

string

review item id (e.g. "CFR-6312").

id

string

review id (e.g. "CR-345").
Methods

DELETE

Removes an item from a review.

GET

Returns detailed information for a specific review item.

available response representations:

  • 200 - application/xml [expand]
  • 200 - application/json [expand]

/rest-service/reviews-v1/{id}/comments?render=<value>

resource-wide template parameters
parameter value description

id

string

the review perma-id
Methods

GET

Return all the comments visible to the requesting user for the review.

request query parameters
parameter value description

render

boolean

Default: false

indicate whether to render the wiki text in the returned comments. If set to "true", the comments will contain a <messageAsHtml> element containing the wiki rendered html.

available response representations:

  • 200 - application/xml (comments) [expand]
  • 200 - application/json (comments) [expand]
  • 400 - application/xml (error) [expand]
  • 400 - application/json (error) [expand]
  • 403 - application/xml (error) [expand]
  • 403 - application/json (error) [expand]
  • 404 - application/xml (error) [expand]
  • 404 - application/json (error) [expand]

POST

Add a general comment to the review.

acceptable request representations:

  • application/xml [expand]
  • application/json [expand]

available response representations:

  • 201 - application/xml (generalCommentData) [expand]
  • 201 - application/json (generalCommentData) [expand]
  • 400 - application/xml (error) [expand]
  • 400 - application/json (error) [expand]
  • 403 - application/xml (error) [expand]
  • 403 - application/json (error) [expand]
  • 404 - application/xml (error) [expand]
  • 404 - application/json (error) [expand]

/rest-service/reviews-v1/{id}/comments/general?render=<value>

resource-wide template parameters
parameter value description

id

string

review perma-id
Methods

GET

request query parameters
parameter value description

render

boolean

Default: false

indicate whether to render the wiki text in the returned comments. If set to "true", the comments will contain a <messageAsHtml> element containing the wiki rendered html.

available response representations:

  • 200 - application/xml (comments) [expand]
  • 200 - application/json (comments) [expand]
  • 400 - application/xml (error) [expand]
  • 400 - application/json (error) [expand]
  • 403 - application/xml (error) [expand]
  • 403 - application/json (error) [expand]
  • 404 - application/xml (error) [expand]
  • 404 - application/json (error) [expand]

/rest-service/reviews-v1/{id}/comments/versioned?render=<value>

resource-wide template parameters
parameter value description

id

string

review perma-id
Methods

GET

request query parameters
parameter value description

render

boolean

Default: false

indicate whether to render the wiki text in the returned comments. If set to "true", the comments will contain a <messageAsHtml> element containing the wiki rendered html.

available response representations:

  • 200 - application/xml (comments) [expand]
  • 200 - application/json (comments) [expand]
  • 400 - application/xml (error) [expand]
  • 400 - application/json (error) [expand]
  • 403 - application/xml (error) [expand]
  • 403 - application/json (error) [expand]
  • 404 - application/xml (error) [expand]
  • 404 - application/json (error) [expand]

/rest-service/reviews-v1/{id}/reviewitems/{riId}/comments?render=<value>

resource-wide template parameters
parameter value description

riId

string

the review item id.

id

string

the review perma id
Methods

GET

request query parameters
parameter value description

render

boolean

Default: false

indicate whether to render the wiki text in the returned comments. If set to "true", the comments will contain a <messageAsHtml> element containing the wiki rendered html.

available response representations:

  • 200 - application/xml (comments) [expand]
  • 200 - application/json (comments) [expand]
  • 400 - application/xml (error) [expand]
  • 400 - application/json (error) [expand]
  • 403 - application/xml (error) [expand]
  • 403 - application/json (error) [expand]
  • 404 - application/xml (error) [expand]
  • 404 - application/json (error) [expand]

POST

This call includes the Location repsonse header that contains the URL of the newly created entity.

acceptable request representations:

  • application/xml (versionedLineCommentData) [expand]
  • application/json (versionedLineCommentData) [expand]

available response representations:

  • 200 - application/xml [expand]
  • 200 - application/json [expand]

/rest-service/reviews-v1/{id}/comments/{cId}/replies?render=<value>

resource-wide template parameters
parameter value description

id

string

the review perma-id (e.g. "CR-45").

cId

string

the comment to reply to
Methods

GET

Gets the replies to the given comment.

request query parameters
parameter value description

render

boolean

Default: false

true if the comments should also be rendered into html, into the element <messageAsHtml>

available response representations:

  • 200 - application/xml (comments) [expand]
  • 200 - application/json (comments) [expand]
  • 400 - application/xml (error) [expand]
  • 400 - application/json (error) [expand]
  • 403 - application/xml (error) [expand]
  • 403 - application/json (error) [expand]
  • 404 - application/xml (error) [expand]
  • 404 - application/json (error) [expand]

POST

Adds a reply to the given comment. This call includes the Location repsonse header that contains the URL of the newly created entity.

acceptable request representations:

  • application/xml (generalCommentData) [expand]
  • application/json (generalCommentData) [expand]

available response representations:

  • 201 - application/xml (generalCommentData) [expand]
  • 201 - application/json (generalCommentData) [expand]

/rest-service/reviews-v1/{id}/comments/markAllAsRead

resource-wide template parameters
parameter value description

id

string

the review perma-id (e.g. "CR-45").
Methods

POST

For the effective user, mark all comments in a review as read (except those marked as leave unread).

available response representations:

  • 200 - application/xml (detailedReviewData) [expand]
  • 200 - application/json (detailedReviewData) [expand]

/rest-service/reviews-v1/{id}/comments/{cId}/markAsRead

resource-wide template parameters
parameter value description

id

string

the review perma id

cId

string

the comment perma id.
Methods

POST

Mark the given comment as read for the user used to make this POST.

available response representations:

  • 200 - application/xml (commentData) [expand]
  • 200 - application/json (commentData) [expand]

/rest-service/reviews-v1/{id}/comments/{cId}/markAsLeaveUnread

resource-wide template parameters
parameter value description

id

string

the review perma id for the comment

cId

string

the comment perma id
Methods

POST

Marks the comment as leave unread to the current user - it will not automatically be marked as read by crucible.

available response representations:

  • 200 - application/xml (commentData) [expand]
  • 200 - application/json (commentData) [expand]

/rest-service/reviews-v1/{id}/comments/{cId}/replies/{rId}

resource-wide template parameters
parameter value description

id

string

The review perma id

rId

string

the perma id of the reply to delete

cId

string

the reply's parent comment perma id
Methods

POST

Updates a reply with the given newComment.

acceptable request representations:

  • application/xml (generalCommentData) [expand]
  • application/json (generalCommentData) [expand]

DELETE

Deletes the reply.

/rest-service/reviews-v1/{id}/publish

resource-wide template parameters
parameter value description

id

string

the review perma id to look for draft comments
Methods

POST

Publishes all the draft comments of the current user.

/rest-service/reviews-v1/{id}/publish/{cId}

resource-wide template parameters
parameter value description

id

string

the review perma id

cId

string

the comment perma id
Methods

POST

publishes the given draft comment.

/rest-service/reviews-v1/{id}/complete?ignoreWarnings=<value>

resource-wide template parameters
parameter value description

id

string

the review perma id
Methods

POST

Completes the review for the current user

request query parameters
parameter value description

ignoreWarnings

boolean

Default: true

if {@code ignoreWarnings==true} then condition failure warnings will be ignored

available response representations:

  • 409 - application/xml [expand]
  • 409 - application/json [expand]

/rest-service/reviews-v1/{id}/uncomplete?ignoreWarnings=<value>

resource-wide template parameters
parameter value description

id

string

the review perma id
Methods

POST

Uncompletes the review for the current user.

request query parameters
parameter value description

ignoreWarnings

boolean

Default: true

if {@code ignoreWarnings==true} then condition failure warnings will be ignored

available response representations:

  • 409 - application/xml [expand]
  • 409 - application/json [expand]

/rest-service/reviews-v1/{id}/transition?action=<value>&ignoreWarnings=<value>

resource-wide template parameters
parameter value description

id

string

the review perma-id (e.g. "CR-45").
Methods

POST

Change the state of a review by performing an action on it.

request query parameters
parameter value description

action

string

the string representation of the action to perform. Valid actions are:

  • action:abandonReview -- abandon (i.e. cancel) a review
  • action:deleteReview -- permanently delete a review
  • action:submitReview -- submit a review to the moderator for approval
  • action:approveReview -- approve a review (i.e. issue it to the reviewers)
  • action:rejectReview -- reject a review submitted for approval
  • action:summarizeReview -- summarize a review
  • action:closeReview -- close a review once it has been summarized
  • action:reopenReview -- re-open a closed review
  • action:recoverReview -- recover an abandoned review
Note:
  • to complete a review use the /complete endpoint
  • to uncomplete a review use the /uncomplete endpoint

ignoreWarnings

boolean

Default: true

if ignoreWarnings==true then condition failure warnings will be ignored

available response representations:

  • 200 - application/xml (reviewData) [expand]
  • 200 - application/json (reviewData) [expand]
  • 409 - application/xml [expand]
  • 409 - application/json [expand]

/rest-service/reviews-v1/{id}/close

resource-wide template parameters
parameter value description

id

string

the review perma id to close. it should be in the open state.
Methods

POST

Closes the given review with the summary given.

acceptable request representations:

  • application/xml (closeReviewSummary) [expand]
  • application/json (closeReviewSummary) [expand]

available response representations:

  • 200 - application/xml (reviewData) [expand]
  • 200 - application/json (reviewData) [expand]

/rest-service/reviews-v1/{id}/remind

resource-wide template parameters
parameter value description

id

string

the review perma id to remind about. it should be in the open state.
Methods

POST

Immediately send a reminder to incomplete reviewers about the given review.

acceptable request representations:

available response representations:

/rest-service/projects-v1?excludeAllowedReviewers=<value>

Provides an API for working with Projects.

Methods

GET

Deprecated since FishEye 3.5.0 for removal in 4.0. Use GET /rest-service-fecru/admin/projects instead.

Get the list of projects that the authenticated user is entitled to access.
request query parameters
parameter value description

excludeAllowedReviewers

boolean

Default: false

if set to true, user data (e.g. allowedReviewers) which is expensive to compute, will not be included in the response data. Defaults to false so allowedReviewers are included in the response.

available response representations:

  • 200 - application/xml (projects) [expand]
  • 200 - application/json (projects) [expand]

/rest-service/projects-v1/{key}?excludeAllowedReviewers=<value>

resource-wide template parameters
parameter value description

key

string

the key of a Crucible project.
Methods

GET

Deprecated since FishEye 3.5.0 for removal in 4.0. Use GET /rest-service-fecru/admin/projects/[key] instead.

Returns a project description.

If the specified project does not exist, or the caller does not have permission to access the project, 404 is returned.

request query parameters
parameter value description

excludeAllowedReviewers

boolean

Default: false

available response representations:

  • 200 - application/xml (projectData) [expand]
  • 200 - application/json (projectData) [expand]
  • 404 - application/xml (error) [expand]
  • 404 - application/json (error) [expand]

/rest-service/repositories-v1?name=<value>&enabled=<value>&available=<value>&type=<value>&limit=<value>

Methods

GET

Returns a list of all repositories. This includes plugin provided repositories

request query parameters
parameter value description

name

string

filter repositories by the repository key, only repositories of keys containing this value would be returned if value was provided. Case insensitive.

enabled

boolean

filter repositories by enabled flag. Only enabled/disabled repositories would be returned accordingly if value was provided.

available

boolean

filter repositories by its availability. Only available/unavailable repositories would be returned accordingly if value was provided.

type

string

filter repositories by type. Allowed values: cvs, svn, p4, git, hg, plugin (for light SCM repositories). Parameter can be specified more than once.

limit

int

Default: 10000

maximum number of repositories to be returned.

available response representations:

  • 200 - application/xml (repositories) [expand]
  • 200 - application/json (repositories) [expand]

/rest-service/repositories-v1/content/{repository}/{revision}/{path:.*$}

resource-wide template parameters
parameter value description

path

string

the path of a file.

repository

string

the key of the Crucible SCM plugin repository.

revision

string

the SCM revision string.
Methods

GET

Returns the raw content of the specified file revision as a binary stream. No attempt is made to identify the content type and no mime type is provided.

available response representations:

  • 200 [expand]

/rest-service/repositories-v1/change/{repository}/{revision}

resource-wide template parameters
parameter value description

repository

string

the key of the Crucible SCM plugin repository.

revision

string

the SCM revision string.
Methods

GET

Represents a particular changeset.

available response representations:

  • 200 - application/xml (change) [expand]
  • 200 - application/json (change) [expand]

/rest-service/repositories-v1/changes/{repository}/{path:.*$}?oldestCsid=<value>&includeOldest=<value>&newestCsid=<value>&includeNewest=<value>&max=<value>

resource-wide template parameters
parameter value description

path

string

only show change sets which contain at least one revision with a path under this path. Changesets with some revisions outside this path still include all revisions. i.e. Revisions outside the path are *not* excluded from the change set.

repository

string

the key of the Crucible SCM plugin repository.
Methods

GET

Represents a sorted list of changesets, newest first.

Note that when providing a path, use a trailing slash in the request url to indicate that it is a directory (use a "/" for the root directory of the repository). This may be necessary for some SCM plugins (including svn-light).

request query parameters
parameter value description

oldestCsid

string

only return change sets after this change set. If omitted there is no restriction.

includeOldest

boolean

include the change set with id "from" in the change sets returned.

newestCsid

string

only return change sets before this change set. If omitted there is no restriction.

includeNewest

boolean

include the change set with id "to" in the change sets returned.

max

int

return only the newest change sets, to a maximum of maxChangesets.

available response representations:

  • 200 - application/xml (changes) [expand]
  • 200 - application/json (changes) [expand]

/rest-service/repositories-v1/{repository}/{revision}/{path:.*$}

resource-wide template parameters
parameter value description

path

string

the path of a file or versioned directory (note that versioned directories are not supported by all SCM plugins).

repository

string

the key of the Crucible SCM plugin repository.

revision

string

the SCM revision string.
Methods

GET

Represents the details of a versioned entity (file or directory). This resource can be reached by following the file's self-link from a browse result.

Note that most responses support title expansion to minimize the costs of accessing the resources. Since file meta data is not always provided by SCM plugins, it is not expanded by default in the rest responses. Use title expansion to explicitly make Crucible include it.

The xml root element declares which elements are expandable (in this response: details and diffRevision). To expand both, use: ?expand=details,diffRevision

available response representations:

  • 200 - application/xml (scmVersionedEntity) [expand]
  • 200 - application/json (scmVersionedEntity) [expand]
  • 401 - application/xml [expand]
  • 401 - application/json [expand]

/rest-service/repositories-v1/{repository}/svn

resource-wide template parameters
parameter value description

repository

string

the key of a FishEye or Crucible SCM plugin repository
Methods

GET

For backward compatibility we provide this method, but repositories should be referred to just by their key.

available response representations:

  • 200 - application/xml (svnRepositoryData) [expand]
  • 200 - application/json (svnRepositoryData) [expand]

/rest-service/repositories-v1/{repository}

resource-wide template parameters
parameter value description

repository

string

the key of the Crucible SCM plugin repository.
Methods

GET

Returns the details of the repository with the specified repository key. When the repository exists, but the user has no access to it (possibly because the user is not authenticated), a 401 is returned.

The supplied repository key can be either a Crucible SCM plugin repository, or a FishEye repository.

available response representations:

  • 200 - application/xml (repositoryData) [expand]
  • 200 - application/json (repositoryData) [expand]

/rest-service/repositories-v1/browse/{repository}/{path:.*$}

resource-wide template parameters
parameter value description

path

string

path to a directory. When path represents a file name, the result is unspecified.

repository

string

the key of the Crucible SCM plugin repository.
Methods

GET

Lists the contents of the specified directory.

available response representations:

  • 200 - application/xml (listing) [expand]
  • 200 - application/json (listing) [expand]

/rest-service/repositories-v1/history/{repository}/{revision}/{path:.*$}

resource-wide template parameters
parameter value description

path

string

the path of a file or versioned directory (note that versioned directories are not supported by all SCM plugins).

repository

string

the key of the Crucible SCM plugin repository.

revision

string

the SCM revision string.
Methods

GET

Represents the history of a versioned entity.

available response representations:

  • 200 - application/xml (history) [expand]
  • 200 - application/json (history) [expand]
View cookie preferences