The Bitbucket Cloud REST API

Workspaces

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.

List workspaces for the current user

GET /2.0/user/permissions/workspaces

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:

owner
collaborator
member

The collaborator role is being removed from the Bitbucket Cloud API. For more information, see the deprecation announcement.

Example:

1
2
$ curl https://api.bitbucket.org/2.0/user/permissions/workspaces

{
  "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",
      }
    }
  ]
}

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

Note that the query parameter values need to be URL escaped so that = would become %3D.

OAuth 2.0 scopes required:

account

Request

Query parameters

string

Query string to narrow down the response. See filtering and sorting for details.

sort

string

Name of a response property to sort results. See filtering and sorting for details.

Example

cURL

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.bitbucket.org/2.0/user/permissions/workspaces' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

200

401

All of the workspace memberships for the authenticated user.

Content type	Value
application/json	Paginated Workspace Memberships

List workspaces for user

GET /2.0/workspaces

Returns a list of workspaces accessible by the authenticated user.

Example:

1
2
$ curl https://api.bitbucket.org/2.0/workspaces

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

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=true
sort=created_on

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

OAuth 2.0 scopes required:

account

Request

Query parameters

role

string

1
2
        Filters the workspaces based on the authenticated user's role on each workspace.

        * **member**: returns a list of all the workspaces which the caller is a member of
            at least one workspace group or repository
        * **collaborator**: returns a list of workspaces which the caller has write access
            to at least one repository in the workspace
        * **owner**: returns a list of workspaces which the caller has administrator access

Valid values: owner, collaborator, member

string

Query string to narrow down the response. See filtering and sorting for details.

sort

string

Name of a response property to sort results. See filtering and sorting for details.

Example

cURL

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.bitbucket.org/2.0/workspaces' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

200

401

The list of workspaces accessible by the authenticated user.

Content type	Value
application/json	Paginated Workspaces

Get a workspace

GET /2.0/workspaces/{workspace}

Returns the requested workspace.