Skip to end of metadata
Go to start of metadata

Overview

Use this resource to get information associated with an individual repository. You can use these calls with public or private repositories. Private repositories require the caller to authenticate with an account that has the appropriate authorization. You can also use the UUID of the repository for more information see, Universally Unique Identifier.

GET a repository

Returns a single repository.

Parameter
Required?
Description
ownerYesThe accountname of the repo owner.
repo_slugYesThe repository slug.
GET https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}
 Click here to expand...

POST a new repository

To create a new repository, POST directly to the desired URL, providing a JSON request body that contains the properties of the new repository.

Parameter
Required?
Description
ownerYesThe account of the repo owner.
repo_slugYesThe repository slug.

The POST body should match the repository object layout, but only a subset of its properties need to be specified:

Field nameDescription
scmThe SCM type for the new repo. Either "hg" or "git". When omitted, the type of your most recently created repository will be used (optional).

name

The name for the repository. When omitted, this assumes that value of the repo_slug part of the URL (optional).
is_privateWhether the repository should be public (false) or private (true).
descriptionThe human readable description of the repository (optional).
fork_policy

Control the rules for forking this repository. Available values are:

  • allow_forks: unrestricted forking
  • no_public_forks: restrict forking to private forks (forks cannot be made public later)
  • no_forks: deny all forking
languageThe programming language used in the repository. Must be a valid (lowercase) item as shown in the drop-down list on the repository's admin page (optional).
has_issuesWhether the repository should have an issue tracker (optional – defaults to false).
has_wikiWhether the repository should have a wiki (optional – defaults to false).
POST https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug

DELETE a repository

Removes a repository.  

Parameter
Required?
Description
ownerYesThe account name of the repo owner.
repo_slugYesThe repository slug.
DELETE https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug} 

GET a list of watchers

Gets the list of accounts watching a repository. 

Parameter
Required?
Description
ownerYesThe account of the repo owner.
repo_slugYesThe repository slug.
GET https://bitbucket.org/api/2.0/repositories/{owner}/{repo_slug}/watchers
 Click here to expand...

GET a list of forks

Gets the list of repository forks, This call returns a repository object for each fork.

Parameter
Required?
Description
ownerYesThe account of the repo owner.
repo_slugYesThe repository slug.
GET https://bitbucket.org/api/2.0/repositories/{owner}/{repo_slug}/forks
 Click here to expand...
  • No labels

21 Comments

  1. Anonymous

    When I try to create a new repository with a repo_slug containing a colon, I get back the error: "Invalid URL slug value. Slugs must be limited to ASCII word characters.". This seems weird because I can create repositories in bitbucket with a colon. Is there a way to create this repository through the API?

  2. Anonymous

    The name can contain a colon, the slug cannot.

  3. Anonymous

    How can I grant to other users access to repository?

  4. What's the difference between repo_slug and name? When I want to create a new repo with POST I need to post repo_slug, not name?

    And when I receive repo with GET I get no repo_slug?

    Seems to be a bit mixed(smile) How to make consistent java->json->java mapping when there seems to be no logic in names? Please let me (us) know if there is logic that I don't get(smile)

    1. repo_slug is how the repo should appear in the URL. name is how it appears on the pages.

    2. Mohammad is correct (thanks!) so in the url for the tutorials repository

      So in this example:

      https://bitbucket.org/teamsinspace/space-repository

      space-repository is the repo_slug

       

  5. forking_policy does not work as documented which implies \{ ... "forking_policy": "no_public_forks" ... \} for private only forking. Repositories are created allowing public forking. Adding \{ ... "no_public_forks": true ...\} to the payload gave me private only forking.

    1. I'm looking into this. Will try to get a response by tomorrow am, alternatively check in with our support team, or click the link for Get Support below.

       

    2. I can confirm that this is still the current behavior. Here were my results:

      forking_policy=allow_forks
      result: allow_forks

      forking_policy=no_public_forks
      result: allow_forks

      forking_policy=no_forks
      result: allow_forks

      no_public_forks=true
      result: no_public_forks

      no_public_forks=true&no_forks=true
      result: no_forks

       

      In other words, the value of forking_policy is completely ignored and can only be controlled by using no_public_forks and no_forks.

      1. Hey Chris,

        Thanks for taking time to comment! I've gone through these a few times and found that

        1. There was an error in the parameters: forking_policy should be fork_policy. 
        2. It does need a better example which includes the formatting.

        I'm making these changes tonight.

        Happy coding! 

        Dan

        1. Thanks for the update Dan. I tested using fork_policy, and each of "allow_forks", "no_public_forks", and "no_forks" worked as expected.

    3. Mohammad Haque I let this slip by and I try very hard not to do that so I apologize. I'm making updates to the doc tonight which should reflect both your advice and some additional corrections.

      Thanks for taking the time to comment!

      Happy coding!

      Dan

  6. When I do a request which returns a list, can I request more than 10 values per page (pagelen > 10) ?

  7. From Version 2#Pagingthroughobjectcollections

    Field
    Value
    pagelen
    Current number of objects on the existing page. Globally, the minimum length is 10 and the maximum is 100. Some APIs may specify a different default. 
  8. One issue that I've found is that this endpoint does not support setting the akismet_key and analytics_key fields. Thus, to create a new repository that has those fields set, I've had to do the following:

    1. POST /2.0/repositories/{user}/{slug}

    2. PUT /1.0/repositories/{user}/{slug}

    Each request contains the same data, but needs to have the data format changed for the different API versions. When doing this, ensure that any false boolean fields for the 1.0 data are blank or they will be treated as true (for instance, a value of 0 in a boolean field will result in that field being set to true).

    1. Good day Chris,

      I'm out this week but will be trying to keep up with comments as they come. I'll hopefully have a resolution or update soon.

      Thanks,

      Dan

    2. E M

      thank you for sharing this. The PUT is still missing in 2.0

  9. > GET a list of watchers

    > GET https://bitbucket.org/api/2.0/{owner}/{repo_slug}/watchers

    It seems like the request URL is wrong.

    The precise URL is `https://bitbucket.org/api/2.0/repositories/{owner}/{repo_slug}/watchers`. (missing `/repositories` in the URL)

    And is there same document issue on `GET a list of forks` section ?

    Thanks.

    1. Yep I've fixed both instances.

      Thanks so much for taking the time to comment!

      Dan

  10. Is there a way to get all the users that are collaborators on specific repository?

    Rastko

  11. It is worth noting that the "language" field of the "POST a new repository" body must not only be lower case, but period (and other?) characters must be omitted.

    Language in admin panel: "Node.js"
    Language in JSON: "nodejs"