The Bitbucket Cloud REST API

Developer Day is June 9th, 2022. Register now for free!

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

OAuth scopes required:

NONE

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

cURL

Node.js

Java

Python

PHP

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

Responses

200

404

The workspace.

Content type	Value
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 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

cURL

Node.js

Java

Python

PHP

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

Responses

200

403

404

The paginated list of installed webhooks.

Content type	Value
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 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

cURL

Node.js

Java

Python

PHP

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

Responses

201

403

404

If the webhook was registered successfully.

Content type	Value
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 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

cURL

Node.js

Java

Python

PHP

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

Responses

200

404

The webhook subscription object.

Content type	Value
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 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

cURL

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'https://api.bitbucket.org/2.0/workspaces/{workspace}/hooks/{uid}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'