Addon
Branch restrictions
Branching model
Commit statuses
Commits
Deployments
Downloads
Issue tracker
Pipelines
Projects
Pullrequests
Refs
Reports
Repositories
Snippets
Source
Ssh
Users
Webhooks
Workspaces
Other operations

Rate this page:

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.

account

Request

Query parameters
q

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

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'

Responses

All of the workspace memberships for the authenticated user.

Content typeValue
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.

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

q

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

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

Responses

The list of workspaces accessible by the authenticated user.

Content typeValue
application/json

Paginated Workspaces

Get a workspace

GET /2.0/workspaces/{workspace}

Returns the requested workspace.

Request