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.

OAuth 2.0 scopes required:
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.

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

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

Path parameters
workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Example

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'

Responses

The workspace.

Content typeValue
application/json

allOf [object, Workspace]

List webhooks for a workspace

GET /2.0/workspaces/{workspace}/hooks

Returns a paginated list of webhooks installed on this workspace.

OAuth 2.0 scopes required:
webhook

Request

Path parameters
workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Example

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'

Responses

The paginated list of installed webhooks.

Content typeValue
application/json

Paginated Webhook Subscriptions

Create a webhook for a workspace

POST /2.0/workspaces/{workspace}/hooks

Creates a new webhook on the specified workspace.

Workspace webhooks are fired for events from all repositories contained by that workspace.

Example:

1
2
$ 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,
      "events": [
        "repo:push",
        "issue:created",
        "issue:updated"
      ]
    }'

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.

OAuth 2.0 scopes required:
webhook

Request

Path parameters
workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Example

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'

Responses

If the webhook was registered successfully.

Content typeValue
application/json

allOf [object, Webhook Subscription]

Header Parameters
Location

string

The URL of new newly created webhook.

Get a webhook for a workspace

GET /2.0/workspaces/{workspace}/hooks/{uid}

Returns the webhook with the specified id installed on the given workspace.

OAuth 2.0 scopes required:
webhook

Request

Path parameters
uid Required

string

Installed webhook's ID

workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Example

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'

Responses

The webhook subscription object.

Content typeValue
application/json

allOf [object, Webhook Subscription]

Update a webhook for a workspace

PUT /2.0/workspaces/{workspace}/hooks/{uid}

Updates the specified webhook subscription.

The following properties can be mutated:

  • description
  • url
  • active
  • events
OAuth 2.0 scopes required:
webhook

Request

Path parameters
uid Required

string

Installed webhook's ID

workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Example

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'

Responses

The webhook subscription object.

Content typeValue
application/json

allOf [object, Webhook Subscription]

Delete a webhook for a workspace

DELETE /2.0/workspaces/{workspace}/hooks/{uid}

Deletes the specified webhook subscription from the given workspace.

OAuth 2.0 scopes required:
webhook

Request

Path parameters
uid Required

string

Installed webhook's ID

workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Example

1
2
3
curl --request DELETE \
  --url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/hooks/{uid}' \
  --header 'Authorization: Bearer <access_token>'

Responses

When the webhook was deleted successfully

List users in a workspace

GET /2.0/workspaces/{workspace}/members

Returns all members of the requested workspace.

OAuth 2.0 scopes required:
account

Request

Path parameters
workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Example

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'

Responses