# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Atlassian Bitbucket Commits API
  version: 1.0.0
extends: openapi/atlassian-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: 16
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single commit
      effect: read
      questions:
      - How do I look up the author and message of one commit in a Bitbucket repo?
      - What details does a single commit record include?
      instructions:
      - text: Get commit {commit} in {workspace}/{repo_slug}.
        slots:
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show me the details 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:
      - How do I sign off on a specific commit as approved?
      - Can anyone with read access approve a commit in a public repo?
      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:
      - Can I take back an approval I gave a commit?
      - How do I unapprove a commit I signed off on too early?
      instructions:
      - text: Remove my approval from commit {commit} in {workspace}/{repo_slug}.
        slots:
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Unapprove 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 review comments have been left on this commit, inline ones included?
      - Can I sort or filter the comments on a commit?
      instructions:
      - text: List the 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 {commit} matching {q}, sorted by {sort}.
        slots:
          commit: path.commit
          q: query.q
          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 review comment on a commit?
      - Can I reply to an existing comment thread on a commit?
      instructions:
      - text: Add a comment to commit {commit} in {workspace}/{repo_slug}.
        slots:
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Post a reply on commit {commit} under its existing comment thread.
        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 one comment on a commit
      effect: read
      questions:
      - How do I fetch a single commit comment by id?
      - What does one comment on a commit contain?
      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 me 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 comment on a commit
      effect: write
      questions:
      - Can I change the wording of a comment I left on a commit?
      - Is only the text of a commit comment editable?
      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: Rewrite 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 comment on a commit
      effect: destructive
      questions:
      - How do I delete a comment I left on a commit?
      - What happens when I delete a commit comment that has replies?
      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 commit comment {comment_id}.
        slots:
          comment_id: path.comment_id
      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:
      - How do I get the git log of a Bitbucket repository?
      - Are repository commits returned newest first?
      instructions:
      - text: List all commits in {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show me the commit history across every branch of repo {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 repository commits with include/exclude in the body
      effect: read
      questions:
      - My include and exclude lists are too long for the URL; how can I still filter the repo's commits?
      - Can I POST commit filters instead of putting them in the query string?
      instructions:
      - text: List commits in {workspace}/{repo_slug} passing include and exclude refs in the request body.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Query repo {repo_slug} commits via POST with a long 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 branch or revision
      effect: read
      questions:
      - How do I see the commit history of just one branch?
      - Can I list the commits leading up to a specific tag or revision?
      instructions:
      - text: List commits on revision {revision} in {workspace}/{repo_slug}.
        slots:
          revision: path.revision
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show the git log for 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 include/exclude in the body
      effect: read
      questions:
      - How do I filter a branch's commit history when my exclude list is too long for the URL?
      - Can I POST include and exclude refs for one revision's commit log?
      instructions:
      - text: List commits on revision {revision} in {workspace}/{repo_slug} with include and exclude refs in the body.
        slots:
          revision: path.revision
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: POST a filtered commit query for branch {revision}.
        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 git diff between commits
      effect: read
      questions:
      - How do I get the raw diff between two commits?
      - Can I ignore whitespace or limit a diff to one file path?
      - What does a diff of a single commit compare against?
      instructions:
      - text: Show the diff for {spec} in {workspace}/{repo_slug}.
        slots:
          spec: path.spec
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Diff {spec} only for file {path}, ignoring whitespace set to {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: Get per-file line change stats between commits
      effect: read
      questions:
      - How many lines were added and removed per file between two commits?
      - Which files changed between two revisions, and how?
      instructions:
      - text: Get the diffstat for {spec} in {workspace}/{repo_slug}.
        slots:
          spec: path.spec
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Summarize files changed in {spec} under path {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 merge base of two commits
      effect: read
      questions:
      - Where did these two branches diverge?
      - How do I find the best common ancestor 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 common ancestor commit 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 git patch for a commit or commit range
      effect: read
      questions:
      - Can I download a commit as a patch I can apply with git am?
      - How do I get a patch series between two 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: Produce a patch series for commit range {spec}.
        slots:
          spec: path.spec
      method: generated
      generated: '2026-10-01'