# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Bitbucket Commits API
  version: 1.0.0
extends: openapi/bitbucket-commits-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: 25
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a commit
      effect: read
      questions:
      - Who authored this commit and what was its message?
      - Can I look up a single commit by hash?
      instructions:
      - text: Get commit {commit} in {workspace}/{repo_slug}.
        slots:
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show the author and message of commit {commit}.
        slots:
          commit: path.commit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/approve'].post
  update:
    x-apievangelist-phrasing:
      intent: Approve a commit
      effect: write
      questions:
      - Can I sign off on an individual commit?
      - How do I add my approval to a commit?
      instructions:
      - text: Approve commit {commit} in {workspace}/{repo_slug}.
        slots:
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Add my approval to commit {commit}.
        slots:
          commit: path.commit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/approve'].delete
  update:
    x-apievangelist-phrasing:
      intent: Withdraw my approval of a commit
      effect: destructive
      questions:
      - How do I take back my approval on a commit?
      - Can I unapprove a commit I signed off by mistake?
      instructions:
      - text: Unapprove commit {commit} in {workspace}/{repo_slug}.
        slots:
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Withdraw my approval from commit {commit}.
        slots:
          commit: path.commit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments on a commit
      effect: read
      questions:
      - What have people said about this commit, inline and general?
      - Can I sort a commit's comments newest first?
      instructions:
      - text: List comments on commit {commit} in {workspace}/{repo_slug}.
        slots:
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show comments on {commit} sorted by {sort}.
        slots:
          commit: path.commit
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/comments'].post
  update:
    x-apievangelist-phrasing:
      intent: Comment on a commit
      effect: write
      questions:
      - How do I leave a comment on a commit?
      - Can I reply to an existing comment thread on a commit?
      instructions:
      - text: Post a comment on commit {commit} in {workspace}/{repo_slug}.
        slots:
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Reply to the discussion on commit {commit}.
        slots:
          commit: path.commit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/comments/{comment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a commit comment
      effect: read
      questions:
      - Can I fetch one comment on a commit by id?
      - Who wrote a particular commit comment and when?
      instructions:
      - text: Get comment {comment_id} on commit {commit} in {workspace}/{repo_slug}.
        slots:
          comment_id: path.comment_id
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show commit comment {comment_id}.
        slots:
          comment_id: path.comment_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/comments/{comment_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a commit comment
      effect: write
      questions:
      - How do I fix a typo in a comment I left on a commit?
      - Can I edit the text of an existing commit comment?
      instructions:
      - text: Edit comment {comment_id} on commit {commit} in {workspace}/{repo_slug}.
        slots:
          comment_id: path.comment_id
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Update the text of my commit comment {comment_id}.
        slots:
          comment_id: path.comment_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/comments/{comment_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a commit comment
      effect: destructive
      questions:
      - How do I delete a comment I left on a commit?
      - What happens to replies when a commit comment is deleted?
      instructions:
      - text: Delete comment {comment_id} on commit {commit} in {workspace}/{repo_slug}.
        slots:
          comment_id: path.comment_id
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Remove my commit comment {comment_id}.
        slots:
          comment_id: path.comment_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/reports'].get
  update:
    x-apievangelist-phrasing:
      intent: List code insight reports on a commit
      effect: read
      questions:
      - Which code insight reports have been posted on this commit?
      - Can I see all the security and test reports linked to a commit?
      instructions:
      - text: List the reports on commit {commit} in {workspace}/{repo_slug}.
        slots:
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show every code insight report attached to commit {commit}.
        slots:
          commit: path.commit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a code insight report on a commit
      effect: read
      questions:
      - What did one specific code insight report on my commit conclude?
      - Can I fetch a single commit report by its ID to check its result?
      instructions:
      - text: Get 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: Show the result of code insight 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}'].put
  update:
    x-apievangelist-phrasing:
      intent: Publish a code insight report to a commit
      effect: write
      questions:
      - How do I post my scanner's results to a commit as a code insight report?
      - Can I update a report I already uploaded by reusing the same report ID?
      instructions:
      - text: Create report {reportId} titled {title} on commit {commit} in {workspace}/{repo_slug}.
        slots:
          reportId: path.reportId
          title: requestBody.title
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Upload report {reportId} for commit {commit} with result {result} and details {details}.
        slots:
          reportId: path.reportId
          commit: path.commit
          result: requestBody.result
          details: requestBody.details
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a code insight report from a commit
      effect: destructive
      questions:
      - How do I remove a code insight report that was posted on a commit by mistake?
      - Does deleting a commit report also remove its annotations?
      instructions:
      - text: Delete 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: Remove code insight report {reportId} 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 annotations in a commit report
      effect: read
      questions:
      - Which individual findings are listed in a code insight report?
      - Can I page through all annotations a report flagged on a commit?
      instructions:
      - text: List annotations for 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: Show every finding in code insight report {reportId} of 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: Upload many annotations to a report at once
      effect: write
      questions:
      - How do I attach a batch of vulnerability findings to a report in one call?
      - Can I bulk upload line-level annotations for a code insight report?
      instructions:
      - text: Bulk upload annotations to 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: Push a batch of findings into code insight 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: Get one annotation from a commit report
      effect: read
      questions:
      - What are the details of one specific finding in a code insight report?
      - Can I fetch a single annotation by its ID?
      instructions:
      - text: Get annotation {annotationId} in report {reportId} on commit {commit}, repo {workspace}/{repo_slug}.
        slots:
          annotationId: path.annotationId
          reportId: path.reportId
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show finding {annotationId} from code insight 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: Create or update a single report annotation
      effect: write
      questions:
      - How do I flag one line of code as a finding in a code insight report?
      - Can I set the severity and file path on an individual annotation?
      instructions:
      - text: Create annotation {annotationId} in report {reportId} on commit {commit} in {workspace}/{repo_slug} for file {path} line {line}.
        slots:
          annotationId: path.annotationId
          reportId: path.reportId
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
          path: requestBody.path
          line: requestBody.line
      - text: Set annotation {annotationId} on report {reportId} to severity {severity} with summary {summary}.
        slots:
          annotationId: path.annotationId
          reportId: path.reportId
          severity: requestBody.severity
          summary: requestBody.summary
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}/annotations/{annotationId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one annotation from a commit report
      effect: destructive
      questions:
      - How do I remove a single false-positive finding from a report?
      - Can I delete one annotation without deleting the whole report?
      instructions:
      - text: Delete annotation {annotationId} from 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: Remove finding {annotationId} from code insight report {reportId}.
        slots:
          annotationId: path.annotationId
          reportId: path.reportId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commits'].get
  update:
    x-apievangelist-phrasing:
      intent: List a repository's commits
      effect: read
      questions:
      - What are the latest commits in my repo, like git log?
      - Can I page through a repository's full commit history?
      instructions:
      - text: List commits in {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show the recent commit log for {repo_slug}.
        slots:
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commits'].post
  update:
    x-apievangelist-phrasing:
      intent: List commits with include and exclude in the body
      effect: read
      questions:
      - My include/exclude list is too long for the URL, can I send it in a request body?
      - Which commits are on one set of branches but not another, using a POST body?
      instructions:
      - text: List commits in {workspace}/{repo_slug} with include and exclude refs sent in the body.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Query the commit log of {repo_slug} using a long include/exclude list.
        slots:
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commits/{revision}'].get
  update:
    x-apievangelist-phrasing:
      intent: List commits reachable from a revision
      effect: read
      questions:
      - What commits lead up to a particular branch or hash?
      - Can I see the history of a single branch only?
      instructions:
      - text: List commits reachable from {revision} in {workspace}/{repo_slug}.
        slots:
          revision: path.revision
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show the commit log of branch {revision}.
        slots:
          revision: path.revision
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commits/{revision}'].post
  update:
    x-apievangelist-phrasing:
      intent: List a revision's commits with body filters
      effect: read
      questions:
      - Can I filter a revision's history with a long exclude list in the body?
      - Which commits from a branch are not in several other branches?
      instructions:
      - text: List commits from {revision} in {workspace}/{repo_slug} with include/exclude in the request body.
        slots:
          revision: path.revision
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Query history of {revision} excluding many refs via a POST body.
        slots:
          revision: path.revision
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/diff/{spec}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a raw diff between commits
      effect: read
      questions:
      - What changed between two commits, as a git-style diff?
      - Can I ignore whitespace when diffing two revisions?
      - Can I limit a diff to one file path?
      instructions:
      - text: Show the raw diff for {spec} in {workspace}/{repo_slug}.
        slots:
          spec: path.spec
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Diff {spec} restricted to {path}, ignoring whitespace {ignore_whitespace}.
        slots:
          spec: path.spec
          path: query.path
          ignore_whitespace: query.ignore_whitespace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/diffstat/{spec}'].get
  update:
    x-apievangelist-phrasing:
      intent: Summarize lines changed between commits
      effect: read
      questions:
      - How many lines were added and removed per file between two commits?
      - Which files were modified, added or renamed in a change?
      instructions:
      - text: Show the diffstat for {spec} in {workspace}/{repo_slug}.
        slots:
          spec: path.spec
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Count lines changed per file for {spec} under {path}.
        slots:
          spec: path.spec
          path: query.path
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/merge-base/{revspec}'].get
  update:
    x-apievangelist-phrasing:
      intent: Find the common ancestor of two commits
      effect: read
      questions:
      - Where did these two branches diverge?
      - What is the merge base of two commits?
      instructions:
      - text: Find the merge base for {revspec} in {workspace}/{repo_slug}.
        slots:
          revspec: path.revspec
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Get the best common ancestor of {revspec}.
        slots:
          revspec: path.revspec
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/patch/{spec}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a patch series for commits
      effect: read
      questions:
      - Can I export a commit as a patch file I can apply elsewhere?
      - Is there a git format-patch style output for a range of commits?
      instructions:
      - text: Get the patch for {spec} in {workspace}/{repo_slug}.
        slots:
          spec: path.spec
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Export {spec} as an applyable patch series.
        slots:
          spec: path.spec
      method: generated
      generated: '2026-10-01'