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

Server

Bitbucket Data Center / / Modules

Insights

Operations

GET

Get insights latest projects {projectKey} repos {repositorySlug} commits {commitId} annotations

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

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'

200Response

{
  "annotations": [
    {
      "link": "http://example.com/my/file/analysis?line=5",
      "externalId": "external.id",
      "severity": "HIGH",
      "message": "This is an annotation message",
      "type": "BUG",
      "path": "src/some/structure/file.ext",
      "line": 5,
      "reportKey": "report.key"
    }
  ]
}

GET

Get insights latest projects {projectKey} repos {repositorySlug} commits {commitId} reports

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

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'

200Response

{
  "values": [
    {
      "link": "http://integration.example.com",
      "logoUrl": "http://integration.example.com/logo",
      "reporter": "Reporter/tool that produced this report",
      "details": "This is the details of the report, it can be a longer string describing the report",
      "createdDate": 1630041546433,
      "result": "PASS",
      "key": "report.key",
      "data": [
        {
          "value": {},
          "type": "NUMBER",
          "title": "data.title"
        }
      ],
      "title": "report.title"
    }
  ],
  "size": 1,
  "isLastPage": true,
  "nextPageStart": 2154,
  "start": 2154,
  "limit": 25
}

GET

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

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

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'

200Response

{
  "link": "http://integration.example.com",
  "logoUrl": "http://integration.example.com/logo",
  "reporter": "Reporter/tool that produced this report",
  "details": "This is the details of the report, it can be a longer string describing the report",
  "createdDate": 1630041546433,
  "result": "PASS",
  "key": "report.key",
  "data": [
    {
      "value": {},
      "type": "NUMBER",
      "title": "data.title"
    }
  ],
  "title": "report.title"
}

PUT

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

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

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' \
  --header 'Content-Type: application/json' \
  --data '{
  "coverageProviderKey": "<string>",
  "createdDate": 1630041546433,
  "data": [
    {
      "value": {},
      "type": "NUMBER",
      "title": "data.title"
    }
  ],
  "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"
}'

200Response

{
  "link": "http://integration.example.com",
  "logoUrl": "http://integration.example.com/logo",
  "reporter": "Reporter/tool that produced this report",
  "details": "This is the details of the report, it can be a longer string describing the report",
  "createdDate": 1630041546433,
  "result": "PASS",
  "key": "report.key",
  "data": [
    {
      "value": {},
      "type": "NUMBER",
      "title": "data.title"
    }
  ],
  "title": "report.title"
}

DEL

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

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 insights latest projects {projectKey} repos {repositorySlug} commits {commitId} reports {key} annotations

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

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'

200Response

{
  "annotations": [
    {
      "link": "http://example.com/my/file/analysis?line=5",
      "externalId": "external.id",
      "severity": "HIGH",
      "message": "This is an annotation message",
      "type": "BUG",
      "path": "src/some/structure/file.ext",
      "line": 5,
      "reportKey": "report.key"
    }
  ]
}

POST

Post insights latest projects {projectKey} repos {repositorySlug} commits {commitId} reports {key} 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 insights latest projects {projectKey} repos {repositorySlug} commits {commitId} reports {key} 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

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

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"
}'