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:

{
        "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

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: `1group={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_id	Yes	The 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_id	Yes	The workspace ID.
name	Yes	The 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":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.

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

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

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

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:

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:

{
    "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_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.

Was this helpful?

It wasn't accurate

It wasn't clear

It wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community