OptionalclientOptions: ClientOptionsCreate a variable for an environment
Create a deployment environment level variable.
Create an environment
Create an environment.
Create or update an annotation
Creates or updates an individual annotation for the specified report. Annotations are individual findings that have been identified as part of a report, for example, a line of code that represents a vulnerability. These annotations can be attached to a specific file and even a specific line in that file, however, that is optional. Annotations are not mandatory and a report can contain up to 1000 annotations.
Just as reports, annotation needs to be uploaded with a unique ID that can later be used to identify the report as an alternative to the generated UUID. If you want to use an existing id from your own system, we recommend prefixing it with your system's name to avoid collisions, for example, mySystem-annotation001.
curl --request PUT 'https://api.bitbucket.org/2.0/repositories/<username>/<reposity-name>/commit/<commit-hash>/reports/mySystem-001/annotations/mysystem-annotation001' \
--header 'Content-Type: application/json' \
--data-raw '{
"title": "Security scan report",
"annotation_type": "VULNERABILITY",
"summary": "This line represents a security thread.",
"severity": "HIGH",
"path": "my-service/src/main/java/com/myCompany/mysystem/logic/Main.java",
"line": 42
}'
annotation_type: VULNERABILITY, CODE_SMELL, BUG result: PASSED, FAILED, IGNORED, SKIPPED severity: HIGH, MEDIUM, LOW, CRITICAL
Please refer to the Code Insights documentation for more information.
Create or update a report
Creates or updates a report for the specified commit. To upload a report, make sure to generate an ID that is unique across all reports for that commit. If you want to use an existing id from your own system, we recommend prefixing it with your system's name to avoid collisions, for example, mySystem-001.
curl --request PUT 'https://api.bitbucket.org/2.0/repositories/<username>/<reposity-name>/commit/<commit-hash>/reports/mysystem-001' \
--header 'Content-Type: application/json' \
--data-raw '{
"title": "Security scan report",
"details": "This pull request introduces 10 new dependency vulnerabilities.",
"report_type": "SECURITY",
"reporter": "mySystem",
"link": "http://www.mysystem.com/reports/001",
"result": "FAILED",
"data": [
{
"title": "Duration (seconds)",
"type": "DURATION",
"value": 14
},
{
"title": "Safe to merge?",
"type": "BOOLEAN",
"value": false
}
]
}'
report_type: SECURITY, COVERAGE, TEST, BUG result: PASSED, FAILED, PENDING data.type: BOOLEAN, DATE, DURATION, LINK, NUMBER, PERCENTAGE, TEXT
| Type Field | Value Field Type | Value Field Display |
|---|---|---|
| None/ Omitted | Number, String or Boolean (not an array or object) | Plain text |
| BOOLEAN | Boolean | The value will be read as a JSON boolean and displayed as 'Yes' or 'No'. |
| DATE | Number | The value will be read as a JSON number in the form of a Unix timestamp (milliseconds) and will be displayed as a relative date if the date is less than one week ago, otherwise it will be displayed as an absolute date. |
| DURATION | Number | The value will be read as a JSON number in milliseconds and will be displayed in a human readable duration format. |
| LINK | Object: {"text": "Link text here", "href": "https://link.to.annotation/in/external/tool"} |
The value will be read as a JSON object containing the fields "text" and "href" and will be displayed as a clickable link on the report. |
| NUMBER | Number | The value will be read as a JSON number and large numbers will be displayed in a human readable format (e.g. 14.3k). |
| PERCENTAGE | Number (between 0 and 100) | The value will be read as a JSON number between 0 and 100 and will be displayed with a percentage sign. |
| TEXT | String | The value will be read as a JSON string and will be displayed as-is |
Please refer to the Code Insights documentation for more information.
Run a pipeline
Endpoint to create and initiate a pipeline. There are a number of different options to initiate a pipeline, where the payload of the request will determine which type of pipeline will be instantiated.
One way to trigger pipelines is by specifying the branch for which you want to trigger a pipeline.
The specified branch will be used to determine which pipeline definition from the bitbucket-pipelines.yml file will be applied to initiate the pipeline. The pipeline will then do a clone of the repository and checkout the latest revision of the specified branch.
$ curl -X POST -is -u '{atlassian_account_email}:{api_token}' \
-H 'Content-Type: application/json' \
https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pipelines/ \
-d '
{
"target": {
"ref_type": "branch",
"type": "pipeline_ref_target",
"ref_name": "master"
}
}'
You can initiate a pipeline for a specific commit and in the context of a specified reference (e.g. a branch, tag or bookmark). The specified reference will be used to determine which pipeline definition from the bitbucket-pipelines.yml file will be applied to initiate the pipeline. The pipeline will clone the repository and then do a checkout the specified reference.
The following reference types are supported:
branchnamed_branchbookmarktag$ curl -X POST -is -u '{atlassian_account_email}:{api_token}' \
-H 'Content-Type: application/json' \
https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pipelines/ \
-d '
{
"target": {
"commit": {
"type": "commit",
"hash": "ce5b7431602f7cbba007062eeb55225c6e18e956"
},
"ref_type": "branch",
"type": "pipeline_ref_target",
"ref_name": "master"
}
}'
You can trigger a specific pipeline that is defined in your bitbucket-pipelines.yml file for a specific commit.
In addition to the commit revision, you specify the type and pattern of the selector that identifies the pipeline definition. The resulting pipeline will then clone the repository and checkout the specified revision.
$ curl -X POST -is -u '{atlassian_account_email}:{api_token}' \
-H 'Content-Type: application/json' \
https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pipelines/ \
-d '
{
"target": {
"commit": {
"hash":"a3c4e02c9a3755eccdc3764e6ea13facdf30f923",
"type":"commit"
},
"selector": {
"type":"custom",
"pattern":"Deploy to production"
},
"type":"pipeline_commit_target"
}
}'
You can trigger a specific pipeline that is defined in your bitbucket-pipelines.yml file for a specific commit in the context of a specified reference.
In addition to the commit revision, you specify the type and pattern of the selector that identifies the pipeline definition, as well as the reference information. The resulting pipeline will then clone the repository a checkout the specified reference.
$ curl -X POST -is -u '{atlassian_account_email}:{api_token}' \
-H 'Content-Type: application/json' \
https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pipelines/ \
-d '
{
"target": {
"commit": {
"hash":"a3c4e02c9a3755eccdc3764e6ea13facdf30f923",
"type":"commit"
},
"selector": {
"type": "custom",
"pattern": "Deploy to production"
},
"type": "pipeline_ref_target",
"ref_name": "master",
"ref_type": "branch"
}
}'
In addition to triggering a custom pipeline that is defined in your bitbucket-pipelines.yml file as shown in the examples above, you can specify variables that will be available for your build. In the request, provide a list of variables, specifying the following for each variable: key, value, and whether it should be secured or not (this field is optional and defaults to not secured).
$ curl -X POST -is -u '{atlassian_account_email}:{api_token}' \
-H 'Content-Type: application/json' \
https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pipelines/ \
-d '
{
"target": {
"type": "pipeline_ref_target",
"ref_type": "branch",
"ref_name": "master",
"selector": {
"type": "custom",
"pattern": "Deploy to production"
}
},
"variables": [
{
"key": "var1key",
"value": "var1value",
"secured": true
},
{
"key": "var2key",
"value": "var2value"
}
]
}'
You can also initiate a pipeline for a specific pull request.
$ curl -X POST -is -u '{atlassian_account_email}:{api_token}' \
-H 'Content-Type: application/json' \
https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pipelines/ \
-d '
{
"target": {
"type": "pipeline_pullrequest_target",
"source": "pull-request-branch",
"destination": "master",
"destination_commit": {
"hash": "9f848b7"
},
"commit": {
"hash": "1a372fc"
},
"pullrequest": {
"id": "3"
},
"selector": {
"type": "pull-requests",
"pattern": "**"
}
}
}'
By default, pipelines run using the YAML in the repository’s bitbucket-pipelines.yml configuration file.
With an on-demand pipeline, you include the pipeline’s YAML in the request body. That YAML applies only
to that run and overrides the YAML in bitbucket-pipelines.yml.
Just like with regular pipelines, there is a number of different options to initiate an on-demand pipeline. However, since the payload contains YAML configuration in this case, query parameters are used to supply the necessary metadata to determine which type of pipeline will be instantiated. These query parameters are derived from the JSON equivalent by turning each property into a key-value pair with the JSON path of the property as the new key.
You can initiate an on-demand pipeline for a specific branch. This branch will be used to determine which pipeline definition from the supplied YAML configuration will be applied to initiate the pipeline. The pipeline will then do a clone of the repository and check out the latest revision of the specified branch.
To trigger an on-demand pipeline for a branch the requesting user must have write permission for that branch (which can be limited by branch restrictions).
$ curl -X POST -is -u '{atlassian_account_email}:{api_token}' \
-H 'Content-Type: application/yaml' \
https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pipelines?target.type=pipeline_ref_target&target.ref_type=branch&target.ref_name=master \
-d '
pipelines:
default:
- step:
script:
- echo This is an on-demand pipeline'
You can initiate an on-demand pipeline for a specific commit and in the context of a specified reference (branch or tag). The specified reference will be used to determine which pipeline definition from the supplied YAML configuration will be applied to initiate the pipeline. The pipeline will clone the repository and check out the specified reference.
To trigger an on-demand pipeline for a branch the requesting user must have write permission for that branch (which can be limited by branch restrictions).
$ curl -X POST -is -u '{atlassian_account_email}:{api_token}' \
-H 'Content-Type: application/yaml' \
https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pipelines?target.type=pipeline_ref_target&target.ref_type=branch&target.ref_name=master&target.commit.hash=ce5b7431602f7cbba007062eeb55225c6e18e956 \
-d '
pipelines:
default:
- step:
script:
- echo This is an on-demand pipeline'
You can trigger a specific pipeline that is defined in the supplied YAML configuration for a specific commit. In addition to the commit revision, you specify the type and pattern of the selector that identifies the pipeline definition. The resulting pipeline will then clone the repository and checkout the specified revision.
$ curl -X POST -is -u '{atlassian_account_email}:{api_token}' \
-H 'Content-Type: application/yaml' \
https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pipelines?target.type=pipeline_commit_target&target.commit.hash=a3c4e02c9a3755eccdc3764e6ea13facdf30f923&target.selector.type=custom&target.selector.pattern=security-scan \
-d '
pipelines:
custom:
security-scan:
- step:
script:
- echo Run on-demand security scan
In addition to triggering a custom on-demand pipeline that is defined in the supplied YAML configuration as shown in the examples above, you can specify variables that will be available for your build. In the request, provide each variable as an indexed set of query parameters representing its key, value, and whether it should be secured or not (this field is optional and defaults to not secured).
$ curl -X POST -is -u '{atlassian_account_email}:{api_token}' \
-H 'Content-Type: application/yaml' \
https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pipelines?target.type=pipeline_ref_target&target.ref_type=branch&target.ref_name=master&target.selector.type=custom&target.selector.pattern=security-scan&variables[0].key=var1key&variables[0].value=var1value&variables[0].secured=true&variables[1].key=var2key&variables[1].value=var2value \
-d '
pipelines:
custom:
security-scan:
- variables:
- name: var1key
- name: var2key
- step:
script:
- echo Run on-demand security scan'
You can also initiate an on-demand pipeline for a specific pull request.
$ curl -X POST -is -u '{atlassian_account_email}:{api_token}' \
-H 'Content-Type: application/yaml' \
https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pipelines?target.type=pipeline_pullrequest_target&target.source=pull-request-branch&target.destination=destination&target.destination_commit.hash=9f848b7&target.commit.hash=1a372fc&target.pullrequest.id=3&target.selector.type=pull-requests&target.selector.pattern=** \
-d '
pipelines:
pull-requests:
"**":
- step:
script:
- echo This is an on-demand pipeline'
Create a variable for a user
Create an account level variable. This endpoint has been deprecated, and you should use the new workspaces endpoint. For more information, see the announcement.
Create a variable for a user
Create a user level variable. This endpoint has been deprecated, and you should use the new workspaces endpoint. For more information, see the announcement.
Create a variable for a workspace
Create a workspace level variable.
Create a known host
Create a repository level known host.
Create a schedule
Create a schedule for the given repository.
Create a variable for a repository
Create a repository level variable.
Create repository runner
Create repository runner.
Create workspace runner
Create workspace runner.
Delete an annotation
Deletes a single Annotation matching the provided ID.
Delete a commit application property
Delete an application property value stored against a commit.
Delete a variable for an environment
Delete a deployment environment level variable.
Delete an environment
Delete an environment
Delete a variable for a team
Delete a team level variable. This endpoint has been deprecated, and you should use the new workspaces endpoint. For more information, see the announcement.
Delete a variable for a user
Delete an account level variable. This endpoint has been deprecated, and you should use the new workspaces endpoint. For more information, see the announcement.
Delete a variable for a workspace
Delete a workspace level variable.
Delete a pull request application property
Delete an application property value stored against a pull request.
Delete a report
Deletes a single Report matching the provided ID.
Delete a repository application property
Delete an application property value stored against a repository.
Delete a cache
Delete a repository cache.
Delete caches
Delete repository cache versions by name.
Delete SSH key pair
Delete the repository SSH key pair.
Delete a known host
Delete a repository level known host.
Delete a schedule
Delete a schedule.
Delete a variable for a repository
Delete a repository level variable.
Delete repository runner
Delete repository runner by uuid.
Delete a user application property
Delete an application property value stored against a user.
Delete workspace runner
Delete workspace runner by uuid.
Get an annotation
Returns a single Annotation matching the provided ID.
List annotations
Returns a paginated list of Annotations for a specified report.
Get a commit application property
Retrieve an application property value stored against a commit.
Get a deployment
Retrieve a deployment
List deployments
Find deployments
List variables for an environment
Find deployment environment level variables.
Get an environment
Retrieve an environment
List environments
Find environments
Get OpenID configuration for OIDC in Pipelines
This is part of OpenID Connect for Pipelines, see https://support.atlassian.com/bitbucket-cloud/docs/integrate-pipelines-with-resource-servers-using-oidc/
Get keys for OIDC in Pipelines
This is part of OpenID Connect for Pipelines, see https://support.atlassian.com/bitbucket-cloud/docs/integrate-pipelines-with-resource-servers-using-oidc/
Get the logs for the build container or a service container for a given step of a pipeline.
Retrieve the log file for a build container or service container.
This endpoint supports (and encourages!) the use of HTTP Range requests to deal with potentially very large log files.
Get a pipeline
Retrieve a specified pipeline
List pipelines
Find pipelines in a repository.
Note that unlike other endpoints in the Bitbucket API, this endpoint utilizes query parameters to allow filtering and sorting of returned results. See query parameters for specific details.
Get a step of a pipeline
Retrieve a given step of a pipeline.
Get log file for a step
Retrieve the log file for a given step of a pipeline.
This endpoint supports (and encourages!) the use of HTTP Range requests to deal with potentially very large log files.
List steps for a pipeline
Find steps for the given pipeline.
Get a summary of test reports for a given step of a pipeline.
Get test case reasons (output) for a given test case in a step of a pipeline.
Get test cases for a given step of a pipeline.
Get a variable for a team
Retrieve a team level variable. This endpoint has been deprecated, and you should use the new workspaces endpoint. For more information, see the announcement.
Get a variable for a user
Retrieve a user level variable. This endpoint has been deprecated, and you should use the new workspaces endpoint. For more information, see the announcement.
Get variable for a workspace
Retrieve a workspace level variable.
List variables for an account
Find account level variables. This endpoint has been deprecated, and you should use the new workspaces endpoint. For more information, see the announcement.
List variables for a user
Find user level variables. This endpoint has been deprecated, and you should use the new workspaces endpoint. For more information, see the announcement.
List variables for a workspace
Find workspace level variables.
Get a pull request application property
Retrieve an application property value stored against a pull request.
List pull requests that contain a commit
Returns a paginated list of all pull requests as part of which this commit was reviewed. Pull Request Commit Links app must be installed first before using this API; installation automatically occurs when 'Go to pull request' is clicked from the web interface for a commit's details.
Get a report
Returns a single Report matching the provided ID.
List reports
Returns a paginated list of Reports linked to this commit.
Get a repository application property
Retrieve an application property value stored against a repository.
Get cache content URI
Retrieve the URI of the content of the specified cache.
List caches
Retrieve the repository pipelines caches.
Get configuration
Retrieve the repository pipelines configuration.
Get a known host
Retrieve a repository level known host.
List known hosts
Find repository level known hosts.
Get a schedule
Retrieve a schedule by its UUID.
List executions of a schedule
Retrieve the executions of a given schedule.
List schedules
Retrieve the configured schedules for the given repository.
Get SSH key pair
Retrieve the repository SSH key pair excluding the SSH private key. The private key is a write only field and will never be exposed in the logs or the REST API.
Get a variable for a repository
Retrieve a repository level variable.
List variables for a repository
Find repository level variables.
Get repository runner
Retrieve repository runner by uuid.
Get repository runners
Retrieve repository runners.
Get workspace runner
Get workspace runner by uuid.
Get workspace runners
Retrieve workspace runners.
Get a user application property
Retrieve an application property value stored against a user.
Search for code in a user's repositories
This API will be deprecated on November 1, 2026.
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 +).
Search for code in a team's repositories
This API will be deprecated on November 1, 2026.
Search for code in the repositories of the specified team.
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 +).
Try fields=%2Bvalues.*.*.*.* to get an idea what's possible.
Search for code in a workspace
This API will be deprecated on November 1, 2026.
Search for code in the repositories of the specified workspace.
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 +).
Try fields=%2Bvalues.*.*.*.* to get an idea what's possible.
Stop a pipeline
Signal the stop of a pipeline and all of its steps that not have completed yet.
Update a commit application property
Update an application property value stored against a commit.
Update a variable for an environment
Update a deployment environment level variable.
Update an environment
Update an environment
Update a variable for a team
Update a team level variable. This endpoint has been deprecated, and you should use the new workspaces endpoint. For more information, see the announcement.
Update a variable for a user
Update a user level variable. This endpoint has been deprecated, and you should use the new workspaces endpoint. For more information, see the announcement.
Update variable for a workspace
Update a workspace level variable.
Update a pull request application property
Update an application property value stored against a pull request.
Update the next build number
Update the next build number that should be assigned to a pipeline. The next build number that will be configured has to be strictly higher than the current latest build number for this repository.
Update a repository application property
Update an application property value stored against a repository.
Update configuration
Update the pipelines configuration for a repository.
Update SSH key pair
Create or update the repository SSH key pair. The private key will be set as a default SSH identity in your build container.
Update a known host
Update a repository level known host.
Update a schedule
Update a schedule.
Update a variable for a repository
Update a repository level variable.
Update repository runner
Update repository runner.
Update a user application property
Update an application property value stored against a user.
Update workspace runner
Update workspace runner.
Bulk create or update annotations
Bulk upload of annotations. Annotations are individual findings that have been identified as part of a report, for example, a line of code that represents a vulnerability. These annotations can be attached to a specific file and even a specific line in that file, however, that is optional. Annotations are not mandatory and a report can contain up to 1000 annotations.
Add the annotations you want to upload as objects in a JSON array and make sure each annotation has the external_id field set to a unique value. If you want to use an existing id from your own system, we recommend prefixing it with your system's name to avoid collisions, for example, mySystem-annotation001. The external id can later be used to identify the report as an alternative to the generated UUID. You can upload up to 100 annotations per POST request.
Sample cURL request:
Possible field values:
annotation_type: VULNERABILITY, CODE_SMELL, BUG result: PASSED, FAILED, IGNORED, SKIPPED severity: HIGH, MEDIUM, LOW, CRITICAL
Please refer to the Code Insights documentation for more information.