Bitbucket Documentation

Index

Skip to end of metadata
Go to start of metadata

The bitbucket 'groups' REST resource provides functionality for querying information about groups, creating new ones, updating memberships, and deleting them.

Querying Your Groups

$ curl --request GET --user username:password https://api.bitbucket.org/1.0/groups/username/
[
    {
        "name": "developers",
        "permission": "read",
        "auto_add": false,
        "members": [
            {
                "username": "jstepka",
                "first_name": "Justen",
                "last_name": "Stepka",
                "avatar": "https://secure.gravatar.com/avatar/12e5043280f67465b68ac42985082498?d=identicon&s=32",
                "resource_uri": "/1.0/users/jstepka"
            },
            {
                "username": "detkin",
                "first_name": "Dylan",
                "last_name": "Etkin",
                "avatar": "https://secure.gravatar.com/avatar/e1ef8ef737e394a17ffbc27c889c2b22?d=identicon&s=32",
                "resource_uri": "/1.0/users/detkin"
            }
        ],
        "owner": {
            "username": "baratrion",
            "first_name": "Mehmet S",
            "last_name": "Catalbas",
            "avatar": "https://secure.gravatar.com/avatar/55a1369161d3a648729b59cabf160e70?d=identicon&s=32",
            "resource_uri": "/1.0/users/baratrion"
        },
        "slug": "developers"
    }
]

The command above lists all the groups for the account owner.

While other fields are descriptive auto_add, permission, and slug fields need clarification. auto_add is used in conjunction with permission to enable default access to newly created repositories. slug is used to fetch group specific information in API calls.

Alternatively, you can use a validated email address in place of a username for the Groups API:

$ curl --request GET --user username:password https://api.bitbucket.org/1.0/groups/username@example.com/
[
    {
        "name": "developers",
        "permission": "read",
        "auto_add": false,
        "members": [
            {
                "username": "jstepka",
                "first_name": "Justen",
                "last_name": "Stepka",
                "avatar": "https://secure.gravatar.com/avatar/12e5043280f67465b68ac42985082498?d=identicon&s=32",
                "resource_uri": "/1.0/users/jstepka"
            },
            {
                "username": "detkin",
                "first_name": "Dylan",
                "last_name": "Etkin",
                "avatar": "https://secure.gravatar.com/avatar/e1ef8ef737e394a17ffbc27c889c2b22?d=identicon&s=32",
                "resource_uri": "/1.0/users/detkin"
            }
        ],
        "owner": {
            "username": "baratrion",
            "first_name": "Mehmet S",
            "last_name": "Catalbas",
            "avatar": "https://secure.gravatar.com/avatar/55a1369161d3a648729b59cabf160e70?d=identicon&s=32",
            "resource_uri": "/1.0/users/baratrion"
        },
        "slug": "developers"
    }
]

Adding Groups

To create a group called designers:

$ curl --request POST --user username:password https://api.bitbucket.org/1.0/groups/username@example.com/ --data "name=designers"
{
    "name": "designers", 
    "permission": "read", 
    "auto_add": false, 
    "members": [], 
    "owner": {
        "username": "baratrion", 
        "first_name": "Mehmet S", 
        "last_name": "Catalbas", 
        "avatar": "https://secure.gravatar.com/avatar/55a1369161d3a648729b59cabf160e70?d=identicon&s=32", 
        "resource_uri": "/1.0/users/baratrion"
    }, 
    "slug": "designers"
}

This will return 200 status code on success with the response body containing details about the newly created group.

Updating Groups

To update the settings of a group, issue a PUT request with your username and the group slug.

Let's change the name of the designers group to developers and grant default write access to it for all newly created repositories.

$ curl --request PUT --user username:password https://api.bitbucket.org/1.0/groups/username@example.com/designers/ --data "name=developers&permission=write&auto_add=true"
{
    "name": "developers",
    "permission": "write",
    "auto_add": true,
    "members": [],
    "owner": {
        "username": "baratrion",
        "first_name": "Mehmet S",
        "last_name": "Catalbas",
        "avatar": "https://secure.gravatar.com/avatar/55a1369161d3a648729b59cabf160e70?d=identicon&s=32",
        "resource_uri": "/1.0/users/baratrion"
    },
    "slug": "developers"
}

You may need to add --header "Content-Length: 0" when making PUT requests.

Deleting Groups

To delete a group:

$ curl --request DELETE --user username:password https://api.bitbucket.org/1.0/groups/username/test/

Listing Members of Groups

To list all the members of the developers group:

$ curl --request GET --user username:password https://api.bitbucket.org/1.0/groups/username/developers/members/
[
    {
        "username": "jstepka",
        "first_name": "Justen",
        "last_name": "Stepka",
        "avatar": "https://secure.gravatar.com/avatar/12e5043280f67465b68ac42985082498?d=identicon&s=32",
        "resource_uri": "/1.0/users/jstepka"
    },
    {
        "username": "detkin",
        "first_name": "Dylan",
        "last_name": "Etkin",
        "avatar": "https://secure.gravatar.com/avatar/e1ef8ef737e394a17ffbc27c889c2b22?d=identicon&s=32",
        "resource_uri": "/1.0/users/detkin"
    }
]

Adding Members to Groups

To add a member with the username brao to the group developers:

curl --request PUT --user username:password https://api.bitbucket.org/1.0/groups/username/developers/members/brao/

Alternatively, you can add the member brao to a group using one of his validated email address.

Removing Members from Groups

To remove a member with the username brao from the group developers:

$ curl --request DELETE --user username:password https://api.bitbucket.org/1.0/groups/username/developers/members/brao/

Alternatively, you can remove the user members brao from a group using one of his validated email address.

Status Codes

401: Unauthorized

Returned if you try to access somebody else's group.

400: Bad Request

  • Returned when the permission is not read, write, or admin.
  • Returned when trying to add yourself to one of your groups.

404: Not Found

Returned if the specified resource does not exist.

409: Conflict/Duplicate

Returned when trying to add a member and if member is already in a group.

Labels
  • None

5 Comments

Hide/Show Comments

  1. Mar 22, 2011

    Anonymous

    Not sure why "permission" is used here instead of "privilege".  "privilege" is used in group privileges and privileges API.

  2. Aug 31, 2011

    Anonymous

    How do I specify a group name with space? It appears that there is some weird lower-casing occurring also....

    1. Aug 31, 2011

      Anthony Steiner

      I'm going to assume you can use %20 (urlencoded space), + or _ en lieu of a space. And if those don't work, try no spaces.

      1. Sep 01, 2011

        Anonymous

        No, apparently group names are mapped into lower case, and spaces are represented as dashes.

        So: "Viewer Release Management" > "viewer-release-management"

        1. Sep 01, 2011

          Anthony Steiner

          Hmm... the lowercase is expected. Linux servers are case-sensitive, so they're conforming urls to a case-type. The dash surprises me...