pullrequests Resource

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.

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.
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:

  • 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.

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]
  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.

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 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.

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 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.

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 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.

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 username element of the user object.

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

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.
GET https://api.bitbucket.org/2.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.

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
  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.

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
  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.

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://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.

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://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.

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://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.

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://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.

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://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:

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.

  • raw: the raw text as the user typed it
  • markup: the markup language used
  • html: the rendered HTML version of the markup
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:

  • 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_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://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
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.

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

Was this helpful?

Thanks for your feedback!

19 Archived comments

  1. User avatar

    s3m3n

    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.

    19 Dec 2013
  2. User avatar

    Anonymous

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

    01 Mar 2014
  3. User avatar

    Bogdan Taranu

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

    16 Apr 2014
    1. User avatar

      Bogdan Taranu

      Found it out. It's a commit (smile)

      27 Apr 2014
  4. User avatar

    Bogdan Taranu

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

    17 Apr 2014
    1. User avatar

      Dan Stevens [Atlassian]

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

      17 Apr 2014
  5. User avatar

    Bogdan Taranu

    Could you also provide an example for approve and merge/decline and reject example containing  the optional parameters?

    27 Apr 2014
  6. User avatar

    Sebastiaan Stok

    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.

    The last statement "The state parameter can be repeated to include pull requests in different states." is wrong.

    You can use a comma-character to get more states ( https://api.bitbucket.org/2.0/repositories/jespern/django-piston/pullrequests?state=MERGED,OPEN&format=json ) but using state[]=OPEN&state[]=MERGED doesn't work.

    06 Jun 2014
    1. User avatar

      Dan Stevens [Atlassian]

      Hey Sebastiaan,

      Thanks for taking the time to comment, and sorry for the delay in replying. After running through this a couple times I see you're correct. So I've modified that statement to show you must comma separate states in a call.

      Thanks again for taking time to help us make these docs better.

      23 Jun 2014
    1. User avatar

      jenkins-test

      Sebastiaan, When I use the get for the list of pull request, I always get the same error: 

      {"error": {"message": "Resource not found"}}

      GET https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/pullrequests?state=[OPEN, MERGED, DECLINED]

      MY SCRIPT:

      curl --silent -X GET -g https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/pullrequests?state=[OPEN]

       

      28 Apr 2015
      1. User avatar

        Erik van Zijst [Atlassian]

        Make sure you're not including square brackets around the state string.

        If you are still having problems, please send us the complete request information at support@bitbucket.org and we help you spot the mistake.

        28 Apr 2015
  7. User avatar

    Hirakiuchi Daisuke

    In `POST a pull request approval`, response example shows 'role', user' keys.
    But the response for my pullrequest approval contains only 'approved' key.

    Which is correct documented example or my test result ?

    Thanks.

    23 Aug 2014
    1. User avatar

      DJ Marcaida

      This is also true for me. Will someone please confirm this?

      09 Mar 2015
  8. User avatar

    Hirakiuchi Daisuke

    In `DELETE a pull request approval`, response described that 「On success, this method returns: HTTP/1.1 204 NO CONTENT 」.

    But the response for my test request was HTTP 200 and json which has only approved key.

    Which is correct documented example or my test result ?

    Thanks.

    23 Aug 2014
    1. User avatar

      DJ Marcaida

      Also true for me. Please confirm.

      09 Mar 2015
  9. User avatar

    james young

    When sending a POST to merge a commit, I get the following error in my local app and in the Bitbucket REST Browser (http://restbrowser.bitbucket.org/)

     

    "error":  { "message": "name, email or commit message not provided",

     

    The "detail" property is a very long python stack trace that I did not include here.  You can see it in this gist though: https://gist.github.com/jamsyoung/ac7ce113214e2843b82b

    In the documentation above, I did not see where "name" and "email" are listed as possible parameters and "message" is marked as not required.  I still get the same error when I provide a "message".

    What am I missing?

    Thanks

    31 Oct 2014
    1. User avatar

      james young

      I have got this working.  The problem, in my opinion, is that the documentation on this page does not cover all the fine details.  For a more detailed breakdown on how I got this working, please refer to my comment on the issue that was created by Dan Falk on 2014-01-14.

      https://bitbucket.org/site/master/issue/8744/500-error-when-trying-to-merge-pull

       

      01 Nov 2014
  10. User avatar

    Yong Gu

    Hi,

    I got stuck in trying to create pull request via the api and it always says '{"error"=>{"fields"=>{"source"=>["This field is required."]}, "message"=>"Bad request"}}'. I am using ruby gem oauth-ruby and did include the source in JSON body. Here is the json in ruby hash i was trying to send:

    {
      title: options[:title],
      description: options[:description],
      source: {
        branch: {
          name: options[:source_branch]
        },
        repository: {
          full_name: repository_full_name 
        }
      },
      destination: {
        branch: {
        name: options[:destination_branch] 
        }
      }
    }
    In fact, in my code, i use both v1 and v2. I created a lib which use like this: '/1.0/services' and '/2.0/repositories/dummy/pullrequests'. 
    For 1.0 apis, everything works correctly including those POST requests. I send the request in the same way for 2.0 apis, but it seems POST requests does not work.

     

    Please advise and thanks a lot.

    01 Dec 2014
  11. User avatar

    DJ Marcaida

    In Accept and merge a pull request, passing a value passed for the message parameter doesn't show up in the response. Is that intended?

    09 Mar 2015
Powered by Confluence and Scroll Viewport