Skip to end of metadata
Go to start of metadata

Overview

The groups endpoint provides functionality for querying information about groups, creating new ones, updating memberships, and deleting them. Both individual and team accounts can define groups.  To manage group information on an individual account, the caller must authenticate with administrative rights on the account. To manage groups for a team account, the caller must authenticate as a team member with administrative rights on the team. A group contains the following fields:

These following table describes each of the fields in a groups structure.

FieldDescription
nameThe display name for the group as specified when you created the group.
permissionThe permission assigned to the group.
auto_addA boolean flag indicating whether new repositories automatically receive this group.
membersAn array of user profiles, one for each group member. Groups can be empty.
ownerA user profile representing the group owner.
slug

The group identifier. The slug is an identifier constructed by the Bitbucket service. Bitbucket creates a slug by converting spaces to dashes and making all text lower case. So, if you name a group Viewer Release Management then its slug is:

viewer-release-management

GET a list of matching groups

Get a list groups matching one or more filters.  The caller must authenticate with administrative rights or as a group member to view a group. This method has the following parameters:

Parameter
Required?
Description
filterYes

A filter in the following format:

group={ownername}/{group_slug}

This method gets all visible groups matching one of the provided filters. A group is visible to the caller if it  is owned by the caller or if the caller is one of its members.

GET https://bitbucket.org/api/1.0/groups?{filter}&{filter}&...
 Click to view the data returned on success...

GET a list of groups

Get a list of an account's groups.  The caller must authenticate with administrative rights on the account or as a group member to view a group. This method has the following parameters:

Parameter
Required?
Description
accountnameYesThe team or individual account name. You can supply a user name or a valid email address.
GET https://bitbucket.org/api/1.0/groups/{accountname}/
 Click to view the data returned on success...

POST a new group

Creates a new group.  The caller must authenticate with administrative rights on an account to access its groups. This method has the following parameters:

Parameter
Required?
Description
accountnameYesThe team or individual account name. You can supply a user name or a valid email address.
nameYesThe name of the group.

To create a group called designers:

curl --request POST --user username:password https://bitbucket.org/api/1.0/groups/username@example.com/ --data "name=designers"
POST https://bitbucket.org/api/1.0/groups/{accountname}  --data "name=string"
 Click here to expand...

 

Update a group

Updates an existing group resource.   The caller must authenticate with administrative rights on the account. This method has the following parameters:

Parameter
Required?
Description
accountnameYesThe team or individual account name. You can supply an account name or the primary email address for the account.
nameNoThe name of the group.
group_slugYesThe group's slug.
auto_addNoA boolean value. True to automatically add the group
permissionNoOne of read, write, or admin.

This command expects a JSON request payload.  The following example changes the designers group's name to developers and grants default write access to the group for all newly created repositories.

curl --request PUT --user username:password https://bitbucket.org/api/1.0/groups/username@example.com/designers/ --header "Content-Type: application/json" --header "Accept: application/json" --data '{"name":"developers","permission":"write","auto_add":true}'
PUT https://bitbucket.org/api/1.0/groups/{accountname}/{group_slug}/  --header "Accept: application/json" --data '{"name":"developers","permission":"write","auto_add":true}'
 Click to view the data returned on success...

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

DELETE a group

Deletes a group.  The caller must authenticate with administrative rights on the account. This method has the following parameters:

Parameter
Required?
Description
accountnameYesThe team or individual account name. You can supply an account name or the primary email address for the account.
group_slugYesThe group's slug.
DELETE  https://bitbucket.org/api/1.0/groups/{accountname}/{group_slug}/ 

On success, this call returns HTTP/1.1 204 NO CONTENT.

GET the group members

Gets the membership for a group. The caller must authenticate with administrative rights on the account. This method has the following parameters:

Parameter
Required?
Description
accountnameYesThe team or individual account name. You can supply an account name or the primary email address for the account.
group_slugYesThe group's slug.
GET https://bitbucket.org/api/1.0/groups/{accountname}/{group_slug}/ members
 Click to view the data returned on success...

PUT new member into a group

Adds a member to a group. This call requires the  Content-Type: application/json  in the header.  You should also supply an empty --data {} element. Finally, the caller must authenticate with administrative rights on an account to access its groups. This method has the following parameters:

Parameter
Required?
Description
accountnameYesThe team or individual account name. You can supply an account name or the primary email address for the account.
group_slugYesThe slug of the group.
membernameYesAn individual account. You can supply an account name or the primary email address for the account. Account names are case sensitive.

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

curl --request PUT --user username:password --header "Content-Type: application/json" https://bitbucket.org/api/1.0/groups/username/developers/members/brao/ --data '{}'
PUT https://bitbucket.org/api/1.0/groups/{accountname}/{group_slug}/members/{membername}
 Click here to expand...

DELETE a member

Deletes a member from a group.  The caller must authenticate with administrative rights on the account. This method has the following parameters:

Parameter
Required?
Description
accountnameYesThe team or individual account name. You can supply an account name or the primary email address for the account.
group_slugYesThe group's slug.
membernameYesA individual account name. You can supply an account name or the primary email address for the account.
DELETE  https://bitbucket.org/api/1.0/groups/{accountname}/{group_slug}/members/{membername}

On success, this call returns HTTP/1.1 204 NO CONTENT.

Acknowledgements

Many thanks to Anthony Steiner who provided additional testing and commentary that refined the content of this page.