Bitbucket Documentation

Index

Skip to end of metadata
Go to start of metadata

The bitbucket 'repositories' REST resource provides functionality for getting information about repositories, creating new ones, updating their settings and deleting them.

Overview

You can access public repositories without authentication, but you will only receive a subset of information, and you cannot gain access to private repositories. By authenticating, you will get a more detailed set of information, the ability to create repositories, and the ability to update settings or delete repositories you have access to.

Example:

$ curl https://api.bitbucket.org/1.0/users/jespern/

{
  "repositories": [
    {
      "slug": "django-piston",
      "name": "django-piston",
      "resource_uri": "/1.0/repositories/jespern/django-piston/",
      "followers_count": 173,
      "website": "",
      "description": "Piston is a Django mini-framework creating APIs."
    }
  ],
  "user": {
    "username": "jespern",
    "avatar": "https://secure.gravatar.com/avatar/b658715b9635ef057daf2a22d4a8f36e?d=identicon&s=32",
    "resource_uri": "/1.0/users/jespern/",
    "last_name": "Noehr",
    "first_name": "Jesper"
  }
}

Querying the repositories you have access to

If you want to see list of repositories you have access to, you can do:

$ curl --user username:password https://api.bitbucket.org/1.0/user/repositories/
[
    {
        "owner": "jespern",
        "slug": "arriving",
        "is_private": true,
        "name": "arriving"
    },
    {
        "owner": "jespern",
        "slug": "jespern",
        "is_private": true,
        "name": "jespern"
    },
    {
        "owner": "jespern",
        "slug": "jespern-jekyll",
        "is_private": true,
        "name": "jespern-jekyll"
    },
    {
        "owner": "jespern",
        "slug": "bitbucket-issue-query",
        "is_private": true,
        "name": "bitbucket-issue-query"
    },
    {
        "owner": "erik",
        "slug": "org.eclipse.mylyn.bitbucket",
        "is_private": true,
        "name": "org.eclipse.mylyn.bitbucket"
    },
    {
        "owner": "mcatalbas",
        "slug": "codeigniter",
        "is_private": false,
        "name": "CodeIgniter"
    },
    {
        "owner": "brodie",
        "slug": "hg-project",
        "is_private": true,
        "name": "hg-project"
    },
    {
        "owner": "dchambers",
        "slug": "django-piston",
        "is_private": false,
        "name": "django-piston"
    }
]

Searching

If you do not specify username and repo, you can search through repositories. You can do that by specifying the 'name' query string parameter.

Example: Searching for 'django-':

$ curl "https://api.bitbucket.org/1.0/repositories/?name=django-"

{
  "query": "django-",
  "count": 372,
  "repositories": [
    {
      "website": "",
      "name": "django-registration",
      "description": "A user-registration application for Django.",
      "followers_count": 159,
      "slug": "django-registration",
      "resource_uri": "/1.0/repositories/ubernostrum/django-registration/"
    },
    {
      "website": "",
      "name": "django-profiles",
      "description": "A user-profile application for Django.",
      "followers_count": 60,
      "slug": "django-profiles",
      "resource_uri": "/1.0/repositories/ubernostrum/django-profiles/"
    },
    # many more...
  ]
}

Tags and Branches

You can get a list of branches and tags for a given repository.

Get a list of tags for a given repository:

GET /repositories/USERNAME/REPO_SLUG/tags/

Get a list of branches for a given repository:

GET /repositories/USERNAME/REPO_SLUG/branches/

Parameters:

  • USERNAME: The owner's username.
  • REPO_SLUG: The slug of the repository.

Getting a Single Repository

GET /repositories/USERNAME/REPO_SLUG/

Parameters:

  • USERNAME: The owner's username.
  • REPO_SLUG: The slug of the repository.

Creating a New Repository

Example:

curl --request POST --user username:password https://api.bitbucket.org/1.0/repositories/ --data name=myrepo --data scm=git

You must specify at least the name and the scm parameter in the POST body (x-www-form-urlencoded).

The scm parameter can have the value 'hg' or 'git' depending on which type of repository you are trying to create.

Returns the newly created repository on success, otherwise returns a response code other than '200'.
This will create a public repository. To create a private repository, add the is_private=True parameter.

Updating an Existing Repository

PUT /repositories/USERNAME/REPO_SLUG/

Parameters:

  • USERNAME: The owner's username.
  • REPO_SLUG: The slug of the repository.

You can send just a single field and new value, and the existing values will be filled in automatically.

Deleting a Repository

DELETE /repositories/USERNAME/REPO_SLUG/

Parameters:

  • USERNAME: The owner's username.
  • REPO_SLUG: The slug of the repository.

Getting Information about Repository Events

See Events.

Getting Information about Followers of a Repository

See Followers.

RELATED TOPICS

Using the bitbucket REST APIs

Labels
  • None

16 Comments

Hide/Show Comments

  1. Dec 23, 2010

    Matthew Watson [Atlassian]

    Looks like the doco for "Creating a New Repository" is wrong - the params are expected to be post form params, not query params.

    i.e.

    1. Mar 06, 2011

      Erik van Zijst [Atlassian]

      Good catch! Fixed.

  2. Mar 08, 2011

    Anonymous

    curl "https://api.bitbucket.org/1.0/repositories/?name=ruby" doesn't give resource URIs as the doc says
    [23:35]It's pretty annoying since we don't know repo username either…

    1. Mar 08, 2011

      Erik van Zijst [Atlassian]

      You may be mixing GETs and POSTs.

      We only support POST on /1.0/repositories/ (with your new repo name in the request body – NOT the query string). This will create a new repo under your account.

      What do you intend to do? Are you looking for all repositories named "ruby"?

      Cheers,
      Erik

  3. Mar 14, 2011

    Matthew Turk

    Is there any way to get the list of forks of a given repository using the API?  This would be a very handy feature.  The hgbb extension right now uses lxml to scrape and parse the website to get them.

  4. Jun 29, 2011

    Anonymous

    How do you fork a repository with an API call , is it possible?

  5. Aug 04, 2011

    Luciano Longo

    When getting a single repo (/repositories/USERNAME/REPO_SLUG/) I only get 'count', 'start', 'limit' and 'changesets'. It would be really helpful if it would return info as detailed as when you query /users/USERNAME

    Sorry! my bad

  6. Oct 05, 2011

    Anonymous

    Since BitBucket added git support it seems you now have to add an scm parameter otherwise you get "Bad Request"...scm..."This field is required" so to add a new repo the required fields are:

    -d "name=myrepo&scm=hg"

    1. Oct 09, 2011

      Anonymous

      Yeah, they could've set scm to 'hg' by default to support backwards computability for everyone already using their api (sad)

      1. Oct 09, 2011

        Erik van Zijst [Atlassian]

        Yes, that's a very good point. I'll see if I can fix that up tomorrow morning.

        1. Oct 09, 2011

          Erik van Zijst [Atlassian]

          Done.

          Note that Bitbucket keeps track of the kind of repos you create and if you don't specify an scm type, it will use the scm type of your most recently created repository.

          If you have never created a repository, it will default to hg.

  7. Nov 17, 2011

    Anonymous

    Is it possible to set "no_private_forks=true" using the curl commad? Using

    curl -X POST -u username:password https://api.bitbucket.org/1.0/repositories/ -d name=myrepo -d scm=git -d no_private_forks=true

    Doesn't produce the expected result (no_private_forks stays false). This is a bit strange, since e.g. adding "has_issues=true" works fine. Any tips?

  8. Mar 09, 2012

    Jeroen de Bruin

    Is it possible to get rid of the password in the `curl` command and use ssh authentication?

    1. Mar 09, 2012

      David Chambers [Atlassian]

      You can't connect to the API via SSH. You can, however, ask us for a consumer key which would allow you to connect via OAuth. Contact support@bitbucket.org if you'd like a consumer key.

      1. Mar 09, 2012

        Jeroen de Bruin

        Thanks a lot for your fast reply!

        I have contacted support for a consumer key.

  9. Apr 25, 2012

    Anonymous

    Any thoughts on adding forking support to repo creation? Or even it's own call?