Support for Server products ended Feb. 15, 2024. Learn what this means for you.

Server

Bitbucket Data Center / / Modules

Builds and Deployments

Operations

GET

Get Code Insights annotations for a commit

Get annotations for the given commit ID, filtered by any query parameters given.

Request

Path parameters

projectKey

string

Required

commitId

string

Required

repositorySlug

string

Required

Query parameters

severity

string

path

string

externalId

string

type

string

key

string

Responses

The requested annotations.

application/json;charset=UTF-8

RestInsightAnnotationsResponse

GET/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/annotations

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/annotations' \
  --header 'Accept: application/json;charset=UTF-8'

GET

Get all Code Insights reports for a commit

Retrieve all reports for the given commit.

Request

Path parameters

projectKey

string

Required

commitId

string

Required

repositorySlug

string

Required

Query parameters

start

number

limit

number

Responses

A page of reports

application/json;charset=UTF-8

object

GET/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports' \
  --header 'Accept: application/json;charset=UTF-8'

GET

Get a Code Insights report

Retrieve the specified report.

Request

Path parameters

projectKey

string

Required

commitId

string

Required

repositorySlug

string

Required

key

string

Required

Responses

The specified report.

application/json;charset=UTF-8

RestInsightReport

GET/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports/{key}

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports/{key}' \
  --header 'Accept: application/json;charset=UTF-8'

PUT

Create a Code Insights report

Create a new insight report, or replace the existing one if a report already exists for the given repository, commit, and report key. A request to replace an existing report will be rejected if the authenticated user was not the creator of the specified report.

The report key should be a unique string chosen by the reporter and should be unique enough not to potentially clash with report keys from other reporters. We recommend using reverse DNS namespacing or a similar standard to ensure that collision is avoided.

Report parameters

Parameter	Description	Required?	Restrictions	Type
title	A short string representing the name of the report	Yes	Max length: 450 characters (but we recommend that it is shorter so that the display is nicer)	String
details	A string to describe the purpose of the report. This string may contain escaped newlines and if it does it will display the content accordingly.	No	Max length: 2000 characters	String
result	Indicates whether the report is in a passed or failed state	No	One of: PASS, FAIL	String
data	An array of data fields (described below) to display information on the report	No	Maximum 6 data fields	Array
reporter	A string to describe the tool or company who created the report	No	Max length: 450 characters	String
link	A URL linking to the results of the report in an external tool.	No	Must be a valid http or https URL	String
logoUrl	A URL to the report logo. If none is provided, the default insights logo will be used.	No	Must be a valid http or https URL	String

Data parameters

The data field on the report is an array with at most 6 data fields (JSON maps) containing information that is to be displayed on the report (see the request example).

Parameter	Description	Type
title	A string describing what this data field represents	String
type	The type of data contained in the value field. If not provided, then the value will be detected as a boolean, number or string. One of: BOOLEAN, DATE, DURATION, LINK, NUMBER, PERCENTAGE, TEXT	String
value	A value based on the type provided. Either a raw value (string, number or boolean) or a map. See below.

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: {"linktext": "Link text here", "href": "https://link.to.annotation/in/external/tool"}	The value will be read as a JSON object containing the fields "linktext" 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

Request

Path parameters

projectKey

string

Required

commitId

string

Required

repositorySlug

string

Required

key

string

Required

Request bodyapplication/json

The request object containing the details of the report to create (see example).

coverageProviderKey

string

createdDate

integer

data

array<RestInsightReportData>

Required

details

string

link

string

logoUrl

string

reporter

string

result

string

title

string

Required

Responses

The created report.

application/json;charset=UTF-8

RestInsightReport

PUT/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports/{key}

curl

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'http://{baseurl}/rest/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports/{key}' \
  --header 'Accept: application/json;charset=UTF-8' \
  --header 'Content-Type: application/json' \
  --data '{
  "coverageProviderKey": "<string>",
  "createdDate": 1630041546433,
  "data": [
    {
      "title": "data.title",
      "type": "NUMBER",
      "value": {}
    }
  ],
  "details": "This is the details of the report, it can be a longer string describing the report.",
  "link": "http://insight.example.com",
  "logoUrl": "http://insight.example.com/logo",
  "reporter": "Reporter/tool that produced this report",
  "result": "PASS",
  "title": "report.title"
}'

DEL

Delete a Code Insights report

Delete a report for the given commit. Also deletes any annotations associated with this report.

Request

Path parameters

projectKey

string

Required

commitId

string

Required

repositorySlug

string

Required

key

string

Required

Responses

The report and associated annotations were successfully deleted.

DEL/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports/{key}

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports/{key}'

GET

Get Code Insights annotations for a report

Retrieve the specified report's annotations.

Request

Path parameters

projectKey

string

Required

commitId

string

Required

repositorySlug

string

Required

key

string

Required

Responses

The specified annotations.

application/json;charset=UTF-8

RestInsightAnnotationsResponse

GET/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports/{key}/annotations

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports/{key}/annotations' \
  --header 'Accept: application/json;charset=UTF-8'

POST

Add Code Insights annotations

Add annotations to the given report. The request should be a JSON object mapping the string "annotations" to an array of maps containing the annotation data, as described below. See also the example request.

A few things to note:- Annotations are an extension of a report, so a report must first exist in order to post annotations. Annotations are posted separately from the report, and can be posted in bulk using this endpoint.

Only the annotations that are on lines changed in the unified diff will be displayed. This means it is likely not all annotations posted will be displayed on the pull request It also means that if the user is viewing a side-by-side diff, commit diff or iterative review diff they will not be able to view the annotations.
A report cannot have more than 1000 annotations by default, however this property is congurable at an instance level. If the request would result in more than the maximum number of annotations being stored then the entire request is rejected and no new annotations are stored.
There is no de-duplication of annotations on Bitbucket so be sure that reruns of builds will first delete the report and annotations before creating them.

Annotation parameters

Parameter	Description	Required?	Restrictions	Type
path	The path of the file on which this annotation should be placed. This is the path of the filerelative to the git repository. If no path is provided, then it will appear in the overview modalon all pull requests where the tip of the branch is the given commit, regardless of which files weremodified.	No		String
line	The line number that the annotation should belong to. If no line number is provided, then it willdefault to 0 and in a pull request it will appear at the top of the file specified by the path field.	No	Non-negative integer	Integer
message	The message to display to users	Yes	The maximum length accepted is 2000 characters, however the user interface may truncate this valuefor display purposes. We recommend that the message is short and succinct, with further detailsavailable to the user if needed on the page linked to by the the annotation link.	String
severity	The severity of the annotation	Yes	One of: LOW, MEDIUM, HIGH	String
link	An http or https URL representing the location of the annotation in the external tool	No		String
type	The type of annotation posted	No	One of: VULNERABILITY, CODE_SMELL, BUG	String
externalId	If the caller requires a link to get or modify this annotation, then an ID must be provided. It isnot used or required by Bitbucket, but only by the annotation creator for updating or deleting thisspecific annotation.	No	A string value shorter than 450 characters	String

Request

Path parameters

projectKey

string

Required

commitId

string

Required

repositorySlug

string

Required

key

string

Required

Request bodyapplication/json

The annotations to add.

annotations

array<RestSingleAddInsightAnnotationRequest>

Responses

An empty response indicating that the request succeeded.

POST/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports/{key}/annotations

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports/{key}/annotations' \
  --header 'Content-Type: application/json' \
  --data '{
  "annotations": [
    {
      "externalId": "message-1",
      "line": 4,
      "link": "https://link.to.tool/that/produced/annotation/message-1",
      "message": "This is a bug here because reasons",
      "path": "path/to/file/in/repo",
      "severity": "MEDIUM",
      "type": "CODE_SMELL"
    }
  ]
}'

DEL

Delete Code Insights annotations

Delete annotations for a given report that match the given external IDs, or all annotations if no external IDs are provided.

Request

Path parameters

projectKey

string

Required

commitId

string

Required

repositorySlug

string

Required

key

string

Required

Query parameters

externalId

string

Responses

The annotations were successfully deleted.

DEL/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports/{key}/annotations

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports/{key}/annotations'

PUT

Create or replace a Code Insights annotation

Create an annotation with the given external ID, or replace it if it already exists. A request to replace an existing annotation will be rejected if the authenticated user was not the creator of the specified report.

Request

Path parameters

projectKey

string

Required

externalId

string

Required

commitId

string

Required

repositorySlug

string

Required

key

string

Required

Request bodyapplication/json

The new annotation that is to replace the existing one.

externalId

string

line

integer

link

string

message

string

Required

path

string

severity

string

Required

type

string

Responses

No content, indicating that the request succeeded.

PUT/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports/{key}/annotations/{externalId}

curl

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'http://{baseurl}/rest/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports/{key}/annotations/{externalId}' \
  --header 'Content-Type: application/json' \
  --data '{
  "externalId": "message-1",
  "line": 4,
  "link": "https://link.to.tool/that/produced/annotation/message-1",
  "message": "This is a bug here because reasons",
  "path": "path/to/file/in/repo",
  "severity": "MEDIUM",
  "type": "CODE_SMELL"
}'

POST

Get build status statistics for multiple commits

Produces a list of the build statistics for multiple commits. Commits without any builds associated with them will not be returned.
For example if the commit e00cf62997a027bbf785614a93e2e55bb331d268 does not have any build statuses associated with it, it will not be present in the response.

Request

Request bodyapplication/json

full SHA1 of each commit

array<string>

Responses

The number of successful/failed/in-progress/cancelled/unknown builds for each commit (with the caveat that the commits without any builds associated with them will not be present in the response)

application/json

RestMultipleBuildStats

POST/build-status/latest/commits/stats

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/build-status/latest/commits/stats' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '[
  "db0dd118fa6ccdf1d593fef00df839dd27702df7"
]'

GET

Get build status statistics for commit

Gets statistics regarding the builds associated with a commit

Request

Path parameters

commitId

string

Required

Query parameters

includeUnique

boolean

Responses

The number of successful/failed/in-progress/cancelled/unknown builds for the commit

application/json

RestBuildStats

GET/build-status/latest/commits/stats/{commitId}

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/build-status/latest/commits/stats/{commitId}' \
  --header 'Accept: application/json'

200Response

{
  "cancelled": 2154,
  "failed": 2154,
  "inProgress": 2154,
  "successful": 2154,
  "unknown": 2154
}

POST

Create a required builds merge check

Create a required build merge check for the given repository.

The authenticated user must have REPO_ADMIN permission for the target repository to register a required build merge check.

The contents of the required build merge check request are:

These fields are required:

buildParentKeys: A non-empty list of build parent keys that require green builds for this merge check to pass
refMatcher.id: The value to match refs against in the target branch
refMatcher.type.id: The type of ref matcher, one of: "ANY_REF", "BRANCH", "PATTERN", "MODEL_CATEGORY" or "MODEL_BRANCH"

These fields are optional:

exemptRefMatcher.id The value to exempt refs in the source branch from this check
exemptRefMatcher.type.id: The type of exempt ref matcher, one of: "ANY_REF", "BRANCH", "PATTERN", "MODEL_CATEGORY" or "MODEL_BRANCH"

Request

Path parameters

projectKey

string

Required

repositorySlug

string

Required

Request body/

The request specifying the required build parent keys, ref matcher and exemption matcher

buildParentKeys

array<string>

Required

exemptRefMatcher

RestRefMatcher

refMatcher

object

Required

Responses

A response containing the newly created required build merge check.

application/json;charset=UTF-8

RestRequiredBuildCondition

POST/required-builds/latest/projects/{projectKey}/repos/{repositorySlug}/condition

curl

Node.js

Java

Python

PHP

1
2
3

curl --request POST \
  --url 'http://{baseurl}/rest/required-builds/latest/projects/{projectKey}/repos/{repositorySlug}/condition' \
  --header 'Accept: application/json;charset=UTF-8'

PUT

Update a required builds merge check

Update the required builds merge check for the given ID.

The authenticated user must have REPO_ADMIN permission for the target repository to update a required build merge check.

The contents of the required build merge check request are:

These fields are required:

buildParentKeys: A non-empty list of build parent keys that require green builds for this merge check to pass
refMatcher.id: The value to match refs against in the target branch
refMatcher.type.id: The type of ref matcher, one of: "ANY_REF", "BRANCH", "PATTERN", "MODEL_CATEGORY" or "MODEL_BRANCH"

These fields are optional:

exemptRefMatcher.id The value to exempt refs in the source branch from this check
exemptRefMatcher.type.id: The type of exempt ref matcher, one of: "ANY_REF", "BRANCH", "PATTERN", "MODEL_CATEGORY" or "MODEL_BRANCH"

Request

Path parameters

projectKey

string

Required

integer

Required

repositorySlug

string

Required

Request body/

The request specifying the required build parent keys, ref matcher and exemption matcher

buildParentKeys

array<string>

Required

exemptRefMatcher

RestRefMatcher

refMatcher

object

Required

Responses

The details needed to update a required build merge check.

application/json;charset=UTF-8

RestRequiredBuildCondition

PUT/required-builds/latest/projects/{projectKey}/repos/{repositorySlug}/condition/{id}

curl

Node.js

Java

Python

PHP

1
2
3

curl --request PUT \
  --url 'http://{baseurl}/rest/required-builds/latest/projects/{projectKey}/repos/{repositorySlug}/condition/{id}' \
  --header 'Accept: application/json;charset=UTF-8'

DEL

Delete a required builds merge check

Deletes a required build existing merge check, given it's ID.

The authenticated user must have REPO_ADMIN permission for the target repository to delete a required build merge check.

Request

Path parameters

projectKey

string

Required

integer

Required

repositorySlug

string

Required

Responses

An empty response indicating the merge check was successfully deleted, or was never present.

DEL/required-builds/latest/projects/{projectKey}/repos/{repositorySlug}/condition/{id}

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/required-builds/latest/projects/{projectKey}/repos/{repositorySlug}/condition/{id}'

GET

Get required builds merge checks

Returns a page of required build merge checks that have been configured for this repository.

The authenticated user must have REPO_READ permission for the target repository to request a page of required build merge checks.

Request

Path parameters

projectKey

string

Required

repositorySlug

string

Required

Query parameters

start

number

limit

number

Responses

The required build merge checks associated with the provided repository.

application/json;charset=UTF-8

object

GET/required-builds/latest/projects/{projectKey}/repos/{repositorySlug}/conditions

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/required-builds/latest/projects/{projectKey}/repos/{repositorySlug}/conditions' \
  --header 'Accept: application/json;charset=UTF-8'

GET

Get a specific build status

Get a specific build status.

The authenticated user must have REPO_READ permission for the provided repository.The request can also be made with anonymous 2-legged OAuth.
Since 7.14

Request

Path parameters

projectKey

string

Required

commitId

string

Required

repositorySlug

string

Required

Query parameters

key

string

Required

Responses

The build status associated with the provided commit and key

application/json;charset=UTF-8

RestBuildStatus

GET/api/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/builds

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/builds?key={key}' \
  --header 'Accept: application/json;charset=UTF-8'

POST

Store a build status

Store a build status.

The authenticated user must have REPO_READ permission for the repository that this build status is for. The request can also be made with anonymous 2-legged OAuth.

Request

Path parameters

projectKey

string

Required

commitId

string

Required

repositorySlug

string

Required

Request body/

The contents of the build status request are: These fields are required:

key: The string referring to this branch plan/job
state: The build status state, one of: "SUCCESSFUL", "FAILED", "INPROGRESS", "CANCELLED", "UNKNOWN"
url: URL referring to the build result page in the CI tool.

These fields are optional:

buildNumber (optional): A unique identifier for this particular run of a plan<
dateAdded (optional): milliseconds since epoch. If not provided current date is used.
description (optional): Describes the build result
duration (optional): Duration of a completed build in milliseconds.
name (optional): A short string that describes the build plan
parent (optional): The identifier for the plan or job that ran the branch plan that produced this build status.
ref (optional): The fully qualified git reference e.g. refs/heads/master.
testResults (optional): A summary of the passed, failed and skipped tests.

buildNumber

string

description

string

duration

integer

key

string

Required

lastUpdated

integer

name

string

parent

string

ref

string

state

string

Required

testResults

object

Responses

The build status was posted

POST/api/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/builds

curl

Node.js

Java

Python

PHP

1
2

curl --request POST \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/builds'

DEL

Delete a specific build status

Delete a specific build status.

The authenticated user must have REPO_ADMIN permission for the provided repository.

Request

Path parameters

projectKey

string

Required

commitId

string

Required

repositorySlug

string

Required

Query parameters

key

string

Required

Responses

The build status associated with the provided commit and key has been deleted

DEL/api/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/builds

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/builds?key={key}'

GET

Get a deployment

Get the deployment matching the specified Repository, key, environmentKey and deploymentSequenceNumber.

The user must have REPO_READ.

Request

Path parameters

projectKey

string

Required

commitId

string

Required

repositorySlug

string

Required

Query parameters

deploymentSequenceNumber

string

key

string

environmentKey

string

Responses

The deployment

application/json;charset=UTF-8

RestDeployment

GET/api/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/deployments

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/deployments' \
  --header 'Accept: application/json;charset=UTF-8'

POST

Create or update a deployment

Create or update a deployment.

The authenticated user must have REPO_READ permission for the repository.

Request

Path parameters

projectKey

string

Required

commitId

string

Required

repositorySlug

string

Required

Request body/

the details of the deployment to create, as detailed by the request body

deploymentSequenceNumber

integer

Required

description

string

Required

displayName

string

Required

environment

RestDeploymentEnvironment

Required

key

string

Required

lastUpdated

integer

state

string

Required

url

string

Required

Responses

The deployment was created

application/json;charset=UTF-8

RestDeployment

POST/api/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/deployments

curl

Node.js

Java

Python

PHP

1
2
3

curl --request POST \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/deployments' \
  --header 'Accept: application/json;charset=UTF-8'

DEL

Delete a deployment

Delete the deployment matching the specified Repository, key, environmentKey and deploymentSequenceNumber.

The user must have REPO_ADMIN.

Request

Path parameters

projectKey

string

Required

commitId

string

Required

repositorySlug

string

Required

Query parameters

deploymentSequenceNumber

string

key

string

environmentKey

string

Responses

the request has been processed

DEL/api/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/deployments

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/deployments'