Get started with Bitbucket Cloud
New to Bitbucket Cloud? Check out our get started guides for new users.
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
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 |
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} |
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. |
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. |
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"
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. |
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.
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.
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. |
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. |
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"
}
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.
Was this helpful?