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
1 2 3 curl --request GET \ --url 'http://{baseurl}/rest/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/annotations' \ --header 'Accept: application/json'
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "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
1 2 3 curl --request GET \ --url 'http://{baseurl}/rest/insights/latest/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/reports' \ --header 'Accept: application/json'
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 { "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}
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { "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

ParameterDescriptionRequired?RestrictionsType
titleA short string representing the name of the reportYesMax 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. NoMax length: 2000 charactersString
resultIndicates whether the report is in a passed or failed stateNoOne of: PASS, FAILString
dataAn array of data fields (described below) to display information on the reportNoMaximum 6 data fieldsArray
reporterA string to describe the tool or company who created the reportNoMax length: 450 charactersString
linkA URL linking to the results of the report in an external tool.NoMust be a valid http or https URLString
logoUrlA URL to the report logo. If none is provided, the default insights logo will be used.NoMust be a valid http or https URLString

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).
ParameterDescriptionType
titleA string describing what this data field representsString
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 FieldValue Field TypeValue Field Display
None/OmittedNumber, String or Boolean (not an array or object)Plain text
BOOLEANBooleanThe value will be read as a JSON boolean and displayed as 'Yes' or 'No'.
DATENumber 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.
DURATIONNumber The value will be read as a JSON number in milliseconds and will be displayed in a human readable duration format.
LINKObject: {"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.
NUMBERNumber The value will be read as a JSON number and large numbers will be displayed in a human readable format (e.g. 14.3k).
PERCENTAGENumber (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.
TEXTStringThe 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}
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { "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}
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
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "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

ParameterDescriptionRequired?RestrictionsType
pathThe 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.NoString
lineThe 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.NoNon-negative integerInteger
messageThe message to display to usersYesThe 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
severityThe severity of the annotationYesOne of: LOW, MEDIUM, HIGHString
linkAn http or https URL representing the location of the annotation in the external toolNoString
typeThe type of annotation postedNoOne of: VULNERABILITY, CODE_SMELL, BUGString
externalIdIf 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.NoA string value shorter than 450 charactersString

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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 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
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}
1 2 3 4 5 6 7 8 9 10 11 12 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" }'

Rate this page: