openapi: 3.0.0
info:
title: 'Atlassian user'
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: support@bitbucket.org
paths:
/repositories/{workspace}/{repo_slug}/permissions-config/users:
get:
tags:
- Repositories
description: >-
Returns a paginated list of explicit user permissions for the given
repository.
This endpoint does not support BBQL features.
summary: Atlassian List Explicit User Permissions For A Repository
responses:
'200':
description: Paginated of explicit user permissions on the repository.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_repository_user_permissions'
examples:
response:
value:
pagelen: 10
values:
- type: repository_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/repositories/atlassian_tutorial/geordi/permissions-config/users/557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
- type: repository_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//repositories/atlassian_tutorial/geordi/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 requesting user isn't an admin of the repository.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: No repository exists for the given repository slug and workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:repository:bitbucket
- read:user:bitbucket
operationId: atlassianListExplicitUserPermissionsForARepository
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}/permissions-config/users/{selected_user_id}:
delete:
tags:
- Repositories
description: >-
Deletes the repository user permission between the requested repository
and user, if one exists.
Only users with admin permission for the
repository may access this resource.
The only authentication
method for this endpoint is via app passwords.
summary: Atlassian Delete An Explicit User Permission For A Repository
responses:
'204':
description: The repository user 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 repository, 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, repository, and user doesn't exist for
the given identifiers.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
operationId: atlassianDeleteAnExplicitUserPermissionForARepository
get:
tags:
- Repositories
description: >-
Returns the explicit user permission for a given user and
repository.
Only users with admin permission for the repository
may access this resource.
Permissions can be:
*
`admin`
* `write`
* `read`
* `none`
summary: Atlassian Get An Explicit User Permission For A Repository
responses:
'200':
description: Explicit user permission for user and repository
content:
application/json:
schema:
$ref: '#/components/schemas/repository_user_permission'
examples:
response:
value:
type: repository_user_permission
user:
type: user
display_name: Colin Cameron
uuid: '{d301aafa-d676-4ee0-88be-962be7417567}'
account_id: 557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
nickname: Colin Cameron
permission: admin
links:
self:
href: >-
https://api.bitbucket.org/2.0/repositories/atlassian_tutorial/geordi/permissions-config/users/557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
'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 repository.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: >-
One or both of the workspace and repository doesn't exist for the
given identifiers.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: oauth2
scopes:
- read:repository:bitbucket
- read:user:bitbucket
operationId: atlassianGetAnExplicitUserPermissionForARepository
put:
tags:
- Repositories
description: >-
Updates the explicit user permission for a given user and repository.
The selected user must be a member of
the workspace, and cannot be
the workspace owner.
Only users with admin permission for the
repository may access this resource.
The only authentication
method for this endpoint is via app passwords.
Permissions can
be:
* `admin`
* `write`
* `read`
summary: Atlassian Update An Explicit User Permission For A Repository
responses:
'200':
description: Explicit user permission updated
content:
application/json:
schema:
$ref: '#/components/schemas/repository_user_permission'
examples:
response:
value:
type: repository_user_permission
user:
type: user
display_name: Colin Cameron
uuid: '{d301aafa-d676-4ee0-88be-962be7417567}'
account_id: 557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
nickname: Colin Cameron
permission: write
links:
self:
href: >-
https://api.bitbucket.org/2.0/repositories/atlassian_tutorial/geordi/permissions-config/users/557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
'400':
description: >-
No permission value was provided or the value is invalid (not one of
read, write, or admin), or the selected user is not a valid user to
update.
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 repository, 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, repository, and selected user doesn't
exist for the given identifiers.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
requestBody:
$ref: >-
#/components/requestBodies/bitbucket.apps.permissions.serializers.RepoPermissionUpdateSchema
security:
- oauth2:
- repository:admin
- basic: []
- api_key: []
operationId: atlassianUpdateAnExplicitUserPermissionForARepository
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: selected_user_id
in: path
description: >
This can either be the UUID of the account, surrounded by
curly-braces, for
example: `{account UUID}`, OR an Atlassian Account 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
/user:
get:
tags:
- Users
description: Returns the currently logged in user.
summary: Atlassian Get Current User
responses:
'200':
description: The current user.
content:
application/json:
schema:
$ref: '#/components/schemas/account'
'401':
description: When the request wasn't authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- account
- basic: []
- api_key: []
operationId: atlassianGetCurrentUser
parameters: []
/user/emails:
get:
tags:
- Users
description: >-
Returns all the authenticated user's email addresses. Both
confirmed
and unconfirmed.
summary: Atlassian List Email Addresses For Current User
responses:
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- email
- basic: []
- api_key: []
operationId: atlassianListEmailAddressesForCurrentUser
parameters: []
/user/emails/{email}:
get:
tags:
- Users
description: >-
Returns details about a specific one of the authenticated
user's
email addresses.
Details describe whether the address
has been confirmed by the user and
whether it is the user's primary
address or not.
summary: Atlassian Get An Email Address For Current User
responses:
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- email
- basic: []
- api_key: []
operationId: atlassianGetAnEmailAddressForCurrentUser
parameters:
- name: email
in: path
description: Email address of the user.
required: true
schema:
type: string
/user/permissions/repositories:
get:
tags:
- Repositories
description: >-
Returns an object for each repository the caller has explicit
access
to and their effective permission — the highest level of
permission the
caller has. This does not return public repositories
that the user was
not granted any specific permission in, and does
not distinguish between
explicit and implicit
privileges.
Permissions can be:
* `admin`
*
`write`
* `read`
Results may be further [filtered or
sorted](/cloud/bitbucket/rest/intro/#filtering) by
repository or
permission by adding the following query string
parameters:
*
`q=repository.name="geordi"` or `q=permission>"read"`
*
`sort=repository.name`
Note that the query parameter values need
to be URL escaped so that `=`
would become `%3D`.
summary: Atlassian List Repository Permissions For A User
responses:
'200':
description: >-
Repository permissions for the repositories a caller has explicit
access to.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_repository_permissions'
examples:
response:
value:
pagelen: 10
values:
- type: repository_permission
user:
type: user
nickname: evzijst
display_name: Erik van Zijst
uuid: '{d301aafa-d676-4ee0-88be-962be7417567}'
repository:
type: repository
name: geordi
full_name: bitbucket/geordi
uuid: '{85d08b4e-571d-44e9-a507-fa476535aa98}'
permission: admin
page: 1
size: 1
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/#filtering).
required: false
schema:
type: string
security:
- oauth2:
- account
- repository
- basic: []
- api_key: []
operationId: atlassianListRepositoryPermissionsForAUser
parameters: []
/user/permissions/workspaces:
get:
tags:
- Workspaces
description: >-
Returns an object for each workspace the caller is a member of,
and
their effective role - the highest level of privilege the caller
has.
If a user is a member of multiple groups with distinct roles,
only the
highest level is returned.
Permissions can
be:
* `owner`
* `collaborator`
* `member`
**The
`collaborator` role is being removed from the Bitbucket Cloud API. For
more information,
see the [deprecation
announcement](/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 or
sorted](/cloud/bitbucket/rest/intro/#filtering) by
workspace or
permission by adding the following query string parameters:
*
`q=workspace.slug="bbworkspace1"` or `q=permission="owner"`
*
`sort=workspace.slug`
Note that the query parameter values need
to be URL escaped so that `=`
would become `%3D`.
summary: Atlassian List Workspaces For The Current User
responses:
'200':
description: All of the workspace memberships for the authenticated user.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_workspace_memberships'
examples:
response:
value:
pagelen: 10
page: 1
size: 1
values:
- type: workspace_membership
permission: owner
last_accessed: '2019-03-07T12:35:02.900024+00:00'
added_on: '2018-10-11T17:42:02.961424+00:00'
user:
type: user
uuid: '{470c176d-3574-44ea-bb41-89e8638bcca4}'
nickname: evzijst
display_name: Erik van Zijst
workspace:
type: workspace
uuid: '{a15fb181-db1f-48f7-b41f-e1eff06929d6}'
slug: bbworkspace1
name: Atlassian Bitbucket
'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. See
[filtering and sorting](/cloud/bitbucket/rest/intro/#filtering) for
details.
required: false
schema:
type: string
- name: sort
in: query
description: >2
Name of a response property to sort results. See
[filtering and
sorting](/cloud/bitbucket/rest/intro/#sorting-query-results)
for details.
required: false
schema:
type: string
security:
- oauth2:
- account
- basic: []
- api_key: []
operationId: atlassianListWorkspacesForTheCurrentUser
parameters: []
/users/{selected_user}:
get:
tags:
- Users
description: >-
Gets the public information associated with a user account.
If
the user's profile is private, `location`, `website` and
`created_on`
elements are omitted.
Note that the user object returned by this
operation is changing significantly, due to privacy changes.
See the
[announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-changes-gdpr/#changes-to-bitbucket-user-objects)
for details.
summary: Atlassian Get A User
responses:
'200':
description: The user object
content:
application/json:
schema:
$ref: '#/components/schemas/account'
'404':
description: >-
If no user exists for the specified UUID, or if the specified
account is a team account, not a personal account.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2: []
- basic: []
- api_key: []
operationId: atlassianGetAUser
parameters:
- name: selected_user
in: path
description: |
This can either be an Atlassian Account ID OR the UUID of the account,
surrounded by curly-braces, for example: `{account UUID}`.
required: true
schema:
type: string
/users/{selected_user}/pipelines_config/variables:
get:
tags:
- Pipelines
deprecated: true
summary: Atlassian List Variables For A User
description: >-
Find user level variables.
This endpoint has been deprecated, and you
should use the new workspaces endpoint. For more information, see [the
announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-teams-deprecation/).
operationId: atlassianGetpipelinevariablesforuser
parameters:
- name: selected_user
description: >-
Either the UUID of the account surrounded by curly-braces, for
example `{account UUID}`, OR an Atlassian Account ID.
required: true
in: path
schema:
type: string
responses:
'200':
description: The found user level variables.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_pipeline_variables'
security:
- oauth2:
- pipeline
- basic: []
- api_key: []
post:
tags:
- Pipelines
deprecated: true
summary: Atlassian Create A Variable For A User
description: >-
Create a user level variable.
This endpoint has been deprecated, and
you should use the new workspaces endpoint. For more information, see
[the
announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-teams-deprecation/).
operationId: atlassianCreatepipelinevariableforuser
parameters:
- name: selected_user
description: >-
Either the UUID of the account surrounded by curly-braces, for
example `{account UUID}`, OR an Atlassian Account ID.
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 account 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'
security:
- oauth2:
- pipeline:variable
- basic: []
- api_key: []
/users/{selected_user}/pipelines_config/variables/{variable_uuid}:
get:
tags:
- Pipelines
deprecated: true
summary: Atlassian Get A Variable For A User
description: >-
Retrieve a user level variable.
This endpoint has been deprecated,
and you should use the new workspaces endpoint. For more information,
see [the
announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-teams-deprecation/).
operationId: atlassianGetpipelinevariableforuser
parameters:
- name: selected_user
description: >-
Either the UUID of the account surrounded by curly-braces, for
example `{account UUID}`, OR an Atlassian Account ID.
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 account or variable with the given UUID was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- pipeline
- basic: []
- api_key: []
put:
tags:
- Pipelines
deprecated: true
summary: Atlassian Update A Variable For A User
description: >-
Update a user level variable.
This endpoint has been deprecated, and
you should use the new workspaces endpoint. For more information, see
[the
announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-teams-deprecation/).
operationId: atlassianUpdatepipelinevariableforuser
parameters:
- name: selected_user
description: >-
Either the UUID of the account surrounded by curly-braces, for
example `{account UUID}`, OR an Atlassian Account ID.
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 account or the variable was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- pipeline:variable
- basic: []
- api_key: []
delete:
tags:
- Pipelines
deprecated: true
summary: Atlassian Delete A Variable For A User
description: >-
Delete an account level variable.
This endpoint has been deprecated,
and you should use the new workspaces endpoint. For more information,
see [the
announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-teams-deprecation/).
operationId: atlassianDeletepipelinevariableforuser
parameters:
- name: selected_user
description: >-
Either the UUID of the account surrounded by curly-braces, for
example `{account UUID}`, OR an Atlassian Account ID.
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':
description: The account or the variable with the provided UUID does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- pipeline:variable
- basic: []
- api_key: []
/users/{selected_user}/properties/{app_key}/{property_name}:
put:
responses:
'204':
description: An empty response.
operationId: atlassianUpdateuserhostedpropertyvalue
summary: Atlassian Update A User Application Property
description: >-
Update an [application
property](/cloud/bitbucket/application-properties/) value stored against
a user.
parameters:
- required: true
in: path
name: selected_user
description: >-
Either the UUID of the account surrounded by curly-braces, for
example `{account UUID}`, OR an Atlassian Account ID.
schema:
type: string
- required: true
in: path
name: app_key
description: The key of the Connect app.
schema:
type: string
- required: true
in: path
name: property_name
description: The name of the property.
schema:
type: string
requestBody:
$ref: '#/components/requestBodies/application_property'
tags:
- Properties
security:
- oauth2: []
- basic: []
- api_key: []
delete:
responses:
'204':
description: An empty response.
operationId: atlassianDeleteuserhostedpropertyvalue
summary: Atlassian Delete A User Application Property
description: >-
Delete an [application
property](/cloud/bitbucket/application-properties/) value stored against
a user.
parameters:
- required: true
in: path
name: selected_user
description: >-
Either the UUID of the account surrounded by curly-braces, for
example `{account UUID}`, OR an Atlassian Account ID.
schema:
type: string
- required: true
in: path
name: app_key
description: The key of the Connect app.
schema:
type: string
- required: true
in: path
name: property_name
description: The name of the property.
schema:
type: string
tags:
- Properties
security:
- oauth2: []
- basic: []
- api_key: []
get:
responses:
'200':
description: The value of the property.
content:
application/json:
schema:
$ref: '#/components/schemas/application_property'
operationId: atlassianRetrieveuserhostedpropertyvalue
summary: Atlassian Get A User Application Property
description: >-
Retrieve an [application
property](/cloud/bitbucket/application-properties/) value stored against
a user.
parameters:
- required: true
in: path
name: selected_user
description: >-
Either the UUID of the account surrounded by curly-braces, for
example `{account UUID}`, OR an Atlassian Account ID.
schema:
type: string
- required: true
in: path
name: app_key
description: The key of the Connect app.
schema:
type: string
- required: true
in: path
name: property_name
description: The name of the property.
schema:
type: string
tags:
- Properties
security:
- oauth2: []
- basic: []
- api_key: []
/users/{selected_user}/search/code:
get:
tags:
- Search
summary: Atlassian Search For Code In A User S Repositories
description: >-
Search for code in the repositories of the specified user.
Note
that searches can match in the file's text (`content_matches`),
the
path (`path_matches`), or both.
You can use the same syntax for
the search query as in the UI.
E.g. to search for "foo" only within
the repository "demo",
use the query parameter
`search_query=foo+repo:demo`.
Similar to other APIs, you can
request more fields using a
`fields` query parameter. E.g. to get
some more information about
the repository of matched files, use the
query
parameter
`search_query=foo&fields=%2Bvalues.file.commit.repository`
(the
`%2B` is a URL-encoded `+`).
operationId: atlassianSearchaccount
parameters:
- name: selected_user
in: path
description: >-
Either the UUID of the account surrounded by curly-braces, for
example `{account UUID}`, OR an Atlassian Account ID.
required: true
schema:
type: string
- name: search_query
in: query
description: The search query
required: true
schema:
type: string
- name: page
in: query
description: Which page of the search results to retrieve
required: false
schema:
type: integer
format: int32
default: 1
- name: pagelen
in: query
description: How many search results to retrieve per page
required: false
schema:
type: integer
format: int32
default: 10
responses:
'200':
description: Successful search
content:
application/json:
schema:
$ref: '#/components/schemas/search_result_page'
examples:
response:
value:
size: 1
page: 1
pagelen: 10
query_substituted: false
values:
- type: code_search_result
content_match_count: 2
content_matches:
- lines:
- line: 2
segments: []
- line: 3
segments:
- text: 'def '
- text: foo
match: true
- text: '():'
- line: 4
segments:
- text: ' print("snek")'
- line: 5
segments: []
path_matches:
- text: src/
- text: foo
match: true
- text: .py
file:
path: src/foo.py
type: commit_file
links:
self:
href: >-
https://api.bitbucket.org/2.0/repositories/my-workspace/demo/src/ad6964b5fe2880dbd9ddcad1c89000f1dbcbc24b/src/foo.py
'400':
description: |
If the search request was invalid due to one of the
following reasons:
* the specified type of target account doesn''t match the actual
account type;
* malformed pagination properties;
* missing or malformed search query, in the latter case an error
key will be returned in `error.data.key` property.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: >-
Search is not enabled for the requested user, navigate to
[https://bitbucket.org/search](https://bitbucket.org/search) to turn
it on
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'429':
description: Too many requests, try again later
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- repository
- basic: []
- api_key: []
/users/{selected_user}/ssh-keys:
get:
tags:
- Ssh
description: Returns a paginated list of the user's SSH public keys.
summary: Atlassian List Ssh Keys
responses:
'200':
description: A list of the SSH keys associated with the account.
content:
application/json:
schema:
$ref: '#/components/schemas/paginated_ssh_user_keys'
examples:
response:
value:
page: 1
pagelen: 10
size: 1
values:
- comment: user@myhost
created_on: '2018-03-14T13:17:05.196003+00:00'
key: >-
ssh-ed25519
AAAAC3NzaC1lZDI1NTE5AAAAIKqP3Cr632C2dNhhgKVcon4ldUSAeKiku2yP9O9/bDtY
label: ''
last_used: '2018-03-20T13:18:05.196003+00:00'
links:
self:
href: >-
https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}/ssh-keys/b15b6026-9c02-4626-b4ad-b905f99f763a
owner:
display_name: Mark Adams
links:
avatar:
href: >-
https://bitbucket.org/account/markadams-atl/avatar/32/
html:
href: https://bitbucket.org/markadams-atl/
self:
href: >-
https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}
type: user
username: markadams-atl
nickname: markadams-atl
uuid: '{d7dd0e2d-3994-4a50-a9ee-d260b6cefdab}'
type: ssh_key
uuid: '{b15b6026-9c02-4626-b4ad-b905f99f763a}'
'403':
description: If the specified user's keys are not accessible to the current user
'404':
description: If the specified user does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- account
- basic: []
- api_key: []
operationId: atlassianListSSHKeys
post:
tags:
- Ssh
description: >-
Adds a new SSH public key to the specified user account and returns the
resulting key.
Example:
```
$ curl -X POST -H
"Content-Type: application/json" -d '{"key": "ssh-ed25519
AAAAC3NzaC1lZDI1NTE5AAAAIKqP3Cr632C2dNhhgKVcon4ldUSAeKiku2yP9O9/bDtY
user@myhost"}'
https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}/ssh-keys
```
summary: Atlassian Add A New Ssh Key
responses:
'201':
description: The newly created SSH key.
content:
application/json:
schema:
$ref: '#/components/schemas/ssh_account_key'
examples:
response:
value:
comment: user@myhost
created_on: '2018-03-14T13:17:05.196003+00:00'
key: >-
ssh-ed25519
AAAAC3NzaC1lZDI1NTE5AAAAIKqP3Cr632C2dNhhgKVcon4ldUSAeKiku2yP9O9/bDtY
label: ''
last_used: '2018-03-20T13:18:05.196003+00:00'
links:
self:
href: >-
https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}/ssh-keys/b15b6026-9c02-4626-b4ad-b905f99f763a
owner:
display_name: Mark Adams
links:
avatar:
href: >-
https://bitbucket.org/account/markadams-atl/avatar/32/
html:
href: https://bitbucket.org/markadams-atl/
self:
href: >-
https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}
type: user
username: markadams-atl
nickname: markadams-atl
uuid: '{d7dd0e2d-3994-4a50-a9ee-d260b6cefdab}'
type: ssh_key
uuid: '{b15b6026-9c02-4626-b4ad-b905f99f763a}'
'400':
description: If the submitted key or related value is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: >-
If the current user does not have permission to add a key for the
specified user
'404':
description: If the specified user does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ssh_account_key'
description: >-
The new SSH key object. Note that the username property has been
deprecated due to [privacy
changes](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-changes-gdpr/#removal-of-usernames-from-user-referencing-apis).
security:
- oauth2:
- account:write
- basic: []
- api_key: []
operationId: atlassianAddANewSSHKey
parameters:
- name: selected_user
in: path
description: |
This can either be an Atlassian Account ID OR the UUID of the account,
surrounded by curly-braces, for example: `{account UUID}`.
required: true
schema:
type: string
/users/{selected_user}/ssh-keys/{key_id}:
delete:
tags:
- Ssh
description: Deletes a specific SSH public key from a user's account.
summary: Atlassian Delete A Ssh Key
responses:
'204':
description: The key has been deleted
'400':
description: If the submitted key or related value is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: >-
If the current user does not have permission to add a key for the
specified user
'404':
description: If the specified user does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- account:write
- basic: []
- api_key: []
operationId: atlassianDeleteASSHKey
get:
tags:
- Ssh
description: Returns a specific SSH public key belonging to a user.
summary: Atlassian Get A Ssh Key
responses:
'200':
description: The specific SSH key matching the user and UUID
content:
application/json:
schema:
$ref: '#/components/schemas/ssh_account_key'
examples:
response:
value:
comment: user@myhost
created_on: '2018-03-14T13:17:05.196003+00:00'
key: >-
ssh-ed25519
AAAAC3NzaC1lZDI1NTE5AAAAIKqP3Cr632C2dNhhgKVcon4ldUSAeKiku2yP9O9/bDtY
label: ''
last_used: '2018-03-20T13:18:05.196003+00:00'
links:
self:
href: >-
https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}/ssh-keys/b15b6026-9c02-4626-b4ad-b905f99f763a
owner:
display_name: Mark Adams
links:
avatar:
href: >-
https://bitbucket.org/account/markadams-atl/avatar/32/
html:
href: https://bitbucket.org/markadams-atl/
self:
href: >-
https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}
type: user
username: markadams-atl
nickname: markadams-atl
uuid: '{d7dd0e2d-3994-4a50-a9ee-d260b6cefdab}'
type: ssh_key
uuid: '{b15b6026-9c02-4626-b4ad-b905f99f763a}'
'403':
description: If the specified user or key is not accessible to the current user
'404':
description: If the specified user or key does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- oauth2:
- account
- basic: []
- api_key: []
operationId: atlassianGetASSHKey
put:
tags:
- Ssh
description: >-
Updates a specific SSH public key on a user's account
Note: Only
the 'comment' field can be updated using this API. To modify the key or
comment values, you must delete and add the key
again.
Example:
```
$ curl -X PUT -H "Content-Type:
application/json" -d '{"label": "Work key"}'
https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}/ssh-keys/{b15b6026-9c02-4626-b4ad-b905f99f763a}
```
summary: Atlassian Update A Ssh Key
responses:
'200':
description: The newly updated SSH key.
content:
application/json:
schema:
$ref: '#/components/schemas/ssh_account_key'
examples:
response:
value:
comment: ''
created_on: '2018-03-14T13:17:05.196003+00:00'
key: >-
ssh-ed25519
AAAAC3NzaC1lZDI1NTE5AAAAIKqP3Cr632C2dNhhgKVcon4ldUSAeKiku2yP9O9/bDtY
label: Work key
last_used: '2018-03-20T13:18:05.196003+00:00'
links:
self:
href: >-
https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}/ssh-keys/b15b6026-9c02-4626-b4ad-b905f99f763a
owner:
display_name: Mark Adams
links:
avatar:
href: >-
https://bitbucket.org/account/markadams-atl/avatar/32/
html:
href: https://bitbucket.org/markadams-atl/
self:
href: >-
https://api.bitbucket.org/2.0/users/{ed08f5e1-605b-4f4a-aee4-6c97628a673e}
type: user
username: markadams-atl
nickname: markadams-atl
uuid: '{d7dd0e2d-3994-4a50-a9ee-d260b6cefdab}'
type: ssh_key
uuid: '{b15b6026-9c02-4626-b4ad-b905f99f763a}'
'400':
description: If the submitted key or related value is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: >-
If the current user does not have permission to add a key for the
specified user
'404':
description: If the specified user does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/error'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ssh_account_key'
description: The updated SSH key object
security:
- oauth2:
- account:write
- basic: []
- api_key: []
operationId: atlassianUpdateASSHKey
parameters:
- name: key_id
in: path
description: The SSH key's UUID value.
required: true
schema:
type: string
- name: selected_user
in: path
description: |
This can either be an Atlassian Account ID OR the UUID of the account,
surrounded by curly-braces, for example: `{account UUID}`.
required: true
schema:
type: string
/workspaces/{workspace}/projects/{project_key}/permissions-config/users:
get:
tags:
- Projects
description: >-
Returns a paginated list of explicit user permissions for the given
project.
This endpoint does not support BBQL features.
summary: Atlassian 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'
examples:
response:
value:
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
- read:user:bitbucket
operationId: atlassianListExplicitUserPermissionsForAProject
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
/workspaces/{workspace}/projects/{project_key}/permissions-config/users/{selected_user_id}:
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: Atlassian 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.
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 selected user 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: []
operationId: atlassianDeleteAnExplicitUserPermissionForAProject
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: Atlassian Get An Explicit User Permission For A Project
responses:
'200':
description: Explicit user permission for user and project
content:
application/json:
schema:
$ref: '#/components/schemas/project_user_permission'
examples:
response:
value:
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.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: The requesting user isn't an admin of the project.
content:
application/json:
schema:
$ref: '#/components/schemas/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
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
- read:user:bitbucket
operationId: atlassianGetAnExplicitUserPermissionForAProject
put:
tags:
- Projects
description: >-
Updates the explicit user permission for a given user and project. The
selected
user must be a member of the workspace, and cannot be the
workspace owner.
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: Atlassian Update An Explicit User Permission For A Project
responses:
'200':
description: Explicit user permission updated
content:
application/json:
schema:
$ref: '#/components/schemas/project_user_permission'
examples:
response:
value:
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: write
links:
self:
href: >-
https://api.bitbucket.org/2.0/workspaces/atlassian_tutorial/projects/PRJ/permissions-config/users/557058:ba8948b2-49da-43a9-9e8b-e7249b8e324a
'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 selected user doesn't
exist for the given identifiers or the requesting user is not
authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/error'
requestBody:
$ref: >-
#/components/requestBodies/bitbucket.apps.permissions.serializers.ProjectPermissionUpdateSchema
security:
- oauth2:
- project:admin
- basic: []
- api_key: []
operationId: atlassianUpdateAnExplicitUserPermissionForAProject
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
tags:
- name: Pipelines
- name: Projects
- name: Properties
- name: Repositories
- name: Search
- name: Ssh
- name: Users
- name: Workspaces
x-revision: 3c039d08312e
x-atlassian-narrative:
documents:
- anchor: authentication
title: Authentication methods
description: How to authenticate API actions
icon: >-
data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxOTcuNjQ3MyAxODYuODEzOCI+CiAgPGRlZnM+CiAgICA8c3R5bGU+CiAgICAgIC5jbHMtMSB7CiAgICAgICAgaXNvbGF0aW9uOiBpc29sYXRlOwogICAgICB9CgogICAgICAuY2xzLTIgewogICAgICAgIGZpbGw6ICNkZTM1MGI7CiAgICAgIH0KCiAgICAgIC5jbHMtMyB7CiAgICAgICAgZmlsbDogI2ZmNTYzMDsKICAgICAgfQoKICAgICAgLmNscy00IHsKICAgICAgICBmaWxsOiAjZGZlMWU1OwogICAgICAgIG1peC1ibGVuZC1tb2RlOiBtdWx0aXBseTsKICAgICAgfQoKICAgICAgLmNscy01IHsKICAgICAgICBmaWxsOiAjZmFmYmZjOwogICAgICB9CgogICAgICAuY2xzLTYgewogICAgICAgIGZpbGw6ICNlYmVjZjA7CiAgICAgIH0KCiAgICAgIC5jbHMtNyB7CiAgICAgICAgZmlsbDogbm9uZTsKICAgICAgICBzdHJva2U6ICMwMDY1ZmY7CiAgICAgICAgc3Ryb2tlLW1pdGVybGltaXQ6IDEwOwogICAgICAgIHN0cm9rZS13aWR0aDogMnB4OwogICAgICB9CgogICAgICAuY2xzLTggewogICAgICAgIGZpbGw6ICM1ZTZjODQ7CiAgICAgIH0KCiAgICAgIC5jbHMtOSB7CiAgICAgICAgZmlsbDogIzI1Mzg1ODsKICAgICAgfQoKICAgICAgLmNscy0xMCB7CiAgICAgICAgZmlsbDogIzI2ODRmZjsKICAgICAgfQoKICAgICAgLmNscy0xMSB7CiAgICAgICAgZmlsbDogIzAwNjVmZjsKICAgICAgfQogICAgPC9zdHlsZT4KICA8L2RlZnM+CiAgPHRpdGxlPlNlY3VyaXR5IHdpdGggS2V5PC90aXRsZT4KICA8ZyBjbGFzcz0iY2xzLTEiPgogICAgPGcgaWQ9IkxheWVyXzIiIGRhdGEtbmFtZT0iTGF5ZXIgMiI+CiAgICAgIDxnIGlkPSJPYmplY3RzIj4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTIiIGQ9Ik00Mi4wNjcyLDBoLjYxMTRhOCw4LDAsMCwxLDgsOFYyMy4yMzM4YTAsMCwwLDAsMSwwLDBIMzQuMDY3MmEwLDAsMCwwLDEsMCwwVjhBOCw4LDAsMCwxLDQyLjA2NzIsMFoiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTIiIGQ9Ik0xMDguMjIsMGguNjExNGE4LDgsMCwwLDEsOCw4VjIzLjIzMzhhMCwwLDAsMCwxLDAsMEgxMDAuMjJhMCwwLDAsMCwxLDAsMFY4QTgsOCwwLDAsMSwxMDguMjIsMFoiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTIiIGQ9Ik0xNzQuMzcyMiwwaC42MTE0YTgsOCwwLDAsMSw4LDhWMjMuMjMzOGEwLDAsMCwwLDEsMCwwSDE2Ni4zNzIyYTAsMCwwLDAsMSwwLDBWOEE4LDgsMCwwLDEsMTc0LjM3MjIsMFoiLz4KICAgICAgICA8cmVjdCBjbGFzcz0iY2xzLTIiIHg9IjM0LjA2NzIiIHk9IjIzLjIzMzgiIHdpZHRoPSIxNjMuNTgiIGhlaWdodD0iMTYzLjU4Ii8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0yIiBkPSJNNDIuMDY3MiwwSDU5LjI5YTgsOCwwLDAsMSw4LDhWMjMuMjIyOGEwLDAsMCwwLDEsMCwwSDM0LjA2NzJhMCwwLDAsMCwxLDAsMFY4YTgsOCwwLDAsMSw4LThaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0yIiBkPSJNMTA3LjI0NTgsMGgxNy4yMjI4YTgsOCwwLDAsMSw4LDhWMjMuMjIyOGEwLDAsMCwwLDEsMCwwSDk5LjI0NThhMCwwLDAsMCwxLDAsMFY4YTgsOCwwLDAsMSw4LThaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0yIiBkPSJNMTcyLjQyNDQsMGgxNy4yMjI4YTgsOCwwLDAsMSw4LDhWMjMuMjIyOGEwLDAsMCwwLDEsMCwwSDE2NC40MjQ0YTAsMCwwLDAsMSwwLDBWOGE4LDgsMCwwLDEsOC04WiIvPgogICAgICAgIDxyZWN0IGNsYXNzPSJjbHMtMyIgeD0iMTcuNDU1OCIgeT0iMjMuMjMzOCIgd2lkdGg9IjE2My41OCIgaGVpZ2h0PSIxNjMuNTgiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTMiIGQ9Ik0yNS40NTU4LDBINDIuNjc4NmE4LDgsMCwwLDEsOCw4VjIzLjIyMjhhMCwwLDAsMCwxLDAsMEgxNy40NTU4YTAsMCwwLDAsMSwwLDBWOEE4LDgsMCwwLDEsMjUuNDU1OCwwWiIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtMyIgZD0iTTkwLjYzNDQsMGgxNy4yMjI4YTgsOCwwLDAsMSw4LDhWMjMuMjIyOGEwLDAsMCwwLDEsMCwwSDgyLjYzNDRhMCwwLDAsMCwxLDAsMFY4QTgsOCwwLDAsMSw5MC42MzQ0LDBaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0zIiBkPSJNMTU1LjgxMywwaDE3LjIyMjhhOCw4LDAsMCwxLDgsOFYyMy4yMjI4YTAsMCwwLDAsMSwwLDBIMTQ3LjgxM2EwLDAsMCwwLDEsMCwwVjhBOCw4LDAsMCwxLDE1NS44MTMsMFoiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTMiIGQ9Ik0yNS40NTU4LDBINDIuNjc4NmE4LDgsMCwwLDEsOCw4VjIzLjIyMjhhMCwwLDAsMCwxLDAsMEgxNy40NTU4YTAsMCwwLDAsMSwwLDBWOEE4LDgsMCwwLDEsMjUuNDU1OCwwWiIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtMyIgZD0iTTkwLjYzNDQsMGgxNy4yMjI4YTgsOCwwLDAsMSw4LDhWMjMuMjIyOGEwLDAsMCwwLDEsMCwwSDgyLjYzNDRhMCwwLDAsMCwxLDAsMFY4QTgsOCwwLDAsMSw5MC42MzQ0LDBaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0zIiBkPSJNMTU1LjgxMywwaDE3LjIyMjhhOCw4LDAsMCwxLDgsOFYyMy4yMjI4YTAsMCwwLDAsMSwwLDBIMTQ3LjgxM2EwLDAsMCwwLDEsMCwwVjhBOCw4LDAsMCwxLDE1NS44MTMsMFoiLz4KICAgICAgICA8cmVjdCBjbGFzcz0iY2xzLTIiIHg9IjM1Ljc1OTYiIHk9IjU2LjgwNjUiIHdpZHRoPSIzMy4yMjI4IiBoZWlnaHQ9IjE1LjYwMzgiLz4KICAgICAgICA8cmVjdCBjbGFzcz0iY2xzLTIiIHg9IjEzMS4yMDE2IiB5PSIxMzYuOTYxNSIgd2lkdGg9IjMzLjIyMjgiIGhlaWdodD0iMTUuNjAzOCIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtNCIgZD0iTTU3LjM3MDksNzEuNjAzNmg3MC43NWE5LDksMCwwLDEsOSw5djM1LjM3NDlhNDQuMzc0OCw0NC4zNzQ4LDAsMCwxLTQ0LjM3NDgsNDQuMzc0OGgwYTQ0LjM3NDgsNDQuMzc0OCwwLDAsMS00NC4zNzQ4LTQ0LjM3NDhWODAuNjAzNkE5LDksMCwwLDEsNTcuMzcwOSw3MS42MDM2WiIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtNSIgZD0iTTY2LjM3MSw2Ni42NjE3aDcwLjc1YTksOSwwLDAsMSw5LDl2MzUuMzc0OWE0NC4zNzQ4LDQ0LjM3NDgsMCwwLDEtNDQuMzc0OCw0NC4zNzQ4aDBBNDQuMzc0OCw0NC4zNzQ4LDAsMCwxLDU3LjM3MSwxMTEuMDM2NlY3NS42NjE3YTksOSwwLDAsMSw5LTlaIi8+CiAgICAgICAgPHBhdGggaWQ9Il9SZWN0YW5nbGVfIiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTYiIGQ9Ik02MS4zNzEsNjYuNjYxN2g3MC43NWE5LDksMCwwLDEsOSw5djM1LjM3NDlhNDQuMzc0OCw0NC4zNzQ4LDAsMCwxLTQ0LjM3NDgsNDQuMzc0OGgwQTQ0LjM3NDgsNDQuMzc0OCwwLDAsMSw1Mi4zNzEsMTExLjAzNjZWNzUuNjYxN0E5LDksMCwwLDEsNjEuMzcxLDY2LjY2MTdaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy03IiBkPSJNOTYuNzQ1OSwxNDcuNzQ0MWEzNi43NDg3LDM2Ljc0ODcsMCwwLDEtMzYuNzA3NC0zNi43MDc0Vjc4LjA1ODRhMy43MzMzLDMuNzMzMywwLDAsMSwzLjcyOS0zLjcyOWg2NS45NTYzYTMuNzMzMywzLjczMzMsMCwwLDEsMy43MjksMy43Mjl2MzIuOTc4NEEzNi43NDg2LDM2Ljc0ODYsMCwwLDEsOTYuNzQ1OSwxNDcuNzQ0MVoiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTQiIGQ9Ik0xMDAuNjg5MywxNjMuMzE2N1YxMTEuMDk3M2EzLjk0NDMsMy45NDQzLDAsMCwwLTcuODg4NywwdjUyLjIyYTIyLjUyNTIsMjIuNTI1MiwwLDAsMC0xOC41NDc5LDIyLjE0YzAsLjQ1Ni4wMTc4LjkwNzguMDQ0NywxLjM1NzFIODIuMjFjLS4wNDE0LS40NDc0LS4wNjg4LS44OTktLjA2ODgtMS4zNTcxYTE0LjYyLDE0LjYyLDAsMCwxLDE0LjU5NzQtMTQuNjA0MWwuMDA2MS4wMDA2LjAwNjgtLjAwMDdBMTQuNjIxMSwxNC42MjExLDAsMCwxLDExMS4zNSwxODUuNDU2NmMwLC40NTgxLS4wMjczLjkxLS4wNjg4LDEuMzU3MWg3LjkxMjhjLjAyNjktLjQ0OTMuMDQ0Ny0uOTAxMS4wNDQ3LTEuMzU3MUEyMi41MjU5LDIyLjUyNTksMCwwLDAsMTAwLjY4OTMsMTYzLjMxNjdaIi8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy0yIiB4PSIxNy40NTU4IiB5PSIzNi40NzAyIiB3aWR0aD0iMzMuMjIyOCIgaGVpZ2h0PSIxNS42MDM4Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy0yIiB4PSIxNy40NTU4IiB5PSIxNTguMTIxNyIgd2lkdGg9IjMzLjIyMjgiIGhlaWdodD0iMTUuNjAzOCIvPgogICAgICAgIDxyZWN0IGNsYXNzPSJjbHMtMiIgeD0iMTQ3LjgxMyIgeT0iMzYuNDcwMiIgd2lkdGg9IjMzLjIyMjgiIGhlaWdodD0iMTUuNjAzOCIvPgogICAgICAgIDxyZWN0IGNsYXNzPSJjbHMtMiIgeD0iMTUwLjA2NDMiIHk9IjE1Ny41NTEzIiB3aWR0aD0iMzMuMjIyOCIgaGVpZ2h0PSIxNS42MDM4Ii8+CiAgICAgICAgPHBhdGggaWQ9Il9QYXRoXyIgZGF0YS1uYW1lPSImbHQ7UGF0aCZndDsiIGNsYXNzPSJjbHMtOCIgZD0iTTEwNy41MjU0LDEwMS4wMDI3YTExLjc3OTQsMTEuNzc5NCwwLDEsMC0xOS44Niw4LjU1NDhBNC4wNDE3LDQuMDQxNywwLDAsMSw4OC44NSwxMTMuNjJsLTIuMTA0LDcuMjY4MWEzLDMsMCwwLDAsMi44ODE3LDMuODM0MmgxMi4yMzcxYTMsMywwLDAsMCwyLjg4MTctMy44MzQybC0yLjA5NTktNy4yNGE0LjA3NDMsNC4wNzQzLDAsMCwxLDEuMTgwOC00LjA5NDVBMTEuNzE3MiwxMS43MTcyLDAsMCwwLDEwNy41MjU0LDEwMS4wMDI3WiIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtOSIgZD0iTTEwNC43NDYxLDEyMC44ODc3bC0yLjA5NTktNy4yNGE0LjA3NDQsNC4wNzQ0LDAsMCwxLDEuMTgwOC00LjA5NDUsMTEuNzYyOSwxMS43NjI5LDAsMCwwLTUuMDYtMTkuOTMxMywxMS45MSwxMS45MSwwLDAsMC04Ljc5OCwxMC45OTQ5LDExLjcxODUsMTEuNzE4NSwwLDAsMCwzLjY5MjksOC45NDFBNC4wNDE2LDQuMDQxNiwwLDAsMSw5NC44NSwxMTMuNjJsLTMuMjE0LDExLjEwMjNoMTAuMjI4OEEzLDMsMCwwLDAsMTA0Ljc0NjEsMTIwLjg4NzdaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0xMCIgZD0iTTgxLjc5NzUsMTAwLjMxYTMuOTQzOSwzLjk0MzksMCwwLDAtMy45NDQzLTMuOTQ0M0g0MS4wNDE3YTMuOTQ0MywzLjk0NDMsMCwwLDAsMCw3Ljg4ODdINzcuODUzMkEzLjk0MzksMy45NDM5LDAsMCwwLDgxLjc5NzUsMTAwLjMxWiIvPgogICAgICAgIDxwYXRoIGlkPSJfUGF0aF8yIiBkYXRhLW5hbWU9IiZsdDtQYXRoJmd0OyIgY2xhc3M9ImNscy0xMSIgZD0iTTQxLjA0MTYsMTA0LjI1MzlIOTYuODUzMmEzLjk0NDMsMy45NDQzLDAsMCwwLDAtNy44ODg3SDQxLjA0MTZhMy45NDQzLDMuOTQ0MywwLDAsMCwwLDcuODg4N1oiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTEwIiBkPSJNODEuNzk3NSwxMDAuMzFhMy45NDM5LDMuOTQzOSwwLDAsMC0zLjk0NDMtMy45NDQzSDQxLjA0MTdhMy45NDQzLDMuOTQ0MywwLDAsMCwwLDcuODg4N0g3Ny44NTMyQTMuOTQzOSwzLjk0MzksMCwwLDAsODEuNzk3NSwxMDAuMzFaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0xMCIgZD0iTTIyLjQ5MzIsMTIyLjgwMjlBMjIuNDkyOSwyMi40OTI5LDAsMSwxLDQ0Ljk4NTgsMTAwLjMxLDIyLjUxODUsMjIuNTE4NSwwLDAsMSwyMi40OTMyLDEyMi44MDI5Wm0wLTM3LjA5NzJBMTQuNjA0MiwxNC42MDQyLDAsMSwwLDM3LjA5NzIsMTAwLjMxLDE0LjYyMDcsMTQuNjIwNywwLDAsMCwyMi40OTMyLDg1LjcwNTdaIi8+CiAgICAgIDwvZz4KICAgIDwvZz4KICA8L2c+Cjwvc3ZnPgo='
body: >2
The purpose of this section is to describe how to authenticate when
making API calls using the Bitbucket REST API.
--
* [Basic auth](#basic-auth)
* [Access Tokens](#access-tokens)
* [Repository Access Tokens](#repository-access-tokens)
* [Project Access Tokens](#project-access-tokens)
* [Workspace Access Tokens](#workspace-access-tokens)
* [App passwords](#app-passwords)
* [OAuth 2.0](#oauth-2-0)
* [Making requests](#making-requests)
* [Repository cloning](#repository-cloning)
* [Refresh tokens](#refresh-tokens)
* [Bitbucket OAuth 2.0 Scopes](#bitbucket-oauth-2-0-scopes)
* [Forge App Scopes](#forge-app-scopes)
### Basic auth
Basic HTTP Authentication as per
[RFC-2617](https://tools.ietf.org/html/rfc2617) (Digest not supported).
Note that Basic Auth is available only with username and [app
password](https://bitbucket.org/account/settings/app-passwords/) as
credentials.
### Access Tokens
Access Tokens are passwords (or tokens) that provide access to a
_single_ repository, project or workspace.
These tokens can authenticate with Bitbucket APIs for scripting, CI/CD
tools, Bitbucket Cloud-connected apps,
and Bitbucket Cloud integrations.
Access Tokens are linked to a repository, project, or workspace, not a
user account.
The level of access provided by the token is set when a repository, or
workspace admin creates it,
by setting permission scopes.
There are three types of Access Token:
* **Repository Access Tokens** can connect to a single repository,
preventing them from accessing any other repositories or workspaces.
* **Project Access Tokens** can connect to a single project, providing
access to any repositories within the project.
* **Workspace Access Tokens** can connect to a single workspace and have
access to any projects and repositories within that workspace.
When using Bitbucket APIs with an Access Token, the token will be
treated as the "user" in the
Bitbucket UI and Bitbucket logs. This includes when using the Access
Token to leave a comment on a pull request,
push a commit, or merge a pull request. The Bitbucket UI and API
responses will show the
Repository/Project/Workspace Access Token as a user. The username shown
in the Bitbucket UI is the Access
Token _name_, and a custom icon is used to differentiate it from a
regular user in the UI.
#### Considerations for using Access Tokens
* After creation, an Access Token can't be viewed or modified. The
token's name, created date,
last accessed date, and scopes are visible on the repository, project,
or workspace **Access Tokens** page.
* Access Tokens can access a limited set of Bitbucket's permission
scopes.
* Provided you set the correct permission scopes, you can use an Access
Token to clone (`repository`)
and push (`repository:write`) code to the token's repository or the
repositories the token can access.
* You can't use an Access Token to log into the Bitbucket website.
* Access Tokens don't require two-step verification.
* You can set permission scopes (specific access rights) for each Access
Token.
* You can't use an Access Token to manipulate or query repository,
project, or workspace permissions.
* Access Tokens are not listed in any repository or workspace permission
API response.
* Access Tokens are deactivated when deleting the resource tied to it (a
repository, project, or workspace).
Repository Access Tokens are also revoked when transferring the
repository to another workspace.
* Any content created by the Access Token will persist after the Access
Token has been revoked.
* Access Tokens can interact with branch restriction APIs, but the token
can't be configured as a user with merge access when using branch
restrictions.
There are some APIs which are inaccessible for Access Tokens, these are:
* [Add a repository deploy
key](/cloud/bitbucket/rest/api-group-deployments/#api-repositories-workspace-repo-slug-deploy-keys-post)
* [Update a repository deploy
key](/cloud/bitbucket/rest/api-group-deployments/#api-repositories-workspace-repo-slug-deploy-keys-key-id-put)
* [Delete a repository deploy
key](/cloud/bitbucket/rest/api-group-deployments/#api-repositories-workspace-repo-slug-deploy-keys-key-id-delete)
#### Repository Access Tokens
For details on creating, managing, and using Repository Access Tokens,
visit
[Repository Access
Tokens](https://support.atlassian.com/bitbucket-cloud/docs/repository-access-tokens/).
The available scopes for Repository Access Tokens are:
- [`repository`](#repository)
- [`repository:write`](#repository-write)
- [`repository:admin`](#repository-admin)
- [`repository:delete`](#repository-delete)
- [`pullrequest`](#pullrequest)
- [`pullrequest:write`](#pullrequest-write)
- [`webhook`](#webhook)
- [`pipeline`](#pipeline)
- [`pipeline:write`](#pipeline-write)
- [`pipeline:variable`](#pipeline-variable)
- [`runner`](#runner)
- [`runner:write`](#runner-write)
#### Project Access Tokens
For details on creating, managing, and using Project Access Tokens,
visit
[Project Access
Tokens](https://support.atlassian.com/bitbucket-cloud/docs/project-access-tokens/).
The available scopes for Project Access Tokens are:
- [`project`](#project)
- [`repository`](#repository)
- [`repository:write`](#repository-write)
- [`repository:admin`](#repository-admin)
- [`repository:delete`](#repository-delete)
- [`pullrequest`](#pullrequest)
- [`pullrequest:write`](#pullrequest-write)
- [`webhook`](#webhook)
- [`pipeline`](#pipeline)
- [`pipeline:write`](#pipeline-write)
- [`pipeline:variable`](#pipeline-variable)
- [`runner`](#runner)
- [`runner:write`](#runner-write)
#### Workspace Access Tokens
For details on creating, managing, and using Workspace Access Tokens,
visit
[Workspace Access
Tokens](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-tokens/).
The available scopes for Workspace Access Tokens are:
- [`project`](#project)
- [`project:admin`](#project-admin)
- [`repository`](#repository)
- [`repository:write`](#repository-write)
- [`repository:admin`](#repository-admin)
- [`repository:delete`](#repository-delete)
- [`pullrequest`](#pullrequest)
- [`pullrequest:write`](#pullrequest-write)
- [`webhook`](#webhook)
- [`account`](#account)
- [`pipeline`](#pipeline)
- [`pipeline:write`](#pipeline-write)
- [`pipeline:variable`](#pipeline-variable)
- [`runner`](#runner)
- [`runner:write`](#runner-write)
### App passwords
App passwords allow users to make API calls to their Bitbucket account
through apps such as Sourcetree.
Some important points about app passwords:
* You cannot view an app password or adjust permissions after you create
the app password. Because app passwords are encrypted on our database
and cannot be viewed by anyone. They are essentially designed to be
disposable. If you need to change the scopes or lost the password just
create a new one.
* You cannot use them to log into your Bitbucket account.
* You cannot use app passwords to manage team actions.
App passwords are tied to an individual account's credentials and should not be shared. If you're sharing your app password you're essentially giving direct, authenticated, access to everything that password has been scoped to do with the Bitbucket API's.
* You can use them for API call authentication, even if you don't have
two-step verification enabled.
* You can set permission scopes (specific access rights) for each app
password.
For details on creating, managing, and using App passwords, visit
[App
passwords](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/).
### OAuth 2.0
Our OAuth 2 implementation is merged in with our existing OAuth 1 in
such a way that existing OAuth 1 consumers automatically become
valid OAuth 2 clients. The only thing you need to do is edit your
existing consumer and configure a callback URL.
Once that is in place, you'll have the following 2 URLs:
https://bitbucket.org/site/oauth2/authorize
https://bitbucket.org/site/oauth2/access_token
For obtaining access/bearer tokens, we support three of RFC-6749's grant
flows, plus a custom Bitbucket flow for exchanging JWT tokens for access
tokens.
Note that Resource Owner Password Credentials Grant (4.3) is no longer
supported.
#### 1. Authorization Code Grant (4.1)
The full-blown 3-LO flow. Request authorization from the end user by
sending their browser to:
https://bitbucket.org/site/oauth2/authorize?client_id={client_id}&response_type=code
The callback includes the `?code={}` query parameter that you can swap
for an access token:
$ curl -X POST -u "client_id:secret" \
https://bitbucket.org/site/oauth2/access_token \
-d grant_type=authorization_code -d code={code}
#### 2. Implicit Grant (4.2)
This flow is useful for browser-based add-ons that operate without
server-side backends.
Request the end user for authorization by directing the browser to:
https://bitbucket.org/site/oauth2/authorize?client_id={client_id}&response_type=token
That will redirect to your preconfigured callback URL with a fragment
containing the access token
(`#access_token={token}&token_type=bearer`) where your page's js can
pull it out of the URL.
#### 3. Client Credentials Grant (4.4)
Somewhat like our existing "2-LO" flow for OAuth 1. Obtain an access
token that represents not an end user, but the owner of the
client/consumer:
$ curl -X POST -u "client_id:secret" \
https://bitbucket.org/site/oauth2/access_token \
-d grant_type=client_credentials
#### 4. Bitbucket Cloud JWT Grant (urn:bitbucket:oauth2:jwt)
If your Atlassian Connect add-on uses JWT authentication, you can swap a
JWT for an OAuth access token. The resulting access token represents the
account for which the add-on is installed.
Make sure you send the JWT token in the Authorization request header
using the "JWT" scheme (case sensitive). Note that this custom scheme
makes this different from HTTP Basic Auth (and so you cannot use "curl
-u").
$ curl -X POST -H "Authorization: JWT {jwt_token}" \
https://bitbucket.org/site/oauth2/access_token \
-d grant_type=urn:bitbucket:oauth2:jwt
#### Making Requests
Once you have an access token, as per RFC-6750, you can use it in a
request in any of
the following ways (in decreasing order of desirability):
1. Send it in a request header: `Authorization: Bearer {access_token}`
2. Include it in a (application/x-www-form-urlencoded) POST body as
`access_token={access_token}`
3. Put it in the query string of a non-POST:
`?access_token={access_token}`
#### Repository Cloning
Since add-ons will not be able to upload their own SSH keys to clone
with, access tokens can be used as Basic HTTP Auth credentials to
clone securely over HTTPS. This is much like GitHub, yet slightly
different:
$ git clone https://x-token-auth:{access_token}@bitbucket.org/user/repo.git
The literal string `x-token-auth` as a substitute for username is
required (note the difference with GitHub where the actual token is in
the username field).
#### Refresh Tokens
Our access tokens expire in one hour. When this happens you'll get 401
responses.
Most access tokens grant responses (Implicit and JWT excluded).
Therefore, you should include a
refresh token that can then be used to generate a new access token,
without the need for end user participation:
$ curl -X POST -u "client_id:secret" \
https://bitbucket.org/site/oauth2/access_token \
-d grant_type=refresh_token -d refresh_token={refresh_token}
### Bitbucket OAuth 2.0 scopes
Bitbucket's API applies a number of privilege scopes to endpoints. In
order to access an endpoint, a request will need to have the necessary
scopes.
OAuth 2.0 Scopes are applicable for OAuth 2, Access Tokens, and App
passwords auth mechanisms as well as Bitbucket Connect apps.
Scopes are declared in the descriptor as a list of strings, with each
string being the name of a unique scope.
A descriptor lacking the `scopes` element is implicitly assumed to
require all scopes and as a result, Bitbucket will require end users
authorizing/installing the add-on
to explicitly accept all scopes.
Our best practice suggests you add only the scopes your add-on needs,
but no more than it needs.
Invalid scope strings will cause the descriptor to be rejected and the
installation to fail.
The available scopes are:
- [project](#project)
- [project:write](#project-write)
- [project:admin](#project-admin)
- [repository](#repository)
- [repository:write](#repository-write)
- [repository:admin](#repository-admin)
- [repository:delete](#repository-delete)
- [pullrequest](#pullrequest)
- [pullrequest:write](#pullrequest-write)
- [issue](#issue)
- [issue:write](#issue-write)
- [wiki](#wiki)
- [webhook](#webhook)
- [snippet](#snippet)
- [snippet:write](#snippet-write)
- [email](#email)
- [account](#account)
- [account:write](#account-write)
- [pipeline](#pipeline)
- [pipeline:write](#pipeline-write)
- [pipeline:variable](#pipeline-variable)
- [runner](#runner)
- [runner:write](#runner-write)
#### project
Provides access to view the project or projects.
This scope implies the [`repository`](#repository) scope, giving read
access to all the repositories in a project or projects.
#### project:write
This scope is deprecated, and has been made obsolete by `project:admin`.
Please see the deprecation notice
[here](/cloud/bitbucket/deprecation-notice-project-write-scope).
#### project:admin
Provides admin access to a project or projects. No distinction is made
between public and private projects. This scope doesn't implicitly grant
the [`project`](#project) scope or the
[`repository:write`](#repository-write) scope on any repositories under
the project. It gives access to the admin features of a project only,
not direct access to its repositories' contents.
* ability to create the project
* ability to update the project
* ability to delete the project
#### repository
Provides read access to a repository or repositories.
Note that this scope does not give access to a repository's pull
requests.
* access to the repo's source code
* clone over HTTPS
* access the file browsing API
* download zip archives of the repo's contents
* the ability to view and use the issue tracker on any repo (created
issues, comment, vote, etc)
* the ability to view and use the wiki on any repo (create/edit pages)
#### repository:write
Provides write (not admin) access to a repository or repositories. No
distinction is made between public and private repositories. This scope
implicitly grants the [`repository`](#repository) scope, which does not
need to be requested separately.
This scope alone does not give access to the pull requests API.
* push access over HTTPS
* fork repos
#### repository:admin
Provides admin access to a repository or repositories. No distinction is
made between public and private repositories. This scope doesn't
implicitly grant the [`repository`](#repository) or the
[`repository:write`](#repository-write) scopes. It gives access to the
admin features of a repo only, not direct access to its contents. This
scope can be used or misused to grant read access to other users, who
can then clone the repo, but users that need to read and write source
code would also request explicit read or write.
This scope comes with access to the following functionality:
* View and manipulate committer mappings
* List and edit deploy keys
* Ability to delete the repo
* View and edit repo permissions
* View and edit branch permissions
* Import and export the issue tracker
* Enable and disable the issue tracker
* List and edit issue tracker version, milestones and components
* Enable and disable the wiki
* List and edit default reviewers
* List and edit repo links (Jira/Bamboo/Custom)
* List and edit the repository webhooks
* Initiate a repo ownership transfer
#### repository:delete
Provides access to delete a repository or repositories.
#### pullrequest
Provides read access to pull requests.
This scope implies the [`repository`](#repository) scope, giving read
access to the pull request's destination repository.
* see and list pull requests
* create and resolve tasks
* comment on pull requests
#### pullrequest:write
Implicitly grants the [`pullrequest`](#pullrequest) scope and adds the
ability to create, merge and decline pull requests.
This scope also implicitly grants the
[`repository:write`](#repository-write) scope, giving write access to
the pull request's destination repository. This is necessary to allow
merging.
* merge pull requests
* decline pull requests
* create pull requests
* approve pull requests
#### issue
Ability to interact with issue trackers the way non-repo members can.
This scope doesn't implicitly grant any other scopes and doesn't give
implicit access to the repository.
* view, list and search issues
* create new issues
* comment on issues
* watch issues
* vote for issues
#### issue:write
This scope implicitly grants the [`issue`](#issue) scope and adds the
ability to transition and delete issues.
This scope doesn't implicitly grant any other scopes and doesn't give
implicit access to the repository.
* transition issues
* delete issues
#### wiki
Provides access to wikis. This scope provides both read and write access
(wikis are always editable by anyone with access to them).
This scope doesn't implicitly grant any other scopes and doesn't give
implicit access to the repository.
* view wikis
* create pages
* edit pages
* push to wikis
* clone wikis
#### webhook
Gives access to webhooks. This scope is required for any webhook-related
operation.
This scope gives read access to existing webhook subscriptions on all
resources the authorization mechanism can access, without needing
further scopes.
For example:
- A client can list all existing webhook subscriptions on a repository.
The [`repository`](#repository) scope is not required.
- Existing webhook subscriptions for the issue tracker on a repo can be
retrieved without the [`issue`](#issue) scope. All that is required is
the `webhook` scope.
To create webhooks, the client will need read access to the resource.
Such as: for [`issue:created`](#issue-created), the client will need to
have both the `webhook` and the [`issue`](#issue) scope.
* list webhook subscriptions on any accessible repository, user, team,
or snippet
* create/update/delete webhook subscriptions.
#### snippet
Provides read access to snippets.
No distinction is made between public and private snippets (public
snippets are accessible without any form of authentication).
* view any snippet
* create snippet comments
#### snippet:write
Provides write access to snippets.
No distinction is made between public and private snippets (public
snippets are accessible without any form of authentication).
This scope implicitly grants the [`snippet`](#snippet) scope which does
not need to be requested separately.
* create snippets
* edit snippets
* delete snippets
#### email
Ability to see the user's primary email address. This should make it
easier to use Bitbucket Cloud as a login provider for apps or external
applications.
#### account
When used for:
* **user-related APIs** — Gives read-only access to the user's account
information.
Note that this doesn't include any ability to change any of the data.
This scope allows you to view the user's:
* email addresses
* language
* location
* website
* full name
* SSH keys
* user groups
* **workspace-related APIs** — Grants access to view the workspace's:
* users
* user permissions
* projects
#### account:write
Ability to change properties on the user's account.
* delete the authorizing user's account
* manage the user's groups
* change a user's email addresses
* change username, display name and avatar
#### pipeline
Gives read-only access to pipelines, steps, deployment environments and
variables.
#### pipeline:write
Gives write access to pipelines. This scope allows a user to:
* Stop pipelines
* Rerun failed pipelines
* Resume halted pipelines
* Trigger manual pipelines.
This scope is not needed to trigger a build using a push. Performing a
`git push` (or equivalent actions) will trigger the build. The token
doing the push only needs the [`repository:write`](#repository-write)
scope.
This doesn't give write access to create variables.
#### pipeline:variable
Gives write access to create variables in pipelines at the various
levels:
* Workspace
* Repository
* Deployment
#### runner
Gives read-only access to pipelines runners setup against a workspace or
repository.
#### runner:write
Gives write access to create/edit/disable/delete pipelines runners setup
against a workspace or repository.
### Forge app scopes
In order for a Forge app integration to access Bitbucket API endpoints,
it needs to include certain privilege scopes in the app manifest. These
are different from Bitbucket OAuth 2.0 scopes.
Unlike OAuth 2.0 scopes, Forge app scopes do not implicitly grant other
scopes, for example, `write:repository:bitbucket` does not implicitly
grant `read:repository:bitbucket`.
Only a subset of Bitbucket API endpoints are currently available for
Forge app integrations. These will be labeled with Forge app scopes.
Our best practice suggests you only add the scopes your app needs, but
no more than it needs.
The available scopes are:
- [`read:repository:bitbucket`](#read-repository-bitbucket)
- [`write:repository:bitbucket`](#write-repository-bitbucket)
- [`admin:repository:bitbucket`](#admin-repository-bitbucket)
- [`delete:repository:bitbucket`](#delete-repository-bitbucket)
- [`read:pullrequest:bitbucket`](#read-pullrequest-bitbucket)
- [`write:pullrequest:bitbucket`](#write-pullrequest-bitbucket)
- [`read:project:bitbucket`](#read-project-bitbucket)
- [`admin:project:bitbucket`](#admin-project-bitbucket)
- [`read:workspace:bitbucket`](#read-workspace-bitbucket)
- [`read:user:bitbucket`](#read-user-bitbucket)
- [`read:pipeline:bitbucket`](#read-pipeline-bitbucket)
- [`write:pipeline:bitbucket`](#write-pipeline-bitbucket)
- [`admin:pipeline:bitbucket`](#admin-pipeline-bitbucket)
- [`read:runner:bitbucket`](#read-runner-bitbucket)
- [`write:runner:bitbucket`](#write-runner-bitbucket)
#### read:repository:bitbucket
Allows viewing of repository data. Note that this scope does not give
access to a repository's pull requests.
* access to the repository's source code
* access the file browsing API
* access to certain repository configurations such as branching model,
default reviewers, etc.
#### write:repository:bitbucket
Allows modification of repository data. No distinction is made between
public and private repositories. This scope does not imply the
`read:repository:bitbucket` scope, so you need to request that
separately if required. This scope alone does not give access to the
pull request API.
* update/delete source, branches, tags, etc.
* fork repositories
#### admin:repository:bitbucket
Allows admin activities on repositories. No distinction is made between
public and private repositories. This scope does not implicitly grant
the `read:repository:bitbucket` or the `write:repository:bitbucket`
scopes. It gives access to the admin features of a repository only, not
direct access to its contents. This scope does not allow modification of
repository permissions. This scope comes with access to the following
functionality:
* create repository
* view repository permissions
* view and edit branch restrictions
* edit branching model settings
* edit default reviewers
* view and edit inheritance state for repository settings
#### delete:repository:bitbucket
Allows deletion of repositories.
#### read:pullrequest:bitbucket
Allows viewing of pull requests, plus the ability to comment on pull
requests.
This scope does not imply the `read:repository:bitbucket` scope. With
this scope, you could retrieve some data specific to the
source/destination repositories of a pull request using pull request
endpoints, but it does not give access to repository API endpoints.
#### write:pullrequest:bitbucket
Allows the ability to create, update, approve, decline, and merge pull
requests.
This scope does not imply the `write:repository:bitbucket` scope.
#### read:project:bitbucket
Allows viewing of project and project permission data.
#### admin:project:bitbucket
Allows the ability to create, update, and delete project. No distinction
is made between public and private projects.
This scope does not implicitly grant the `read:project:bitbucket` scope
or any repository scopes. It gives access to the admin features of a
project only, not direct access to its repositories' contents.
#### read:workspace:bitbucket
Allows viewing of workspace and workspace permission data.
#### read:user:bitbucket
Allows viewing of user data. This scope is typically required for
permission related endpoints.
#### read:pipeline:bitbucket
Allows read access to all pipeline information (pipelines, steps,
caches, artifacts, logs, tests, code-insights).
#### write:pipeline:bitbucket
Allows running pipelines (i.e., start/stop/create pipeline) and
uploading tests/code-insights.
This scope does not imply the `read:pipeline:bitbucket` scope.
#### admin:pipeline:bitbucket
Allows admin activities, such as creating pipeline variables.
This scope does not implicitly grant the `read:pipeline:bitbucket` or
the `write:pipeline:bitbucket` scopes.
#### read:runner:bitbucket
Allows viewing of runners information.
#### write:runner:bitbucket
Allows runners management.
This scope does not imply the `read:runners:bitbucket` scope.
- anchor: filtering
title: Filter and sort API objects
description: Query the 2.0 API for specific objects
icon: >-
data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgMTk0LjE5MTkgMTQ3LjYwOTIiPgogIDxkZWZzPgogICAgPHN0eWxlPgogICAgICAuY2xzLTEgewogICAgICAgIGlzb2xhdGlvbjogaXNvbGF0ZTsKICAgICAgfQoKICAgICAgLmNscy0yIHsKICAgICAgICBmaWxsOiAjY2ZkNGRiOwogICAgICB9CgogICAgICAuY2xzLTMsIC5jbHMtNCB7CiAgICAgICAgZmlsbDogIzg3NzdkOTsKICAgICAgfQoKICAgICAgLmNscy00IHsKICAgICAgICBtaXgtYmxlbmQtbW9kZTogbXVsdGlwbHk7CiAgICAgIH0KCiAgICAgIC5jbHMtNSB7CiAgICAgICAgZmlsbDogIzAwNjVmZjsKICAgICAgfQoKICAgICAgLmNscy02IHsKICAgICAgICBmaWxsOiAjY2NlMGZmOwogICAgICB9CgogICAgICAuY2xzLTcgewogICAgICAgIGZpbGw6IHVybCgjbGluZWFyLWdyYWRpZW50KTsKICAgICAgfQogICAgPC9zdHlsZT4KICAgIDxsaW5lYXJHcmFkaWVudCBpZD0ibGluZWFyLWdyYWRpZW50IiB4MT0iNDE2LjMwODIiIHkxPSI3NS4wNDc5IiB4Mj0iNTg0Ljg1NTYiIHkyPSI3NS4wNDc5IiBncmFkaWVudFRyYW5zZm9ybT0idHJhbnNsYXRlKC00NDMuOTQ2NyAxMjMuMDY4Nikgcm90YXRlKC0xMy43OTc2KSIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPgogICAgICA8c3RvcCBvZmZzZXQ9IjAiIHN0b3AtY29sb3I9IiNmZmYiLz4KICAgICAgPHN0b3Agb2Zmc2V0PSIwLjY5MDgiIHN0b3AtY29sb3I9IiNmZmYiIHN0b3Atb3BhY2l0eT0iMC4xIi8+CiAgICA8L2xpbmVhckdyYWRpZW50PgogIDwvZGVmcz4KICA8dGl0bGU+TWFnbmlmeWluZyBHbGFzczwvdGl0bGU+CiAgPGcgY2xhc3M9ImNscy0xIj4KICAgIDxnIGlkPSJMYXllcl8yIiBkYXRhLW5hbWU9IkxheWVyIDIiPgogICAgICA8ZyBpZD0iT2JqZWN0cyI+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0yIiBkPSJNMTMxLjExMjUsOTQuOTMwN2wtOS44ODc4LTUuOTg4OC04LjMyOTIsMTMuNzUxOSw5Ljg4NzgsNS45ODg4YTE1LjYwMywxNS42MDMsMCwwLDEsNS44OCw2LjM4MzVoMGExNS42MDMsMTUuNjAzLDAsMCwwLDUuODgsNi4zODM1bDQwLjExNDMsMjQuMjk2NGExMi44NjY0LDEyLjg2NjQsMCwwLDAsMTcuNjcwOS00LjM0aDBhMTIuODY2NCwxMi44NjY0LDAsMCwwLTQuMzQtMTcuNjcwOUwxNDcuODc0OSw5OS40MzkyYTE1LjYwMywxNS42MDMsMCwwLDAtOC4zODEyLTIuMjU0MmgwQTE1LjYwMywxNS42MDMsMCwwLDEsMTMxLjExMjUsOTQuOTMwN1oiLz4KICAgICAgICA8cGF0aCBpZD0iX1BhdGhfIiBkYXRhLW5hbWU9IiZsdDtQYXRoJmd0OyIgY2xhc3M9ImNscy0zIiBkPSJNMTMxLjExMjUsOTQuOTMwN2wtMy4wMTE4LTEuODI0MkE4LjAzODgsOC4wMzg4LDAsMCwwLDExNy4wNiw5NS44MTc4aDBhOC4wMzg4LDguMDM4OCwwLDAsMCwyLjcxMTMsMTEuMDQwNWwzLjAxMTgsMS44MjQyYTE1LjYwMywxNS42MDMsMCwwLDEsNS44OCw2LjM4MzVoMGExNS42MDMsMTUuNjAzLDAsMCwwLDUuODgsNi4zODM1bDQwLjExNDMsMjQuMjk2NGExMi44NjY0LDEyLjg2NjQsMCwwLDAsMTcuNjcwOS00LjM0aDBhMTIuODY2NCwxMi44NjY0LDAsMCwwLTQuMzQtMTcuNjcwOUwxNDcuODc0OSw5OS40MzkyYTE1LjYwMywxNS42MDMsMCwwLDAtOC4zODEyLTIuMjU0M2gwQTE1LjYwMywxNS42MDMsMCwwLDEsMTMxLjExMjUsOTQuOTMwN1oiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTQiIGQ9Ik0xMzkuMTQzNyw5Ny4xNzkyYTE1LjU5NzMsMTUuNTk3MywwLDAsMS04LjAzMTItMi4yNDg1bC0zLjAxMTgtMS44MjQyQTguMDM4OCw4LjAzODgsMCwwLDAsMTE3LjA2LDk1LjgxNzhoMGE4LjAzODgsOC4wMzg4LDAsMCwwLDIuNzExMywxMS4wNDA1bDMuMDExOCwxLjgyNDJhMTUuNTk3LDE1LjU5NywwLDAsMSw1LjcwNjksNi4wNjQ4LDY3Ljg0ODEsNjcuODQ4MSwwLDAsMCwxMC42NTM2LTE3LjU2ODFaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy01IiBkPSJNODMuMjUzNywxMzIuNTU2QTY3LjIzNDgsNjcuMjM0OCwwLDAsMSw5LjcxLDMyLjQyOTUsNjYuNzk3NCw2Ni43OTc0LDAsMCwxLDUxLjE4MzcsMS45NjY2bC4wMDA3LDBBNjYuNzk2Miw2Ni43OTYyLDAsMCwxLDEwMi4wNTEsOS43NTI1aDBBNjcuMjM0Niw2Ny4yMzQ2LDAsMCwxLDgzLjI1MzcsMTMyLjU1NloiLz4KICAgICAgICA8cGF0aCBpZD0iX1BhdGhfMiIgZGF0YS1uYW1lPSImbHQ7UGF0aCZndDsiIGNsYXNzPSJjbHMtNiIgZD0iTTIzLjQzOSw0MC43NDgyQTUxLjE5MDgsNTEuMTkwOCwwLDAsMCwxMTEuMDEsOTMuNzg4OSw1MS4xOTA4LDUxLjE5MDgsMCwwLDAsMjMuNDM5LDQwLjc0ODJaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy03IiBkPSJNNzkuNDMzLDExNi45ODJBNTEuMjE2Miw1MS4yMTYyLDAsMCwwLDExOC40MjQxLDY3LjAzN2E0OS4xMzkxLDQ5LjEzOTEsMCwwLDEtNS4wODY3LDIuMjc4OWMtMTUuNzAyOSw1Ljk2MDktMjkuNjg5NSwyLjExLTM2LjQ5ODcuMTMwOC0yMC40MzA3LTUuOTM5LTI0Ljc5LTE3LjM3ODUtMzkuMDQxNC0yNC41ODIzYTQ4LjMwOTIsNDguMzA5MiwwLDAsMC0xNC4wOTM5LTQuNTNjLS4wODYyLjEzOTUtLjE3OTMuMjczLS4yNjQ0LjQxMzVBNTEuMTkwNyw1MS4xOTA3LDAsMCwwLDc5LjQzMywxMTYuOTgyWiIvPgogICAgICA8L2c+CiAgICA8L2c+CiAgPC9nPgo8L3N2Zz4K'
body: "\nYou can query the 2.0 API for specific objects using a simple language which resembles SQL.\n\nNote that filtering and querying by username has been deprecated, due to privacy changes. \nSee the [announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-changes-gdpr/#changes-to-querying) \nfor details.\n\n\n\n* [Supported endpoints](#supported-endpoints)\n* [Operators](#operators)\n* [Data types](#data-types)\n* [Querying](#querying)\n* [Sorting query results](#sorting-query-results)\n\n-\n\n### Supported endpoints\n\nMost 2.0 API resources that return paginated collections of objects support a single, shared, generic querying language that is used to filter down a result set.\n\nThis includes, but is in no way limited to:\n\n /2.0/repositories/{username}\n /2.0/repositories/{username}/{slug}/refs\n /2.0/repositories/{username}/{slug}/refs/branches\n /2.0/repositories/{username}/{slug}/refs/tags\n /2.0/repositories/{username}/{slug}/forks\n /2.0/repositories/{username}/{slug}/src\n /2.0/repositories/{username}/{slug}/issues\n /2.0/repositories/{username}/{slug}/pullrequests\n\nFiltering and sorting supports several distinct operators and data types as well as basic features, like logical operators (AND, OR).\nAs examples, the following queries could be used on the issue tracker endpoint (`/2.0/repositories/{workspace}/{slug}/issues/`):\n\n\t(state = \"open\" OR state = \"new\") AND assignee = null\n\treporter.nickname != \"evzijst\" AND priority >= \"major\"\n\t(title ~ \"unicode\" OR content.raw ~ \"unicode\") AND created_on > 2015-10-04T14:00:00-07:00\n\nFilter queries can be added to the URL using the q= query parameter. To sort the response, add sort=. Note that the entire query string is put in the q parameter and hence needs to be URL-encoded as shown in the following example:\n\n\t/2.0/repositories/foo/bar/issues?q=state=\"new\"&sort=-updated_on\n\n\n### Operators\n\nFiltering and sorting supports the following operators:\n\n| Operator | Definition | Example |\n|-|--|-|\n| \"=\" | test for equality | `nickname = \"evzijst\"` |\n| \"!=\" | not equal | `is_private != true` |\n| \"~\" | case-insensitive text contains | `description ~ \"beef\"` |\n| \"!~\" | case-insensitive not contains | `description !~ \"fubar\"` |\n| \">\" | greater than | `priority > \"major\"` |\n| \">=\" | greater than or equal | `priority <= \"trivial\"` |\n| \"<\" | less than | `id < 1234` |\n| \"<=\" | less than or equal | `updated_on <= 2015-03-04` |\n\n### Data types\n\nFiltering and sorting supports the following data types:\n\n| Type | Description | Example |\n|--|--||\n| **String** | any text inside double quotes | `\"foo\"` |\n| **Number** | arbitrary precision integers and floats | `1, -10.302` |\n| **Null** | to test for the absence of a value | `null` |\n| **boolean** | the unquoted strings true or false | `true, false` |\n| **datetime** | an unquoted [ISO-8601][iso-8601] date time string with the timezone offset, milliseconds and entire time component being optional | `2015-03-04T14:08:59.123+02:00`, `2015-03-04T14:08:59` Date time strings are assumed to be in UTC, unless an explicit timezone offset is provided |\n\n[https://en.wikipedia.org/wiki/ISO_8601]: /iso-8601\n\n### Querying\n\nObjects can be filtered based on their properties. In principle, every element in an object's JSON document schema can be used as a filter criterion.\n\nNote that while the array of objects in a paginated response is wrapped in an\nenvelope with a `values` element, this prefix should not be included in the\nquery fields (so use `/2.0/repositories/foo/bar/issues?q=state=\"new\"`, not\n`/2.0/repositories/foo/bar/issues?q=values.state=\"new\"`).\n\n\n### Examples\n\nFields that contain embedded instances
of other object types (e.g. owner is an embedded user object, while parent is an embedded repository) can be traversed recursively. For instance:\n\n\tparent.owner.nickname = \"bitbucket\"\n\nTo find pull requests which merge into master, come from a fork of the repo rather than a branch inside the repo, and on which I am a reviewer:\n\n```\nsource.repository.full_name != \"main/repo\" AND state = \"OPEN\" AND reviewers.nickname = \"evzijst\" AND destination.branch.name = \"master\"\n```\n```\n/2.0/repositories/main/repo/pullrequests?q=source.repository.full_name+%21%3D+%22main%2Frepo%22+AND+state+%3D+%22OPEN%22+AND+reviewers.nickname+%3D+%22evzijst%22+AND+destination.branch.name+%3D+%22master%22\n```\n\nTo find new or on-hold issues related to the UI, created or updated in the last day (SF local time), that have not yet been assigned to anyone:\n\n```\n(state = \"new\" OR state = \"on hold\") AND assignee = null AND component = \"UI\" and updated_on > 2015-11-11T00:00:00-07:00\n```\n```\n/2.0/repositories/main/repo/issues?q=%28state+%3D+%22new%22+OR+state+%3D+%22on+hold%22%29+AND+assignee+%3D+null+AND+component+%3D+%22UI%22+and+updated_on+%3E+2015-11-11T00%3A00%3A00-07%3A00\n```\n\nTo find all tags with the string \"2015\" in the name:\n\n```\nname ~ \"2015\"\n```\n```\n/2.0/repositories/{username}/{slug}/refs/tags?q=name+%7E+%222015%22\n```\nOr all my branches:\n\n```\nname ~ \"erik/\"\n```\n```\n/2.0/repositories/{username}/{slug}/refs/?q=name+%7E+%22erik%2F%22\n```\n### Sorting query results\n\nYou can sort result sets using the ?sort= query parameter, available on the same resources that support filtering:\n\n* In principle, every field that can be queried can also be used as a key for sorting.\n* By default the sort order is ascending. To reverse the order, prefix the field name with a hyphen (e.g. ?sort=-updated_on).\n* Only one field can be sorted on. Compound fields (e.g. sort on state first, followed by updated_on) are not supported.\n\n\n"
- anchor: pagination
title: Pagination
description: Learn more about pagination
icon: >-
data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgMjM4LjgyIDE1MS42Ij48ZGVmcz48c3R5bGU+LmNscy0xe2ZpbGw6I2IyZDRmZjt9LmNscy0ye2ZpbGw6IzRjOWFmZjt9LmNscy0ze2ZpbGw6IzAwNTJjYzt9LmNscy00e29wYWNpdHk6MC42O30uY2xzLTV7ZmlsbDp1cmwoI2xpbmVhci1ncmFkaWVudCk7fS5jbHMtNntmaWxsOnVybCgjbGluZWFyLWdyYWRpZW50LTIpO30uY2xzLTd7ZmlsbDp1cmwoI2xpbmVhci1ncmFkaWVudC0zKTt9LmNscy04e2ZpbGw6dXJsKCNsaW5lYXItZ3JhZGllbnQtNCk7fS5jbHMtOXtmaWxsOnVybCgjbGluZWFyLWdyYWRpZW50LTUpO30uY2xzLTEwLC5jbHMtMTEsLmNscy0xMntmaWxsOm5vbmU7fS5jbHMtMTB7c3Ryb2tlOiMzMzg0ZmY7fS5jbHMtMTAsLmNscy0xMSwuY2xzLTEyLC5jbHMtMTN7c3Ryb2tlLW1pdGVybGltaXQ6MTA7c3Ryb2tlLXdpZHRoOjJweDt9LmNscy0xMXtzdHJva2U6I2ZmYWIwMDt9LmNscy0xMntzdHJva2U6I2ZhZmJmYzt9LmNscy0xM3tmaWxsOiNmZmFiMDA7c3Ryb2tlOiMyNjg0ZmY7fTwvc3R5bGU+PGxpbmVhckdyYWRpZW50IGlkPSJsaW5lYXItZ3JhZGllbnQiIHkxPSI2NS4xNyIgeDI9Ijg2LjM4IiB5Mj0iNjUuMTciIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj48c3RvcCBvZmZzZXQ9IjAiIHN0b3AtY29sb3I9IiM0YzlhZmYiLz48c3RvcCBvZmZzZXQ9IjAuMDgiIHN0b3AtY29sb3I9IiM0YzlhZmYiIHN0b3Atb3BhY2l0eT0iMC45NCIvPjxzdG9wIG9mZnNldD0iMC4yNCIgc3RvcC1jb2xvcj0iIzRjOWFmZiIgc3RvcC1vcGFjaXR5PSIwLjc4Ii8+PHN0b3Agb2Zmc2V0PSIwLjQ1IiBzdG9wLWNvbG9yPSIjNGM5YWZmIiBzdG9wLW9wYWNpdHk9IjAuNTMiLz48c3RvcCBvZmZzZXQ9IjAuNTUiIHN0b3AtY29sb3I9IiM0YzlhZmYiIHN0b3Atb3BhY2l0eT0iMC40Ii8+PC9saW5lYXJHcmFkaWVudD48bGluZWFyR3JhZGllbnQgaWQ9ImxpbmVhci1ncmFkaWVudC0yIiB4MT0iMTUyLjQ0IiB5MT0iNjUuMTciIHgyPSIyMzguODIiIHkyPSI2NS4xNyIgeGxpbms6aHJlZj0iI2xpbmVhci1ncmFkaWVudCIvPjxsaW5lYXJHcmFkaWVudCBpZD0ibGluZWFyLWdyYWRpZW50LTMiIHgxPSIxOC44NSIgeTE9IjExOC43OCIgeDI9IjEyNi4wOCIgeTI9IjExLjU2IiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+PHN0b3Agb2Zmc2V0PSIwLjA2IiBzdG9wLWNvbG9yPSIjMDA2NWZmIi8+PHN0b3Agb2Zmc2V0PSIwLjE5IiBzdG9wLWNvbG9yPSIjMDA2NWZmIiBzdG9wLW9wYWNpdHk9IjAuOTQiLz48c3RvcCBvZmZzZXQ9IjAuNDYiIHN0b3AtY29sb3I9IiMwMDY1ZmYiIHN0b3Atb3BhY2l0eT0iMC43OCIvPjxzdG9wIG9mZnNldD0iMC44MiIgc3RvcC1jb2xvcj0iIzAwNjVmZiIgc3RvcC1vcGFjaXR5PSIwLjUzIi8+PHN0b3Agb2Zmc2V0PSIxIiBzdG9wLWNvbG9yPSIjMDA2NWZmIiBzdG9wLW9wYWNpdHk9IjAuNCIvPjwvbGluZWFyR3JhZGllbnQ+PGxpbmVhckdyYWRpZW50IGlkPSJsaW5lYXItZ3JhZGllbnQtNCIgeDE9IjExMi43NSIgeTE9IjExOC43OCIgeDI9IjIxOS45NyIgeTI9IjExLjU2IiB4bGluazpocmVmPSIjbGluZWFyLWdyYWRpZW50LTMiLz48bGluZWFyR3JhZGllbnQgaWQ9ImxpbmVhci1ncmFkaWVudC01IiB4MT0iNTAuOTciIHkxPSIxMzMuNjEiIHgyPSIxODcuODYiIHkyPSItMy4yOCIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIG9mZnNldD0iMC42NiIgc3RvcC1jb2xvcj0iIzI1Mzg1OCIvPjxzdG9wIG9mZnNldD0iMC44OCIgc3RvcC1jb2xvcj0iIzI1Mzg1OCIgc3RvcC1vcGFjaXR5PSIwLjgzIi8+PHN0b3Agb2Zmc2V0PSIxIiBzdG9wLWNvbG9yPSIjMjUzODU4IiBzdG9wLW9wYWNpdHk9IjAuNyIvPjwvbGluZWFyR3JhZGllbnQ+PC9kZWZzPjx0aXRsZT5WaWV3IFZlcnNpb25zPC90aXRsZT48ZyBpZD0iTGF5ZXJfMiIgZGF0YS1uYW1lPSJMYXllciAyIj48ZyBpZD0iU29mdHdhcmUiPjxjaXJjbGUgY2xhc3M9ImNscy0xIiBjeD0iOTQuNTMiIGN5PSIxNDcuOTMiIHI9IjMuNjciLz48Y2lyY2xlIGNsYXNzPSJjbHMtMiIgY3g9IjEwNi45NCIgY3k9IjE0Ny45MyIgcj0iMy42NyIvPjxjaXJjbGUgY2xhc3M9ImNscy0zIiBjeD0iMTE5LjM0IiBjeT0iMTQ3LjkzIiByPSIzLjY3Ii8+PGNpcmNsZSBjbGFzcz0iY2xzLTIiIGN4PSIxMzEuNzUiIGN5PSIxNDcuOTMiIHI9IjMuNjciLz48Y2lyY2xlIGNsYXNzPSJjbHMtMSIgY3g9IjE0NC4xNiIgY3k9IjE0Ny45MyIgcj0iMy42NyIvPjxnIGNsYXNzPSJjbHMtNCI+PHJlY3QgaWQ9Il9SZWN0YW5nbGVfIiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTUiIHk9IjI1LjkyIiB3aWR0aD0iODYuMzgiIGhlaWdodD0iNzguNDkiLz48L2c+PGcgY2xhc3M9ImNscy00Ij48cmVjdCBpZD0iX1JlY3RhbmdsZV8yIiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTYiIHg9IjE1Mi40NCIgeT0iMjUuOTIiIHdpZHRoPSI4Ni4zOCIgaGVpZ2h0PSI3OC40OSIvPjwvZz48cmVjdCBpZD0iX1JlY3RhbmdsZV8zIiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTciIHg9IjE2LjI4IiB5PSIxNC4xMiIgd2lkdGg9IjExMi4zNiIgaGVpZ2h0PSIxMDIuMDkiLz48cmVjdCBpZD0iX1JlY3RhbmdsZV80IiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTgiIHg9IjExMC4xOCIgeT0iMTQuMTIiIHdpZHRoPSIxMTIuMzYiIGhlaWdodD0iMTAyLjA5Ii8+PHJlY3QgaWQ9Il9SZWN0YW5nbGVfNSIgZGF0YS1uYW1lPSImbHQ7UmVjdGFuZ2xlJmd0OyIgY2xhc3M9ImNscy05IiB4PSI0Ny42OSIgd2lkdGg9IjE0My40NSIgaGVpZ2h0PSIxMzAuMzQiLz48bGluZSBjbGFzcz0iY2xzLTEwIiB4MT0iNzkuMTYiIHkxPSIxNi4xOCIgeDI9IjExNy4yNCIgeTI9IjE2LjE4Ii8+PGxpbmUgY2xhc3M9ImNscy0xMCIgeDE9IjYyLjkzIiB5MT0iMTYuMTgiIHgyPSI3Mi42IiB5Mj0iMTYuMTgiLz48bGluZSBjbGFzcz0iY2xzLTExIiB4MT0iNzkuMTYiIHkxPSIyNi45NSIgeDI9IjExNy4yNCIgeTI9IjI2Ljk1Ii8+PGxpbmUgY2xhc3M9ImNscy0xMCIgeDE9IjYyLjkzIiB5MT0iMjYuOTUiIHgyPSI3Mi42IiB5Mj0iMjYuOTUiLz48bGluZSBjbGFzcz0iY2xzLTEwIiB4MT0iNzkuMTYiIHkxPSIzNy43MiIgeDI9IjE1MC43IiB5Mj0iMzcuNzIiLz48bGluZSBjbGFzcz0iY2xzLTEwIiB4MT0iNjIuOTMiIHkxPSIzNy43MiIgeDI9IjcyLjYiIHkyPSIzNy43MiIvPjxsaW5lIGNsYXNzPSJjbHMtMTEiIHgxPSIxNTAuNyIgeTE9IjQ4LjQ5IiB4Mj0iMTc1LjU5IiB5Mj0iNDguNDkiLz48bGluZSBjbGFzcz0iY2xzLTEyIiB4MT0iMTEwLjMyIiB5MT0iNDguNDkiIHgyPSIxNDMuMDUiIHkyPSI0OC40OSIvPjxsaW5lIGNsYXNzPSJjbHMtMTEiIHgxPSI3OS4xNiIgeTE9IjQ4LjQ5IiB4Mj0iMTAxLjM3IiB5Mj0iNDguNDkiLz48bGluZSBjbGFzcz0iY2xzLTEwIiB4MT0iNjIuOTMiIHkxPSI0OC40OSIgeDI9IjcyLjYiIHkyPSI0OC40OSIvPjxsaW5lIGNsYXNzPSJjbHMtMTAiIHgxPSI3OS4xNiIgeTE9IjU5LjI2IiB4Mj0iMTUwLjciIHkyPSI1OS4yNiIvPjxsaW5lIGNsYXNzPSJjbHMtMTAiIHgxPSI2Mi45MyIgeTE9IjU5LjI2IiB4Mj0iNzIuNiIgeTI9IjU5LjI2Ii8+PGxpbmUgY2xhc3M9ImNscy0xMCIgeDE9Ijc5LjE2IiB5MT0iNzAuMDMiIHgyPSIxNzUuNTkiIHkyPSI3MC4wMyIvPjxsaW5lIGNsYXNzPSJjbHMtMTAiIHgxPSI2Mi45MyIgeTE9IjcwLjAzIiB4Mj0iNzIuNiIgeTI9IjcwLjAzIi8+PGxpbmUgY2xhc3M9ImNscy0xMSIgeDE9Ijc5LjE2IiB5MT0iODAuNzkiIHgyPSIxMTcuMjQiIHkyPSI4MC43OSIvPjxsaW5lIGNsYXNzPSJjbHMtMTAiIHgxPSI2Mi45MyIgeTE9IjgwLjc5IiB4Mj0iNzIuNiIgeTI9IjgwLjc5Ii8+PGxpbmUgY2xhc3M9ImNscy0xMyIgeDE9Ijc5LjE2IiB5MT0iOTEuNTYiIHgyPSIxNDkuMDYiIHkyPSI5MS41NiIvPjxsaW5lIGNsYXNzPSJjbHMtMTAiIHgxPSI2Mi45MyIgeTE9IjkxLjU2IiB4Mj0iNzIuNiIgeTI9IjkxLjU2Ii8+PGxpbmUgY2xhc3M9ImNscy0xMCIgeDE9IjYyLjkzIiB5MT0iODAuNzkiIHgyPSI3Mi42IiB5Mj0iODAuNzkiLz48bGluZSBjbGFzcz0iY2xzLTEwIiB4MT0iNjIuOTMiIHkxPSI5MS41NiIgeDI9IjcyLjYiIHkyPSI5MS41NiIvPjxsaW5lIGNsYXNzPSJjbHMtMTEiIHgxPSI3OS4xNiIgeTE9IjEwMi4zMyIgeDI9IjExNy4yNCIgeTI9IjEwMi4zMyIvPjxsaW5lIGNsYXNzPSJjbHMtMTAiIHgxPSI2Mi45MyIgeTE9IjEwMi4zMyIgeDI9IjcyLjYiIHkyPSIxMDIuMzMiLz48bGluZSBjbGFzcz0iY2xzLTEwIiB4MT0iMTI1Ljk4IiB5MT0iMTEzLjEiIHgyPSIxNDkuMDYiIHkyPSIxMTMuMSIvPjxsaW5lIGNsYXNzPSJjbHMtMTIiIHgxPSI3OS4xNiIgeTE9IjExMy4xIiB4Mj0iMTE3LjI0IiB5Mj0iMTEzLjEiLz48bGluZSBjbGFzcz0iY2xzLTEwIiB4MT0iNjIuOTMiIHkxPSIxMTMuMSIgeDI9IjcyLjYiIHkyPSIxMTMuMSIvPjwvZz48L2c+PC9zdmc+'
body: >2
Endpoints that return collections of objects should always apply
pagination.
Paginated collections are always wrapped in the following wrapper
object:
```json
{
"size": 5421,
"page": 2,
"pagelen": 10,
"next": "https://api.bitbucket.org/2.0/repositories/pypy/pypy/commits?page=3",
"previous": "https://api.bitbucket.org/2.0/repositories/pypy/pypy/commits?page=1",
"values": [
...
]
}
```
Pagination is often page-bound, with a query parameter page indicating
which
page is to be returned.
However, clients are not expected to construct URLs themselves by
manipulating
the page number query parameter. Instead, the response contains a link
to the
next page. This link should be treated as an opaque location that is not
to be
constructed by clients or even assumed to be predictable. The only
contract
around the next link is that it will return the next chunk of results.
Lack of a next link in the response indicates the end of the collection.
The paginated response contains the following fields:
| Field | Value |
||-|
| `size` | Total number of objects in the response. This is an
optional element that is not provided in all responses, as it can be
expensive to compute. |
| `page` | Page number of the current results. This is an optional
element that is not provided in all responses. |
| `pagelen` | Current number of objects on the existing page. Globally,
the minimum length is 10 and the maximum is 100. Some APIs may specify a
different default. |
| `next` | Link to the next page if it exists. The last page of a
collection does not have this value. Use this link to navigate the
result set and refrain from constructing your own URLs. |
| `previous` | Link to previous page if it exists. A collections first
page does not have this value. This is an optional element that is not
provided in all responses. Some result sets strictly support forward
navigation and never provide previous links. Clients must anticipate
that backwards navigation is not always available. Use this link to
navigate the result set and refrain from constructing your own URLs. |
| `values` | The list of objects. This contains at most `pagelen`
objects. |
The link to the next page is included such that you don't have to
hardcode or construct any links. Only values and next are guaranteed
(except the last page, which lacks next). This is because the previous
and size values can be expensive for some data sets.
It is important to realize that Bitbucket support both list-based
pagination and iterator-based pagination. List-based pagination assumes
that the collection is a discrete, immutable, consistently ordered,
finite array of objects with a fixed size. Clients navigate a list-based
collection by requesting offset-based chunks. In Bitbucket Cloud,
list-based responses include the optional size, page, and previous
element. The the next and previous links typically resemble something
like /foo/bar?page=4.
However, not all result sets can be treated as immutable and finite –
much like how programming languages tend to distinguish between lists
and arrays on one hand and iterators or stream on the other. Where an
list-based pagination offers random access into any point in a
collection, iterator-based pagination can only navigate forward one
element at a time. In Bitbucket such iterator-based pagination contains
the next link and pagelen elements, but not necessarily anything else.
In these cases, the next link's value often contains an unpredictable
hash instead of an explicit page number. The commits resource uses
iterator-based pagination.
- anchor: partial-response
title: Partial responses
description: Tweak which fields are returned
icon: >-
data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgMTYyLjQ0ODcgMjEwLjExMTUiPgogIDxkZWZzPgogICAgPHN0eWxlPgogICAgICAuY2xzLTEgewogICAgICAgIGlzb2xhdGlvbjogaXNvbGF0ZTsKICAgICAgfQoKICAgICAgLmNscy0yLCAuY2xzLTYsIC5jbHMtOCB7CiAgICAgICAgZmlsbDogbm9uZTsKICAgICAgfQoKICAgICAgLmNscy0yLCAuY2xzLTggewogICAgICAgIHN0cm9rZTogIzAwNjVmZjsKICAgICAgICBzdHJva2Utd2lkdGg6IDJweDsKICAgICAgfQoKICAgICAgLmNscy0yIHsKICAgICAgICBzdHJva2UtbGluZWpvaW46IHJvdW5kOwogICAgICB9CgogICAgICAuY2xzLTMgewogICAgICAgIGZpbGw6ICNlN2U4ZWM7CiAgICAgIH0KCiAgICAgIC5jbHMtNCB7CiAgICAgICAgZmlsbDogI2ZmZTM4MDsKICAgICAgfQoKICAgICAgLmNscy01IHsKICAgICAgICBmaWxsOiAjZmZmMGIyOwogICAgICB9CgogICAgICAuY2xzLTYgewogICAgICAgIHN0cm9rZTogI2ZmOTkxZjsKICAgICAgICBzdHJva2Utd2lkdGg6IDEuODE1NnB4OwogICAgICB9CgogICAgICAuY2xzLTYsIC5jbHMtOCB7CiAgICAgICAgc3Ryb2tlLW1pdGVybGltaXQ6IDEwOwogICAgICB9CgogICAgICAuY2xzLTcgewogICAgICAgIG1peC1ibGVuZC1tb2RlOiBtdWx0aXBseTsKICAgICAgICBmaWxsOiB1cmwoI2xpbmVhci1ncmFkaWVudCk7CiAgICAgIH0KCiAgICAgIC5jbHMtOSB7CiAgICAgICAgZmlsbDogI2Y0ZjVmNzsKICAgICAgfQogICAgPC9zdHlsZT4KICAgIDxsaW5lYXJHcmFkaWVudCBpZD0ibGluZWFyLWdyYWRpZW50IiB4MT0iMTEzLjM4MTgiIHkxPSI0OS40MyIgeDI9IjE1My43ODkzIiB5Mj0iOS4wMjI1IiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+CiAgICAgIDxzdG9wIG9mZnNldD0iMCIgc3RvcC1jb2xvcj0iI2ZhZmJmYyIvPgogICAgICA8c3RvcCBvZmZzZXQ9IjAuMjc4NiIgc3RvcC1jb2xvcj0iI2VmZjFmMyIvPgogICAgICA8c3RvcCBvZmZzZXQ9IjAuNzY4OCIgc3RvcC1jb2xvcj0iI2QxZDZkZCIvPgogICAgICA8c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNjMWM3ZDAiLz4KICAgIDwvbGluZWFyR3JhZGllbnQ+CiAgPC9kZWZzPgogIDx0aXRsZT5Eb2N1bWVudCBUYWJsZTwvdGl0bGU+CiAgPGcgY2xhc3M9ImNscy0xIj4KICAgIDxnIGlkPSJMYXllcl8yIiBkYXRhLW5hbWU9IkxheWVyIDIiPgogICAgICA8ZyBpZD0iT2JqZWN0cyI+CiAgICAgICAgPGxpbmUgY2xhc3M9ImNscy0yIiB4MT0iMTcuNDcxIiB5MT0iMTcxLjc1NzMiIHgyPSI3OS4yOTgiIHkyPSIxNzEuNzU3MyIvPgogICAgICAgIDxwb2x5Z29uIGlkPSJfUGF0aF8iIGRhdGEtbmFtZT0iJmx0O1BhdGgmZ3Q7IiBjbGFzcz0iY2xzLTMiIHBvaW50cz0iMTYyLjQ0NSAzOC43MTEgMTYyLjQ0NSAyMTAuMTExIDAgMjEwLjExMSAwIDAgMTIzLjcwNCAwIDE2Mi40MTUgMzguNzExIDE2Mi40NDUgMzguNzExIi8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy00IiB4PSIxOC45MTE3IiB5PSI3OC4xNTQyIiB3aWR0aD0iNDcuODQ4NSIgaGVpZ2h0PSI3OS42NTM3Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy01IiB4PSIxOC45MTE3IiB5PSI1MS42MDMiIHdpZHRoPSIxMjMuNDUyOSIgaGVpZ2h0PSIyNi41NTEyIi8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy02IiB4PSIxOC45MTE3IiB5PSI1MS42MDMiIHdpZHRoPSIxMjMuNDUyOSIgaGVpZ2h0PSIxMDYuMjA0OSIvPgogICAgICAgIDxsaW5lIGNsYXNzPSJjbHMtNiIgeDE9IjY2Ljc2MDEiIHkxPSI1MS42MDMiIHgyPSI2Ni43NjAxIiB5Mj0iMTU3LjgwNzkiLz4KICAgICAgICA8bGluZSBjbGFzcz0iY2xzLTYiIHgxPSI5MS4zMjg0IiB5MT0iNTEuNjAzIiB4Mj0iOTEuMzI4NCIgeTI9IjE1Ny44MDc5Ii8+CiAgICAgICAgPGxpbmUgY2xhc3M9ImNscy02IiB4MT0iMTE1Ljg5NjciIHkxPSI1MS42MDMiIHgyPSIxMTUuODk2NyIgeTI9IjE1Ny44MDc5Ii8+CiAgICAgICAgPGxpbmUgY2xhc3M9ImNscy02IiB4MT0iMTguOTExNyIgeTE9Ijc4LjE1NDIiIHgyPSIxNDIuMzY0NiIgeTI9Ijc4LjE1NDIiLz4KICAgICAgICA8bGluZSBjbGFzcz0iY2xzLTYiIHgxPSIxOC45MTE3IiB5MT0iMTA0LjcwNTUiIHgyPSIxNDIuMzY0NiIgeTI9IjEwNC43MDU1Ii8+CiAgICAgICAgPGxpbmUgY2xhc3M9ImNscy02IiB4MT0iMTguOTExNyIgeTE9IjEzMS4yNTY3IiB4Mj0iMTQyLjM2NDYiIHkyPSIxMzEuMjU2NyIvPgogICAgICAgIDxwb2x5Z29uIGNsYXNzPSJjbHMtNyIgcG9pbnRzPSIxNjIuNDQ1IDM4LjcxMSAxNjIuNDE1IDM4LjcxMSAxMjMuODcyIDAuMTY5IDEyMy44NzIgNTkuOTIxIDE2Mi40NDUgMzkuMTM3IDE2Mi40NDUgMzguNzExIi8+CiAgICAgICAgPGxpbmUgY2xhc3M9ImNscy04IiB4MT0iMTguMzk3MyIgeTE9IjE4MS4zNDQiIHgyPSI3OS4xMTM1IiB5Mj0iMTgxLjM0NCIvPgogICAgICAgIDxsaW5lIGNsYXNzPSJjbHMtOCIgeDE9IjE4LjM5NzMiIHkxPSIxOTAuOTMwNiIgeDI9IjUxLjMwNDkiIHkyPSIxOTAuOTMwNiIvPgogICAgICAgIDxsaW5lIGNsYXNzPSJjbHMtOCIgeDE9IjE4LjM5NzMiIHkxPSIxNzEuNzU3MyIgeDI9Ijc5LjExMzUiIHkyPSIxNzEuNzU3MyIvPgogICAgICAgIDxsaW5lIGNsYXNzPSJjbHMtOCIgeDE9IjE4LjM5NzMiIHkxPSIzNi4xNzA1IiB4Mj0iNzkuMTEzNSIgeTI9IjM2LjE3MDUiLz4KICAgICAgICA8bGluZSBjbGFzcz0iY2xzLTgiIHgxPSIxOC4zOTczIiB5MT0iMjYuNTgzOCIgeDI9Ijc5LjExMzUiIHkyPSIyNi41ODM4Ii8+CiAgICAgICAgPHBvbHlnb24gY2xhc3M9ImNscy05IiBwb2ludHM9IjE2Mi40NDkgMzguNzQyIDEyMy43MDcgMzguNzQyIDEyMy43MDcgMCAxNjIuNDQ5IDM4Ljc0MiIvPgogICAgICA8L2c+CiAgICA8L2c+CiAgPC9nPgo8L3N2Zz4K'
body: >2
By default, each endpoint returns the full representation of a resource
and in
some cases that can be a lot of data. For example, retrieving a list of
pull
requests can amount to quite a large document.
For better performance, you can ask the server to only return the fields
you
really need and to omit unwanted data. To request a partial response and
to
add or remove specific fields from a response, use the `fields` query
parameter.
### Example
Most API resources embed a substantial list of links pointing to related
resources. This saves the client from constructing its own URLs, but is
somewhat wasteful when the client doesn't need them.
To significantly reduce the size of the response, use `?fields=-links`:
```json
$ curl https://api.bitbucket.org/2.0/users/evzijst?fields=-links
{
"nickname": "evzijst",
"account_status": "active",
"website": "",
"display_name": "Erik van Zijst",
"uuid": "{a288a0ab-e13b-43f0-a689-c4ef0a249875}",
"created_on": "2010-07-07T05:16:36+00:00",
"location": null,
"type": "user"
}
```
### Fields parameter syntax
The `fields` parameter supports 3 modes of operation:
1. Removal of select fields (e.g. `-links`)
2. Pulling in additional fields not normally returned by an endpoint,
while
still getting all the default fields (e.g. `+reviewers`)
3. Omitting all fields, except those specified (e.g.
`owner.display_name`)
The fields parameter can contain a list of multiple comma-separated
field names
(e.g. `fields=owner.display_name,uuid,links.self.href`). The parameter
itself is
not repeated.
As discussed at [Condensed Versus Full
Objects](serialization#representations),
most objects that are embedded inside other objects (like how `owner` is
an
embedded `user` object in `repository`) appear in "condensed" form that
omits
many fields. The `fields` parameter allows us to pull in additional
fields in
such cases.
For example, the embedded repository object in a pull request does not
normally
contain its `owner`. To add that in we can use:
`+values.destination.repository.owner`.
### Wildcards
The asterisk can be used to match all fields on a particular level. For
example, removing all entries from the `links` element can be done like
this:
```json
$ curl https://api.bitbucket.org/2.0/users/evzijst?fields=-links.*
{
"nickname": "evzijst",
"account_status": "active",
"website": "",
"display_name": "Erik van Zijst",
"uuid": "{a288a0ab-e13b-43f0-a689-c4ef0a249875}",
"links": {},
"created_on": "2010-07-07T05:16:36+00:00",
"location": null,
"type": "user"
}
```
Wildcards can be used in combination with exclusion and inclusion. For
instance, `-*,+foo,+bar` will remove all elements from the root level
and then
add in `foo` and `bar`.
### URL encoding
Be aware that when using the `+foo.bar` syntax in the query string, that
the
"+" must be URL encoded as "%2B" and so the URL will be:
```
https://api.bitbucket.org/2.0/repositories/evzijst/interruptingcow?fields=%2Bowner.created_on
```
Without URL escaping, "+" is interpreted as an encoded space which will
not
match any fields.
### Field discovery
While a resource's `self` URL, as well its "collection" URL typically
return
the full object with all its fields, there are some exceptions for
fields that
are overly verbose or costly to generate.
For instance, a pull request contains the embedded lists of reviewers
and
participants. These fields are included from the `self` URL, but not
from the
`/pullrequests` collections resource, as it would impact performance too
much.
To discover any additional fields that might not be included by default,
`fields=*` can be used.
### More examples
If we want to get a list of all reviewer nicknames on pull requests I
created,
we could combine a [filter](filtering) with a partial response. This
will omit
all other data from the response:
```
/2.0/repositories/bitbucket/bitbucket/pullrequests?fields=values.id,values.reviewers.nickname,values.state&q=author.uuid%3D%22%7Bd301aafa-d676-4ee0-88be-962be7417567%7D%22
{
"values": [
{
"reviewers": [
{
"nickname": "abhin"
},
{
"nickname": "dtao"
},
{
"nickname": "csomme"
}
],
"state": "OPEN",
"id": 11355
},
{
"reviewers": [
{
"nickname": "csomme"
},
{
"nickname": "abhin"
},
{
"nickname": "dstevens"
}
],
"state": "MERGED",
"id": 11347
},
{
"reviewers": [
{
"nickname": "csomme"
},
{
"nickname": "jmooring"
},
{
"nickname": "zdavis"
},
{
"nickname": "flexbox"
}
],
"state": "OPEN",
"id": 11344
}
]
}
```
- anchor: serialization
title: Schemas and Serialization
description: Learn more about object representations
icon: >-
data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyMjAuNzYyNCAyMDUuNTg2Ij4KICA8ZGVmcz4KICAgIDxzdHlsZT4KICAgICAgLmNscy0xIHsKICAgICAgICBpc29sYXRpb246IGlzb2xhdGU7CiAgICAgIH0KCiAgICAgIC5jbHMtMiwgLmNscy02IHsKICAgICAgICBtaXgtYmxlbmQtbW9kZTogbXVsdGlwbHk7CiAgICAgIH0KCiAgICAgIC5jbHMtMTMsIC5jbHMtMywgLmNscy00LCAuY2xzLTYgewogICAgICAgIGZpbGw6IG5vbmU7CiAgICAgICAgc3Ryb2tlOiAjYzFjN2QwOwogICAgICAgIHN0cm9rZS1saW5lY2FwOiByb3VuZDsKICAgICAgICBzdHJva2UtbWl0ZXJsaW1pdDogMTA7CiAgICAgICAgc3Ryb2tlLXdpZHRoOiAycHg7CiAgICAgIH0KCiAgICAgIC5jbHMtNCB7CiAgICAgICAgc3Ryb2tlLWRhc2hhcnJheTogMy43ODE2IDUuMjk0MzsKICAgICAgfQoKICAgICAgLmNscy01IHsKICAgICAgICBmaWxsOiAjMDA2NWZmOwogICAgICB9CgogICAgICAuY2xzLTYgewogICAgICAgIHN0cm9rZS1kYXNoYXJyYXk6IDMuOTIxOSA1LjQ5MDc7CiAgICAgIH0KCiAgICAgIC5jbHMtNyB7CiAgICAgICAgZmlsbDogIzAwNTJjYzsKICAgICAgfQoKICAgICAgLmNscy04IHsKICAgICAgICBmaWxsOiAjNGM5YWZmOwogICAgICB9CgogICAgICAuY2xzLTkgewogICAgICAgIGZpbGw6ICMwMDQ5YjA7CiAgICAgIH0KCiAgICAgIC5jbHMtMTAgewogICAgICAgIGZpbGw6ICM1N2Q5YTM7CiAgICAgIH0KCiAgICAgIC5jbHMtMTEgewogICAgICAgIGZpbGw6ICM3OWYyYzA7CiAgICAgIH0KCiAgICAgIC5jbHMtMTIgewogICAgICAgIGZpbGw6ICMzNmIzN2U7CiAgICAgIH0KCiAgICAgIC5jbHMtMTMgewogICAgICAgIHN0cm9rZS1kYXNoYXJyYXk6IDMuODY4MSA1LjQxNTQ7CiAgICAgIH0KCiAgICAgIC5jbHMtMTQgewogICAgICAgIGZpbGw6ICM0MjUyNmU7CiAgICAgIH0KCiAgICAgIC5jbHMtMTUgewogICAgICAgIGZpbGw6ICMzNDQ1NjM7CiAgICAgIH0KCiAgICAgIC5jbHMtMTYgewogICAgICAgIGZpbGw6ICM1MDVmNzk7CiAgICAgIH0KICAgIDwvc3R5bGU+CiAgPC9kZWZzPgogIDx0aXRsZT5JbnRlZ3JhdGlvbnM8L3RpdGxlPgogIDxnIGNsYXNzPSJjbHMtMSI+CiAgICA8ZyBpZD0iTGF5ZXJfMiIgZGF0YS1uYW1lPSJMYXllciAyIj4KICAgICAgPGcgaWQ9Ik9iamVjdHMiPgogICAgICAgIDxnIGNsYXNzPSJjbHMtMiI+CiAgICAgICAgICA8Zz4KICAgICAgICAgICAgPGxpbmUgY2xhc3M9ImNscy0zIiB4MT0iNzUuMjExNCIgeTE9IjE4Ny44NTczIiB4Mj0iNzcuMDI0OCIgeTI9IjE4Ny4xMTA5Ii8+CiAgICAgICAgICAgIDxsaW5lIGNsYXNzPSJjbHMtNCIgeDE9IjgxLjkyMDUiIHkxPSIxODUuMDk1NiIgeDI9IjEzOC4yMjEyIiB5Mj0iMTYxLjkyMDMiLz4KICAgICAgICAgICAgPGxpbmUgY2xhc3M9ImNscy0zIiB4MT0iMTQwLjY2OSIgeTE9IjE2MC45MTI2IiB4Mj0iMTQyLjQ4MjQiIHkyPSIxNjAuMTY2MiIvPgogICAgICAgICAgPC9nPgogICAgICAgIDwvZz4KICAgICAgICA8cG9seWdvbiBjbGFzcz0iY2xzLTUiIHBvaW50cz0iMTk0LjUyNiAyNi41NTIgMTc2LjkwMSAzOC4yNDEgMTU5LjI3IDI2LjU1MiAxNzYuOTAxIDE0Ljg3IDE5NC41MjYgMjYuNTUyIi8+CiAgICAgICAgPGxpbmUgY2xhc3M9ImNscy02IiB4MT0iMTgzLjcxMzUiIHkxPSI0My4yMTg4IiB4Mj0iMTgzLjcxMzUiIHkyPSI5Ny44ODMyIi8+CiAgICAgICAgPHBvbHlnb24gY2xhc3M9ImNscy03IiBwb2ludHM9IjE3Ni45MDEgMzguMjQxIDE3Ni45MDEgNTguMTY2IDE1OS4yNyA0Ni40NzcgMTU5LjI3IDI2LjU1MiAxNzYuOTAxIDM4LjI0MSIvPgogICAgICAgIDxwb2x5Z29uIGNsYXNzPSJjbHMtOCIgcG9pbnRzPSIxOTQuNTI2IDI2LjU1MiAxOTQuNTI2IDQ2LjQ3NyAxNzYuOTAxIDU4LjE2NiAxNzYuOTAxIDM4LjI0MSAxOTQuNTI2IDI2LjU1MiIvPgogICAgICAgIDxsaW5lIGNsYXNzPSJjbHMtNiIgeDE9IjQ3Ljk0ODgiIHkxPSI0Mi4yMTg4IiB4Mj0iMTU5LjExNzIiIHkyPSI0Mi4yMTg4Ii8+CiAgICAgICAgPHBvbHlnb24gY2xhc3M9ImNscy01IiBwb2ludHM9IjIyMC43NjIgOTkuNzUyIDE2Ny44MTcgMTM0Ljg2NCAxMTQuODU0IDk5Ljc1MiAxNjcuODE3IDY0LjY1NyAyMjAuNzYyIDk5Ljc1MiIvPgogICAgICAgIDxwb2x5Z29uIGNsYXNzPSJjbHMtOSIgcG9pbnRzPSIxNjcuODE3IDEzNC44NjQgMTY3LjgxNyAxOTQuNzE4IDExNC44NTQgMTU5LjYwNiAxMTQuODU0IDk5Ljc1MiAxNjcuODE3IDEzNC44NjQiLz4KICAgICAgICA8cG9seWdvbiBjbGFzcz0iY2xzLTgiIHBvaW50cz0iMjIwLjc2MiA5OS43NTIgMjIwLjc2MiAxNTkuNjA2IDE2Ny44MTcgMTk0LjcxOCAxNjcuODE3IDEzNC44NjQgMjIwLjc2MiA5OS43NTIiLz4KICAgICAgICA8cG9seWdvbiBjbGFzcz0iY2xzLTEwIiBwb2ludHM9IjExMC41NDEgMjEuNjA0IDc3Ljk0OSA0My4yMTkgNDUuMzQ1IDIxLjYwNCA3Ny45NDkgMCAxMTAuNTQxIDIxLjYwNCIvPgogICAgICAgIDxwb2x5Z29uIGNsYXNzPSJjbHMtMTEiIHBvaW50cz0iMTEwLjU0MSAyMS42MDQgMTEwLjU0MSA1OC40NDkgNzcuOTQ5IDgwLjA2NCA3Ny45NDkgNDMuMjE5IDExMC41NDEgMjEuNjA0Ii8+CiAgICAgICAgPHBvbHlnb24gY2xhc3M9ImNscy01IiBwb2ludHM9IjE0MS4xOSAxNDguMDczIDE2Ny44MTMgMTMwLjQxNyAxOTQuNDQ0IDE0OC4wNzMgMTY3LjgxMyAxNjUuNzE5IDE0MS4xOSAxNDguMDczIi8+CiAgICAgICAgPHBvbHlnb24gY2xhc3M9ImNscy05IiBwb2ludHM9IjE2Ny44MTMgMTMwLjQxNyAxNjcuODEzIDEwMC4zMjEgMTk0LjQ0NCAxMTcuOTc2IDE5NC40NDQgMTQ4LjA3MyAxNjcuODEzIDEzMC40MTciLz4KICAgICAgICA8cG9seWdvbiBjbGFzcz0iY2xzLTgiIHBvaW50cz0iMTQxLjE5IDE0OC4wNzMgMTQxLjE5IDExNy45NzYgMTY3LjgxMyAxMDAuMzIxIDE2Ny44MTMgMTMwLjQxNyAxNDEuMTkgMTQ4LjA3MyIvPgogICAgICAgIDxwb2x5Z29uIGNsYXNzPSJjbHMtMTIiIHBvaW50cz0iNDUuMzQ1IDIxLjYwNCA0NS4zNDUgNDQuOTg0IDU3LjIzMSA1Mi44NjQgNTcuMjMxIDY2LjI5NiA3Ny45NDkgODAuMDY0IDc3Ljk0OSA0My4yMTkgNDUuMzQ1IDIxLjYwNCIvPgogICAgICAgIDxnIGNsYXNzPSJjbHMtMiI+CiAgICAgICAgICA8Zz4KICAgICAgICAgICAgPGxpbmUgY2xhc3M9ImNscy0zIiB4MT0iMjQuNjQzOCIgeTE9Ijg2Ljk1NDQiIHgyPSIyNi4wMTU3IiB5Mj0iODUuNTUzMSIvPgogICAgICAgICAgICA8bGluZSBjbGFzcz0iY2xzLTEzIiB4MT0iMjkuODA0IiB5MT0iODEuNjgzNCIgeDI9IjYwLjM4MTEiIHkyPSI1MC40NDkyIi8+CiAgICAgICAgICAgIDxsaW5lIGNsYXNzPSJjbHMtMyIgeDE9IjYyLjI3NTIiIHkxPSI0OC41MTQzIiB4Mj0iNjMuNjQ3IiB5Mj0iNDcuMTEzIi8+CiAgICAgICAgICA8L2c+CiAgICAgICAgPC9nPgogICAgICAgIDxwb2x5Z29uIGNsYXNzPSJjbHMtNSIgcG9pbnRzPSIzNS4yNTUgODkuNjQ1IDE3LjczNiAxMDEuNDkyIDAgODkuOTYyIDE3LjUyNSA3OC4xMjEgMzUuMjU1IDg5LjY0NSIvPgogICAgICAgIDxwb2x5Z29uIGNsYXNzPSJjbHMtNyIgcG9pbnRzPSIxNy43MzYgMTAxLjQ5MiAxNy45MTUgMTIxLjQxNiAwLjE3OSAxMDkuODg3IDAgODkuOTYyIDE3LjczNiAxMDEuNDkyIi8+CiAgICAgICAgPGxpbmUgY2xhc3M9ImNscy02IiB4MT0iMjAuNTg0OSIgeTE9IjEwNS41MzA1IiB4Mj0iNjUuODc0OSIgeTI9IjE3MS4zNjgxIi8+CiAgICAgICAgPHBvbHlnb24gY2xhc3M9ImNscy04IiBwb2ludHM9IjM1LjI1NSA4OS42NDUgMzUuNDM0IDEwOS41NjkgMTcuOTE1IDEyMS40MTYgMTcuNzM2IDEwMS40OTIgMzUuMjU1IDg5LjY0NSIvPgogICAgICAgIDxwb2x5Z29uIGNsYXNzPSJjbHMtMTQiIHBvaW50cz0iOTIuMzk0IDE3My44MTUgNzQuODc1IDE4NS42NjIgNTcuMTM5IDE3NC4xMzIgNzQuNjY0IDE2Mi4yOTEgOTIuMzk0IDE3My44MTUiLz4KICAgICAgICA8cG9seWdvbiBjbGFzcz0iY2xzLTE1IiBwb2ludHM9Ijc0Ljg3NSAxODUuNjYyIDc1LjA1NCAyMDUuNTg2IDU3LjMxOSAxOTQuMDU3IDU3LjEzOSAxNzQuMTMyIDc0Ljg3NSAxODUuNjYyIi8+CiAgICAgICAgPHBvbHlnb24gY2xhc3M9ImNscy0xNiIgcG9pbnRzPSI5Mi4zOTQgMTczLjgxNSA5Mi41NzQgMTkzLjczOSA3NS4wNTQgMjA1LjU4NiA3NC44NzUgMTg1LjY2MiA5Mi4zOTQgMTczLjgxNSIvPgogICAgICA8L2c+CiAgICA8L2c+CiAgPC9nPgo8L3N2Zz4K'
body: >2
-
* [Open API Specification](#open-api-specification)
* [JSON Schema](#json-schema)
* [Condensed Versus Full Objects](#condensed-versus-full-objects)
____
### Open API Specification
Bitbucket uses the [Open API Specification](https://openapis.org) (OAI,
formerly known as Swagger) to describe its APIs. Our OAI specification
schema
is hosted at
[https://api.bitbucket.org/swagger.json](https://api.bitbucket.org/swagger.json)
and serves as the canonical definition and comprehensive declaration of
all
available endpoints.
The OAI specification makes writing client applications easier by:
auto-generating boilerplate code (like data object classes) and dealing
with
authentication and error handling.
You can find a comprehensive set of open tools for the OAI specification
at:
[https://github.com/swagger-api](https://github.com/swagger-api).
### JSON Schema
Bitbucket uses JSON Schema to describe the layout of every type of
object
consumed or produced by the API. These schemas are collected under the
`#definitions` element of our swagger.json file.
When an endpoint expects an object as part of a POST or PUT, it also
expects
the object to validate against the JSON schemas. The same applies to
objects
returned by an endpoint.
### Condensed Versus Full Objects
Most objects in Bitbucket come both in "full" and "partial"
representation.
The full representation is when all elements are included. This is the
layout
returned by a resource's `self` location (e.g.
`/2.0/repositories/foo/bar`),
as well as resource collection endpoints (e.g. `/2.0/repositories`).
However, Bitbucket objects often embed other objects. For example, a
`repository`
object embeds a `user` object for its owner. Likewise, a `pullrequest`
object
embeds its `repository` object.
These related objects are embedded, or inlined, to reduce the "chatter"
when
clients make frequent followup API calls to collect information on
common,
related information.
Embedded related objects are typically limited in their fields to avoid
such
object graphs from becoming too deep and noisy. They often exclude their
own
nested objects in an attempt to strike a balance between performance and
utility.
An object's embedded or condensed representation tends to be
standardized,
meaning the fields included is the same set, regardless of where the
object
was embedded.
- anchor: uri-uuid
title: URI, UUID, and structures
description: URL's, UUID's, errors, and timestamps
icon: >-
data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgMTc5LjI2IDE3Ny42NSI+PGRlZnM+PHN0eWxlPi5jbHMtMXtmaWxsOnVybCgjbGluZWFyLWdyYWRpZW50KTt9LmNscy0ye2ZpbGw6IzA5MWU0Mjt9LmNscy0xMCwuY2xzLTExLC5jbHMtMywuY2xzLTQsLmNscy05e2ZpbGw6bm9uZTt9LmNscy0ze3N0cm9rZTojOTljMWZmO30uY2xzLTMsLmNscy00e3N0cm9rZS1saW5lY2FwOnJvdW5kO3N0cm9rZS1saW5lam9pbjpyb3VuZDtzdHJva2Utd2lkdGg6MDt9LmNscy0xMiwuY2xzLTQsLmNscy05e3N0cm9rZTojZTVlOGVjO30uY2xzLTV7ZmlsbDojMzQ0NTYzO30uY2xzLTZ7ZmlsbDojZmY4YjAwO30uY2xzLTd7ZmlsbDojZmZjNDAwO30uY2xzLTh7ZmlsbDojMDA2NWZmO30uY2xzLTEwLC5jbHMtMTEsLmNscy0xMiwuY2xzLTEzLC5jbHMtOXtzdHJva2UtbWl0ZXJsaW1pdDoxMDtzdHJva2Utd2lkdGg6MnB4O30uY2xzLTEwe3N0cm9rZTojZmZhYjAwO30uY2xzLTExLC5jbHMtMTN7c3Ryb2tlOiMwMDY1ZmY7fS5jbHMtMTJ7ZmlsbDojOTljMWZmO30uY2xzLTEze2ZpbGw6I2U1ZThlYzt9PC9zdHlsZT48bGluZWFyR3JhZGllbnQgaWQ9ImxpbmVhci1ncmFkaWVudCIgeDE9IjAuNCIgeTE9IjE3OC4wNSIgeDI9IjE3OC44NSIgeTI9Ii0wLjQiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj48c3RvcCBvZmZzZXQ9IjAiIHN0b3AtY29sb3I9IiMwOTFlNDIiLz48c3RvcCBvZmZzZXQ9IjAuMDciIHN0b3AtY29sb3I9IiMwZDIyNDUiLz48c3RvcCBvZmZzZXQ9IjAuNDkiIHN0b3AtY29sb3I9IiMxZjMyNTMiLz48c3RvcCBvZmZzZXQ9IjAuNzkiIHN0b3AtY29sb3I9IiMyNTM4NTgiLz48L2xpbmVhckdyYWRpZW50PjwvZGVmcz48dGl0bGU+Q29kZTwvdGl0bGU+PGcgaWQ9IkxheWVyXzIiIGRhdGEtbmFtZT0iTGF5ZXIgMiI+PGcgaWQ9IlNvZnR3YXJlIj48cmVjdCBpZD0iX1JlY3RhbmdsZV8iIGRhdGEtbmFtZT0iJmx0O1JlY3RhbmdsZSZndDsiIGNsYXNzPSJjbHMtMSIgd2lkdGg9IjE3OS4yNiIgaGVpZ2h0PSIxNzcuNjUiLz48cGF0aCBjbGFzcz0iY2xzLTIiIGQ9Ik0xNzkuMjYsMjYuNjRIMFY3MS43NUExNjYuNDEsMTY2LjQxLDAsMCwwLDYzLjI0LDU5LjUxYTE4OC40MSwxODguNDEsMCwwLDAsMTcuMzktOC4zNmMxOC40NC05LjQzLDQ4LjM3LTE3LjksOTguNjItMTNabS0xNTkuNDQsMzRoMFptMC0xNC4wOGgwWiIvPjxsaW5lIGNsYXNzPSJjbHMtMyIgeDE9IjE5LjgxIiB5MT0iNDYuNTgiIHgyPSIyNS4wNyIgeTI9IjQ2LjU4Ii8+PGxpbmUgY2xhc3M9ImNscy0zIiB4MT0iMjUuMDciIHkxPSI2MC42NiIgeDI9IjE5LjgxIiB5Mj0iNjAuNjYiLz48bGluZSBjbGFzcz0iY2xzLTMiIHgxPSIxOS44MSIgeTE9Ijc0Ljc0IiB4Mj0iMjUuMDciIHkyPSI3NC43NCIvPjxsaW5lIGNsYXNzPSJjbHMtMyIgeDE9IjI1LjA3IiB5MT0iODguODIiIHgyPSIxOS44MSIgeTI9Ijg4LjgyIi8+PGxpbmUgY2xhc3M9ImNscy0zIiB4MT0iMjUuMDciIHkxPSIxMDIuODkiIHgyPSIxOS44MSIgeTI9IjEwMi44OSIvPjxsaW5lIGNsYXNzPSJjbHMtMyIgeDE9IjI1LjA3IiB5MT0iMTE2Ljk3IiB4Mj0iMTkuODEiIHkyPSIxMTYuOTciLz48bGluZSBjbGFzcz0iY2xzLTMiIHgxPSIyNS4wNyIgeTE9IjEzMS4wNSIgeDI9IjE5LjgxIiB5Mj0iMTMxLjA1Ii8+PGxpbmUgY2xhc3M9ImNscy0zIiB4MT0iMjUuMDciIHkxPSIxNDUuMTMiIHgyPSIxOS44MSIgeTI9IjE0NS4xMyIvPjxsaW5lIGNsYXNzPSJjbHMtMyIgeDE9IjI1LjA3IiB5MT0iMTU5LjIxIiB4Mj0iMTkuODEiIHkyPSIxNTkuMjEiLz48bGluZSBjbGFzcz0iY2xzLTQiIHgxPSI1NS44OSIgeTE9IjEzMS4wNSIgeDI9IjkzLjk5IiB5Mj0iMTMxLjA1Ii8+PGxpbmUgY2xhc3M9ImNscy00IiB4MT0iNTUuODkiIHkxPSIxNDUuMTMiIHgyPSIxMzkuNjciIHkyPSIxNDUuMTMiLz48cmVjdCBjbGFzcz0iY2xzLTUiIHdpZHRoPSIxNzkuMjYiIGhlaWdodD0iMjYuNjQiLz48Y2lyY2xlIGNsYXNzPSJjbHMtNiIgY3g9IjEzLjUiIGN5PSIxMi4wOCIgcj0iNS4xMSIvPjxjaXJjbGUgY2xhc3M9ImNscy03IiBjeD0iMzAuMTgiIGN5PSIxMi4wOCIgcj0iNS4xMSIvPjxjaXJjbGUgY2xhc3M9ImNscy04IiBjeD0iNDYuODYiIGN5PSIxMi4wOCIgcj0iNS4xMSIvPjxwYXRoIGNsYXNzPSJjbHMtOSIgZD0iTTc1LjQxLDg4LjgyIi8+PHBhdGggY2xhc3M9ImNscy05IiBkPSJNMzIuODksODguODIiLz48bGluZSBjbGFzcz0iY2xzLTEwIiB4MT0iMzIuODkiIHkxPSI3NC43NCIgeDI9Ijc1LjQxIiB5Mj0iNzQuNzQiLz48bGluZSBjbGFzcz0iY2xzLTExIiB4MT0iMzIuODkiIHkxPSI2MC42NiIgeDI9Ijc1LjQxIiB5Mj0iNjAuNjYiLz48bGluZSBjbGFzcz0iY2xzLTkiIHgxPSIzMi44OSIgeTE9IjQ2LjU4IiB4Mj0iNTUuODkiIHkyPSI0Ni41OCIvPjxsaW5lIGNsYXNzPSJjbHMtMTIiIHgxPSIxOS44MSIgeTE9IjQ2LjU4IiB4Mj0iMjUuMDciIHkyPSI0Ni41OCIvPjxsaW5lIGNsYXNzPSJjbHMtMTIiIHgxPSIxOS44MSIgeTE9IjYwLjY2IiB4Mj0iMjUuMDciIHkyPSI2MC42NiIvPjxsaW5lIGNsYXNzPSJjbHMtMTIiIHgxPSIxOS44MSIgeTE9Ijc0Ljc0IiB4Mj0iMjUuMDciIHkyPSI3NC43NCIvPjxsaW5lIGNsYXNzPSJjbHMtMTIiIHgxPSIxOS44MSIgeTE9Ijg4LjgyIiB4Mj0iMjUuMDciIHkyPSI4OC44MiIvPjxsaW5lIGNsYXNzPSJjbHMtMTIiIHgxPSIxOS44MSIgeTE9IjEwMi44OSIgeDI9IjI1LjA3IiB5Mj0iMTAyLjg5Ii8+PGxpbmUgY2xhc3M9ImNscy0xMiIgeDE9IjE5LjgxIiB5MT0iMTE2Ljk3IiB4Mj0iMjUuMDciIHkyPSIxMTYuOTciLz48bGluZSBjbGFzcz0iY2xzLTEyIiB4MT0iMTkuODEiIHkxPSIxMzEuMDUiIHgyPSIyNS4wNyIgeTI9IjEzMS4wNSIvPjxsaW5lIGNsYXNzPSJjbHMtMTIiIHgxPSIxOS44MSIgeTE9IjE0NS4xMyIgeDI9IjI1LjA3IiB5Mj0iMTQ1LjEzIi8+PGxpbmUgY2xhc3M9ImNscy0xMiIgeDE9IjE5LjgxIiB5MT0iMTU5LjIxIiB4Mj0iMjUuMDciIHkyPSIxNTkuMjEiLz48bGluZSBpZD0iX0xpbmVfIiBkYXRhLW5hbWU9IiZsdDtMaW5lJmd0OyIgY2xhc3M9ImNscy0xMCIgeDE9Ijg0LjI0IiB5MT0iMTE2Ljk3IiB4Mj0iMTU2LjY1IiB5Mj0iMTE2Ljk3Ii8+PHBhdGggY2xhc3M9ImNscy05IiBkPSJNMzIuODksMTE3aDBaIi8+PGxpbmUgY2xhc3M9ImNscy0xMCIgeDE9IjEwMiIgeTE9IjEzMS4wNSIgeDI9IjE2My42MiIgeTI9IjEzMS4wNSIvPjxsaW5lIGNsYXNzPSJjbHMtMTMiIHgxPSI1NS44OSIgeTE9IjEzMS4wNSIgeDI9IjkzLjk5IiB5Mj0iMTMxLjA1Ii8+PGxpbmUgY2xhc3M9ImNscy0xMyIgeDE9IjU1Ljg5IiB5MT0iMTQ1LjEzIiB4Mj0iMTM5LjY3IiB5Mj0iMTQ1LjEzIi8+PGxpbmUgY2xhc3M9ImNscy05IiB4MT0iNzguOSIgeTE9IjE1OS4yMSIgeDI9IjExMy41MSIgeTI9IjE1OS4yMSIvPjxsaW5lIGNsYXNzPSJjbHMtOSIgeDE9IjU5LjYxIiB5MT0iODguODIiIHgyPSI5OS4zMyIgeTI9Ijg4LjgyIi8+PGxpbmUgY2xhc3M9ImNscy05IiB4MT0iNTkuNjEiIHkxPSIxMDIuODkiIHgyPSI5OS4zMyIgeTI9IjEwMi44OSIvPjxjaXJjbGUgY2xhc3M9ImNscy02IiBjeD0iMTMuNSIgY3k9IjEyLjA4IiByPSI1LjExIi8+PGNpcmNsZSBjbGFzcz0iY2xzLTciIGN4PSIzMC4xOCIgY3k9IjEyLjA4IiByPSI1LjExIi8+PGNpcmNsZSBjbGFzcz0iY2xzLTgiIGN4PSI0Ni44NiIgY3k9IjEyLjA4IiByPSI1LjExIi8+PC9nPjwvZz48L3N2Zz4='
body: >2
You should be familiar with REST architecture before writing an
integration. Read this overview page to gain a good understanding of
Bitbucket's REST implementation.
-
* [URI structure](#uri-structure)
* [HTTP methods](#http-methods)
* [UUID](#universally-unique-identifier)
* [User object and UUID](#user-object-and-uuid)
* [Repository object and UUID](#repository-object-and-uuid)
* [Team object and UUID](#team-object-and-uuid)
* [Standard error responses](#standardized-error-responses)
* [Standard ISO-8601 timestamps](#standard-iso-8601-timestamps)
-
### URI structure
All Bitbucket Cloud requests start with the
`https://api.bitbucket.org/2.0` prefix (for the 2.0 API) and
`https://api.bitbucket.org/1.0` prefix (1.0 API).
The next segment of the URI path depends on the endpoint of the request.
For example, using the curl command and the repositories endpoint you
can list all the issues on Bitbucket's tutorial repository:
```
curl
https://api.bitbucket.org/2.0/repositories/tutorials/tutorials.bitbucket.org
```
Given a specific endpoint, you can then drill down to a particular
aspect or resource of that endpoint. The issues resource on a repository
is an example:
```
curl
https://api.bitbucket.org/1.0/repositories/tutorials/tutorials.bitbucket.org/issues
```
#### HTTP methods
A given endpoint or resource has a series of actions (or methods)
associated with it. The Bitbucket service supports these standard HTTP
methods:
| Call | Description |
||-|
| GET | Retrieves information. |
| PUT | Updates existing information. |
| POST | Creates new information. |
| DELETE | Removes existing information. |
For example, you can call use the POST action on the issues resource and
create an issue on the issue tracker.
**Specifying content length**
You can get a `411 Length Required` response. If this happens, the API
requires a Content-Length header but the client is not sending it. You
should add the header yourself, for example using the curl client:
```
curl -r PUT --header "Content-Length: 0" -u user:app_password
https://api.bitbucket.org/1.0/emails/rap@atlassian.com
```
### Universally Unique Identifier
UUID's provide a single point of recognition for users, teams, and
repositories. The UUID is distinct from the username, team name, and
repository name fields and remains the same even when those fields
change. For example when a user changes their username or moves a
repository you will need to modify calls which use those identifiers but
not if you are pointing to the UUID.
#### UUID examples and structure
UUID's work with both the 1.0 and 2.0 APIs for the user, team, and
repository objects. The following examples the following characters are
replacements for curly brackets: `%7B` replaces `{` and `%7D` replaces
`}`. You will see this structure in the following example sections.
#### User object and UUID
When you make a call using either the username or the UUID for that user
the response is the same.
**Call with username**:
```
curl https://api.bitbucket.org/2.0/users/tutorials
```
***Call with UUID for the user**:
```
curl
https://api.bitbucket.org/2.0/users/%7Bc788b2da-b7a2-404c-9e26-d3f077557007%7D
```
**Response**
```JSON
{
"username": "tutorials",
"nickname": "tutorials",
"account_status": "active",
"website": "https://tutorials.bitbucket.org/",
"display_name": "tutorials account",
"uuid": "{c788b2da-b7a2-404c-9e26-d3f077557007}",
"links": {
"self": {
"href": "https://api.bitbucket.org/2.0/users/tutorials"
},
"repositories": {
"href": "https://api.bitbucket.org/2.0/repositories/tutorials"
},
"html": {
"href": "https://bitbucket.org/tutorials"
},
"followers": {
"href": "https://api.bitbucket.org/2.0/users/tutorials/followers"
},
"avatar": {
"href": "https://bitbucket-assetroot.s3.amazonaws.com/c/photos/2013/Nov/25/tutorials-avatar-1563784409-6_avatar.png"
},
"following": {
"href": "https://api.bitbucket.org/2.0/users/tutorials/following"
}
},
"created_on": "2011-12-20T16:34:07.132459+00:00",
"location": "Santa Monica, CA",
"type": "user"
}
```
#### Repository object and UUID
Once you have the UUID for a repository you no longer need a username or
team name to make the API call so long as you use an empty field. This
helps you resolve repositories no matter if the username or team name
changes.
**Call with team name (1team) and repository name (moxie)**:
```
curl https://api.bitbucket.org/2.0/repositories/1team/moxie
```
**Call with UUID and empty field**:
```
curl
https://api.bitbucket.org/2.0/repositories/%7B%7D/%7B21fa9bf8-b5b2-4891-97ed-d590bad0f871%7D
```
**Call with UUID and teamname**:
```
curl
https://api.bitbucket.org/2.0/repositories/1team/%7B21fa9bf8-b5b2-4891-97ed-d590bad0f871%7D
```
**Response**
```JSON
{
"created_on": "2013-11-08T01:11:03.222520+00:00",
"description": "",
"fork_policy": "allow_forks",
"full_name": "1team/moxie",
"has_issues": false,
"has_wiki": false,
"is_private": false,
"language": "",
"links": {
"avatar": {
"href": "https://bitbucket.org/1team/moxie/avatar/32/"
},
"branches": {
"href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/refs/branches"
},
"clone": [
{
"href": "https://bitbucket.org/1team/moxie.git",
"name": "https"
},
{
"href": "ssh://git@bitbucket.org/1team/moxie.git",
"name": "ssh"
}
],
"commits": {
"href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/commits"
},
"downloads": {
"href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/downloads"
},
"forks": {
"href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/forks"
},
"hooks": {
"href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/hooks"
},
"html": {
"href": "https://bitbucket.org/1team/moxie"
},
"pullrequests": {
"href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/pullrequests"
},
"self": {
"href": "https://api.bitbucket.org/2.0/repositories/1team/moxie"
},
"tags": {
"href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/refs/tags"
},
"watchers": {
"href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/watchers"
}
},
"name": "moxie",
"owner": {
"display_name": "the team",
"links": {
"avatar": {
"href": "https://bitbucket.org/account/1team/avatar/32/"
},
"html": {
"href": "https://bitbucket.org/1team/"
},
"self": {
"href": "https://api.bitbucket.org/2.0/teams/1team"
}
},
"type": "team",
"username": "1team",
"uuid": "{aa559944-83c9-4963-a9a8-69ac8d9cf5d2}"
},
"project": {
"key": "PROJ",
"links": {
"avatar": {
"href": "https://bitbucket.org/account/user/1team/projects/PROJ/avatar/32"
},
"html": {
"href": "https://bitbucket.org/account/user/1team/projects/PROJ"
}
},
"name": "Untitled project",
"type": "project",
"uuid": "{ab52aaeb-16ad-4fb0-bb1d-47e4f00367ff}"
},
"scm": "git",
"size": 33348,
"type": "repository",
"updated_on": "2013-11-08T01:11:03.263237+00:00",
"uuid": "{21fa9bf8-b5b2-4891-97ed-d590bad0f871}",
"website": ""
}
```
#### Team object and UUID
This example shows a call for a list of team members using both the team
name and with the UUID for the team object. As the call is
unauthenticated in the following example the response object will only
show members with public profiles. The response is the same in either
case.
**Call with teamname**
```
curl https://api.bitbucket.org/2.0/teams/1team/members
```
**Call with UUID for team object**
```
curl
https://api.bitbucket.org/2.0/teams/%7Baa559944-83c9-4963-a9a8-69ac8d9cf5d2%7D/members
```
**Response**
```JSON
{
"page": 1,
"pagelen": 50,
"size": 2,
"values": [
{
"created_on": "2011-12-20T16:34:07.132459+00:00",
"display_name": "tutorials account",
"links": {
"avatar": {
"href": "https://bitbucket.org/account/tutorials/avatar/32/"
},
"followers": {
"href": "https://api.bitbucket.org/2.0/users/tutorials/followers"
},
"following": {
"href": "https://api.bitbucket.org/2.0/users/tutorials/following"
},
"hooks": {
"href": "https://api.bitbucket.org/2.0/users/tutorials/hooks"
},
"html": {
"href": "https://bitbucket.org/tutorials/"
},
"repositories": {
"href": "https://api.bitbucket.org/2.0/repositories/tutorials"
},
"self": {
"href": "https://api.bitbucket.org/2.0/users/tutorials"
},
"snippets": {
"href": "https://api.bitbucket.org/2.0/snippets/tutorials"
}
},
"location": null,
"type": "user",
"username": "tutorials",
"nickname": "tutorials",
"account_status": "active",
"uuid": "{c788b2da-b7a2-404c-9e26-d3f077557007}",
"website": "https://tutorials.bitbucket.org/"
},
{
"created_on": "2013-12-10T14:44:13+00:00",
"display_name": "Dan Stevens [Atlassian]",
"links": {
"avatar": {
"href": "https://bitbucket.org/account/dans9190/avatar/32/"
},
"followers": {
"href": "https://api.bitbucket.org/2.0/users/dans9190/followers"
},
"following": {
"href": "https://api.bitbucket.org/2.0/users/dans9190/following"
},
"hooks": {
"href": "https://api.bitbucket.org/2.0/users/dans9190/hooks"
},
"html": {
"href": "https://bitbucket.org/dans9190/"
},
"repositories": {
"href": "https://api.bitbucket.org/2.0/repositories/dans9190"
},
"self": {
"href": "https://api.bitbucket.org/2.0/users/dans9190"
},
"snippets": {
"href": "https://api.bitbucket.org/2.0/snippets/dans9190"
}
},
"location": null,
"type": "user",
"username": "dans9190",
"nickname": "dans9190",
"account_status": "active",
"uuid": "{1cd06601-cd0e-4fce-be03-e9ac226978b7}",
"website": ""
}
]
}
```
### Standardized error responses
The 2.0 API standardizes the error response layout. The 2.0 API serves a
JSON
object along with the appropriate HTTP status code. The JSON object
provides a
detailed problem description.
```json
{
"type": "error",
"error": {
"message": "Bad request",
"fields": {
"src": [
"This field is required."
]
},
"detail": "You must specify a valid source branch when creating a pull request.",
"id": "d23a1cc5178f7637f3d9bf2d13824258",
"data": {
"extra": "Optional, endpoint-specific data to further augment the error."
}
}
}
```
This object contains an error element which contains the following
nested
elements:
| Element | Description |
||-|
| message | A short description of the problem. This element is always
present. Its value may be localized. |
| fields | This optional element is used in response to POST or PUT
operations in which clients have provided invalid input. It contains a
list of one or more client-provided fields that failed validation. The
values may be localized. |
| detail | An optional detailed explanation of the failure. Its value
may be localized.
| id | An optional unique error identifier that identifies the
error in Bitbucket's logging system. If you feel you hit a bug in an API
and this field is provided, please mention it if you decide to contact
support as it will greatly help us narrow down the problem. |
### Standard ISO-8601 timestamps
All 2.0 APIs use standardized ISO-8601 timestamps. In most cases, our
APIs return UTC timestamps and for these, the timezone offset part will
be 00:00. In rare cases where the original localized timestamp has
significance, the timezone offset may identify the event's original
timezone.
- anchor: cors-hypermedia
title: Cors and hypermedia
description: Learn about resources and linking
icon: >-
data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgMjM2LjYgMjE4LjQzIj48ZGVmcz48c3R5bGU+LmNscy0xe2lzb2xhdGlvbjppc29sYXRlO30uY2xzLTIsLmNscy0zLC5jbHMtNHtmaWxsOm5vbmU7c3Ryb2tlLWxpbmVjYXA6cm91bmQ7c3Ryb2tlLW1pdGVybGltaXQ6MTA7c3Ryb2tlLXdpZHRoOjExcHg7fS5jbHMtMntzdHJva2U6dXJsKCNsaW5lYXItZ3JhZGllbnQpO30uY2xzLTN7c3Ryb2tlOnVybCgjTmV3X0dyYWRpZW50X1N3YXRjaF8xNCk7fS5jbHMtNHtzdHJva2U6dXJsKCNOZXdfR3JhZGllbnRfU3dhdGNoXzEpO30uY2xzLTV7ZmlsbDojNDI1MjZlO30uY2xzLTZ7ZmlsbDojZmY1NjMwO30uY2xzLTEwLC5jbHMtNywuY2xzLTh7bWl4LWJsZW5kLW1vZGU6bXVsdGlwbHk7fS5jbHMtN3tmaWxsOnVybCgjbGluZWFyLWdyYWRpZW50LTIpO30uY2xzLTh7ZmlsbDp1cmwoI2xpbmVhci1ncmFkaWVudC0zKTt9LmNscy05e2ZpbGw6IzAwNjVmZjt9LmNscy0xMHtmaWxsOnVybCgjbGluZWFyLWdyYWRpZW50LTQpO308L3N0eWxlPjxsaW5lYXJHcmFkaWVudCBpZD0ibGluZWFyLWdyYWRpZW50IiB5MT0iMTY3Ljg3IiB4Mj0iMTkxLjU2IiB5Mj0iMTY3Ljg3IiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+PHN0b3Agb2Zmc2V0PSIwIiBzdG9wLWNvbG9yPSIjNTA1Zjc5Ii8+PHN0b3Agb2Zmc2V0PSIxIiBzdG9wLWNvbG9yPSIjMzQ0NTYzIi8+PC9saW5lYXJHcmFkaWVudD48bGluZWFyR3JhZGllbnQgaWQ9Ik5ld19HcmFkaWVudF9Td2F0Y2hfMTQiIHgxPSIxMTIuODMiIHkxPSIxMzEuNzIiIHgyPSIyMzYuNiIgeTI9IjEzMS43MiIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIG9mZnNldD0iMCIgc3RvcC1jb2xvcj0iIzAwNTJjYyIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iIzI2ODRmZiIvPjwvbGluZWFyR3JhZGllbnQ+PGxpbmVhckdyYWRpZW50IGlkPSJOZXdfR3JhZGllbnRfU3dhdGNoXzEiIHgxPSI0NS4wNiIgeTE9Ijg2LjY5IiB4Mj0iMTY4Ljg4IiB5Mj0iODYuNjkiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj48c3RvcCBvZmZzZXQ9IjAiIHN0b3AtY29sb3I9IiNkZTM1MGIiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNmZjc0NTIiLz48L2xpbmVhckdyYWRpZW50PjxsaW5lYXJHcmFkaWVudCBpZD0ibGluZWFyLWdyYWRpZW50LTIiIHgxPSIzNDQ3LjkzIiB5MT0iLTkxOC43OSIgeDI9IjM0NTEuNCIgeTI9Ii0xMDMyLjc2IiBncmFkaWVudFRyYW5zZm9ybT0idHJhbnNsYXRlKC01NzIuMzggMzcwNC4yOSkgcm90YXRlKC02NC4zNCkiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj48c3RvcCBvZmZzZXQ9IjAuMzEiIHN0b3AtY29sb3I9IiNjMWM3ZDAiIHN0b3Atb3BhY2l0eT0iMCIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iI2MxYzdkMCIvPjwvbGluZWFyR3JhZGllbnQ+PGxpbmVhckdyYWRpZW50IGlkPSJsaW5lYXItZ3JhZGllbnQtMyIgeDE9IjM1MDYuNiIgeTE9Ii03OTYuNjYiIHgyPSIzNTEwLjA3IiB5Mj0iLTkxMC42MyIgeGxpbms6aHJlZj0iI2xpbmVhci1ncmFkaWVudC0yIi8+PGxpbmVhckdyYWRpZW50IGlkPSJsaW5lYXItZ3JhZGllbnQtNCIgeDE9IjM1ODEuNjgiIHkxPSItOTA2LjgyIiB4Mj0iMzU4NS4xNiIgeTI9Ii0xMDIwLjc5IiB4bGluazpocmVmPSIjbGluZWFyLWdyYWRpZW50LTIiLz48L2RlZnM+PHRpdGxlPldlYmhvb2tzPC90aXRsZT48ZyBjbGFzcz0iY2xzLTEiPjxnIGlkPSJMYXllcl8yIiBkYXRhLW5hbWU9IkxheWVyIDIiPjxnIGlkPSJTb2Z0d2FyZSI+PHBhdGggY2xhc3M9ImNscy0yIiBkPSJNMTg2LjA2LDE2Ny44N0gxMTcuNzJBMjcuNTgsMjcuNTgsMCwwLDAsOTIuMjQsMTg1YTQ1LjA2LDQ1LjA2LDAsMSwxLTQxLjY4LTYyLjE5Ii8+PHBhdGggY2xhc3M9ImNscy0zIiBkPSJNMTE4LjMzLDUwLjUybDM0LjE1LDU5LjE4YTI3LjU5LDI3LjU5LDAsMCwwLDI3LjU4LDEzLjUxLDQ1LjA2LDQ1LjA2LDAsMSwxLTMzLDY3LjE5Ii8+PHBhdGggY2xhc3M9ImNscy00IiBkPSJNNTAuNTYsMTY3Ljg3bDM0LjE4LTU5LjE2YTI3LjU5LDI3LjU5LDAsMCwwLTIuMDktMzAuNjQsNDUuMDYsNDUuMDYsMCwxLDEsNzQuNy01Ii8+PHBhdGggY2xhc3M9ImNscy01IiBkPSJNMTg2LjA2LDE5OS42NmEzMS43OSwzMS43OSwwLDEsMSwzMS43OS0zMS43OUEzMS44MiwzMS44MiwwLDAsMSwxODYuMDYsMTk5LjY2WiIvPjxnIGlkPSJfR3JvdXBfIiBkYXRhLW5hbWU9IiZsdDtHcm91cCZndDsiPjxwYXRoIGNsYXNzPSJjbHMtNiIgZD0iTTQ5LjU2LDE5OS42NGEzMS43OSwzMS43OSwwLDEsMSwzMi43Ny0zMC43N0EzMS44MiwzMS44MiwwLDAsMSw0OS41NiwxOTkuNjRaIi8+PC9nPjxwYXRoIGNsYXNzPSJjbHMtNyIgZD0iTTU0LjEyLDE4MC4zNmE1OC45LDU4LjksMCwwLDAtMS41OS0xMS4yN3MtMi4zNS05LjQ0LTcuMzMtMTYuODNhNDMuODksNDMuODksMCwwLDAtMTEuNzMtMTEuMTcsMzEuNzcsMzEuNzcsMCwwLDAsMjkuMjgsNTYuMTNDNTguMjksMTkyLjQ0LDU0LjY4LDE4Ni45LDU0LjEyLDE4MC4zNloiLz48cGF0aCBjbGFzcz0iY2xzLTgiIGQ9Ik0xODkuNjIsMTgwLjM2QTU4LjksNTguOSwwLDAsMCwxODgsMTY5LjA4cy0yLjM1LTkuNDQtNy4zMy0xNi44M0E0My44OSw0My44OSwwLDAsMCwxNjksMTQxLjA4YTMxLjc3LDMxLjc3LDAsMCwwLDI5LjI4LDU2LjEzQzE5My43OSwxOTIuNDQsMTkwLjE4LDE4Ni45LDE4OS42MiwxODAuMzZaIi8+PGcgaWQ9Il9Hcm91cF8yIiBkYXRhLW5hbWU9IiZsdDtHcm91cCZndDsiPjxwYXRoIGNsYXNzPSJjbHMtOSIgZD0iTTg5LjksMzMuNzhhMzIuNDYsMzIuNDYsMCwxLDEsMTEuODgsNDQuMzRBMzIuNDksMzIuNDksMCwwLDEsODkuOSwzMy43OFoiLz48L2c+PHBhdGggY2xhc3M9ImNscy0xMCIgZD0iTTEyMi4yMyw2Ni4xM2E1OC45LDU4LjksMCwwLDAtMS41OS0xMS4yN3MtMi4zNS05LjQ0LTcuMzMtMTYuODNjLTMuMzctNS05LjA2LTkuNzktMTUuNDMtMTMuNDhBMzIuNDQsMzIuNDQsMCwwLDAsMTI4Ljc3LDgwLjZDMTI1LjMxLDc2LjM5LDEyMi43LDcxLjYxLDEyMi4yMyw2Ni4xM1oiLz48L2c+PC9nPjwvZz48L3N2Zz4='
body: >2
This section describes [Cross-origin resource
sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)
(CORS), what content types we support in requests and responses, and
hyperlinking resources in each json responses.
-
* [CORS](#cors)
* [Supported content types](#supported-content-types)
* [Resource links](#resource-links)
-
### Cors
The Bitbucket API supports Cross-origin resource sharing to allow
requests for restricted resources across domains. For more information
you can refer to:
* [Wikipedia article on
CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)
* [W3C CORS recommendation](https://www.w3.org/TR/cors/)
Sending a general request from the api to bitbucket.com:
`curl -i https://api.bitbucket.org -H "origin: http://bitbucket.com"`
Gives this result:
HTTP/1.1 302 FOUND
Server: nginx/1.6.2
Vary: Cookie
Cache-Control: max-age=900
Content-Type: text/html; charset=utf-8
Strict-Transport-Security: max-age=31536000
Date: Tue, 21 Jun 2016 17:54:37 GMT
Location: http://confluence.atlassian.com/x/IYBGDQ
X-Served-By: app-110
X-Static-Version: 2c820eb0d2b3
ETag: "d41d8cd98f00b204e9800998ecf8427e"
X-Content-Type-Options: nosniff
X-Render-Time: 0.00379920005798
Connection: Keep-Alive
X-Version: 2c820eb0d2b3
X-Frame-Options: SAMEORIGIN
X-Request-Count: 383
X-Cache-Info: cached
Content-Length: 0
Sending the same request with the CORS check -X OPTIONS in the call:
`curl -i https://api.bitbucket.org -H "origin: http://bitbucket.com" -X
OPTIONS`
Gives this result:
HTTP/1.1 302 FOUND
Server: nginx/1.6.2
Vary: Cookie
Cache-Control: max-age=900
Content-Type: text/html; charset=utf-8
Access-Control-Expose-Headers: Accept-Ranges, Content-Encoding, Content-Length, Content-Type, ETag, Last-Modified
Strict-Transport-Security: max-age=31536000
Date: Tue, 21 Jun 2016 18:04:30 GMT
Access-Control-Max-Age: 86400
Location: http://confluence.atlassian.com/x/IYBGDQ
X-Served-By: app-111
Access-Control-Allow-Origin: *
X-Static-Version: 2c820eb0d2b3
ETag: "d41d8cd98f00b204e9800998ecf8427e"
X-Content-Type-Options: nosniff
X-Render-Time: 0.00371098518372
Connection: keep-alive
X-Version: 2c820eb0d2b3
X-Frame-Options: SAMEORIGIN
X-Request-Count: 357
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Accept, Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, Origin, Range, X-CsrftokenX-Requested-With
X-Cache-Info: not cacheable; request wasn't a GET or HEAD
Content-Length: 0
### Supported content types
The default and primary content type for 2.0 APIs is JSON. This applies
both to responses from the server and to the request bodies provided by
the client.
Unless documented otherwise, whenever creating a new (POST) or modifying
an existing (PUT) object, your client must provide the object's normal
representation. Not every object element can be mutated. For example, a
repository's created_on date is an auto-generated, immutable field. Your
client can omit immutable fields from a request body.
In some cases, a resource might also accept regular
application/x-www-url-form-encoded POST and PUT bodies. Such bodies can
be more convenient in scripts and command line usage. Requests bodies
can contain contain nested elements or they can be flat (without nested
elements). Clients can send flat request bodies as either as
application/json or as application/x-www-url-form-encoded. Nested
objects always require JSON.
### Resource links
Every 2.0 object contains a links element that points to related
resources or alternate representations. Use links to quickly discover
and traverse to related objects. Links serve a "self-documenting"
function for each endpoint. For example, the following request for a
specific user:
`$ curl https://api.bitbucket.org/2.0/users/tutorials`
```json
{
"username": "tutorials",
"nickname": "tutorials",
"account_status": "active",
"website": "https://tutorials.bitbucket.org/",
"display_name": "tutorials account",
"uuid": "{c788b2da-b7a2-404c-9e26-d3f077557007}",
"links": {
"self": {
"href": "https://api.bitbucket.org/2.0/users/tutorials"
},
"repositories": {
"href": "https://api.bitbucket.org/2.0/repositories/tutorials"
},
"html": {
"href": "https://bitbucket.org/tutorials"
},
"followers": {
"href": "https://api.bitbucket.org/2.0/users/tutorials/followers"
},
"avatar": {
"href": "https://bitbucket-assetroot.s3.amazonaws.com/c/photos/2013/Nov/25/tutorials-avatar-1563784409-6_avatar.png"
},
"following": {
"href": "https://api.bitbucket.org/2.0/users/tutorials/following"
}
},
"created_on": "2011-12-20T16:34:07.132459+00:00",
"location": "Santa Monica, CA",
"type": "user"
}
```
Links can be actual REST API resources or they can be informational. In
this example, informative resources include the user's avatar and the
HTML URL for the user's Bitbucket account. Your client should avoid
hardcoding an API's URL and instead use the URLs returned in API
responses.
A link's key is its `rel` (relationship) attribute and it contains a
mandatory href element. For example, the following link:
```json
"self": {
"href": "https://api.bitbucket.org/api/2.0/users/tutorials"
}
```
The rel for this link is self and the href is
https://api.bitbucket.org/api/2.0/users/tutorials. A single rel key can
contain an list (array) of href objects. Your client should anticipate
that any rel key can contain one or more href objects.
Finally, links can also contain optional elements. Two common optional
elements are the name element and the title element. They are often used
to disambiguate links that share the same rel key. In the example below,
the repository object that contains a clone link with two href objects.
Each object contains the optional name element to clarify its use.
```json
"links": {
"self": {
"href": "https://api.bitbucket.org/2.0/repositories/evzijst/bitbucket"
},
"clone": [
{
"href": "https://api.bitbucket.org/evzijst/bitbucket.git",
"name": "https"
},
{
"href": "ssh://git@bitbucket.org/erik/bitbucket.git",
"name": "ssh"
}
],
...
}
```
Links can support [URI Templates](https://tools.ietf.org/html/rfc6570);
Those that do contain a `"templated": "true"` element.
- anchor: bb-connect
title: Atlassian Connect
description: Build Bitbucket add-ons with Connect
icon: >-
data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgMjU3LjMxNjMgMTYyLjU5OTQiPgogIDxkZWZzPgogICAgPHN0eWxlPgogICAgICAuY2xzLTEgewogICAgICAgIGlzb2xhdGlvbjogaXNvbGF0ZTsKICAgICAgfQoKICAgICAgLmNscy0yIHsKICAgICAgICBmaWxsOiAjMzQ0NTYzOwogICAgICB9CgogICAgICAuY2xzLTMgewogICAgICAgIGZpbGw6ICMxZGI5ZDQ7CiAgICAgIH0KCiAgICAgIC5jbHMtNCB7CiAgICAgICAgZmlsbDogIzAwNTdkODsKICAgICAgfQoKICAgICAgLmNscy01LCAuY2xzLTcsIC5jbHMtOSB7CiAgICAgICAgbWl4LWJsZW5kLW1vZGU6IG11bHRpcGx5OwogICAgICB9CgogICAgICAuY2xzLTUgewogICAgICAgIGZpbGw6IHVybCgjTjc1KTsKICAgICAgfQoKICAgICAgLmNscy02IHsKICAgICAgICBmaWxsOiAjMDA2NWZmOwogICAgICB9CgogICAgICAuY2xzLTcgewogICAgICAgIGZpbGw6IHVybCgjTjc1LTIpOwogICAgICB9CgogICAgICAuY2xzLTggewogICAgICAgIGZpbGw6IHVybCgjbGluZWFyLWdyYWRpZW50KTsKICAgICAgfQoKICAgICAgLmNscy05IHsKICAgICAgICBmaWxsOiB1cmwoI043NS0zKTsKICAgICAgfQoKICAgICAgLmNscy0xMCB7CiAgICAgICAgZmlsbDogdXJsKCNUMjAwLVQ3NSk7CiAgICAgIH0KICAgIDwvc3R5bGU+CiAgICA8bGluZWFyR3JhZGllbnQgaWQ9Ik43NSIgeDE9Ii0yMTg5LjU1NiIgeTE9IjI4MDguMjI4NCIgeDI9Ii0yMDkxLjE1NTEiIHkyPSIyODA4LjIyODQiIGdyYWRpZW50VHJhbnNmb3JtPSJtYXRyaXgoMC4xNjgxLCAwLjk4NTgsIDAuOTg1OCwgLTAuMTY4MSwgLTIzNzMuNzM2LCAyNzIyLjEyNzgpIiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+CiAgICAgIDxzdG9wIG9mZnNldD0iMCIgc3RvcC1jb2xvcj0iI2U1ZThlYyIvPgogICAgICA8c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNlNWU4ZWMiIHN0b3Atb3BhY2l0eT0iMC4xIi8+CiAgICA8L2xpbmVhckdyYWRpZW50PgogICAgPGxpbmVhckdyYWRpZW50IGlkPSJONzUtMiIgZGF0YS1uYW1lPSJONzUiIHgxPSItMjE2OC41OTQ3IiB5MT0iMjkzNS4wNTU2IiB4Mj0iLTIwNzAuMTkzNyIgeTI9IjI5MzUuMDU1NiIgeGxpbms6aHJlZj0iI043NSIvPgogICAgPGxpbmVhckdyYWRpZW50IGlkPSJsaW5lYXItZ3JhZGllbnQiIHgxPSIxOTAuMzU0NyIgeTE9IjE1OS45NjciIHgyPSIyNTkuOTQ4NyIgeTI9IjkwLjM3MyIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPgogICAgICA8c3RvcCBvZmZzZXQ9IjAiIHN0b3AtY29sb3I9IiMzNDQ1NjMiLz4KICAgICAgPHN0b3Agb2Zmc2V0PSIxIiBzdG9wLWNvbG9yPSIjNWU2Yzg0Ii8+CiAgICA8L2xpbmVhckdyYWRpZW50PgogICAgPGxpbmVhckdyYWRpZW50IGlkPSJONzUtMyIgZGF0YS1uYW1lPSJONzUiIHgxPSItMjI1Ny4zOTc3IiB5MT0iMjg4NC4yMjYzIiB4Mj0iLTIxNTguOTk2NyIgeTI9IjI4ODQuMjI2MyIgeGxpbms6aHJlZj0iI043NSIvPgogICAgPGxpbmVhckdyYWRpZW50IGlkPSJUMjAwLVQ3NSIgeDE9IjEyNi4wMjU3IiB5MT0iODUuMTA4IiB4Mj0iMTk1LjYxOTciIHkyPSIxNS41MTQiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj4KICAgICAgPHN0b3Agb2Zmc2V0PSIwIiBzdG9wLWNvbG9yPSIjM2RjN2RjIi8+CiAgICAgIDxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iIzljZTNlZSIvPgogICAgPC9saW5lYXJHcmFkaWVudD4KICA8L2RlZnM+CiAgPHRpdGxlPkFkZCBPbiBCbG9ja3MgMjwvdGl0bGU+CiAgPGcgY2xhc3M9ImNscy0xIj4KICAgIDxnIGlkPSJMYXllcl8yIiBkYXRhLW5hbWU9IkxheWVyIDIiPgogICAgICA8ZyBpZD0iT2JqZWN0cyI+CiAgICAgICAgPHJlY3QgaWQ9Il9SZWN0YW5nbGVfIiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTIiIHg9IjEyOC42NTgxIiB5PSI4Ny43NDA1IiB3aWR0aD0iNjQuMzI5MSIgaGVpZ2h0PSI3NC44NTkiLz4KICAgICAgICA8cmVjdCBpZD0iX1JlY3RhbmdsZV8yIiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTMiIHg9IjY0LjMyOTEiIHk9IjEyLjg4MTUiIHdpZHRoPSI2NC4zMjkxIiBoZWlnaHQ9Ijc0Ljg1OSIvPgogICAgICAgIDxyZWN0IGlkPSJfUmVjdGFuZ2xlXzMiIGRhdGEtbmFtZT0iJmx0O1JlY3RhbmdsZSZndDsiIGNsYXNzPSJjbHMtNCIgeT0iODcuNzQwNSIgd2lkdGg9IjY0LjMyOTEiIGhlaWdodD0iNzQuODU5Ii8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy01IiBkPSJNNjQuMzI5MSw4Ny43NEg1OC42NTIzYTYyLjc4NzcsNjIuNzg3NywwLDAsMC0yNC41Njg0LDIwLjc2MjFjLTguMjYwNywxMi4xOTYtNC4zNDM3LDE4LjI0MTUtMTEuNjYzNywzMS42Mzk1QzE2LjUxLDE1MC45Niw4LjA1MSwxNTcuODIsMCwxNjIuNTU2di4wNDM1aDY0LjMyOVoiLz4KICAgICAgICA8cmVjdCBpZD0iX1JlY3RhbmdsZV80IiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTYiIHg9IjY0LjMyOTEiIHk9Ijg3Ljc0MDUiIHdpZHRoPSI2NC4zMjkxIiBoZWlnaHQ9Ijc0Ljg1OSIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtNyIgZD0iTTE5Mi45ODcyLDg3Ljc0SDE4My4zNDNhNjIuNzg3Nyw2Mi43ODc3LDAsMCwwLTI0LjU2ODQsMjAuNzYyMWMtOC4yNjA3LDEyLjE5Ni00LjM0MzgsMTguMjQxNS0xMS42NjM3LDMxLjYzOTVhNTYuNzI0Niw1Ni43MjQ2LDAsMCwxLTE4LjQ1MjcsMTkuOTF2Mi41NDc0aDY0LjMyOVoiLz4KICAgICAgICA8cmVjdCBjbGFzcz0iY2xzLTgiIHg9IjE5Mi45ODcyIiB5PSI4Ny43NDA1IiB3aWR0aD0iNjQuMzI5MSIgaGVpZ2h0PSI3NC44NTkiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTkiIGQ9Ik0xMjguNjU4MiwxMi44ODE1SDExNi41OUE2MS45NjQ2LDYxLjk2NDYsMCwwLDAsMTAxLjMyMzMsMjguMjE1QzkzLjA2MjUsNDAuNDEwOSw5Ni45Nzk0LDQ2LjQ1NjUsODkuNjYsNTkuODU0NCw4My4wMzE2LDcxLjk4NTcsNzMuMTk3LDc5LjE1MTQsNjQuMzI5MSw4My45MTA4djMuODNoNjQuMzI5MVoiLz4KICAgICAgICA8cmVjdCBjbGFzcz0iY2xzLTEwIiB4PSIxMjguNjU4MSIgeT0iMTIuODgxNSIgd2lkdGg9IjY0LjMyOTEiIGhlaWdodD0iNzQuODU5Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy00IiB4PSIxMC4xNjA1IiB5PSI3NC44NTkiIHdpZHRoPSIyNC43NTM2IiBoZWlnaHQ9IjEyLjg4MTUiLz4KICAgICAgICA8cmVjdCBjbGFzcz0iY2xzLTQiIHg9IjUxLjk1MjMiIHk9Ijc0Ljg1OSIgd2lkdGg9IjI0Ljc1MzYiIGhlaWdodD0iMTIuODgxNSIvPgogICAgICAgIDxyZWN0IGNsYXNzPSJjbHMtNCIgeD0iOTMuNzQ0MSIgeT0iNzQuODU5IiB3aWR0aD0iMjQuNzUzNiIgaGVpZ2h0PSIxMi44ODE1Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy0yIiB4PSIxMzguODE4NiIgeT0iNzQuODU5IiB3aWR0aD0iMjQuNzUzNiIgaGVpZ2h0PSIxMi44ODE1Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy0yIiB4PSIxODAuNjEwNCIgeT0iNzQuODU5IiB3aWR0aD0iMjQuNzUzNiIgaGVpZ2h0PSIxMi44ODE1Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy0yIiB4PSIyMjIuNDAyMiIgeT0iNzQuODU5IiB3aWR0aD0iMjQuNzUzNiIgaGVpZ2h0PSIxMi44ODE1Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy0zIiB4PSI3NC40ODk1IiB3aWR0aD0iMjQuNzUzNiIgaGVpZ2h0PSIxMi44ODE1Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy0zIiB4PSIxMTYuMjgxNCIgd2lkdGg9IjI0Ljc1MzYiIGhlaWdodD0iMTIuODgxNSIvPgogICAgICAgIDxyZWN0IGNsYXNzPSJjbHMtMyIgeD0iMTU4LjA3MzIiIHdpZHRoPSIyNC43NTM2IiBoZWlnaHQ9IjEyLjg4MTUiLz4KICAgICAgPC9nPgogICAgPC9nPgogIDwvZz4KPC9zdmc+Cg=='
body: >2
You can use the Atlassian Connect for Bitbucket Cloud to build add-ons
which
can connect with the Bitbucket UI and your own application set. An
add-on could
be an integration with another existing service, new features for the
Atlassian
application, or even a new product that runs within the Atlassian
application.
For complete information see:
[Atlassian Connect for Bitbucket
Cloud](https://developer.atlassian.com/bitbucket/index.html)
servers:
- url: https://api.bitbucket.org/2.0
components:
schemas:
paginated_repository_user_permissions:
type: object
title: Paginated Repository User Permissions
description: A paginated list of repository user permissions.
properties:
size:
type: integer
description: >-
Total number of objects in the response. This is an optional element
that is not provided in all responses, as it can be expensive to
compute.
minimum: 0
page:
type: integer
description: >-
Page number of the current results. This is an optional element that
is not provided in all responses.
minimum: 1
pagelen:
type: integer
description: >-
Current number of objects on the existing page. The default value is
10 with 100 being the maximum allowed value. Individual APIs may
enforce different values.
minimum: 1
next:
type: string
description: >-
Link to the next page if it exists. The last page of a collection
does not have this value. Use this link to navigate the result set
and refrain from constructing your own URLs.
format: uri
previous:
type: string
description: >-
Link to previous page if it exists. A collections first page does
not have this value. This is an optional element that is not
provided in all responses. Some result sets strictly support forward
navigation and never provide previous links. Clients must anticipate
that backwards navigation is not always available. Use this link to
navigate the result set and refrain from constructing your own URLs.
format: uri
values:
type: array
items:
$ref: '#/components/schemas/repository_user_permission'
minItems: 0
uniqueItems: true
additionalProperties: false
repository_user_permission:
type: object
title: Repository User Permission
description: A user's direct permission for a given repository.
properties:
type:
type: string
permission:
type: string
enum:
- read
- write
- admin
- none
user:
$ref: '#/components/schemas/user'
repository:
$ref: '#/components/schemas/repository'
links:
type: object
properties:
self:
type: object
title: Link
description: A link to a resource related to this object.
properties:
href:
type: string
format: uri
name:
type: string
additionalProperties: false
additionalProperties: false
required:
- type
additionalProperties: true
account:
allOf:
- $ref: '#/components/schemas/object'
- type: object
title: Account
description: An account object.
properties:
links:
$ref: '#/components/schemas/account_links'
created_on:
type: string
format: date-time
display_name:
type: string
username:
type: string
pattern: ^[a-zA-Z0-9_\-]+$
uuid:
type: string
additionalProperties: true
error:
type: object
title: Error
description: >-
Base type for most resource objects. It defines the common `type`
element that identifies an object's type. It also identifies the element
as Swagger's `discriminator`.
properties:
type:
type: string
error:
type: object
properties:
message:
type: string
detail:
type: string
data:
type: object
description: Optional structured data that is endpoint-specific.
properties: {}
additionalProperties: true
required:
- message
additionalProperties: false
required:
- type
additionalProperties: true
paginated_repository_permissions:
type: object
title: Paginated Repository Permissions
description: A paginated list of repository permissions.
properties:
size:
type: integer
description: >-
Total number of objects in the response. This is an optional element
that is not provided in all responses, as it can be expensive to
compute.
minimum: 0
page:
type: integer
description: >-
Page number of the current results. This is an optional element that
is not provided in all responses.
minimum: 1
pagelen:
type: integer
description: >-
Current number of objects on the existing page. The default value is
10 with 100 being the maximum allowed value. Individual APIs may
enforce different values.
minimum: 1
next:
type: string
description: >-
Link to the next page if it exists. The last page of a collection
does not have this value. Use this link to navigate the result set
and refrain from constructing your own URLs.
format: uri
previous:
type: string
description: >-
Link to previous page if it exists. A collections first page does
not have this value. This is an optional element that is not
provided in all responses. Some result sets strictly support forward
navigation and never provide previous links. Clients must anticipate
that backwards navigation is not always available. Use this link to
navigate the result set and refrain from constructing your own URLs.
format: uri
values:
type: array
items:
$ref: '#/components/schemas/repository_permission'
minItems: 0
uniqueItems: true
additionalProperties: false
paginated_workspace_memberships:
type: object
title: Paginated Workspace Memberships
description: A paginated list of workspace memberships.
properties:
size:
type: integer
description: >-
Total number of objects in the response. This is an optional element
that is not provided in all responses, as it can be expensive to
compute.
minimum: 0
page:
type: integer
description: >-
Page number of the current results. This is an optional element that
is not provided in all responses.
minimum: 1
pagelen:
type: integer
description: >-
Current number of objects on the existing page. The default value is
10 with 100 being the maximum allowed value. Individual APIs may
enforce different values.
minimum: 1
next:
type: string
description: >-
Link to the next page if it exists. The last page of a collection
does not have this value. Use this link to navigate the result set
and refrain from constructing your own URLs.
format: uri
previous:
type: string
description: >-
Link to previous page if it exists. A collections first page does
not have this value. This is an optional element that is not
provided in all responses. Some result sets strictly support forward
navigation and never provide previous links. Clients must anticipate
that backwards navigation is not always available. Use this link to
navigate the result set and refrain from constructing your own URLs.
format: uri
values:
type: array
items:
$ref: '#/components/schemas/workspace_membership'
minItems: 0
uniqueItems: true
additionalProperties: false
paginated_pipeline_variables:
type: object
title: Paginated Pipeline Variables
description: A paged list of variables.
properties:
page:
type: integer
description: >-
Page number of the current results. This is an optional element that
is not provided in all responses.
values:
type: array
minItems: 0
items:
$ref: '#/components/schemas/pipeline_variable'
description: The values of the current page.
size:
type: integer
description: >-
Total number of objects in the response. This is an optional element
that is not provided in all responses, as it can be expensive to
compute.
pagelen:
type: integer
description: >-
Current number of objects on the existing page. The default value is
10 with 100 being the maximum allowed value. Individual APIs may
enforce different values.
next:
type: string
format: uri
description: >-
Link to the next page if it exists. The last page of a collection
does not have this value. Use this link to navigate the result set
and refrain from constructing your own URLs.
previous:
type: string
format: uri
description: >-
Link to previous page if it exists. A collections first page does
not have this value. This is an optional element that is not
provided in all responses. Some result sets strictly support forward
navigation and never provide previous links. Clients must anticipate
that backwards navigation is not always available. Use this link to
navigate the result set and refrain from constructing your own URLs.
pipeline_variable:
allOf:
- $ref: '#/components/schemas/object'
- additionalProperties: true
type: object
title: Pipeline Variable
description: A Pipelines variable.
properties:
uuid:
type: string
description: The UUID identifying the variable.
key:
type: string
description: The unique name of the variable.
value:
type: string
description: >-
The value of the variable. If the variable is secured, this will
be empty.
secured:
type: boolean
description: >-
If true, this variable will be treated as secured. The value
will never be exposed in the logs or the REST API.
application_property:
additionalProperties: true
type: object
title: Application Property
description: >
An application property. It is a caller defined JSON object that
Bitbucket will store and return.
The `_attributes` field at its top level can be used to control who is
allowed to read and update the property.
The keys of the JSON object must match an allowed pattern. For details,
see [Application properties](/cloud/bitbucket/application-properties/).
properties:
_attributes:
type: array
items:
type: string
enum:
- public
- read_only
search_result_page:
type: object
properties:
size:
type: integer
format: int64
readOnly: true
page:
type: integer
format: int32
readOnly: true
pagelen:
type: integer
format: int32
readOnly: true
query_substituted:
type: boolean
readOnly: true
next:
type: string
format: uri
readOnly: true
previous:
type: string
format: uri
readOnly: true
values:
type: array
readOnly: true
items:
$ref: '#/components/schemas/search_code_search_result'
paginated_ssh_user_keys:
type: object
title: Paginated SSH User Keys
description: A paginated list of SSH keys.
properties:
size:
type: integer
description: >-
Total number of objects in the response. This is an optional element
that is not provided in all responses, as it can be expensive to
compute.
minimum: 0
page:
type: integer
description: >-
Page number of the current results. This is an optional element that
is not provided in all responses.
minimum: 1
pagelen:
type: integer
description: >-
Current number of objects on the existing page. The default value is
10 with 100 being the maximum allowed value. Individual APIs may
enforce different values.
minimum: 1
next:
type: string
description: >-
Link to the next page if it exists. The last page of a collection
does not have this value. Use this link to navigate the result set
and refrain from constructing your own URLs.
format: uri
previous:
type: string
description: >-
Link to previous page if it exists. A collections first page does
not have this value. This is an optional element that is not
provided in all responses. Some result sets strictly support forward
navigation and never provide previous links. Clients must anticipate
that backwards navigation is not always available. Use this link to
navigate the result set and refrain from constructing your own URLs.
format: uri
values:
type: array
items:
$ref: '#/components/schemas/ssh_account_key'
minItems: 0
uniqueItems: true
additionalProperties: false
ssh_account_key:
allOf:
- $ref: '#/components/schemas/ssh_key'
- type: object
title: SSH Account Key
description: Represents an SSH public key for a user.
properties:
owner:
$ref: '#/components/schemas/account'
additionalProperties: true
paginated_project_user_permissions:
type: object
title: Paginated Project User Permissions
description: A paginated list of project user permissions.
properties:
size:
type: integer
description: >-
Total number of objects in the response. This is an optional element
that is not provided in all responses, as it can be expensive to
compute.
minimum: 0
page:
type: integer
description: >-
Page number of the current results. This is an optional element that
is not provided in all responses.
minimum: 1
pagelen:
type: integer
description: >-
Current number of objects on the existing page. The default value is
10 with 100 being the maximum allowed value. Individual APIs may
enforce different values.
minimum: 1
next:
type: string
description: >-
Link to the next page if it exists. The last page of a collection
does not have this value. Use this link to navigate the result set
and refrain from constructing your own URLs.
format: uri
previous:
type: string
description: >-
Link to previous page if it exists. A collections first page does
not have this value. This is an optional element that is not
provided in all responses. Some result sets strictly support forward
navigation and never provide previous links. Clients must anticipate
that backwards navigation is not always available. Use this link to
navigate the result set and refrain from constructing your own URLs.
format: uri
values:
type: array
items:
$ref: '#/components/schemas/project_user_permission'
minItems: 0
uniqueItems: true
additionalProperties: false
project_user_permission:
type: object
title: Project User Permission
description: A user's direct permission for a given project.
properties:
type:
type: string
links:
type: object
properties:
self:
type: object
title: Link
description: A link to a resource related to this object.
properties:
href:
type: string
format: uri
name:
type: string
additionalProperties: false
additionalProperties: false
permission:
type: string
enum:
- read
- write
- create-repo
- admin
- none
user:
$ref: '#/components/schemas/user'
project:
$ref: '#/components/schemas/project'
required:
- type
additionalProperties: true