pullrequests Resource
Overview
Manage pull requests for a Bitbucket Cloud 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.
Field | Description |
---|---|
state | The pull request's current status. The status is either open , rejected , or fulfilled . |
description | Description field for the request. |
links | An map of links pointing to other representation and related data and functionality. |
title | Title of the pull request. |
task_count | The number of open tasks for a specific pull request. |
comment_count | The number of comments for a specific pull request. |
close_source_branch | A boolean flag indicating if merging the pull request closes the source branch. |
destination | A structure containing the commit , branch and repository structures associated with the request destination repository. |
reason | Explains why a pull request was declined. This field is only applicable to pull requests in rejected state. |
id | The pull request's unique ID. Note that pull request IDs are only unique within their associated repository. |
source | A structure containing the commit , branch , and repository structures associated with the request source repository. |
created_on | Date the request was created. |
author | The user who created the pull request. |
updated_on | Date the request was last updated. |
merge_commit | The 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_by | The user that closed the request. |
reviewers | The 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:
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.
Parameter | Required? | Description |
---|---|---|
owner | Yes | The account owning the repo. |
repo_slug | Yes | The 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 (comma separated) to include pull requests in different states.
GET https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/pullrequests?state=[OPEN, MERGED, DECLINED]
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:
{
"title": "REQUIRED title",
"description": "description",
"source": {
"branch": {
"name": "REQUIRED name"
},
"repository": {
"full_name": "owner/repo_slug"
}
},
"destination": {
"branch": {
"name": "name"
},
"commit": {
"hash": "name"
}
},
"close_source_branch": true
}
The response contains the newly created pull request object and its self link in the Location
response header.
Parameter | Required? | Description |
---|---|---|
title | Yes | A string representing the request title . |
description | No | The description of the pull request. |
name | Yes | A string identifying the |
hash | No | The 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_name | No | The 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. |
hash | No | The SHA1 of the head of the destination branch. Necessary only for Mercurial repos where the destination repository has multiple heads. |
close_source_branch | No | 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. |
reviewers | No | A list of user objects to add as reviewers. You only need to provide the |
POST https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/pullrequests/
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):
{
"title": "title",
"description": "description",
"destination": {
"branch": {
"name": "name"
},
"commit": {
"hash": "name"
}
},
"reviewers": [
{
"username": "accountname"
}
],
"close_source_branch": true
}
The response contains the newly created pull request object and its self link in the Location
response header.
Parameter | Required? | Description |
---|---|---|
title | Yes | A string representing the request title . |
description | No | The description of the pull request. |
name | Yes | A string identifying the |
hash | No | The 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_name | No | The 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. |
hash | No | The SHA1 of the head of the destination branch. Necessary only for Mercurial repos where the destination repository has multiple heads. |
close_source_branch | No | 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. |
reviewers | No | A list of user objects to add as reviewers. You only need to provide the |
PUT https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/pullrequests/{id}
GET a specific pull request
Gets an specific pull request.
Parameter | Required? | Description |
---|---|---|
owner | Yes | The account owning the repo. |
repo_slug | Yes | The repo identifier. |
id | Yes | The pull request identifier. |
comment_count | No | The number of comments in the pull request. |
task_count | No | The number of open tasks in the pull request. |
GET https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/pullrequests/{id}
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.
Parameter | Required? | Description |
---|---|---|
owner | Yes | The account owning the repo. |
repo_slug | Yes | The repo identifier. |
id | Yes | The request identifier. |
GET https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/pullrequests/{id}/commits
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.
Parameter | Required? | Description |
---|---|---|
owner | Yes | The account owning the repo. |
repo_slug | Yes | The repo identifier. |
id | Yes | The pull request identifier. |
POST https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/pullrequests/{id}/approve
DELETE a pull request approval
Revoke your approval on a pull request. You can remove approvals on behalf of the authenticated account.
Parameter | Required? | Description |
---|---|---|
owner | Yes | The account owning the repo. |
repo_slug | Yes | The repo identifier. |
id | Yes | The request identifier. |
DELETE https://api.bitbucket.org/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.
Parameter | Required? | Description |
---|---|---|
owner | Yes | The account owning the repo. |
repo_slug | Yes | The repo identifier. |
id | Yes | The request identifier. |
GET https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/pullrequests/{pull_request_id}/diff
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.
Parameter | Required? | Description |
---|---|---|
owner | Yes | The account owning the repo. |
repo_slug | Yes | The repo identifier. |
pull_request_id | Yes | The request identifier. |
GET https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/pullrequests/activity
GET the activity for a pull request
Gets a log of the activity for a specific pull request.
Parameter | Required? | Description |
---|---|---|
owner | Yes | The account owning the repo. |
repo_slug | Yes | The repo identifier. |
pull_request_id | Yes | The request identifier. |
GET https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/pullrequests/{pull_request_id}/activity
Accept and merge a pull request
Accept a pull request and merges into the destination branch. This requires write access on the destination repository.
Parameter | Required? | Description |
---|---|---|
owner | Yes | The account owning the repo. |
repo_slug | Yes | The repo identifier. |
pull_request_id | Yes | The pullrequest identifier. |
message | No | The message that will be used for the merge commit. |
close_source_branch | No | Override the value of close_source_branch that was used at the time of pull request creation. |
POST https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/pullrequests/{pull_request_id}/merge
Decline or reject a pull request
Rejects a pull request. This requires write access on the destination repository.
Parameter | Required? | Description |
---|---|---|
owner | Yes | The account owning the repo. |
repo_slug | Yes | The repo identifier. |
pull_request_id | Yes | The pull request identifier. |
message | No | An optional reason explaining why the pull request is being rejected. |
POST https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/pullrequests/{pull_request_id}/decline
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:
Field | Description |
---|---|
links | Links to the comment's self location, as well as other representations and related resource. |
id | An integer representing an id for the comment. |
parent | The parent comment. This is is applicable only to replies and not present in top-level comments. |
updated_on | The timestamp of the most recent change to the comment. |
filename | The filename the new comment concerns. |
content | The content of the comment.
|
user | The 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:
Inline comments also have an additional link in the links section (rel: " |
created_on | Date 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://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/pullrequests/{pull_request_id}/comments
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 |
---|---|---|
owner | Yes | The account owning the repo. |
repo_slug | Yes | The repo identifier. |
pull_request_id | Yes | The pull request identifier. |
comment_id | Yes | The comment identifier. |