Atlassian Bitbucket Repositories API
The Atlassian Bitbucket Repositories API allows users to interact with and manage repositories in their Bitbucket accounts programmatically.
OpenAPI Specification
openapi: 3.0.0
info:
title: 'Atlassian repositories/'
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:
/repositories/{workspace}:
get:
tags:
- Repositories
description: >-
Returns a paginated list of all repositories owned by the
specified<br>workspace.<br><br>The result can be narrowed down based on
the authenticated user's role.<br><br>E.g. with `?role=contributor`,
only those repositories that the<br>authenticated user has write access
to are returned (this includes any<br>repo the user is an admin on, as
that implies write access).<br><br>This endpoint also supports filtering
and sorting of the results. See<br>[filtering and
sorting](/cloud/bitbucket/rest/intro/#filtering) for more details.
summary: Atlassian List Repositories In A Workspace
responses:
'200':
description: The repositories owned by the specified account.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_repositories'
'404':
description: If the specified account does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'410':
description: If the specified account marked as spam.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
parameters:
- name: role
in: query
description: >2
Filters the result based on the authenticated user's role on each
repository.
* **member**: returns repositories to which the user has explicit
read access
* **contributor**: returns repositories to which the user has
explicit write access
* **admin**: returns repositories to which the user has explicit
administrator access
* **owner**: returns all repositories owned by the current user
required: false
schema:
type: string
enum:
- admin
- contributor
- member
- owner
- 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-
Field by which the results should be sorted as per [filtering and
sorting](/cloud/bitbucket/rest/intro/#filtering).
required: false
schema:
type: string
security:
- oauth2:
- repository
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:repository:bitbucket
operationId: atlassianListRepositoriesInAWorkspace
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
/repositories/{workspace}/{repo_slug}:
delete:
tags:
- Repositories
description: >-
Deletes the repository. This is an irreversible operation.<br><br>This
does not affect its forks.
summary: Atlassian Delete A Repository
responses:
'204':
description: Indicates successful deletion.
'403':
description: >-
If the caller either does not have admin access to the repository,
or the repository is set to read-only.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the repository does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
parameters:
- name: redirect_to
in: query
description: >
If a repository has been moved to a new location, use this parameter
to
show users a friendly message in the Bitbucket UI that the
repository
has moved to a new location. However, a GET to this endpoint will
still
return a 404.
required: false
schema:
type: string
security:
- oauth2:
- repository:delete
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- delete:repository:bitbucket
operationId: atlassianDeleteARepository
get:
tags:
- Repositories
description: Returns the object describing this repository.
summary: Atlassian Get A Repository
responses:
'200':
description: The repository object.
content:
application/json:
schema:
$ref: '#/components/schemas/repository'
'403':
description: >-
If the repository is private and the authenticated user does not
have access to it.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If no repository exists at this location.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- repository
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:repository:bitbucket
operationId: atlassianGetARepository
post:
tags:
- Repositories
description: >-
Creates a new repository.<br><br>Note: In order to set the project for
the newly created repository,<br>pass in either the project key or the
project UUID as part of the<br>request body as shown in the examples
below:<br><br>```<br>$ curl -X POST -H "Content-Type: application/json"
-d '{<br> "scm": "git",<br> "project": {<br> "key":
"MARS"<br> }<br>}'
https://api.bitbucket.org/2.0/repositories/teamsinspace/hablanding<br>```<br><br>or<br><br>```<br>$
curl -X POST -H "Content-Type: application/json" -d '{<br> "scm":
"git",<br> "project": {<br> "key":
"{ba516952-992a-4c2d-acbd-17d502922f96}"<br> }<br>}'
https://api.bitbucket.org/2.0/repositories/teamsinspace/hablanding<br>```<br><br>The
project must be assigned for all repositories. If the project is not
provided,<br>the repository is automatically assigned to the oldest
project in the workspace.<br><br>Note: In the examples above, the
workspace ID `teamsinspace`,<br>and/or the repository name `hablanding`
can be replaced by UUIDs.
summary: Atlassian Create A Repository
responses:
'200':
description: The newly created repository.
content:
application/json:
schema:
$ref: '#/components/schemas/repository'
'400':
description: >-
If the input document was invalid, or if the caller lacks the
privilege to create repositories under the targeted account.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'401':
description: If the request was not authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/repository'
description: >-
The repository that is to be created. Note that most object elements
are optional. Elements "owner" and "full_name" are ignored as the URL
implies them.
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:repository:bitbucket
operationId: atlassianCreateARepository
put:
tags:
- Repositories
description: >-
Since this endpoint can be used to both update and to create
a<br>repository, the request body depends on the intent.<br><br>####
Creation<br><br>See the POST documentation for the repository endpoint
for an example<br>of the request body.<br><br>#### Update<br><br>Note:
Changing the `name` of the repository will cause the location to<br>be
changed. This is because the URL of the repo is derived from the<br>name
(a process called slugification). In such a scenario, it is<br>possible
for the request to fail if the newly created slug conflicts<br>with an
existing repository's slug. But if there is no conflict,<br>the new
location will be returned in the `Location` header of the<br>response.
summary: Atlassian Update A Repository
responses:
'200':
description: The existing repository has been updated
headers:
Location:
description: |-
The location of the repository. This header is only
provided when the repository's name is changed.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/repository'
'201':
description: A new repository has been created
headers:
Location:
description: The location of the newly created repository
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/repository'
'400':
description: >-
If the input document was invalid, or if the caller lacks the
privilege to create repositories under the targeted account.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'401':
description: If the request was not authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/repository'
description: |
The repository that is to be updated.
Note that the elements "owner" and "full_name" are ignored since the
URL implies them.
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:repository:bitbucket
operationId: atlassianUpdateARepository
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
/repositories/{workspace}/{repo_slug}/branch-restrictions:
get:
tags:
- Branch Restrictions
description: >-
Returns a paginated list of all branch restrictions on
the<br>repository.
summary: Atlassian List Branch Restrictions
responses:
'200':
description: A paginated list of branch restrictions
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_branchrestrictions'
'401':
description: If the request was not authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: >-
If the authenticated user does not have admin access to the
repository
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the repository does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
parameters:
- name: kind
in: query
description: Branch restrictions of this type
required: false
schema:
type: string
- name: pattern
in: query
description: Branch restrictions applied to branches of this pattern
required: false
schema:
type: string
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:repository:bitbucket
operationId: atlassianListBranchRestrictions
post:
tags:
- Branch Restrictions
description: >-
Creates a new branch restriction rule for a repository.<br><br>`kind`
describes what will be restricted. Allowed values include:<br>`push`,
`force`, `delete`, `restrict_merges`,
`require_tasks_to_be_completed`,<br>`require_approvals_to_merge`,
`require_default_reviewer_approvals_to_merge`,<br>`require_no_changes_requested`,
`require_passing_builds_to_merge`,
`require_commits_behind`,<br>`reset_pullrequest_approvals_on_change`,
`smart_reset_pullrequest_approvals`,<br>`reset_pullrequest_changes_requested_on_change`,
`require_all_dependencies_merged`,<br>`enforce_merge_checks`, and
`allow_auto_merge_when_builds_pass`.<br><br>Different kinds of branch
restrictions have different requirements:<br><br>* `push` and
`restrict_merges` require `users` and `groups` to be<br> specified.
Empty lists are allowed, in which case permission is<br> denied for
everybody.<br><br>The restriction applies to all branches that match.
There are<br>two ways to match a branch. It is configured in
`branch_match_kind`:<br><br>1. `glob`: Matches a branch against the
`pattern`. A `'*'` in<br> `pattern` will expand to match zero or more
characters, and every<br> other character matches itself. For example,
`'foo*'` will match<br> `'foo'` and `'foobar'`, but not `'barfoo'`.
`'*'` will match all<br> branches.<br>2. `branching_model`: Matches a
branch against the repository's<br> branching model. The `branch_type`
controls the type of branch<br> to match. Allowed values include:
`production`, `development`,<br> `bugfix`, `release`, `feature` and
`hotfix`.<br><br>The combination of `kind` and match must be unique.
This means that<br>two `glob` restrictions in a repository cannot have
the same `kind` and<br>`pattern`. Additionally, two `branching_model`
restrictions in a<br>repository cannot have the same `kind` and
`branch_type`.<br><br>`users` and `groups` are lists of users and groups
that are except from<br>the restriction. They can only be configured in
`push` and<br>`restrict_merges` restrictions. The `push` restriction
stops a user<br>pushing to matching branches unless that user is in
`users` or is a<br>member of a group in `groups`. The `restrict_merges`
stops a user<br>merging pull requests to matching branches unless that
user is in<br>`users` or is a member of a group in `groups`. Adding new
users or<br>groups to an existing restriction should be done via
`PUT`.<br><br>Note that branch restrictions with overlapping matchers is
allowed,<br>but the resulting behavior may be surprising.
summary: Atlassian Create A Branch Restriction Rule
responses:
'201':
description: A paginated list of branch restrictions
content:
application/json:
schema:
$ref: '#/components/schemas/branchrestriction'
'401':
description: If the request was not authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: >-
If the authenticated user does not have admin access to the
repository
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the repository does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/branchrestriction'
description: The new rule
required: true
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:repository:bitbucket
operationId: atlassianCreateABranchRestrictionRule
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
/repositories/{workspace}/{repo_slug}/branch-restrictions/{id}:
delete:
tags:
- Branch Restrictions
description: Deletes an existing branch restriction rule.
summary: Atlassian Delete A Branch Restriction Rule
responses:
'204':
description: ''
'401':
description: If the request was not authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: >-
If the authenticated user does not have admin access to the
repository
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the repository or branch restriction id does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:repository:bitbucket
operationId: atlassianDeleteABranchRestrictionRule
get:
tags:
- Branch Restrictions
description: Returns a specific branch restriction rule.
summary: Atlassian Get A Branch Restriction Rule
responses:
'200':
description: The branch restriction rule
content:
application/json:
schema:
$ref: '#/components/schemas/branchrestriction'
'401':
description: If the request was not authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: >-
If the authenticated user does not have admin access to the
repository
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the repository or branch restriction id does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:repository:bitbucket
operationId: atlassianGetABranchRestrictionRule
put:
tags:
- Branch Restrictions
description: >-
Updates an existing branch restriction rule.<br><br>Fields not present
in the request body are ignored.<br><br>See
[`POST`](/cloud/bitbucket/rest/api-group-branch-restrictions/#api-repositories-workspace-repo-slug-branch-restrictions-post)
for details.
summary: Atlassian Update A Branch Restriction Rule
responses:
'200':
description: The updated branch restriction rule
content:
application/json:
schema:
$ref: '#/components/schemas/branchrestriction'
'401':
description: If the request was not authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: >-
If the authenticated user does not have admin access to the
repository
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the repository or branch restriction id does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/branchrestriction'
description: The new version of the existing rule
required: true
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:repository:bitbucket
operationId: atlassianUpdateABranchRestrictionRule
parameters:
- name: id
in: path
description: The restriction rule's id
required: true
schema:
type: string
- 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
/repositories/{workspace}/{repo_slug}/branching-model:
get:
tags:
- Branching Model
description: >-
Return the branching model as applied to the repository. This view
is<br>read-only. The branching model settings can be changed using
the<br>[settings](#api-repositories-workspace-repo-slug-branching-model-settings-get)
API.<br><br>The returned object:<br><br>1. Always has a `development`
property. `development.branch` contains<br> the actual repository
branch object that is considered to be the<br> `development` branch.
`development.branch` will not be present<br> if it does not
exist.<br>2. Might have a `production` property. `production` will
not<br> be present when `production` is disabled.<br> `production.branch` contains the actual branch object that is<br> considered to be the `production` branch. `production.branch` will<br> not be present if it does not exist.<br>3. Always has a `branch_types`
array which contains all enabled branch<br> types.
summary: Atlassian Get The Branching Model For A Repository
responses:
'200':
description: The branching model object
content:
application/json:
schema:
$ref: '#/components/schemas/branching_model'
examples:
response:
value:
development:
name: master
branch:
type: branch
name: master
target:
hash: 16dffcb0de1b22e249db6799532074cf32efe80f
use_mainbranch: true
production:
name: production
branch:
type: branch
name: production
target:
hash: 16dffcb0de1b22e249db6799532074cf32efe80f
use_mainbranch: false
branch_types:
- kind: release
prefix: release/
- kind: hotfix
prefix: hotfix/
- kind: feature
prefix: feature/
- kind: bugfix
prefix: bugfix/
type: branching_model
links:
self:
href: https://api.bitbucket.org/.../branching-model
'401':
description: If the request was not authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: >-
If the authenticated user does not have read access to the
repository
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the repository does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- repository
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:repository:bitbucket
operationId: atlassianGetTheBranchingModelForARepository
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
/repositories/{workspace}/{repo_slug}/branching-model/settings:
get:
tags:
- Branching Model
description: >-
Return the branching model configuration for a repository. The
returned<br>object:<br><br>1. Always has a `development` property for
the development branch.<br>2. Always a `production` property for the
production branch. The<br> production branch can be disabled.<br>3.
The `branch_types` contains all the branch types.<br><br>This is the raw
configuration for the branching model. A client<br>wishing to see the
branching model with its actual current branches may<br>find the [active
model
API](/cloud/bitbucket/rest/api-group-branching-model/#api-repositories-workspace-repo-slug-branching-model-get)
more useful.
summary: Atlassian Get The Branching Model Config For A Repository
responses:
'200':
description: The branching model configuration
content:
application/json:
schema:
$ref: '#/components/schemas/branching_model_settings'
examples:
response:
value:
development:
is_valid: true
name: 'null'
use_mainbranch: true
production:
is_valid: true
name: production
use_mainbranch: false
enabled: false
branch_types:
- kind: release
enabled: true
prefix: release/
- kind: hotfix
enabled: true
prefix: hotfix/
- kind: feature
enabled: true
prefix: feature/
- kind: bugfix
enabled: false
prefix: bugfix/
type: branching_model_settings
links:
self:
href: https://api.bitbucket.org/.../branching-model/settings
'401':
description: If the request was not authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: >-
If the authenticated user does not have admin access to the
repository
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: If the repository does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- admin:repository:bitbucket
operationId: atlassianGetTheBranchingModelConfigForARepository
put:
tags:
- Branching Model
description: >-
Update the branching model configuration for a repository.<br><br>The
`development` branch can be configured to a specific branch or
to<br>track the main branch. When set to a specific branch it
must<br>currently exist. Only the passed properties will be updated.
The<br>properties not passed will be left unchanged. A request without
a<br>`development` property will leave the development branch
unchanged.<br><br>It is possible for the `development` branch to be
invalid. This<br>happens when it points at a specific branch that has
been<br>deleted. This is indicated in the `is_valid` field for the
branch. It is<br>not possible to update the settings for `development`
if that<br>would leave the branch in an invalid state. Such a request
will be<br>rejected.<br><br>The `production` branch can be a specific
branch, the main<br>branch or disabled. When set to a specific branch it
must currently<br>exist. The `ena
# --- truncated at 32 KB (754 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-repositories--openapi-original.yml