Bitbucket Pipelines Projects API
Bitbucket Cloud projects make it easier for teams to focus on a goal, product, or process by organizing their repositories.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/bitbucket-pipelines-projects-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.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
servers:
- url: https://api.bitbucket.org/2.0
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
schema:
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.
headers:
Location:
description: The location of the newly created project
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/project'
'403':
description: The user requesting to create a project does not have the necessary permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: A workspace doesn't exist at this location.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
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
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/project'
required: true
/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
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
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.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: A project isn't hosted at this location.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
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.
content:
application/json:
schema:
$ref: '#/components/schemas/project'
'401':
description: The request wasn't authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: The requesting user isn't authorized to access the project.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: A project isn't hosted at this location.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
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.
headers:
Location:
description: 'The location of the project. This header is only provided
when the project key is updated.'
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/project'
'201':
description: A new project has been created.
headers:
Location:
description: The location of the newly created project
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/project'
'403':
description: The requesting user isn't authorized to update or create the project.
content:
application/json:
schema:
$ref: '#/components/schemas/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.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
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
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/project'
required: true
/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
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
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
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_default_reviewer_and_type'
example:
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
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the workspace or project does not exist at this location
content:
application/json:
schema:
$ref: '#/components/schemas/error'
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
schema:
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
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
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
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: If the authenticated user does not have admin access to the project
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the specified user, project, or workspace does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
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
content:
application/json:
schema:
$ref: '#/components/schemas/user'
example:
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
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: If the authenticated user does not have admin access to the project
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the specified user, project, or workspace does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
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
content:
application/json:
schema:
$ref: '#/components/schemas/user'
example:
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
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: If the authenticated user does not have admin access to the project
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the specified user, project, or workspace does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
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
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
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
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_project_group_permissions'
example:
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.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: The user doesn't have admin access to the project.
content:
application/json:
schema:
$ref: '#/components/schemas/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
content:
application/json:
schema:
$ref: '#/components/schemas/error'
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
schema:
type: string
- name: project_key
in: path
description: 'The project in question. This is the actual key assigned to the project.
'
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
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.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: The requesting user isn't an admin of the project, or the authentication method was not via app password.
content:
application/json:
schema:
$ref: '#/components/schemas/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
content:
application/json:
schema:
$ref: '#/components/schemas/error'
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
content:
application/json:
schema:
$ref: '#/components/schemas/project_group_permission'
example:
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.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: The user doesn't have admin access to the project.
content:
application/json:
schema:
$ref: '#/components/schemas/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
content:
application/json:
schema:
$ref: '#/components/schemas/error'
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.
content:
application/json:
schema:
$ref: '#/components/schemas/project_group_permission'
example:
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).
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'401':
description: The user couldn't be authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'402':
description: You have reached your plan's user limit and must upgrade before giving access to additional users.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: The requesting user isn't an admin of the project, or the authentication method was not via app password.
content:
application/json:
schema:
$ref: '#/components/schemas/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
content:
application/json:
schema:
$ref: '#/components/schemas/error'
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
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/bitbucket.apps.permissions.serializers.ProjectPermissionUpdateSchema'
description: The permission to grant
required: true
/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
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
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.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_project_user_permissions'
example:
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.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: The user doesn't have admin access to the project.
content:
application/json:
schema:
$ref: '#/components/schemas/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
content:
application/json:
schema:
$ref: '#/components/schemas/error'
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
schema:
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
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
delete:
tags:
- Projects
description: 'Deletes the project user pe
# --- truncated at 32 KB (172 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bitbucket-pipelines/refs/heads/main/openapi/bitbucket-pipelines-projects-api-openapi.yml