repository Resource

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
owner Yes The accountname of the repo owner.
repo_slug Yes The 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
owner Yes The account of the repo owner.
repo_slug Yes The repository slug.

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

Field name Description
scm The 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_private Whether the repository should be public (false) or private (true).
description The 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
language The 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_issues Whether the repository should have an issue tracker (optional – defaults to false).
has_wiki Whether 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 and any associated Wiki and Issue tracker. A 204 NO CONTENT message is returned on success.

This is a destructive action which completely deletes the repository, issue tracker, and wiki. Be sure you have backed up all the data you need before deleting a repository.

Parameter
Required?
Description
owner Yes The account name of the repo owner.
repo_slug Yes The 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
owner Yes The account of the repo owner.
repo_slug Yes The 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
owner Yes The account of the repo owner.
repo_slug Yes The repository slug.
GET https://bitbucket.org/api/2.0/repositories/{owner}/{repo_slug}/forks
  Click here to expand...

Was this helpful?

Thanks for your feedback!

21 Archived comments

  1. User avatar

    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?

    04 Dec 2013
  2. User avatar

    Anonymous

    The name can contain a colon, the slug cannot.

    07 Jan 2014
  3. User avatar

    Anonymous

    How can I grant to other users access to repository?

    24 Jan 2014
  4. User avatar

    Sven Varkel

    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)

    02 Feb 2014
    1. User avatar

      Mohammad Haque

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

      17 Apr 2014
    1. User avatar

      Dan Stevens [Atlassian]

      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

       

      17 Apr 2014
  5. User avatar

    Mohammad Haque

    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.

    17 Apr 2014
    1. User avatar

      Dan Stevens [Atlassian]

      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.

       

      17 Apr 2014
    1. User avatar

      Chris Jean

      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.

      24 Jul 2014
      1. User avatar

        Dan Stevens [Atlassian]

        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

        25 Jul 2014
        1. User avatar

          Chris Jean

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

          25 Jul 2014
    1. User avatar

      Dan Stevens [Atlassian]

      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

      25 Jul 2014
  6. User avatar

    Bogdan Taranu

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

    21 Apr 2014
  7. User avatar

    Mohammad Haque

    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. 
    21 Apr 2014
  8. User avatar

    Chris Jean

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

    28 Jul 2014
    1. User avatar

      Dan Stevens [Atlassian]

      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

      29 Jul 2014
    1. User avatar

      E M

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

      30 May 2015
  9. User avatar

    Hirakiuchi Daisuke

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

    05 Aug 2014
    1. User avatar

      Dan Stevens [Atlassian]

      Yep I've fixed both instances.

      Thanks so much for taking the time to comment!

      Dan

      07 Aug 2014
  10. User avatar

    Rastko Jokic

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

    Rastko

    10 Sep 2014
  11. User avatar

    Troy Kinsella

    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"

     

    02 Apr 2015
Powered by Confluence and Scroll Viewport