Use the Bitbucket REST APIs

Use our REST API, based on open standards, to build third party applications which can use any web development language to access the API.

Using the API, users can sign in and grant your application the right to make calls on their behalf. Then, through the API, your application can access Bitbucket resources such as an individual (or team) account, repositories, and aspects of these resources such as changesets or comments.

Atlassian Connect for Bitbucket

Interested in building integration's with Bitbucket?

Now you can build right into the Bitbucket UI with Atlassian Connect for Bitbucket.

This page

Related pages

Use our API console to view calls and responses

You should be familiar with REST architecture before writing an integration. Good REST resources abound on the internet. Read this overview page to gain a good understanding of Bitbucket's REST implementation. When you are ready to begin, obtain a consumer key for your application.

URI Structure and Methods

All Bitbucket requests start with the https://api.bitbucket.org/2.0 prefix (for the 2.0 API) and https://api.bitbucket.org/1.0 prefix (1.0 API). The next segment of the URI path depends on the endpoint of the request. For example, using the curl command and the repositories endpoint you can list all the issues on Bitbucket's tutorial repository:

curl https://api.bitbucket.org/2.0/repositories/tutorials/tutorials.bitbucket.org

Given a specific endpoint, you can then drill down to a particular aspect or resource of that endpoint. The issues resource on a repository is an example:

curl https://api.bitbucket.org/1.0/repositories/tutorials/tutorials.bitbucket.org/issues

A given endpoint or resource has a series of actions (or methods) associated with it. The Bitbucket service supports these standard HTTP methods:

Call Description
GET
Retrieves information.
PUT
Updates existing information.
POST
Creates new information.
DELETE
Removes existing information.

For example, you can call use the POST action on the issues resource and create an issue on the issue tracker.

Specifying Content Length

You can get a 411 Length Required response. If this happens, the API requires a Content-Length header but the client is not sending it. You should add the header yourself, for example using the curl client:

Universally Unique Identifier (UUID)

UUID's provide a single point of recognition for users, teams, and repositories. The UUID is distinct from the username, team name, and repository name fields and remains the same even when those fields change. For example when a user changes their username or moves a repository you will need to modify calls which use those identifiers but not if you are pointing to the UUID.

UUID example and structure

UUID's work with both the 1.0 and 2.0 APIs for the user, team, and repository

In the following examples the following characters are replacements for curly brackets: %7B replaces and %7D replaces }

User 

Call with username:

Response from user  Expand source

Call with UUID:

Response from UUID call  Expand source

Team

Call with team name:

Call (for team repositories) with UUID:

Repositories
Once you have the UUID for a repository you no longer need a username or team name to make the API call so long as you use an empty field. This helps you resolve repositories no matter if the username or team name changes.

With team name (1team) and repository name (moxie):

Response from repo  Expand source

With UUID:

Supported Versions

There is a 1.0 and 2.0 version of the APIs. The two versions do not encompass the same endpoints or functionality. Currently, you will find that the API 1.0 covers resources that the 2.0 API is yet to cover. Conversely, the 2.0 API has several features that enhance its usability and performance. You should look first to use the 2.0 API whenever possible. The 1.0 APIs are available when the 2.0 does not make the resource you need available.

Supported endpoints and their resources

Bitbucket supports several endpoints. These endpoints may or may not have additional resources. The table below lists the endpoints and their associated resources.

Endpoint Description
            group-privileges
          
Manages a group's repository permissions.
            groups
          
Manages groups and their membership.
            invitations
          
Invite other users to a repository.
            privileges
          
Manage individual user privileges (permissions) on your repositories

repositories











 
Manages repository resources. This endpoint supports the following resources:
            changesets
          
Manage changesets for a repository.
            deploy-keys
          
Manage ssh keys for deploying product builds.
            events
          
Track events on a public repository.
            followers
          
Lists the accounts following a repository.
            issues
          
Manage an issue tracker and the issues associated with it.
            links
          
Manage integrations with JIRA, Bamboo, and custom link resources.
pullrequests
Manage the comments and likes associated with pull request comments.
repository
Manage the branches, tags, and manifest associated with a repository.
services Manages an account's integrated services.
            src
          
Get information about particular files and directories in a repository.
            wiki
          

Get information about pages in a Wiki.

            user
          
Manages the currently authenticated account profile.
users
Manages information related to a specified individual account. This endpoint supports the following resources:
            account
          
Gets information related to an account.
            emails
          
Manages the email address associated with an account.
            invitations
          
Manages the invitations sent by an account.
            oauth
          
Manages the consumers associated with an account.
            privileges
          
Manages privilege settings for teams.
            ssh-keys
          
Manages ssh keys for an account.
teams Retrieves information related to teams.

Authentication

The Bitbucket API grants access to public data without authentication. Access to private data requires the caller to authenticate under an account with the appropriate access. For example, an account's administrative data, such as the email address, requires the caller to either authenticate as the account owner or, in the case of a team, authenticate as a team member with administrative access to the team. If you are testing an application, you can use a client such as cURL together with basic authentication (username/password). For example, the following curl call lists the public and private repositories of the buser:

curl --user buserbb:2934dfad https://api.bitbucket.org/1.0/user/repositories

If you are writing an application to integrate with Bitbucket, you should obtain a consumer key and use the OAuth 1.0a framework to authenticate. For a detailed overview regarding OAuth and Bitbucket, see OAuth on Bitbucket in this documentation.

Was this helpful?

Thanks for your feedback!

65 Archived comments

  1. User avatar

    Anthony Steiner

    NICE! Someone gave this documentation an overhaul. ME LIKEY!

    05 Oct 2012
    1. User avatar

      Anonymous

      >

      E

      22 May 2013
  2. User avatar

    Anonymous

    The doc says that to list all the private and public repositories I can use this command:

    curl --user buserbb:2934dfad https://api.bitbucket.org/1.0/repositories/buserbb

    I swap in my username/password and all I get in return is a bunch of html with a title of "Oops, you've found a dead link"

    25 Oct 2012
    1. User avatar

      manthony

      The proper API is:

      https://api.bitbucket.org/1.0/users/buserbb

      users Endpoint is what you want.

      30 Nov 2012
      1. User avatar

        Anonymous

        I'm also finding that the returned content isn't very helpful. As the default return format is JSON, it should be expected that any errors, dead links (as above), in fact anything, should be returned as JSON.

        This returning HTML has been playing havoc with my trying to debug what are required fields and other issues for two days now, as the documentation for this API is very slim.

        Would it be possible to please change the responses to follow the format specified, and if no format specified then JSON as per the default? Also could we have some examples of how to actually use this API, like example requests for the different request methods on each end-point?

        01 Jan 2013
        1. User avatar

          Anonymous

          Just to clarify, when I get an HTTP 400 the response body (even though the request was JSON) is:

           

          Bad Request <ul class="errorlist"><li>name<ul class="errorlist"><li>You already have a repository with this name.</li></ul></li></ul>

          01 Jan 2013
          1. User avatar

            manthony

            Hi, I'm sorry to hear you are having problems.  You can find examples of how to make requests on each endpoint reference page.  You can also use our REST API browser which is a good way to test the calls if you don't want to use CURL.

            Yes, the returned HTML is really awkward. You should file a enhancement request regarding the return formats.  The devs pay more attention to enhancement requests than doc comments. Maybe because requests are easier to count. (tongue)

            02 Jan 2013
            1. User avatar

              Anonymous

              Thanks for your feedback, I will (smile)

              03 Jan 2013
          1. User avatar

            Anthony Steiner

            If you're looking for an interim fix, the response header's Content-Type property would return text/plain upon an error. It should return the mime of the expected format if else; unless you are using JSONP.  Then you're pretty much back to square one. 

            Edit: Even JSONP returns a mime other than plain/text.

            02 Jan 2013
  3. User avatar

    Anonymous

    Hi, 

    the section "Supported Endpoints and their Resources" is missing a link to the services resource for the repositories endpoint.

    30 Jan 2013
    1. User avatar

      manthony

      Danke! Sie befestigt ist.

      30 Jan 2013
  4. User avatar

    Anonymous

    Are you planning on making it possible to create a new repository?  I have about 150 repositories that need to be created and doing it by hand will hurt (sad)

    31 Jan 2013
    1. User avatar

      Marcus Bertrand [Atlassian]

      You can! See repository Resource for the details.

      31 Jan 2013
  5. User avatar

    Anonymous

    How i get all Pull-Request IDs?

    I try something like this:

    https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/pullrequests/

    27 Feb 2013
    1. User avatar

      Anthony Steiner

      My immediate guess, would be to look for this information in the repositories endpoints. Use the button at the top of the page, There are few API endpoints that aren't included in the docs here, like overview and dashboard that might give you the information you seek. 

      27 Feb 2013
      1. User avatar

        manthony

        There are public apis for the overview and dashboard on the user endpoint.

        05 Mar 2013
        1. User avatar

          Anonymous

          This does not answer the original question. I would like to retrieve the list of pull requests for a repository.

          Am I wrong assuming that this is not supported?

          15 Jul 2013
          1. User avatar

            manthony

            Sorry for the misunderstanding. You are correct our published and supported API does not support this.

            We are currently building a complete pull request API. Unfortunately it's not been finalized yet and so it cannot be published at this time.

            If you want, you can take the current, undocumented and unpublished version for a spin: 

            GET https://bitbucket.org/api/2.0/repositories/{accountname}/{repo_slug}/pullrequests

            But be aware that this API will most likely change before it's being released and so expect breakage. When we do release the final API, it will be announced on our blog.

            17 Jul 2013
            1. User avatar

              Erik van Zijst [Atlassian]

              The correct URL is:

              https://bitbucket.org/api/2.0/repositories/{account}/{repo_slug}/pullrequests

               

               

              22 Aug 2013
  6. User avatar

    Anonymous

    Is there a way to clone a repository with Oauth authentication like Github allows? I can't seem to find documentation for this anywhere?

    07 Mar 2013
    1. User avatar

      manthony

      You can fork (clone) with this resource: repository Resource

       

      07 Mar 2013
    1. User avatar

      Erik van Zijst [Atlassian]

      No. Bitbucket currently only supports OAuth 1.0, which does not support unsigned requests.

      22 Aug 2013
  7. User avatar

    Anonymous

    Hello Anthony

    Is there any way to download a repository files as  zip archive using REST API's.

    29 Mar 2013
    1. User avatar

      manthony

      Hi, we don't have that functionality. You can file an enhancement request for that.

      29 Mar 2013
    1. User avatar

      Trey Brister

      One workaround is to use the API to clone the repo then a shell script can delete the .hg directory then create the zip file from the local repo folder. Then delete the entire repo after creating the zip file.

       

      22 Jan 2015
      1. User avatar

        Anthony Steiner

        Even better: 

        https://bitbucket.org/<user>/<repo>/get/<first-12-characters-of-git-commit-hash>.zip

        Keep in mind, private repos will require a BASIC or oAUTH header int he request. But this should work for your immediate needs.  

        NOTE: this is NOT part of the public API, and like anything that Atlassian has not documented is subject to change.  Use this at your own volition and take it upon yourself to keep aware of it's change. 

        22 Jan 2015
  8. User avatar

    Anonymous

    How can I refresh access token?

    04 Jun 2013
  9. User avatar

    Dillon

    Is there API support for listing teams that a user is part of? I see the teams that my user is part of if I'm using the web page version but I see nothing in the API documentation that allows me to list those teams. Am I missing something or has this not been implemented yet?

    14 Jul 2013
    1. User avatar

      Dillon

      Actually, after reverse engineering the website, I've come to the conclusion that I can get the information I seek by executing the following URI: https://bitbucket.org/account/xhr/header_information/. However, while I'd still like to know if there is a publish REST API method for acheiving this, my new question is: How long do you think this method for obtaining teams will be valid?

      14 Jul 2013
      1. User avatar

        Anthony Steiner

        I would warn you against using those methodologies.  The internal xhr endpoints are likely to change, without notice.  And due to your public discovery of them; I wouldn't be horribly surprised if they lock those endpoints down to internal requests only. 

        14 Jul 2013
    1. User avatar

      manthony

      Yes, there is an endpoint for this:

      https://bitbucket.org/api/1.0/user/privileges/

      Will list the teams for the authenticated user.  And, as Anthony said, you shouldn't rely on APIs that are not listed as part of our public APIs.

      14 Jul 2013
      1. User avatar

        Dillon

        Mary, you're wonderful! I'm not sure how I missed that. Thank you!

        14 Jul 2013
        1. User avatar

          manthony

          Dillion, glad that worked for you.  No worries, I think it is easy to overlook cause it isn't called "teams" anywhere. (big grin) I'm going to see about creating a "functional index" for our REST APIs.  That will help with questions like yours.

          14 Jul 2013
  10. User avatar

    Jon Brown

    Is it possible to create a repo using curl in a team account, or to create one and then transfer via API?

    Also maybe this is silly, but its it possible to authenticate with a ssh key over curl instead of user/pass or another method I could use in a script?

    15 Jul 2013
    1. User avatar

      manthony

      You can use repository Resource this resource to create a repository.  By default, it creates a repo under the currently authenticated user.  You can also use the PUT to change the owner of the repository.

      OAuth is generally considered the way to go with a web app. If you are writing a script you could probably just rely on SSH.  Just google using SSH and shell script and you should find a lot of resources.

      15 Jul 2013
      1. User avatar

        Jon Brown

        Well I hacked around a lot based on that link and couldn't figure out how to change the accountname/owner of an existing repo. I successfully could change the description and other items, but "accountname=newname" didn't work nor did "owner=newname".  

        I discover however that when I create the repo I can assign "owner=myTeamName" and it does exactly what I needed, only easier since it's one step.  It isn't documented so I'll just hope it keeps working.

        17 Jul 2013
        1. User avatar

          manthony

          Thank's Jon.  I have set myself a task to test and update the doc on these APIs.

          17 Jul 2013
          1. User avatar

            Anthony Steiner

            A bit late to the party; but I for one am interested in helping any way I can.  There is a strong community behind BitBucket; we are a resource, don't be afraid to utilize us (big grin).  

            If you need help testing, or validating or anything of the sort I'll be glad to lend a hand. Only thing we ask for in return is transparency with the progress of the product, which you manthony (Mary Anthony btw people... lol) 

            23 Aug 2013
            1. User avatar

              manthony

              Hey Anthony,  Your help would be great.  I'm getting sorted on my end and I'll ping you back via email when I have a block of time to do this.

              26 Aug 2013
  11. User avatar

    Narayana reddy

    Hello,

    Need  help!!

    When I am trying to use privileges endpoint with PUT Request, I am getting 400-BAD REQUEST.

    below are details.

    > PUT https://api.bitbucket.org/1.0/privileges/narayanatera/restrepo2/sakethtera

    > Using Basic Authentication

    > I tried with content types

             "application/json" >> Request Body (privilege:admin)

             and also "application/x-www-form-urlencoded; charset=UTF-8" >> Request Body ({\"permission\": \"write\" })

    Note: I even tried with restbrowser (http://restbrowser.bitbucket.org/), still same issue.

    Did I miss anything here.

     

    Please any body help in this regard.

    Thanks,

    Naren

    10 Sep 2013
  12. User avatar

    Petr Kozelka

    Hi, is there a way to accept pull-request via REST api? Couldn't find it in 1.0 docs.

    25 Oct 2013
    1. User avatar

      Erik van Zijst [Atlassian]

      We're about to announce a complete pull request API, but to give you a head start, you can accept a pull request like this:

      Also, to get a list of all pull requests, you can hit:

      Which will give you links to other content and actions.

      Keep an eye on http://blog.bitbucket.org for the official announcement and API documentation.

      26 Oct 2013
  13. User avatar

    Ardian Franindo

    Hi, how to search all repository with repo_slug==something and search all user with name=someone

    thanks 

    19 Nov 2013
    1. User avatar

      Erik van Zijst [Atlassian]

      The new APIs currently don't cover searching yet. Feel free to raise an issue for it though at https://bitbucket.org/site/master

      19 Nov 2013
  14. User avatar

    Anonymous

    Hi, is there any option how to get user's (homepage feed)? I mean something like this: https://bitbucket.org/{username}/rss/feed?token={token} , but it would be better to get JSON. Thanks for your reply!

    08 Dec 2013
  15. User avatar

    Anonymous

    I get a 404 when visiting https://bitbucket.org/api/2.0 ?

    21 Dec 2013
  16. User avatar

    Anonymous

    Is there anyway with the API to get a list of all users as you can do with the github search API?

    23 Dec 2013
    1. User avatar

      Erik van Zijst [Atlassian]

      No, we do not have a list of all users.

      23 Dec 2013
  17. User avatar

    Michael LaGrasta

    I'd like to create a pull request from the command line using the api and I can't get it to work using Curl or the API browser. Here is what I am trying:

    $ curl -u mnlagrasta -d "source=test1&title=blah" https://bitbucket.org/api/2.0/repositories/mnlagrasta/test/pullrequests/
    {"error": {"fields": {"source": ["malformed object"]}, "message": "Bad request", "detail": null}}

    I've also tried all kinds of variations to specify the source and title through the api console, but it keeps telling me either source and title are required or that the owner and repo slug are missing (even though they are in the url and the "template" fields.

     

    Can anyone post a working example of creating a pull request through the API, preferably using Curl?

     

    Thank you so much!

    04 Feb 2014
    1. User avatar

      Anthony Steiner

      I could be wrong, but I'm almost 100% sure it's expecting a json payload. 

      JSON Payload

       

      Take a peek at the API Apigee Tester at the top of this page... it should help. 

      05 Feb 2014
  18. User avatar

    hadi khosrojerdi

    Can I introduce a WordPress plugin for integration WordPress with bitbucket?

    This plugin have a test page, and users can use it instead of restbrowser.
    05 Feb 2014
  19. User avatar

    Russell Heilling

    Has support for basic authentication been removed?

    I am trying to figure out why the Reviewboard code review tool doesn't work with private repositories, and it looks like it is because the tool is using basic auth.  If I try the curl command below I get a "401 Unauthorised".  The exact same command line with the --digest argument gives the expected response. 

    curl -u russellh:XXXX https://bitbucket.org/api/1.0/repositories/rgh-reviews/rgh-reviews
    05 Mar 2014
    1. User avatar

      Erik van Zijst [Atlassian]

      Nope, Basic Auth should definitely still work.

      That repo in your command in public though, but if you have a private repo that you have access to, but where Basic auth through curl does not work, then please drop us a line at support@bitbucket.org and we'll have a look.

      06 Mar 2014
      1. User avatar

        Russell Heilling

        I'll open a case.  The authenticated access seems to fail for me whether or not the repository is public or private, it is whether I am using basic auth or not that seems to break it.  I first discovered it on a private repo though as you generally don't need to auth at all when dealing with public repos.

        06 Mar 2014
  20. User avatar

    Keith Rosenberg

    Is there no way endpoint to GET /tags or /branches? I have been looking for some mechanism to get tags but it appears there is no endpoint, and additionally, that there is no boolean property or type string that would allow me to generate a custom filter for this when getting the /repositories or /user/repo-slug/commits/ data either. Anyone have a solution to getting all tags?

    i.e. https://api.github.com/repos/jquery/jquery/tags

    05 Apr 2014
    1. User avatar

      Erik van Zijst [Atlassian]

      Here's the documentation for the branches and tags endpoint: repository Resource 1.0#GETalistofbranch-tags

      06 Apr 2014
  21. User avatar

    Luke Deniston

    Is there a way to get JSON of the RSS feeds? That would be really handy.

    https://bitbucket.org/{username}/rss/feed?token=...

    https://bitbucket.org/{team/user}/{repo name}/rss?token=...

    17 Aug 2014
    1. User avatar

      Luke Deniston

      I found this for the repo: https://bitbucket.org/api/1.0/repositories/{team/user}/{repo name}/events/

      But I still haven't found one for the overview of all events like you see on the home page when you log in to BitBucket.

      17 Aug 2014
    1. User avatar

      Anthony Steiner

      There are two "hidden" APIs, that are part of the apigee console. 

      https://bitbucket.org/api/1.0/user/repositories/overview/

      https://bitbucket.org/api/1.0/user/repositories/dashboard/

      Both are auth required.  They're not quite an RSS feed. but should get you close. 

      17 Aug 2014
  22. User avatar

    Sotiris Varotsis

    Is there any way to create a new branch under a repository using either v1 or v2 of the rest api? I can't find anything related to that in either the documentation or the rest api browser.

    06 Nov 2014
  23. User avatar

    Jubayer Arefin

    The REST api browser page should use SSL

    02 Aug 2015
  24. User avatar

    Matthew Peters

    The current link to the API console: http://restbrowser.bitbucket.org/ generates several 404 errors when retrieving JS files.  Because it is just an Apigee provider, you can still use it by going to this URL:

    https://apigee.com/bitbucket/embed/console/bitbucket

    11 Aug 2015
    1. User avatar

      Jubayer Arefin

      Thanks

      12 Aug 2015
  25. User avatar

    Omonami TAIRA

    Is it possible to get the list of tags in addition to releases?

    The existing "downloads" API only works for projects with explicit releases.

    $ curl 'https://bitbucket.org/!api/2.0/repositories/pypy/pypy/downloads'
    {"pagelen": 10, ...
    $ curl 'https://bitbucket.org/!api/2.0/repositories/birkenfeld/sphinx/downloads'
    {"pagelen": 10, "values": [], "page": 1}
    16 Aug 2015
    1. User avatar

      Erik van Zijst [Atlassian]

      We see tags and binary release artifacts as separate resources at the moment and so there are no immediate plans to unify the 2 in a single API.

      However, we are getting ready to (finally) announce an API for tags, branches, bookmarks and Git refs. While the work has not been finished completely, I invite you to have a look by exploring:

      https://api.bitbucket.org/2.0/repositories/pypy/pypy/refs

      This returns all "refs" in the repo. For Hg that includes named branch heads, tags and bookmarks, and for Git all refs are returned.

      If you're only interested in tags, use https://api.bitbucket.org/2.0/repositories/pypy/pypy/refs/tags

      https://api.bitbucket.org/2.0/repositories/pypy/pypy/refs/branches returns both named branches and tags (look for the "type" element to distinguish the 2).

      To download the repo at a particular tag, for now just use the URL that is used on the downloads page: https://bitbucket.org/pypy/pypy/get/pypy3-release-2.4.0.zip

      17 Aug 2015
Powered by Confluence and Scroll Viewport