Site announcement

We are switching off article comments on this website. Read about the upcoming changes to Atlassian Documentation.

Skip to end of metadata
Go to start of metadata

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.

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:

 

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

 

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

60 Comments

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

    1. Anonymous

      >

      E

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

    1. The proper API is:

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

      users Endpoint is what you want.

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

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

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

            1. Anonymous

              Thanks for your feedback, I will (smile)

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

  3. Anonymous

    Hi, 

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

    1. Danke! Sie befestigt ist.

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

  5. Anonymous

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

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

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

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

            1. The correct URL is:

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

               

               

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

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

       

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

  7. Anonymous

    Hello Anthony

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

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

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

       

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

  8. Anonymous

    How can I refresh access token?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    thanks 

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

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

  15. Anonymous

  16. Anonymous

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

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

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

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

  18. 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.
  19. 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
    1. 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.

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

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

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

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

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

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