Skip to end of metadata
Go to start of metadata

Overview

Manage pull requests for a repository. Use this resource to perform CRUD (create/read/update/delete) operations on a pull request. This resource allows you to manage the attributes of a pull request also. For example, you can list the commits or reviewers associated with a pull request. You can also accept or decline a pull request with this resource. Finally, you can use this resource to manage the comments on a pull request as well.

FieldDescription
stateThe pull request's current status. The status is either open, rejected, or fulfilled.
descriptionDescription field for the request.
linksAn map of links pointing to other representation and related data and functionality.
titleTitle of the pull request.
close_source_branchA boolean flag indicating if merging the pull request closes the source branch.
destinationA structure containing the commit, branch and repository structures associated with the request destination repository.
reasonExplains why a pull request was declined. This field is only applicable to pull requests in rejected state.
idThe pull request's unique ID. Note that pull request IDs are only unique within their associated repository.
sourceA structure containing the commit , branch , and repository structures associated with the request source repository.
created_onDate the request was created.
authorThe user who created the pull request.
updated_onDate the request was last updated.
merge_commitThe merge commit object that was created when the pull request was accepted. This is only applicable to pull requests that are in fulfilled state.
closed_byThe user that closed the request.
reviewersThe list of users that were added as reviewers on this pull request when it was created. For performance reasons, the API only returns this list when an API requests a pull request by id.
participants

The list of users that are collaborating on this pull request. Collaborators are user that:

  • are added to the pull request as a reviewer (part of the reviewers list)
  • are not explicit reviewers, but have commented on the pull request
  • are not explicit reviewers, but have approved the pull request

Each user is wrapped in an object that indicates the user's role and whether they have approved the pull request. For performance reasons, the API only returns this list when an API requests a pull request by id.

GET a list of open pull requests

Get a list of of a repository's open pull requests.

ParameterRequired?Description
ownerYesThe account owning the repo.
repo_slugYesThe repo identifier.

This returns a paginated list of pull request objects. Note that the participants list is not included in the pull requests. To obtain the full list of participants, follow the pull requests's self link.

By default, only the open pull requests are returned. Use the state query parameter to access declined (state=DECLINED), open (state=OPEN) or merged (state=MERGED). The state parameter can be repeated to include pull requests in different states.

GET https://bitbucket.org/api/1.0/repositories/{owner}/{repo_slug}/pullrequests?state=[OPEN|MERGED|DECLINED]
 Click here to expand...

POST (create) a new pull request

Creates a new pull request. The request URL you provide is the destination repository URL. For this reason, you must specify an explicit source repository in the request object if you want to pull from a different repository.

Your JSON request body can contain a standard pull request object. However, since not all elements are required or even mutable, you only need to include the elements you want to initialize. The following structure includes all the required and optional parameters for the JSON body:

The response contains the newly created pull request object and its self link in the Location response header.

ParameterRequired?Description
titleYesA string representing the request title.
descriptionNoThe description of the pull request.
nameYes

A string identifying the source or destination branch (for example, develop). You must supply a source branch name. The destination branch name is optional. If you omit the destination name, the parameter defaults to the repository's main branch.

hashNoThe SHA1 of the source branch's head. You only need to specify this parameter for a Mercurial repository whose source branch has multiple heads.
full_nameNoThe full slug of the source repository (for example, evzijst/jira-fork). This parameter is optional and defaults to the current repository (the one from the URL), making it redundant for pull requests within the same repo.
hashNoThe SHA1 of the head of the destination branch. Necessary only for Mercurial repos where the destination repository has multiple heads.
close_source_branchNo

Boolean indicating whether Bitbucket should close the source branch after the pull requests gets merged successfully. Only use this parameter when the source and destination are in the same repo.

reviewersNo

A list of user objects to add as reviewers. You only need to provide the username element of the user object.

POST https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/pullrequests/
 Click here to expand...

PUT a pull request update

Updates an existing pull request. The pull request's status must be open. With the exception of the source and destination parameters, the request body must include all the existing request parameters; Omitting a parameter causes the server to drop the existing value. For example, if the pull requests already has 3 reviewers, the request body must include these 3 reviewers to prevent Bitbucket from dropping them.

A pull request cannot exist without the source and destination parameters. For this reason Bitbucket never drops them. The URL provides the destination and Bitbucket keeps the existing source.  

A caller cannot change any elements of the source repository or the destination repository's name. A caller can change the destination branch. To do this, provide the destination's branch element in the call. 

A pull request is stale when new commits were pushed to the source branch but the request does not yet reflect these new commits. When a PUT is called on a stale request, Bitbucket always updates the source branch to the new head commit before processing the PUT.

A PUT request body can contain any of the following fields (immutable or ignored fields not shown):

The response contains the newly created pull request object and its self link in the Location response header.

ParameterRequired?Description
titleYesA string representing the request title.
descriptionNoThe description of the pull request.
nameYes

A string identifying the destination branch (for example, develop). The destination branch name is optional. If you omit the destination name, the parameter defaults to the repository's main branch.

hashNoThe SHA1 of the source branch's head. You only need to specify this parameter for a Mercurial repository whose source branch has multiple heads.
full_nameNoThe full slug of the source repository (for example, evzijst/jira-fork). This parameter is optional and defaults to the current repository (the one from the URL), making it redundant for pull requests within the same repo.
hashNoThe SHA1 of the head of the destination branch. Necessary only for Mercurial repos where the destination repository has multiple heads.
close_source_branchNo

Boolean indicating whether Bitbucket should close the source branch after the pull requests is successfully merged. Only use this parameter when the source and destination are in the same repo.

reviewersNo

A list of user objects to add as reviewers. You only need to provide the username element of the user object.

PUT https://bitbucket.org/api/1.0/repositories/{owner}/{repo_slug}/pullrequests/{id}
 Click here to expand request body...

GET a specific pull request

Gets an specific pull request.

ParameterRequired?Description
ownerYesThe account owning the repo.
repo_slugYesThe repo identifier.
idYesThe pull request identifier.
GET https://bitbucket.org/api/1.0/repositories/{owner}/{repo_slug}/pullrequests/{id}
 Click here to expand...

GET the commits for a pull request

To get the commits associated with a specific pull request, follow the pull request's commits link. This returns a paginated response.

ParameterRequired?Description
ownerYesThe account owning the repo.
repo_slugYesThe repo identifier.
idYesThe request identifier.
GET https://bitbucket.org/api/1.0/repositories/{owner}/{repo_slug}/pullrequests/{id}/commits
 Click here to expand...

POST a pull request approval

Give your approval on a pull request. You can only approve a request on behalf of the authenticated account. This returns the participant object for the current user.

ParameterRequired?Description
ownerYesThe account owning the repo.
repo_slugYesThe repo identifier.
idYesThe pull request identifier.
POST https://bitbucket.org/api/2.0/repositories/{owner}/{repo_slug}/pullrequests/{id}/approve
 Click here to expand...

DELETE a pull request approval

Revoke your approval on a pull request. You can remove approvals on behalf of the authenticated account.

ParameterRequired?Description
ownerYesThe account owning the repo.
repo_slugYesThe repo identifier.
idYesThe request identifier.
DELETE https://bitbucket.org/api/2.0/repositories/{owner}/{repo_slug}/pullrequests/{id}/approve

On success, this method returns: HTTP/1.1 204 NO CONTENT 

GET the diff for a pull request

Gets the diff or patch for a pull request. This returns a 302 redirect response with the Location header set to the URL that will perform a temporary merge and return the diff of it. The result is identical to diff in the UI.

The diff is returned as raw text (Content-Type: text/plain). For Mercurial, git-style diffs are returned.

By default, 3 lines of context are included. This can be changed using the context=num_lines query parameter. 

ParameterRequired?Description
ownerYesThe account owning the repo.
repo_slugYesThe repo identifier.
idYesThe request identifier.
GET https://bitbucket.org/api/2.0/repositories/{owner}/{repo_slug}/pullrequests/{pull_request_id}/diff
 Click here to expand...

GET the log of all of a repository's pull request activity

Returns all the pull request activity for a repository. This call returns a historical log of all the pull request activity within a repository.

ParameterRequired?Description
ownerYesThe account owning the repo.
repo_slugYesThe repo identifier.
pull_request_idYesThe request identifier.

 

GET https://bitbucket.org/api/2.0/repositories/{owner}/{repo_slug}/pullrequests/activity
 Click here to expand...

GET the activity for a pull request

Gets a log of the activity for a specific pull request.

ParameterRequired?Description
ownerYesThe account owning the repo.
repo_slugYesThe repo identifier.
pull_request_idYesThe request identifier.
GET https://bitbucket.org/api/2.0/repositories/{owner}/{repo_slug}/pullrequests/{pull_request_id}/activity
 Click here to expand...

Accept and merge a pull request

Accept a pull request and merges into the destination branch. This requires write access on the destination repository.

ParameterRequired?Description
ownerYesThe account owning the repo.
repo_slugYesThe repo identifier.
pull_request_idYesThe pullrequest identifier.
messageNo

The message that will be used for the merge commit.

close_source_branchNoOverride the value of close_source_branch that was used at the time of pull request creation.
POST https://bitbucket.org/api/2.0/repositories/{owner}/{repo_slug}/pullrequests/{pull_request_id}/merge
 Click here to expand...

 

Decline or reject a pull request

Rejects a pull request. This requires write access on the destination repository.

ParameterRequired?Description
ownerYesThe account owning the repo.
repo_slugYesThe repo identifier.
pull_request_idYesThe pull request identifier.
messageNo

An optional reason explaining why the pull request is being rejected.

POST https://bitbucket.org/api/2.0/repositories/{owner}/{repo_slug}/pullrequests/{pull_request_id}/decline
 Click here to expand...

 

GET a list of a pull request comments

Gets the array of comments on the specified pull request. A pull request comment has the following fields:

FieldDescription
linksLinks to the comment's self location, as well as other representations and related resource.
idAn integer representing an id for the comment.
parentThe parent comment. This is is applicable only to replies and not present in top-level comments.
updated_onThe timestamp of the most recent change to the comment.
filenameThe filename the new comment concerns.
content

The content of the comment.

  • raw: the raw text as the user typed it
  • markup: the markup language used
  • html: the rendered HTML version of the markup
userThe user that added the comment.
inline

Presence of this element indicates that the comment is an inline code comment. It contains the following nested elements:

  • to: the line number of the new version in the diff that the comment was made on (the "green" line). null if the line does not exist in the new version
  • from: the line number of the old version in the diff that the comment was made on (the "red" line). null if the line did not exist in the old version
  • path: the name of the file the comment was made on

Inline comments also have an additional link in the links section (rel: "code") that points to the raw file diff.

created_onDate and time when the comment was created.

For private repositories, the caller must authenticate as a user with read access to the destination repository.

GET https://bitbucket.org/api/2.0/repositories/{owner}/{repo_slug}/pullrequests/{pull_request_id}/comments
 Click here to expand...

GET an individual pull request comment 

Gets an individual comment on an request. Private repositories require authorization with an account that has appropriate access.

Parameter
Required?
Description
ownerYesThe account owning the repo.
repo_slugYesThe repo identifier.
pull_request_idYesThe pull request identifier.
comment_idYes

The comment identifier.

GET https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/pullrequests/{pull_request_id}/comments/{comment_id}
 Click here to expand...
  • No labels

5 Comments

  1. Spec differs from reality. The overview shows only 3 states of the "state" field: openrejected, or fulfilled. But when you get specific pull request details with GET there is "MERGED" state available.

  2. Anonymous

    What about adding a comment to an existing pull request? Is that possible at all?

  3. At "Get a List of Open Pull Requests", what type of object is "merge_commit"?

  4. I think that GET the log of all of a repository's pull request activity JSON return value may be invalid.

    1. Thanks for your response. I'm not sure the existing example was invalid but I updated it just to be sure. (smile)