API Evangelist conversational phrasing for Atlassian Bitbucket Refs API

# 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 Refs API
  version: 1.0.0
extends: openapi/atlassian-refs-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}/refs'].get
  update:
    x-apievangelist-phrasing:
      intent: List all branches and tags together
      effect: read
      questions:
      - Can I get every branch and tag in a repository in one list?
      - Is it possible to filter refs by name when listing branches and tags together?
      instructions:
      - text: List all branches and tags in {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show refs of any kind in {repo_slug} matching {q}, sorted by {sort}.
        slots:
          repo_slug: path.repo_slug
          q: query.q
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/refs/branches'].get
  update:
    x-apievangelist-phrasing:
      intent: List open branches in a repository
      effect: read
      questions:
      - What branches currently exist in this repository?
      - Can I search branches by name, for example everything starting with feature/?
      instructions:
      - text: List the open branches in {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Find branches only, not tags, in {repo_slug} matching {q}.
        slots:
          repo_slug: path.repo_slug
          q: query.q
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/refs/branches'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a branch
      effect: write
      questions:
      - How do I create a new branch from a specific commit hash?
      - Can I make a branch in a Bitbucket repo without cloning it?
      instructions:
      - text: Create a new branch in {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Branch off a target commit in repo {repo_slug}.
        slots:
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/refs/branches/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a branch
      effect: read
      questions:
      - What commit is a given branch pointing at right now?
      - Does a branch with this name exist in the repo?
      instructions:
      - text: Get branch {name} in {workspace}/{repo_slug}.
        slots:
          name: path.name
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show the head commit of branch {name} in {repo_slug}.
        slots:
          name: path.name
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/refs/branches/{name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a branch
      effect: destructive
      questions:
      - How do I delete a merged feature branch?
      - Can I delete the repository's main branch?
      instructions:
      - text: Delete branch {name} from {workspace}/{repo_slug}.
        slots:
          name: path.name
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Remove the stale branch {name} in {repo_slug}.
        slots:
          name: path.name
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/refs/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List tags in a repository
      effect: read
      questions:
      - Which release tags exist in this repository?
      - Can I sort tags so the newest version comes first?
      instructions:
      - text: List the tags in {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show tags only in {repo_slug} matching {q}, sorted by {sort}.
        slots:
          repo_slug: path.repo_slug
          q: query.q
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/refs/tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a tag
      effect: write
      questions:
      - How do I tag a release commit in a Bitbucket repository?
      - Can I add a message when creating a tag?
      instructions:
      - text: Create tag {name} on commit {target} in {workspace}/{repo_slug}.
        slots:
          name: requestBody.name
          target: requestBody.target
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Tag {target} as {name} in {repo_slug} with message {message}.
        slots:
          target: requestBody.target
          name: requestBody.name
          repo_slug: path.repo_slug
          message: requestBody.message
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/refs/tags/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tag
      effect: read
      questions:
      - Which commit does a release tag point to?
      - Can I look up a single tag by name?
      instructions:
      - text: Get tag {name} in {workspace}/{repo_slug}.
        slots:
          name: path.name
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show the commit behind tag {name} in {repo_slug}.
        slots:
          name: path.name
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/refs/tags/{name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a tag
      effect: destructive
      questions:
      - How do I remove a tag that was created by mistake?
      - Should the tag name include the refs/tags prefix when deleting?
      instructions:
      - text: Delete tag {name} from {workspace}/{repo_slug}.
        slots:
          name: path.name
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Remove the mistaken tag {name} in {repo_slug}.
        slots:
          name: path.name
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'