Bitbucket Pipelines Projects API
Bitbucket Cloud projects make it easier for teams to focus on a goal, product, or process by organizing their repositories.
OpenAPI Specification
swagger: '2.0'
info:
title: Bitbucket Addon Projects API
description: Code against the Bitbucket API to automate simple tasks, embed Bitbucket data into your own site, build mobile or desktop apps, or even add custom UI add-ons into Bitbucket itself using the Connect framework.
version: '2.0'
termsOfService: https://www.atlassian.com/legal/customer-agreement
contact:
name: Bitbucket Support
url: https://support.atlassian.com/bitbucket-cloud/
email: support@bitbucket.org
host: api.bitbucket.org
basePath: /2.0
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Projects
description: 'Bitbucket Cloud projects make it easier for teams to focus on
a goal, product, or process by organizing their repositories.
'
paths:
/workspaces/{workspace}/projects:
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
type: string
post:
tags:
- Projects
description: "Creates a new project.\n\nNote that the avatar has to be embedded as either a data-url\nor a URL to an external image as shown in the examples below:\n\n```\n$ body=$(cat << EOF\n{\n \"name\": \"Mars Project\",\n \"key\": \"MARS\",\n \"description\": \"Software for colonizing mars.\",\n \"links\": {\n \"avatar\": {\n \"href\": \"data:image/gif;base64,R0lGODlhEAAQAMQAAORHHOVSKudfOulrSOp3WOyDZu6QdvCchPGolfO0o/...\"\n }\n },\n \"is_private\": false\n}\nEOF\n)\n$ curl -H \"Content-Type: application/json\" \\\n -X POST \\\n -d \"$body\" \\\n https://api.bitbucket.org/2.0/workspaces/teams-in-space/projects/ | jq .\n{\n // Serialized project document\n}\n```\n\nor even:\n\n```\n$ body=$(cat << EOF\n{\n \"name\": \"Mars Project\",\n \"key\": \"MARS\",\n \"description\": \"Software for colonizing mars.\",\n \"links\": {\n \"avatar\": {\n \"href\": \"http://i.imgur.com/72tRx4w.gif\"\n }\n },\n \"is_private\": false\n}\nEOF\n)\n$ curl -H \"Content-Type: application/json\" \\\n -X POST \\\n -d \"$body\" \\\n https://api.bitbucket.org/2.0/workspaces/teams-in-space/projects/ | jq .\n{\n // Serialized project document\n}\n```"
summary: Create a project in a workspace
responses:
'201':
description: A new project has been created.
schema:
$ref: '#/definitions/project'
headers:
Location:
type: string
description: The location of the newly created project
'403':
description: The user requesting to create a project does not have the necessary permissions.
schema:
$ref: '#/definitions/error'
'404':
description: A workspace doesn't exist at this location.
schema:
$ref: '#/definitions/error'
parameters:
- name: _body
in: body
required: true
schema:
$ref: '#/definitions/project'
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:project:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
/workspaces/{workspace}/projects/{project_key}:
parameters:
- name: project_key
in: path
description: 'The project in question. This is the actual `key` assigned
to the project.
'
required: true
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
type: string
delete:
tags:
- Projects
description: 'Deletes this project. This is an irreversible operation.
You cannot delete a project that still contains repositories.
To delete the project, [delete](/cloud/bitbucket/rest/api-group-repositories/#api-repositories-workspace-repo-slug-delete)
or transfer the repositories first.
Example:
```
$ curl -X DELETE https://api.bitbucket.org/2.0/workspaces/bbworkspace1/projects/PROJ
```'
summary: Delete a project for a workspace
responses:
'204':
description: Successful deletion.
'403':
description: The requesting user isn't authorized to delete the project or the project isn't empty.
schema:
$ref: '#/definitions/error'
'404':
description: A project isn't hosted at this location.
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:project:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
get:
tags:
- Projects
description: Returns the requested project.
summary: Get a project for a workspace
responses:
'200':
description: The project that is part of a workspace.
schema:
$ref: '#/definitions/project'
'401':
description: The request wasn't authenticated.
schema:
$ref: '#/definitions/error'
'403':
description: The requesting user isn't authorized to access the project.
schema:
$ref: '#/definitions/error'
'404':
description: A project isn't hosted at this location.
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- project
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:project:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
put:
tags:
- Projects
description: 'Since this endpoint can be used to both update and to create a
project, the request body depends on the intent.
#### Creation
See the POST documentation for the project collection for an
example of the request body.
Note: The `key` should not be specified in the body of request
(since it is already present in the URL). The `name` is required,
everything else is optional.
#### Update
See the POST documentation for the project collection for an
example of the request body.
Note: The key is not required in the body (since it is already in
the URL). The key may be specified in the body, if the intent is
to change the key itself. In such a scenario, the location of the
project is changed and is returned in the `Location` header of the
response.'
summary: Update a project for a workspace
responses:
'200':
description: The existing project is has been updated.
schema:
$ref: '#/definitions/project'
headers:
Location:
type: string
description: 'The location of the project. This header is only provided
when the project key is updated.'
'201':
description: A new project has been created.
schema:
$ref: '#/definitions/project'
headers:
Location:
type: string
description: The location of the newly created project
'403':
description: The requesting user isn't authorized to update or create the project.
schema:
$ref: '#/definitions/error'
'404':
description: A workspace doesn't exist at the location. Note that the project's absence from this location doesn't raise a 404, since a PUT at a non-existent location can be used to create a new project.
schema:
$ref: '#/definitions/error'
parameters:
- name: _body
in: body
required: true
schema:
$ref: '#/definitions/project'
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:project:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
/workspaces/{workspace}/projects/{project_key}/default-reviewers:
parameters:
- name: project_key
in: path
description: 'The project in question. This is the actual `key` assigned
to the project.
'
required: true
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
type: string
get:
tags:
- Projects
description: 'Return a list of all default reviewers for a project. This is a list of users that will be added as default
reviewers to pull requests for any repository within the project.'
summary: List the default reviewers in a project
responses:
'200':
description: The list of project default reviewers
schema:
$ref: '#/definitions/paginated_default_reviewer_and_type'
examples:
application/json:
pagelen: 10
values:
- user:
display_name: Davis Lee
uuid: '{f0e0e8e9-66c1-4b85-a784-44a9eb9ef1a6}'
reviewer_type: project
type: default_reviewer
- user:
display_name: Jorge Rodriguez
uuid: '{1aa43376-260d-4a0b-9660-f62672b9655d}'
reviewer_type: project
type: default_reviewer
page: 1
size: 2
'403':
description: If the authenticated user does not have admin access to the project
schema:
$ref: '#/definitions/error'
'404':
description: If the workspace or project does not exist at this location
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:pullrequest:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
/workspaces/{workspace}/projects/{project_key}/default-reviewers/{selected_user}:
parameters:
- name: project_key
in: path
description: 'The project in question. This can either be the actual `key` assigned
to the project or the `UUID` (surrounded by curly-braces (`{}`)).
'
required: true
type: string
- name: selected_user
in: path
description: 'This can either be the username or the UUID of the default reviewer,
surrounded by curly-braces, for example: `{account UUID}`.
'
required: true
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
type: string
delete:
tags:
- Projects
description: 'Removes a default reviewer from the project.
Example:
```
$ curl https://api.bitbucket.org/2.0/.../default-reviewers/%7Bf0e0e8e9-66c1-4b85-a784-44a9eb9ef1a6%7D
HTTP/1.1 204
```'
summary: Remove the specific user from the project's default reviewers
responses:
'204':
description: The specified user was removed from the list of project default reviewers
'400':
description: If the specified user is not a default reviewer for the project
schema:
$ref: '#/definitions/error'
'403':
description: If the authenticated user does not have admin access to the project
schema:
$ref: '#/definitions/error'
'404':
description: If the specified user, project, or workspace does not exist
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:project:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
get:
tags:
- Projects
description: Returns the specified default reviewer.
summary: Get a default reviewer
responses:
'200':
description: The specified user that is a default reviewer
schema:
$ref: '#/definitions/user'
examples:
application/json:
display_name: Davis Lee
type: user
uuid: '{f0e0e8e9-66c1-4b85-a784-44a9eb9ef1a6}'
'400':
description: If the specified user is not a default reviewer for the project
schema:
$ref: '#/definitions/error'
'403':
description: If the authenticated user does not have admin access to the project
schema:
$ref: '#/definitions/error'
'404':
description: If the specified user, project, or workspace does not exist
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:pullrequest:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
put:
tags:
- Projects
description: 'Adds the specified user to the project''s list of default reviewers. The method is
idempotent. Accepts an optional body containing the `uuid` of the user to be added.'
summary: Add the specific user as a default reviewer for the project
responses:
'200':
description: The specified user was added as a project default reviewer
schema:
$ref: '#/definitions/user'
examples:
application/json:
display_name: Yaniv Sagy
links:
self:
href: https://api.bitbucket.org/2.0/users/%7Bdd5db7f2-6389-458d-a62a-716773910b7a%7D
avatar:
href: https://secure.gravatar.com/avatar/YS-2.png
html:
href: https://api.bitbucket.org/%7Bdd5db7f2-6389-458d-a62a-716773910b7a%7D/
type: user
uuid: '{dd5db7f2-6389-458d-a62a-716773910b7a}'
account_id: 712020:4efe52fa-b4b4-475b-9eb0-c0a23b7eb194
nickname: Yaniv Sagy
'400':
description: If the specified user cannot be added as a default reviewer for the project
schema:
$ref: '#/definitions/error'
'403':
description: If the authenticated user does not have admin access to the project
schema:
$ref: '#/definitions/error'
'404':
description: If the specified user, project, or workspace does not exist
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:project:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
/workspaces/{workspace}/projects/{project_key}/permissions-config/groups:
parameters:
- name: project_key
in: path
description: 'The project in question. This is the actual key assigned to the project.
'
required: true
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
type: string
get:
tags:
- Projects
description: 'Returns a paginated list of explicit group permissions for the given project.
This endpoint does not support BBQL features.'
summary: List explicit group permissions for a project
responses:
'200':
description: Paginated list of project group permissions
schema:
$ref: '#/definitions/paginated_project_group_permissions'
examples:
application/json:
pagelen: 10
values:
- type: project_group_permission
group:
type: group
name: Administrators
slug: administrators
permission: admin
links:
self:
href: https://api.bitbucket.org/2.0/workspaces/atlassian_tutorial/projects/PRJ/permissions-config/groups/557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
- type: project_group_permission
group:
type: group
name: Developers
slug: developers
permission: write
links:
self:
href: https://api.bitbucket.org/2.0/workspaces/atlassian_tutorial/projects/PRJ/permissions-config/groups/557058:ba8948b2-49da-43a9-9e8b-e7249b8e324c
page: 1
size: 2
'401':
description: The user couldn't be authenticated.
schema:
$ref: '#/definitions/error'
'403':
description: The user doesn't have admin access to the project.
schema:
$ref: '#/definitions/error'
'404':
description: One or both of the workspace and project don't exist for the given identifiers or the requesting user is not authenticated
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:project:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
/workspaces/{workspace}/projects/{project_key}/permissions-config/groups/{group_slug}:
parameters:
- name: group_slug
in: path
description: Slug of the requested group.
required: true
type: string
- name: project_key
in: path
description: 'The project in question. This is the actual key assigned to the project.
'
required: true
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
type: string
delete:
tags:
- Projects
description: 'Deletes the project group permission between the requested project and group, if one exists.
Only users with admin permission for the project may access this resource.'
summary: Delete an explicit group permission for a project
responses:
'204':
description: The project group permission was deleted and no content returned.
'401':
description: The user couldn't be authenticated.
schema:
$ref: '#/definitions/error'
'403':
description: The requesting user isn't an admin of the project, or the authentication method was not via app password.
schema:
$ref: '#/definitions/error'
'404':
description: One or more of the workspace, project, and group doesn't exist for the given identifiers or the requesting user is not authenticated
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:project:bitbucket
- delete:permission:bitbucket
x-atlassian-auth-types:
- api-token
get:
tags:
- Projects
description: 'Returns the group permission for a given group and project.
Only users with admin permission for the project may access this resource.
Permissions can be:
* `admin`
* `create-repo`
* `write`
* `read`
* `none`'
summary: Get an explicit group permission for a project
responses:
'200':
description: Project group permission
schema:
$ref: '#/definitions/project_group_permission'
examples:
application/json:
type: project_group_permission
group:
type: group
name: Administrators
slug: administrators
permission: admin
links:
self:
href: https://api.bitbucket.org/2.0/workspaces/atlassian_tutorial/projects/PRJ/permissions-config/groups/administrators
'401':
description: The user couldn't be authenticated.
schema:
$ref: '#/definitions/error'
'403':
description: The user doesn't have admin access to the project.
schema:
$ref: '#/definitions/error'
'404':
description: One or more of the workspace, project, and group doesn't exist for the given identifiers or the requesting user is not authenticated
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:project:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
put:
tags:
- Projects
description: 'Updates the group permission, or grants a new permission if one does not already exist.
Only users with admin permission for the project may access this resource.
Due to security concerns, the JWT and OAuth authentication methods are unsupported.
This is to ensure integrations and add-ons are not allowed to change permissions.
Permissions can be:
* `admin`
* `create-repo`
* `write`
* `read`'
summary: Update an explicit group permission for a project
responses:
'200':
description: Project group permission updated.
schema:
$ref: '#/definitions/project_group_permission'
examples:
application/json:
type: project_group_permission
group:
type: group
name: Administrators
slug: administrators
permission: write
links:
self:
href: https://api.bitbucket.org/2.0/workspaces/atlassian_tutorial/projects/PRJ/permissions-config/groups/administrators
'400':
description: No permission value was provided or the value is invalid(not one of read, write, create-repo, or admin).
schema:
$ref: '#/definitions/error'
'401':
description: The user couldn't be authenticated.
schema:
$ref: '#/definitions/error'
'402':
description: You have reached your plan's user limit and must upgrade before giving access to additional users.
schema:
$ref: '#/definitions/error'
'403':
description: The requesting user isn't an admin of the project, or the authentication method was not via app password.
schema:
$ref: '#/definitions/error'
'404':
description: One or more of the workspace, project, and group doesn't exist for the given identifiers or the requesting user is not authenticated
schema:
$ref: '#/definitions/error'
parameters:
- name: _body
in: body
description: The permission to grant
required: true
schema:
$ref: '#/definitions/bitbucket.apps.permissions.serializers.ProjectPermissionUpdateSchema'
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:project:bitbucket
- write:permission:bitbucket
x-atlassian-auth-types:
- api-token
/workspaces/{workspace}/projects/{project_key}/permissions-config/users:
parameters:
- name: project_key
in: path
description: 'The project in question. This is the actual key assigned to the project.
'
required: true
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
type: string
get:
tags:
- Projects
description: 'Returns a paginated list of explicit user permissions for the given project.
This endpoint does not support BBQL features.'
summary: List explicit user permissions for a project
responses:
'200':
description: Paginated list of explicit user permissions.
schema:
$ref: '#/definitions/paginated_project_user_permissions'
examples:
application/json:
pagelen: 10
values:
- type: project_user_permission
user:
type: user
display_name: Colin Cameron
uuid: '{d301aafa-d676-4ee0-88be-962be7417567}'
account_id: 557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
permission: admin
links:
self:
href: https://api.bitbucket.org/2.0/workspaces/atlassian_tutorial/projects/PRJ/permissions-config/users/557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
- type: project_user_permission
user:
type: user
display_name: Sean Conaty
uuid: '{504c3b62-8120-4f0c-a7bc-87800b9d6f70}'
account_id: 557058:ba8948b2-49da-43a9-9e8b-e7249b8e324c
permission: write
links:
self:
href: https://api.bitbucket.org/2.0/workspaces/atlassian_tutorial/projects/PRJ/permissions-config/users/557058:ba8948b2-49da-43a9-9e8b-e7249b8e324c
page: 1
size: 2
'401':
description: The user couldn't be authenticated.
schema:
$ref: '#/definitions/error'
'403':
description: The user doesn't have admin access to the project.
schema:
$ref: '#/definitions/error'
'404':
description: One or both of the workspace and project don't exist for the given identifiers or the requesting user is not authenticated
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:project:bitbucket
x-atlassian-auth-types:
- forge-oauth2
- api-token
/workspaces/{workspace}/projects/{project_key}/permissions-config/users/{selected_user_id}:
parameters:
- name: project_key
in: path
description: 'The project in question. This is the actual key assigned to the project.
'
required: true
type: string
- name: selected_user_id
in: path
description: 'This can either be the username, the user''s UUID surrounded by curly-braces,
for example: {account UUID}, or the user''s Atlassian ID.
'
required: true
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
type: string
delete:
tags:
- Projects
description: 'Deletes the project user permission between the requested project and user, if one exists.
Only users with admin permission for the project may access this resource.
Due to security concerns, the JWT and OAuth authentication methods are unsupported.
This is to ensure integrations and add-ons are not allowed to change permissions.'
summary: Delete an explicit user permission for a project
responses:
'204':
description: The project user permission was deleted and no content returned.
'401':
description: The user couldn't be authenticated.
schema:
$ref: '#/definitions/error'
'403':
description: The requesting user isn't an admin of the project, or the authentication method was not via app password.
schema:
$ref: '#/definitions/error'
'404':
description: One or more of the workspace, project, and selected user doesn't exist for the given identifiers or the requesting user is not authenticated
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:project:bitbucket
- delete:permission:bitbucket
x-atlassian-auth-types:
- api-token
get:
tags:
- Projects
description: 'Returns the explicit user permission for a given user and project.
Only users with admin permission for the project may access this resource.
Permissions can be:
* `admin`
* `create-repo`
* `write`
* `read`
* `none`'
summary: Get an explicit user permission for a project
responses:
'200':
description: Explicit user permission for user and project
schema:
$ref: '#/definitions/project_user_permission'
examples:
application/json:
type: project_user_permission
user:
type: user
display_name: Colin Cameron
uuid: '{d301aafa-d676-4ee0-88be-962be7417567}'
account_id: 557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
permission: admin
links:
self:
href: https://api.bitbucket.org/2.0/workspaces/atlassian_tutorial/projects/PRJ/permissions-config/users/557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
'401':
description: The user couldn't be authenticated.
schema:
$ref: '#/definitions/error'
'403':
description: The requesting user isn't an admin of the project.
schema:
$ref: '#/definitions/error'
'404':
description: One or more of the workspace, project, and selected user doesn't exist for the given identifiers or the requesting user is not authenticated
schema:
$ref: '#/definitions/error'
parameters: []
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
# --- truncated at 32 KB (166 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bitbucket-pipelines/refs/heads/main/openapi/bitbucket-pipelines-projects-api-openapi.yml