groups Endpoint

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

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:

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:

{
        "name": "Administrators",
        "permission": "admin",
        "email_forwarding_disabled":false,
        "auto_add": true,
        "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.

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

viewer-release-management

GET a list of matching groups

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
filterYes

A filter in the following format:

group={ownername}/{group_slug}

GET a list of groups

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_idYesThe workspace ID.

POST a new group

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_idYesThe workspace ID.
nameYesThe name of the group.

Example

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"

PUT update a group

PUT https://api.bitbucket.org/1.0/groups/{workspace_id}/{group_slug}/  --header "Accept: application/json" --data '{"name":"developers","permission":"write","auto_add":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_idYesThe workspace ID.
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.

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.

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","auto_add":true}'

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

DELETE a group

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_idYesThe workspace ID.
group_slugYesThe group's slug.


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

GET the group members

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
YesThe workspace ID.
group_slugYesThe group's slug.

PUT new member into a group

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
YesThe workspace ID.
group_slugYesThe slug of the group.
uuidYesUnique identifier for an account.

Example

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

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


The response would look like this:

Click here to expand...
{
    "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

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_idYesThe workspace ID.
group_slugYesThe group's slug.
uuidYesUnique identifier for an account.

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


Last modified on Jul 25, 2019

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.