openapi: 3.1.0 info: title: Atlassian Admin Account Annotations API description: The Atlassian Admin API provides programmatic access to manage Atlassian organizations, users, domains, policies, and events. It enables administrators to automate organization management tasks, integrate with identity providers, and ensure appropriate access to Atlassian products. version: 1.0.0 contact: name: Atlassian Developer url: https://developer.atlassian.com/cloud/admin/ license: name: Atlassian Developer Terms url: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/ x-logo: url: https://wac-cdn.atlassian.com/assets/img/favicons/atlassian/favicon.png servers: - url: https://api.atlassian.com description: Atlassian Cloud API security: - bearerAuth: [] - oauth2: [] tags: - name: Annotations paths: /repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}/annotations: get: tags: - Annotations description: Returns a paginated list of Annotations for a specific report associated with a commit in a Bitbucket repository. This endpoint allows you to retrieve all annotations that were added to a particular report, which typically includes details about code quality issues, security vulnerabilities, or other automated checks performed on the commit. The annotations provide granular feedback on specific lines or sections of code, including severity levels, paths, line numbers, and descriptive messages. You must specify the workspace, repository slug, commit hash, and report ID to access the annotations, and the results are returned in a paginated format to handle large sets of annotation data efficiently. summary: Atlassian List Annotations operationId: listAnnotations parameters: - name: workspace description: This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example `{workspace UUID}`. required: true in: path schema: type: string - name: repo_slug description: The repository. required: true in: path schema: type: string - name: commit description: The commit for which to retrieve reports. required: true in: path schema: type: string - name: reportId description: Uuid or external-if of the report for which to get annotations for. required: true in: path schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/paginated_annotations' examples: paginated-annotations: $ref: '#/components/examples/paginated-annotations' x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - read:repository:bitbucket security: - oauth2: - repository - basic: [] - api_key: [] x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true x-microcks-operation: delay: 0 dispatcher: FALLBACK post: tags: - Annotations description: Creates or updates individual annotation objects within a specified commit report in a Bitbucket repository, allowing developers to programmatically add code analysis findings, linting errors, test results, or other automated feedback directly to a specific commit. The operation requires the workspace ID, repository slug, commit hash, and report ID as path parameters, and accepts an array of annotation objects in the request body, each containing details such as line number, severity, annotation type, summary, and optional description. This bulk operation enables CI/CD pipelines and development tools to efficiently attach multiple code quality insights to a single commit, making review feedback immediately visible within the Bitbucket interface and helping teams maintain code standards through automated checks. operationId: bulkCreateOrUpdateAnnotations summary: Atlassian Bulk Create or Update Annotations parameters: - name: workspace description: This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example `{workspace UUID}`. required: true in: path schema: type: string - name: repo_slug description: The repository. required: true in: path schema: type: string - name: commit description: The commit for which to retrieve reports. required: true in: path schema: type: string - name: reportId description: Uuid or external-if of the report for which to get annotations for. required: true in: path schema: type: string requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/report_annotation' minItems: 1 maxItems: 100 examples: bulk-create-or-update-annotations_2: $ref: '#/components/examples/bulk-create-or-update-annotations_2' description: The annotations to create or update required: true responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/report_annotation' examples: undefined_2: $ref: '#/components/examples/undefined_2' security: - oauth2: - repository - basic: [] - api_key: [] x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationRequestSchema: true GenerateExampleFromOperationResponseSchema: true x-microcks-operation: delay: 0 dispatcher: FALLBACK /repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}/annotations/{annotationId}: get: tags: - Annotations description: This API operation retrieves a specific annotation associated with a code insights report for a particular commit in a Bitbucket repository. By providing the workspace identifier, repository slug, commit hash, report ID, and annotation ID in the URL path, users can fetch detailed information about a single annotation that was previously created for code quality, security findings, or other automated analysis results. The annotation typically contains metadata such as the file path, line number, severity level, and description of an issue or finding detected in the code at that specific commit point. summary: Atlassian Get an Annotation operationId: getAnAnnotation parameters: - name: workspace description: This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example `{workspace UUID}`. required: true in: path schema: type: string - name: repo_slug description: The repository. required: true in: path schema: type: string - name: commit description: The commit the report belongs to. required: true in: path schema: type: string - name: reportId description: Either the uuid or external-id of the report. required: true in: path schema: type: string - name: annotationId description: Either the uuid or external-id of the annotation. required: true in: path schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/report_annotation' examples: report-annotation: $ref: '#/components/examples/report-annotation' '404': description: The annotation with the given ID was not found. content: application/json: schema: $ref: '#/components/schemas/error' x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - read:repository:bitbucket security: - oauth2: - repository - basic: [] - api_key: [] x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true x-microcks-operation: delay: 0 dispatcher: FALLBACK put: tags: - Annotations description: This PUT operation allows users to create or update a specific annotation for a code report associated with a particular commit in a Bitbucket repository. By providing the workspace identifier, repository slug, commit hash, report ID, and annotation ID in the URL path, developers can add detailed feedback or metadata about specific lines or sections of code within that commit's report. Annotations are typically used in CI/CD pipelines or code analysis tools to highlight issues, warnings, or suggestions directly within the Bitbucket interface, enabling better code review workflows and automated quality checks. If an annotation with the specified ID already exists, this operation updates it with the new information provided in the request body; otherwise, it creates a new annotation with that ID. operationId: createOrUpdateAnAnnotation summary: Atlassian Create or Update an Annotation parameters: - name: workspace description: This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example `{workspace UUID}`. required: true in: path schema: type: string - name: repo_slug description: The repository. required: true in: path schema: type: string - name: commit description: The commit the report belongs to. required: true in: path schema: type: string - name: reportId description: Either the uuid or external-id of the report. required: true in: path schema: type: string - name: annotationId description: Either the uuid or external-id of the annotation. required: true in: path schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/report_annotation' examples: report-annotation_2: $ref: '#/components/examples/report-annotation_2' description: The annotation to create or update required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/report_annotation' examples: report-annotation_2: $ref: '#/components/examples/report-annotation_2' '400': description: The provided Annotation object is malformed or incomplete. content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - repository - basic: [] - api_key: [] x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationRequestSchema: true GenerateExampleFromOperationResponseSchema: true x-microcks-operation: delay: 0 dispatcher: FALLBACK delete: tags: - Annotations description: Deletes a specific annotation from a report associated with a commit in a Bitbucket repository. This operation removes an individual annotation identified by its unique annotationId from a report (specified by reportId) that was previously attached to a particular commit. The annotation could represent various code analysis findings such as linting errors, security vulnerabilities, or test failures that were previously reported through Bitbucket's commit insights feature. Once deleted, the annotation will no longer appear in the commit's report overview or affect the overall report status, allowing teams to clean up outdated or incorrect analysis results while maintaining the integrity of their code review and CI/CD workflows. summary: Atlassian Delete an Annotation operationId: deleteAnAnnotation parameters: - name: workspace description: This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example `{workspace UUID}`. required: true in: path schema: type: string - name: repo_slug description: The repository. required: true in: path schema: type: string - name: commit description: The commit the annotation belongs to. required: true in: path schema: type: string - name: reportId description: Either the uuid or external-id of the annotation. required: true in: path schema: type: string - name: annotationId description: Either the uuid or external-id of the annotation. required: true in: path schema: type: string responses: '204': description: No content security: - oauth2: - repository - basic: [] - api_key: [] x-api-evangelist-processing: WriteDescription: true ChooseTags: true x-microcks-operation: delay: 0 dispatcher: FALLBACK components: schemas: report_annotation: allOf: - $ref: '#/components/schemas/object' - additionalProperties: true type: object title: Report Annotation description: A report for a commit. properties: external_id: type: string description: ID of the annotation provided by the annotation creator. It can be used to identify the annotation as an alternative to it's generated uuid. It is not used by Bitbucket, but only by the annotation creator for updating or deleting this specific annotation. Needs to be unique. uuid: type: string description: The UUID that can be used to identify the annotation. annotation_type: enum: - VULNERABILITY - CODE_SMELL - BUG type: string description: The type of the report. path: type: string description: The path of the file on which this annotation should be placed. This is the path of the file relative to the git repository. If no path is provided, then it will appear in the overview modal on all pull requests where the tip of the branch is the given commit, regardless of which files were modified. line: type: integer description: The line number that the annotation should belong to. If no line number is provided, then it will default to 0 and in a pull request it will appear at the top of the file specified by the path field. minimum: 1 summary: type: string description: The message to display to users. details: type: string description: The details to show to users when clicking on the annotation. result: enum: - PASSED - FAILED - SKIPPED - IGNORED type: string description: The state of the report. May be set to PENDING and later updated. severity: enum: - CRITICAL - HIGH - MEDIUM - LOW type: string description: The severity of the annotation. link: type: string format: uri description: A URL linking to the annotation in an external tool. created_on: type: string format: date-time description: The timestamp when the report was created. updated_on: type: string format: date-time description: The timestamp when the report was updated. x-bb-default-fields: - uuid x-bb-url: /rest/2.0/accounts/{target_user.uuid}/repositories/{repository.uuid}/commits/{commit.hash}/reports/{reportUuid}/annotations/{uuid} 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 example: example_value 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 example: example_value required: - type additionalProperties: true object: type: object 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 example: example_value required: - type additionalProperties: true discriminator: propertyName: type paginated_annotations: type: object title: Paginated Annotations description: A paginated list of annotations. properties: page: type: integer description: Page number of the current results. This is an optional element that is not provided in all responses. example: 10 values: type: array minItems: 0 items: $ref: '#/components/schemas/report_annotation' description: The values of the current page. example: [] 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. example: 10 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. example: 10 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. example: https://www.example.com 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. example: https://www.example.com examples: report-annotation: external_id: VULN-2024-001 uuid: 123e4567-e89b-12d3-a456-426614174000 annotation_type: VULNERABILITY path: src/main/java/com/example/Application.java line: 42 summary: SQL injection vulnerability detected details: User input is directly concatenated into SQL query without proper sanitization. This could allow an attacker to execute arbitrary SQL commands. result: FAILED severity: HIGH link: https://security-scanner.example.com/reports/VULN-2024-001 created_on: '2024-01-15T10:30:00Z' updated_on: '2024-01-15T14:45:00Z' undefined_2: - id: annotation_123 report_id: report_456 user_id: user_789 text: This section needs clarification start_position: 150 end_position: 200 created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' - id: annotation_124 report_id: report_456 user_id: user_790 text: Data looks accurate start_position: 350 end_position: 400 created_at: '2024-01-15T11:45:00Z' updated_at: '2024-01-15T11:45:00Z' bulk-create-or-update-annotations_2: - report_annotation: Example annotation text paginated-annotations: page: 1 values: external_id: annotation-12345 uuid: 550e8400-e29b-41d4-a716-446655440000 annotation_type: VULNERABILITY path: src/main/java/com/example/Application.java line: 42 summary: Potential SQL injection vulnerability detected details: User input is being concatenated directly into SQL query without sanitization. Consider using parameterized queries to prevent SQL injection attacks. result: FAILED severity: HIGH link: https://security-scanner.example.com/reports/12345 created_on: '2024-01-15T10:30:00Z' updated_on: '2024-01-15T14:45:00Z' size: 50 pagelen: 10 next: https://api.bitbucket.org/2.0/repositories/example/repo/commit/abc123/annotations?page=2 previous: https://api.bitbucket.org/2.0/repositories/example/repo/commit/abc123/annotations?page=0 report-annotation_2: external_id: VULN-12345 uuid: 123e4567-e89b-12d3-a456-426614174000 annotation_type: VULNERABILITY path: src/main/java/com/example/Application.java line: 42 summary: SQL Injection vulnerability detected details: User input is directly concatenated into SQL query without proper sanitization. This could allow an attacker to execute arbitrary SQL commands. result: FAILED severity: HIGH link: https://security-tool.example.com/reports/VULN-12345 created_on: '2024-01-15T10:30:00Z' updated_on: '2024-01-15T14:45:30Z' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: Use an Atlassian API key as a Bearer token. Create API keys at https://admin.atlassian.com. oauth2: type: oauth2 description: OAuth 2.0 authorization for Atlassian Cloud APIs. flows: authorizationCode: authorizationUrl: https://auth.atlassian.com/authorize tokenUrl: https://auth.atlassian.com/oauth/token scopes: read:org:admin: Read organization information. write:org:admin: Modify organization settings. read:user:admin: Read user information. write:user:admin: Modify user accounts. read:policy:admin: Read organization policies. write:policy:admin: Modify organization policies. read:event:admin: Read organization events. externalDocs: description: Atlassian Admin REST API Documentation url: https://developer.atlassian.com/cloud/admin/organization/rest/intro/