groups Endpoint

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.

Field Description
name The display name for the group as specified when you created the group.
permission The permission assigned to the group.
auto_add A boolean flag indicating whether new repositories automatically receive this group.
members An array of user profiles, one for each group member. Groups can be empty.
owner A 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
filter Yes

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
accountname Yes The 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
accountname Yes The team or individual account name. You can supply a user name or a valid email address.
name Yes The 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
accountname Yes The team or individual account name. You can supply an account name or the primary email address for the account.
name No The name of the group.
group_slug Yes The group's slug.
auto_add No A boolean value. True to automatically add the group
permission No One 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
accountname Yes The team or individual account name. You can supply an account name or the primary email address for the account.
group_slug Yes The 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
accountname Yes The team or individual account name. You can supply an account name or the primary email address for the account.
group_slug Yes The 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
accountname Yes The team or individual account name. You can supply an account name or the primary email address for the account.
group_slug Yes The slug of the group.
membername Yes An 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
accountname Yes The team or individual account name. You can supply an account name or the primary email address for the account.
group_slug Yes The group's slug.
membername Yes A 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.


Was this helpful?

Thanks for your feedback!

Powered by Confluence and Scroll Viewport