# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Bitbucket Reports API
  version: 1.0.0
extends: openapi/bitbucket-reports-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 9
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/reports'].get
  update:
    x-apievangelist-phrasing:
      intent: List reports attached to a commit
      effect: read
      questions:
      - What test, coverage or scan reports exist for a given commit?
      - Can I list the code insights a CI tool has published on one commit?
      instructions:
      - text: Show all code insight reports for commit {commit} in {workspace}/{repo_slug}.
        slots:
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: List reports linked to commit {commit} of repo {repo_slug}.
        slots:
          commit: path.commit
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a single code insight report
      effect: read
      questions:
      - Did a particular code insight report pass or fail?
      - How can I read the details and data fields of one report by ID?
      instructions:
      - text: Retrieve code insight report {reportId} for commit {commit} in {workspace}/{repo_slug}.
        slots:
          reportId: path.reportId
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Look up report {reportId} on commit {commit} and tell me its result.
        slots:
          reportId: path.reportId
          commit: path.commit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update a code insight report
      effect: write
      questions:
      - How can my CI tool publish coverage results as a report on a commit?
      - Can I set a logo, link and report type on a code insight report?
      instructions:
      - text: Publish code insight report {reportId} on commit {commit} in {workspace}/{repo_slug} with title {title}.
        slots:
          reportId: path.reportId
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
          title: requestBody.title
      - text: Upsert report {reportId} on commit {commit} as type {report_type} with result {result}.
        slots:
          reportId: path.reportId
          commit: path.commit
          report_type: requestBody.report_type
          result: requestBody.result
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a code insight report
      effect: destructive
      questions:
      - How can I delete an outdated code insight report from a commit?
      - Is it possible to take down a report my pipeline published?
      instructions:
      - text: Remove code insight report {reportId} from commit {commit} in {workspace}/{repo_slug}.
        slots:
          reportId: path.reportId
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Delete the report {reportId} posted on commit {commit}.
        slots:
          reportId: path.reportId
          commit: path.commit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}/annotations'].get
  update:
    x-apievangelist-phrasing:
      intent: List the findings in a code insight report
      effect: read
      questions:
      - What issues did a code insight report flag, line by line?
      - Can I retrieve the paginated annotations belonging to one report?
      instructions:
      - text: Show annotations of code insight report {reportId} on commit {commit} in {workspace}/{repo_slug}.
        slots:
          reportId: path.reportId
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: List the line-level findings in report {reportId} for commit {commit}.
        slots:
          reportId: path.reportId
          commit: path.commit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}/annotations'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk upload findings to a code insight report
      effect: write
      questions:
      - How can I send all my linter findings to a report in a single request?
      - Is there a batch endpoint for creating or updating report annotations?
      instructions:
      - text: Upload a batch of annotations to code insight report {reportId} on commit {commit} in {workspace}/{repo_slug}.
        slots:
          reportId: path.reportId
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Bulk create or update findings on report {reportId} for commit {commit}.
        slots:
          reportId: path.reportId
          commit: path.commit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}/annotations/{annotationId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a single report finding
      effect: read
      questions:
      - What severity and file location does one report finding have?
      - How can I look up a specific annotation inside a report?
      instructions:
      - text: Retrieve annotation {annotationId} of code insight report {reportId} on commit {commit} in {workspace}/{repo_slug}.
        slots:
          annotationId: path.annotationId
          reportId: path.reportId
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Look up finding {annotationId} in report {reportId}.
        slots:
          annotationId: path.annotationId
          reportId: path.reportId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}/annotations/{annotationId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Upsert one finding on a code insight report
      effect: write
      questions:
      - How can I mark a single vulnerability on a specific file and line in a report?
      - Can I change the result of one annotation to passed after a fix?
      instructions:
      - text: Upsert annotation {annotationId} on code insight report {reportId} for commit {commit} in {workspace}/{repo_slug} with type {annotation_type}.
        slots:
          annotationId: path.annotationId
          reportId: path.reportId
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
          annotation_type: requestBody.annotation_type
      - text: Mark annotation {annotationId} in report {reportId} as {result}.
        slots:
          annotationId: path.annotationId
          reportId: path.reportId
          result: requestBody.result
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}/annotations/{annotationId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a single report finding
      effect: destructive
      questions:
      - How can I drop a single annotation that no longer applies?
      - Is it possible to delete one finding while keeping the rest of the report?
      instructions:
      - text: Remove annotation {annotationId} from code insight report {reportId} on commit {commit} in {workspace}/{repo_slug}.
        slots:
          annotationId: path.annotationId
          reportId: path.reportId
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Delete the single finding {annotationId} in report {reportId}.
        slots:
          annotationId: path.annotationId
          reportId: path.reportId
      method: generated
      generated: '2026-10-01'