Atlassian Bitbucket Workspaces API
The Atlassian Bitbucket Workspaces API enables users to manage and interact with multiple projects within their Bitbucket account.
OpenAPI Specification
openapi: 3.0.0
info:
title: 'Atlassian workspaces/'
description: Needs description.
version: '2.0'
termsOfService: https://www.atlassian.com/legal/customer-agreement
contact:
name: Bitbucket Support
url: https://support.atlassian.com/bitbucket-cloud/
email: [email protected]
paths:
/workspaces/{workspace}:
get:
tags:
- Workspaces
description: Returns the requested workspace.
summary: Atlassian Get a workspace
responses:
'200':
description: The workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/workspace'
'404':
description: If no workspace exists for the specified name or UUID.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2: []
- basic: []
- api_key: []
parameters:
- name: workspace
in: path
description: |
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
required: true
schema:
type: string
/workspaces/{workspace}/hooks:
get:
tags:
- Workspaces
description: Returns a paginated list of webhooks installed on this workspace.
summary: Atlassian List webhooks for a workspace
responses:
'200':
description: The paginated list of installed webhooks.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_webhook_subscriptions'
'403':
description: >-
If the authenticated user is not an owner on the specified
workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the specified workspace does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- webhook
- basic: []
- api_key: []
post:
tags:
- Workspaces
description: >-
Creates a new webhook on the specified workspace.
Workspace webhooks are fired for events from all repositories contained
by that workspace.
Example:
```
$ 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.
summary: Atlassian Create a webhook for a workspace
responses:
'201':
description: If the webhook was registered successfully.
headers:
Location:
description: The URL of new newly created webhook.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/webhook_subscription'
'403':
description: >-
If the authenticated user does not have permission to install
webhooks on the specified workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the specified workspace does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- webhook
- basic: []
- api_key: []
parameters:
- name: workspace
in: path
description: |
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
required: true
schema:
type: string
/workspaces/{workspace}/hooks/{uid}:
delete:
tags:
- Workspaces
description: Deletes the specified webhook subscription from the given workspace.
summary: Atlassian Delete a webhook for a workspace
responses:
'204':
description: When the webhook was deleted successfully
'403':
description: >-
If the authenticated user does not have permission to delete the
webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the webhook or workspace does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- webhook
- basic: []
- api_key: []
get:
tags:
- Workspaces
description: |-
Returns the webhook with the specified id installed on the given
workspace.
summary: Atlassian Get a webhook for a workspace
responses:
'200':
description: The webhook subscription object.
content:
application/json:
schema:
$ref: '#/components/schemas/webhook_subscription'
'404':
description: If the webhook or workspace does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- webhook
- basic: []
- api_key: []
put:
tags:
- Workspaces
description: >-
Updates the specified webhook subscription.
The following properties can be mutated:
* `description`
* `url`
* `secret`
* `active`
* `events`
The 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.
summary: Atlassian Update a webhook for a workspace
responses:
'200':
description: The webhook subscription object.
content:
application/json:
schema:
$ref: '#/components/schemas/webhook_subscription'
'403':
description: >-
If the authenticated user does not have permission to update the
webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the webhook or workspace does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- webhook
- basic: []
- api_key: []
parameters:
- name: uid
in: path
description: Installed webhook's ID
required: true
schema:
type: string
- name: workspace
in: path
description: |
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
required: true
schema:
type: string
/workspaces/{workspace}/members:
get:
tags:
- Workspaces
description: Returns all members of the requested workspace.
summary: Atlassian List users in a workspace
responses:
'200':
description: The list of users that are part of a workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_workspace_memberships'
'401':
description: The request wasn't authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- account
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:workspace:bitbucket
- read:user:bitbucket
parameters:
- name: workspace
in: path
description: |
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
required: true
schema:
type: string
/workspaces/{workspace}/members/{member}:
get:
tags:
- Workspaces
description: |-
Returns the workspace membership, which includes
a `User` object for the member and a `Workspace` object
for the requested workspace.
summary: Atlassian Get user membership for a workspace
responses:
'200':
description: The user that is part of a workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/workspace_membership'
'401':
description: The request wasn't authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: >-
A workspace cannot be found, or a user cannot be found, or the user
is not a a member of the workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- account
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:workspace:bitbucket
- read:user:bitbucket
parameters:
- name: member
in: path
description: Member's UUID or Atlassian ID.
required: true
schema:
type: string
- name: workspace
in: path
description: |
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
required: true
schema:
type: string
/workspaces/{workspace}/permissions:
get:
tags:
- Workspaces
description: >-
Returns the list of members in a workspace
and their permission levels.
Permission can be:
* `owner`
* `collaborator`
* `member`
**The `collaborator` role is being removed from the Bitbucket Cloud API.
For more information,
see the [deprecation
announcement](/cloud/bitbucket/deprecation-notice-collaborator-role/).**
**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](/cloud/bitbucket/announcement-breaking-change-workspace-membership/).**
Results may be further
[filtered](/cloud/bitbucket/rest/intro/#filtering) by
permission by adding the following query string parameters:
* `q=permission="owner"`
summary: Atlassian List user permissions in a workspace
responses:
'200':
description: >-
The list of users that are part of a workspace, along with their
permission.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_workspace_memberships'
examples:
response:
value:
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
'401':
description: The request wasn't authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
parameters:
- name: q
in: query
description: |2-
Query string to narrow down the response as per
[filtering and sorting](/cloud/bitbucket/rest/intro/#filtering).
required: false
schema:
type: string
security:
- oauth2:
- account
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:workspace:bitbucket
- read:user:bitbucket
parameters:
- name: workspace
in: path
description: |
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
required: true
schema:
type: string
/workspaces/{workspace}/permissions/repositories:
get:
tags:
- Workspaces
description: >-
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:
* `admin`
* `write`
* `read`
Results may be further [filtered or
sorted](/cloud/bitbucket/rest/intro/#filtering)
by repository, user, or permission by adding the following query string
parameters:
* `q=repository.name="geordi"` or `q=permission>"read"`
* `sort=user.display_name`
Note that the query parameter values need to be URL escaped so that `=`
would become `%3D`.
summary: Atlassian List all repository permissions for a workspace
responses:
'200':
description: List of workspace's repository permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_repository_permissions'
examples:
response:
value:
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
'403':
description: The requesting user isn't an admin of the workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
parameters:
- name: q
in: query
description: |2-
Query string to narrow down the response as per
[filtering and sorting](/cloud/bitbucket/rest/intro/#filtering).
required: false
schema:
type: string
- name: sort
in: query
description: >2
Name of a response property sort the result by as per
[filtering and
sorting](/cloud/bitbucket/rest/intro/#sorting-query-results).
required: false
schema:
type: string
security:
- oauth2:
- account
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:repository:bitbucket
- read:user:bitbucket
parameters:
- name: workspace
in: path
description: |
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
required: true
schema:
type: string
/workspaces/{workspace}/permissions/repositories/{repo_slug}:
get:
tags:
- Workspaces
description: >-
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:
* `admin`
* `write`
* `read`
Results may be further [filtered or
sorted](/cloud/bitbucket/rest/intro/#filtering)
by user, or permission by adding the following query string parameters:
* `q=permission>"read"`
* `sort=user.display_name`
Note that the query parameter values need to be URL escaped so that `=`
would become `%3D`.
summary: Atlassian List a repository permissions for a workspace
responses:
'200':
description: The repository permission for all users in this repository.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_repository_permissions'
examples:
response:
value:
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
'403':
description: The requesting user isn't an admin of the repository.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
parameters:
- name: q
in: query
description: |2-
Query string to narrow down the response as per
[filtering and sorting](/cloud/bitbucket/rest/intro/#filtering).
required: false
schema:
type: string
- name: sort
in: query
description: >2
Name of a response property sort the result by as per
[filtering and
sorting](/cloud/bitbucket/rest/intro/#sorting-query-results).
required: false
schema:
type: string
security:
- oauth2:
- repository
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:repository:bitbucket
- read:user:bitbucket
parameters:
- name: repo_slug
in: path
description: |
This can either be the repository slug or the UUID of the repository,
surrounded by curly-braces, for example: `{repository UUID}`.
required: true
schema:
type: string
- name: workspace
in: path
description: |
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: `{workspace UUID}`.
required: true
schema:
type: string
/workspaces/{workspace}/pipelines-config/identity/oidc/.well-known/openid-configuration:
get:
tags:
- Workspaces
summary: Atlassian Get OpenID configuration for OIDC in Pipelines
description: >-
This is part of OpenID Connect for Pipelines, see
https://support.atlassian.com/bitbucket-cloud/docs/integrate-pipelines-with-resource-servers-using-oidc/
operationId: getOIDCConfiguration
parameters:
- name: workspace
description: >-
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example `{workspace UUID}`.
required: true
in: path
schema:
type: string
responses:
'200':
description: The OpenID configuration
'404':
description: The workspace was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2: []
- basic: []
- api_key: []
/workspaces/{workspace}/pipelines-config/identity/oidc/keys.json:
get:
tags:
- Workspaces
summary: Atlassian Get keys for OIDC in Pipelines
description: >-
This is part of OpenID Connect for Pipelines, see
https://support.atlassian.com/bitbucket-cloud/docs/integrate-pipelines-with-resource-servers-using-oidc/
operationId: getOIDCKeys
parameters:
- name: workspace
description: >-
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example `{workspace UUID}`.
required: true
in: path
schema:
type: string
responses:
'200':
description: The keys in JSON web key format
'404':
description: The workspace was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2: []
- basic: []
- api_key: []
/workspaces/{workspace}/pipelines-config/variables:
get:
tags:
- Workspaces
summary: Atlassian List variables for a workspace
description: Find workspace level variables.
operationId: getPipelineVariablesForWorkspace
parameters:
- name: workspace
description: >-
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example `{workspace UUID}`.
required: true
in: path
schema:
type: string
responses:
'200':
description: The found workspace level variables.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_pipeline_variables'
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:pipeline:bitbucket
security:
- oauth2:
- pipeline
- basic: []
- api_key: []
post:
tags:
- Workspaces
summary: Atlassian Create a variable for a workspace
description: Create a workspace level variable.
operationId: createPipelineVariableForWorkspace
parameters:
- name: workspace
description: >-
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example `{workspace UUID}`.
required: true
in: path
schema:
type: string
requestBody:
$ref: '#/components/requestBodies/pipeline_variable2'
responses:
'201':
description: The created variable.
headers:
Location:
description: The URL of the newly created pipeline variable.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/pipeline_variable'
'404':
description: The workspace does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'409':
description: A variable with the provided key already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:pipeline:bitbucket
security:
- oauth2:
- pipeline:variable
- basic: []
- api_key: []
/workspaces/{workspace}/pipelines-config/variables/{variable_uuid}:
get:
tags:
- Workspaces
summary: Atlassian Get variable for a workspace
description: Retrieve a workspace level variable.
operationId: getPipelineVariableForWorkspace
parameters:
- name: workspace
description: >-
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example `{workspace UUID}`.
required: true
in: path
schema:
type: string
- name: variable_uuid
description: The UUID of the variable to retrieve.
required: true
in: path
schema:
type: string
responses:
'200':
description: The variable.
content:
application/json:
schema:
$ref: '#/components/schemas/pipeline_variable'
'404':
description: The workspace or variable with the given UUID was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:pipeline:bitbucket
security:
- oauth2:
- pipeline
- basic: []
- api_key: []
put:
tags:
- Workspaces
summary: Atlassian Update variable for a workspace
description: Update a workspace level variable.
operationId: updatePipelineVariableForWorkspace
parameters:
- name: workspace
description: >-
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example `{workspace UUID}`.
required: true
in: path
schema:
type: string
- name: variable_uuid
description: The UUID of the variable.
required: true
in: path
schema:
type: string
requestBody:
$ref: '#/components/requestBodies/pipeline_variable'
responses:
'200':
description: The variable was updated.
content:
application/json:
schema:
$ref: '#/components/schemas/pipeline_variable'
'404':
description: The workspace or the variable was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:pipeline:bitbucket
security:
- oauth2:
- pipeline:variable
- basic: []
- api_key: []
delete:
tags:
- Workspaces
summary: Atlassian Delete a variable for a workspace
description: Delete a workspace level variable.
operationId: deletePipelineVariableForWorkspace
parameters:
- name: workspace
description: >-
This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example `{workspace UUID}`.
required: true
in: path
schema:
type: string
- name: variable_uuid
description: The UUID of the variable to delete.
required: true
in: path
schema:
type: string
responses:
'204':
description: The variable was deleted
'404':
# --- truncated at 32 KB (256 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-workspaces--openapi-original.yml