groups Endpoint

Bitbucket Cloud v1 APIs are deprecated

Bitbucket Cloud REST API version 1 is deprecated effective 30 June 2018, and were removed from the REST API permanently on 29 April 2019. Read the deprecation notice. Or you can jump right to the version 2.0 REST API documentation.

Temporary support for limited 1.0 API resources

The 2.0 REST API will rely on the Atlassian Cloud Admin API for user and group management, but those API endpoints are not yet available. Until the Atlassian platform services are fully available in Bitbucket we will continue to support these 1.0 REST endpoints:

  • /1.0/groups

  • /1.0/group-privileges

  • /1.0/invitations

  • /1.0/users/{accountname}/invitations

Overview

The groups endpoint provides functionality for querying information about Bitbucket Cloud user 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:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 { "name": "Administrators", "permission": "admin", "email_forwarding_disabled":false, "members": [ { "display_name": "Justen Stepka", "account_id": "557057:016ad873-3455-3455-23443-233534545434", "is_team":false, "is_staff":false, "avatar": "https://secure.gravatar.com/avatar/12e5043", "resource_uri": "/1.0/users/jstepka", "nickname":"jstepka", "uuid":"{c423e13e-b541-3e77-b363-3e0b458u8226} } ], "owner": { "display_name": "Justen Stepka", "uuid":"{c423e13e-b541-3e77-b363-3e0b458u8226}, "account_id": "557057:016ad873-3455-3455-23443-233534545434", "is_team":false, "avatar": "https://secure.gravatar.com/avatar/12e5043", "nickname":"jstepka", "resource_uri": "/1.0/users/jstepka" }, "slug": "administrators" }

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

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 lowercase. So, if you name a group Viewer Release Management then its slug is:

viewer-release-management

GET a list of matching groups

1 GET https://api.bitbucket.org/1.0/groups?{filter}&{filter}&...

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 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. This method has the following parameters:

Parameter

Required?

Description

filter

Yes

A filter in the following format:

1 group={ownername}/{group_slug}

GET a list of groups

1 GET https://api.bitbucket.org/1.0/groups/{workspace_id}/

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

Parameter

Required?

Description

workspace_id

Yes

The workspace ID.

POST a new group

1 POST https://api.bitbucket.org/1.0/groups/{workspace_id} --data "name=string"

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

workspace_id

Yes

The workspace ID.

name

Yes

The name of the group.

Example

To create a group called designers:

1 curl --request POST --user username:password https://api.bitbucket.org/1.0/groups/username@example.com/ --data "name=designers"

PUT update a group

1 PUT https://api.bitbucket.org/1.0/groups/{workspace_id}/{group_slug}/ --header "Accept: application/json" --data '{"name":"developers","permission":"write":true}'

Updates an existing group resource. The caller must authenticate with administrative rights on the account. This command expects a JSON request payload. This method has the following parameters:

Parameter

Required?

Description

workspace_id

Yes

The workspace ID.

name

No

The name of the group.

group_slug

Yes

The group's slug.

permission

No

One of read, write, or admin.

Example

The following example changes the designers group's name to developers and grants default write access to the group for all newly created repositories.

1 curl --request PUT --user username:password https://api.bitbucket.org/1.0/groups/username@example.com/designers/ --header "Content-Type: application/json" --header "Accept: application/json" --data '{"name":"developers","permission":"write":true}'

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

DELETE a group

1 DELETE https://api.bitbucket.org/1.0/groups/{workspace_id}/{group_slug}/

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

Parameter

Required?

Description

workspace_id

Yes

The workspace ID.

group_slug

Yes

The group's slug.


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

GET the group members

1 GET https://api.bitbucket.org/1.0/groups/{workspace_id}/{group_slug}/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

workspace_id

Yes

The workspace ID.

group_slug

Yes

The group's slug.

PUT new member into a group

1 PUT https://api.bitbucket.org/1.0/groups/{workspace_id}/{group_slug}/members/{uuid}/ --data '{}'

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. The caller must authenticate with administrative rights for a workspace to access its groups. This method has the following parameters:

Parameter

Required?

Description

workspace_id

Yes

The workspace ID.

group_slug

Yes

The slug of the group.

uuid

Yes

Unique identifier for an account.

Example

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

1 curl --request PUT --user username:password --header "Content-Type: application/json" https://api.bitbucket.org/1.0/groups/test_workspace/developers/members/%7Bc423e13e-b541-3e77-b363-3e0b458u8226%7D/ --data '{}'

The response would look like this:

1 2 3 4 5 6 { "display_name": "Atlassian Tutorials", "is_team": true, "avatar": "https://secure.gravatar.com/avatar/eb4e0ad6934518b3e335345a4ceeef21?d=https%3A%2F%2Fdwz7u9t8u8usb.cloudfront.net%2Fm%2F5441e467b5e2%2Fimg%2Fteam_no_avatar_32.png&s=32", "resource_uri": "/1.0/users/atlassian_tutorial" }

DELETE a member

1 DELETE https://api.bitbucket.org/1.0/groups/{workspace_id}/{group_slug}/members/{uuid}

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

workspace_id

Yes

The workspace ID.

group_slug

Yes

The group's slug.

uuid

Yes

Unique identifier for an account.

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


Additional Help