A workspace is where you create repositories, collaborate on your code, and organize different streams of work in your Bitbucket Cloud account. Workspaces replace the use of teams and users in API calls.
Returns an object for each workspace the caller is a member of, and their effective role - the highest level of privilege the caller has. If a user is a member of multiple groups with distinct roles, only the highest level is returned.
Permissions can be:
ownercollaboratormemberThe collaborator role is being removed from the Bitbucket Cloud API. For more information,
see the deprecation announcement.
When you move your administration from Bitbucket Cloud to admin.atlassian.com, the following fields on
workspace_membership will no longer be present: last_accessed and added_on. See the
deprecation announcement.
Results may be further filtered or sorted by workspace or permission by adding the following query string parameters:
q=workspace.slug="bbworkspace1" or q=permission="owner"sort=workspace.slugNote that the query parameter values need to be URL escaped so that =
would become %3D.
accountstring
string
All of the workspace memberships for the authenticated user.
A paginated list of workspace memberships.
1
2
3
4
curl --request GET \
--url 'https://api.bitbucket.org/2.0/user/permissions/workspaces' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'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
{
"pagelen": 10,
"page": 1,
"size": 1,
"values": [
{
"type": "workspace_membership",
"permission": "owner",
"last_accessed": "2019-03-07T12:35:02.900024+00:00",
"added_on": "2018-10-11T17:42:02.961424+00:00",
"user": {
"type": "user",
"uuid": "{470c176d-3574-44ea-bb41-89e8638bcca4}",
"nickname": "evzijst",
"display_name": "Erik van Zijst"
},
"workspace": {
"type": "workspace",
"uuid": "{a15fb181-db1f-48f7-b41f-e1eff06929d6}",
"slug": "bbworkspace1",
"name": "Atlassian Bitbucket"
}
}
]
}Returns a list of workspaces accessible by the authenticated user.
Results may be further filtered or sorted by workspace or permission by adding the following query string parameters:
q=slug="bbworkspace1" or q=is_private=truesort=created_onNote that the query parameter values need to be URL escaped so that =
would become %3D.
The collaborator role is being removed from the Bitbucket Cloud API. For more information,
see the deprecation announcement.
accountstring
string
string
The list of workspaces accessible by the authenticated user.
A paginated list of workspaces.
1
2
3
4
curl --request GET \
--url 'https://api.bitbucket.org/2.0/workspaces' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
"pagelen": 10,
"page": 1,
"size": 1,
"values": [
{
"uuid": "{a15fb181-db1f-48f7-b41f-e1eff06929d6}",
"links": {
"owners": {
"href": "https://api.bitbucket.org/2.0/workspaces/bbworkspace1/members?q=permission%3D%22owner%22"
},
"self": {
"href": "https://api.bitbucket.org/2.0/workspaces/bbworkspace1"
},
"repositories": {
"href": "https://api.bitbucket.org/2.0/repositories/bbworkspace1"
},
"snippets": {
"href": "https://api.bitbucket.org/2.0/snippets/bbworkspace1"
},
"html": {
"href": "https://bitbucket.org/bbworkspace1/"
},
"avatar": {
"href": "https://bitbucket.org/workspaces/bbworkspace1/avatar/?ts=1543465801"
},
"members": {
"href": "https://api.bitbucket.org/2.0/workspaces/bbworkspace1/members"
},
"projects": {
"href": "https://api.bitbucket.org/2.0/workspaces/bbworkspace1/projects"
}
},
"created_on": "2018-11-14T19:15:05.058566+00:00",
"type": "workspace",
"slug": "bbworkspace1",
"is_private": true,
"name": "Atlassian Bitbucket"
}
]
}Returns the requested workspace.
string
RequiredThe workspace.
allOf [object, Workspace]
Base type for most resource objects. It defines the common type element that identifies an object's type. It also identifies the element as Swagger's discriminator.
A Bitbucket workspace. Workspaces are used to organize repositories.
1
2
3
4
curl --request GET \
--url 'https://api.bitbucket.org/2.0/workspaces/{workspace}' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
"type": "<string>",
"links": {
"avatar": {
"href": "<string>",
"name": "<string>"
},
"html": {
"href": "<string>",
"name": "<string>"
},
"members": {
"href": "<string>",
"name": "<string>"
},
"owners": {
"href": "<string>",
"name": "<string>"
},
"projects": {
"href": "<string>",
"name": "<string>"
},
"repositories": {
"href": "<string>",
"name": "<string>"
},
"snippets": {
"href": "<string>",
"name": "<string>"
},
"self": {
"href": "<string>",
"name": "<string>"
}
},
"uuid": "<string>",
"name": "<string>",
"slug": "<string>",
"is_private": true,
"is_privacy_enforced": true,
"forking_mode": "allow_forks",
"created_on": "<string>",
"updated_on": "<string>"
}Returns a paginated list of webhooks installed on this workspace.
webhookstring
RequiredThe paginated list of installed webhooks.
A paginated list of webhook subscriptions
1
2
3
4
curl --request GET \
--url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/hooks' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"size": 142,
"page": 102,
"pagelen": 159,
"next": "<string>",
"previous": "<string>",
"values": [
{
"type": "<string>",
"uuid": "<string>",
"url": "<string>",
"description": "<string>",
"subject_type": "repository",
"active": true,
"created_at": "<string>",
"events": [
"issue:comment_created"
],
"secret_set": true,
"secret": "<string>"
}
]
}Creates a new webhook on the specified workspace.
Workspace webhooks are fired for events from all repositories contained by that workspace.
Example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14$ curl -X POST -u credentials -H 'Content-Type: application/json' https://api.bitbucket.org/2.0/workspaces/my-workspace/hooks -d ' { "description": "Webhook Description", "url": "https://example.com/", "active": true, "secret": "this is a really bad secret", "events": [ "repo:push", "issue:created", "issue:updated" ] }'
When the secret is provided it will be used as the key to generate a HMAC
digest value sent in the X-Hub-Signature header at delivery time. Passing
a null or empty secret or not passing a secret will leave the webhook's
secret unset. Bitbucket only generates the X-Hub-Signature when the webhook's
secret is set.
This call requires the webhook scope, as well as any scope
that applies to the events that the webhook subscribes to. In the
example above that means: webhook, repository and issue.
The url must properly resolve and cannot be an internal, non-routed address.
Only workspace owners can install webhooks on workspaces.
webhookstring
RequiredIf the webhook was registered successfully.
string
allOf [object, Webhook Subscription]
Base type for most resource objects. It defines the common type element that identifies an object's type. It also identifies the element as Swagger's discriminator.
A Webhook subscription.
1
2
3
4
curl --request POST \
--url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/hooks' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"type": "<string>",
"uuid": "<string>",
"url": "<string>",
"description": "<string>",
"subject_type": "repository",
"active": true,
"created_at": "<string>",
"events": [
"issue:comment_created"
],
"secret_set": true,
"secret": "<string>"
}Returns the webhook with the specified id installed on the given workspace.
webhookstring
Requiredstring
RequiredThe webhook subscription object.
allOf [object, Webhook Subscription]
Base type for most resource objects. It defines the common type element that identifies an object's type. It also identifies the element as Swagger's discriminator.
A Webhook subscription.
1
2
3
4
curl --request GET \
--url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/hooks/{uid}' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"type": "<string>",
"uuid": "<string>",
"url": "<string>",
"description": "<string>",
"subject_type": "repository",
"active": true,
"created_at": "<string>",
"events": [
"issue:comment_created"
],
"secret_set": true,
"secret": "<string>"
}Updates the specified webhook subscription.
The following properties can be mutated:
descriptionurlsecretactiveeventsThe hook's secret is used as a key to generate the HMAC hex digest sent in the
X-Hub-Signature header at delivery time. This signature is only generated
when the hook has a secret.
Set the hook's secret by passing the new value in the secret field. Passing a
null value in the secret field will remove the secret from the hook. The
hook's secret can be left unchanged by not passing the secret field in the
request.
webhookstring
Requiredstring
RequiredThe webhook subscription object.
allOf [object, Webhook Subscription]
Base type for most resource objects. It defines the common type element that identifies an object's type. It also identifies the element as Swagger's discriminator.
A Webhook subscription.
1
2
3
4
curl --request PUT \
--url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/hooks/{uid}' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"type": "<string>",
"uuid": "<string>",
"url": "<string>",
"description": "<string>",
"subject_type": "repository",
"active": true,
"created_at": "<string>",
"events": [
"issue:comment_created"
],
"secret_set": true,
"secret": "<string>"
}Deletes the specified webhook subscription from the given workspace.
webhookstring
Requiredstring
RequiredWhen the webhook was deleted successfully
1
2
3
curl --request DELETE \
--url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/hooks/{uid}' \
--header 'Authorization: Bearer <access_token>'Returns all members of the requested workspace.
This endpoint additionally supports filtering by email address, if called by a workspace administrator, integration or workspace access token. This is done by adding the following query string parameter:
q=user.email IN ("user1@org.com","user2@org.com")When filtering by email, you can query up to 90 addresses at a time. Note that the query parameter values need to be URL escaped, so the final query string should be:
q=user.email%20IN%20(%22user1@org.com%22,%22user2@org.com%22)Email addresses that you filter by (and only these email addresses) can be included in the
response using the fields query parameter:
&fields=+values.user.email - add the email field to the default user response object&fields=values.user.email,values.user.account_id - only return user email addresses and
account IDsOnce again, all query parameter values must be URL escaped.
accountread:workspace:bitbucketstring
RequiredThe list of users that are part of a workspace.
A paginated list of workspace memberships.
1
2
3
4
curl --request GET \
--url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/members' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
"size": 142,
"page": 102,
"pagelen": 159,
"next": "<string>",
"previous": "<string>",
"values": [
{
"type": "<string>",
"links": {
"self": {
"href": "<string>",
"name": "<string>"
}
},
"user": {
"type": "<string>"
},
"workspace": {
"type": "<string>"
}
}
]
}Returns the workspace membership, which includes
a User object for the member and a Workspace object
for the requested workspace.
accountread:workspace:bitbucketstring
Requiredstring
RequiredThe user that is part of a workspace.
allOf [object, Workspace Membership]
Base type for most resource objects. It defines the common type element that identifies an object's type. It also identifies the element as Swagger's discriminator.
A Bitbucket workspace membership. Links a user to a workspace.
1
2
3
4
curl --request GET \
--url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/members/{member}' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"type": "<string>",
"links": {
"self": {
"href": "<string>",
"name": "<string>"
}
},
"user": {
"type": "<string>"
},
"workspace": {
"type": "<string>"
}
}Returns the list of members in a workspace and their permission levels. Permission can be:
ownercollaboratormemberThe collaborator role is being removed from the Bitbucket Cloud API. For more information,
see the deprecation announcement.
When you move your administration from Bitbucket Cloud to admin.atlassian.com, the following fields on
workspace_membership will no longer be present: last_accessed and added_on. See the
deprecation announcement.
Results may be further filtered by permission by adding the following query string parameters:
q=permission="owner"accountread:workspace:bitbucketstring
Requiredstring
The list of users that are part of a workspace, along with their permission.
A paginated list of workspace memberships.
1
2
3
4
curl --request GET \
--url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/permissions' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'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
28
29
30
31
32
33
34
35
36
37
38
{
"pagelen": 10,
"values": [
{
"permission": "owner",
"type": "workspace_membership",
"user": {
"type": "user",
"uuid": "{470c176d-3574-44ea-bb41-89e8638bcca4}",
"display_name": "Erik van Zijst"
},
"workspace": {
"type": "workspace",
"uuid": "{a15fb181-db1f-48f7-b41f-e1eff06929d6}",
"slug": "bbworkspace1",
"name": "Atlassian Bitbucket"
}
},
{
"permission": "member",
"type": "workspace_membership",
"user": {
"type": "user",
"nickname": "seanaty",
"display_name": "Sean Conaty",
"uuid": "{504c3b62-8120-4f0c-a7bc-87800b9d6f70}"
},
"workspace": {
"type": "workspace",
"uuid": "{a15fb181-db1f-48f7-b41f-e1eff06929d6}",
"slug": "bbworkspace1",
"name": "Atlassian Bitbucket"
}
}
],
"page": 1,
"size": 2
}Returns an object for each repository permission for all of a workspace's repositories.
Permissions returned are effective permissions: the highest level of permission the user has. This does not distinguish between direct and indirect (group) privileges.
Only users with admin permission for the team may access this resource.
Permissions can be:
adminwritereadResults may be further filtered or sorted by repository, user, or permission by adding the following query string parameters:
q=repository.name="geordi" or q=permission>"read"sort=user.display_nameNote that the query parameter values need to be URL escaped so that =
would become %3D.
accountread:repository:bitbucketstring
Requiredstring
string
List of workspace's repository permissions.
A paginated list of repository permissions.
1
2
3
4
curl --request GET \
--url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/permissions/repositories' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
"pagelen": 10,
"values": [
{
"type": "repository_permission",
"user": {
"type": "user",
"display_name": "Erik van Zijst",
"uuid": "{d301aafa-d676-4ee0-88be-962be7417567}"
},
"repository": {
"type": "repository",
"name": "geordi",
"full_name": "atlassian_tutorial/geordi",
"uuid": "{85d08b4e-571d-44e9-a507-fa476535aa98}"
},
"permission": "admin"
},
{
"type": "repository_permission",
"user": {
"type": "user",
"display_name": "Sean Conaty",
"uuid": "{504c3b62-8120-4f0c-a7bc-87800b9d6f70}"
},
"repository": {
"type": "repository",
"name": "geordi",
"full_name": "atlassian_tutorial/geordi",
"uuid": "{85d08b4e-571d-44e9-a507-fa476535aa98}"
},
"permission": "write"
},
{
"type": "repository_permission",
"user": {
"type": "user",
"display_name": "Jeff Zeng",
"uuid": "{47f92a9a-c3a3-4d0b-bc4e-782a969c5c72}"
},
"repository": {
"type": "repository",
"name": "whee",
"full_name": "atlassian_tutorial/whee",
"uuid": "{30ba25e9-51ff-4555-8dd0-fc7ee2fa0895}"
},
"permission": "admin"
}
],
"page": 1,
"size": 3
}Returns an object for the repository permission of each user in the requested repository.
Permissions returned are effective permissions: the highest level of permission the user has. This does not distinguish between direct and indirect (group) privileges.
Only users with admin permission for the repository may access this resource.
Permissions can be:
adminwritereadResults may be further filtered or sorted by user, or permission by adding the following query string parameters:
q=permission>"read"sort=user.display_nameNote that the query parameter values need to be URL escaped so that =
would become %3D.
repositoryread:repository:bitbucketstring
Requiredstring
Requiredstring
string
The repository permission for all users in this repository.
A paginated list of repository permissions.
1
2
3
4
curl --request GET \
--url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/permissions/repositories/{repo_slug}' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'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
28
29
30
31
32
33
34
35
36
37
{
"pagelen": 10,
"values": [
{
"type": "repository_permission",
"user": {
"type": "user",
"display_name": "Erik van Zijst",
"uuid": "{d301aafa-d676-4ee0-88be-962be7417567}"
},
"repository": {
"type": "repository",
"name": "geordi",
"full_name": "atlassian_tutorial/geordi",
"uuid": "{85d08b4e-571d-44e9-a507-fa476535aa98}"
},
"permission": "admin"
},
{
"type": "repository_permission",
"user": {
"type": "user",
"display_name": "Sean Conaty",
"uuid": "{504c3b62-8120-4f0c-a7bc-87800b9d6f70}"
},
"repository": {
"type": "repository",
"name": "geordi",
"full_name": "atlassian_tutorial/geordi",
"uuid": "{85d08b4e-571d-44e9-a507-fa476535aa98}"
},
"permission": "write"
}
],
"page": 1,
"size": 2
}Returns the list of projects in this workspace.
projectread:project:bitbucketstring
RequiredThe list of projects in this workspace.
A paginated list of projects
1
2
3
4
curl --request GET \
--url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/projects' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'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
28
29
30
31
32
33
{
"size": 142,
"page": 102,
"pagelen": 159,
"next": "<string>",
"previous": "<string>",
"values": [
{
"type": "<string>",
"links": {
"html": {
"href": "<string>",
"name": "<string>"
},
"avatar": {
"href": "<string>",
"name": "<string>"
}
},
"uuid": "<string>",
"key": "<string>",
"owner": {
"type": "<string>"
},
"name": "<string>",
"description": "<string>",
"is_private": true,
"created_on": "<string>",
"updated_on": "<string>",
"has_publicly_visible_repos": true
}
]
}Returns all workspace pull requests authored by the specified user.
By default only open pull requests are returned. This can be controlled
using the state query parameter. To retrieve pull requests that are
in one of multiple states, repeat the state parameter for each
individual state.
This endpoint also supports filtering and sorting of the results. See filtering and sorting for more details.
pullrequeststring
Requiredstring
Requiredstring
All pull requests authored by the specified user.
A paginated list of pullrequests.
1
2
3
4
curl --request GET \
--url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/pullrequests/{selected_user}' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
{
"size": 142,
"page": 102,
"pagelen": 159,
"next": "<string>",
"previous": "<string>",
"values": [
{
"type": "<string>",
"links": {
"self": {
"href": "<string>",
"name": "<string>"
},
"html": {
"href": "<string>",
"name": "<string>"
},
"commits": {
"href": "<string>",
"name": "<string>"
},
"approve": {
"href": "<string>",
"name": "<string>"
},
"diff": {
"href": "<string>",
"name": "<string>"
},
"diffstat": {
"href": "<string>",
"name": "<string>"
},
"comments": {
"href": "<string>",
"name": "<string>"
},
"activity": {
"href": "<string>",
"name": "<string>"
},
"merge": {
"href": "<string>",
"name": "<string>"
},
"decline": {
"href": "<string>",
"name": "<string>"
}
},
"id": 108,
"title": "<string>",
"rendered": {
"title": {
"raw": "<string>",
"markup": "markdown",
"html": "<string>"
},
"description": {
"raw": "<string>",
"markup": "markdown",
"html": "<string>"
},
"reason": {
"raw": "<string>",
"markup": "markdown",
"html": "<string>"
}
},
"summary": {
"raw": "<string>",
"markup": "markdown",
"html": "<string>"
},
"state": "OPEN",
"author": {
"type": "<string>"
},
"source": {},
"destination": {},
"merge_commit": {
"hash": "<string>"
},
"comment_count": 51,
"task_count": 53,
"close_source_branch": true,
"closed_by": {
"type": "<string>"
},
"reason": "<string>",
"created_on": "<string>",
"updated_on": "<string>",
"reviewers": [
{
"type": "<string>"
}
],
"participants": [
{
"type": "<string>"
}
],
"draft": true
}
]
}Rate this page: