# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Bitbucket Refs API
  version: 1.0.0
extends: openapi/bitbucket-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 branches and tags together
      effect: read
      questions:
      - Can I see every branch and tag in a repo in one list?
      - What refs exist in my repository, both branches and tags?
      instructions:
      - text: List all branches and tags in {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show refs in {workspace}/{repo_slug} matching {q}, branches and tags combined.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
          q: query.q
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/refs/branches'].get
  update:
    x-apievangelist-phrasing:
      intent: List open branches
      effect: read
      questions:
      - Which branches are open in my Bitbucket repo?
      - Can I search branches by name and sort by most recent commit?
      instructions:
      - text: List open branches in {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Find branches in {workspace}/{repo_slug} matching {q}, sorted by {sort}.
        slots:
          workspace: path.workspace
          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'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a branch
      effect: write
      questions:
      - How do I create a new branch from a commit through the API?
      - Can I cut a branch off a specific hash without cloning?
      instructions:
      - text: Create a new branch in {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Cut a fresh branch from a target commit in {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 branch pointing at right now?
      - Can I fetch the details of one branch by name?
      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}.
        slots:
          name: path.name
      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 branch?
      - Can I delete the main branch through the API?
      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
      effect: read
      questions:
      - Which release tags exist in my repo?
      - Can I filter tags by name pattern and sort them?
      instructions:
      - text: List tags in {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Find tags in {workspace}/{repo_slug} matching {q}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
          q: query.q
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/refs/tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an annotated tag
      effect: write
      questions:
      - How do I tag a release commit?
      - Can I add a message when I create a tag?
      instructions:
      - text: Create tag {name} in {workspace}/{repo_slug}.
        slots:
          name: requestBody.name
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Tag commit {target} as {name} with message {message}.
        slots:
          target: requestBody.target
          name: requestBody.name
          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 given tag point to?
      - Can I look up a tag's tagger and message?
      instructions:
      - text: Get tag {name} in {workspace}/{repo_slug}.
        slots:
          name: path.name
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show which commit tag {name} points at.
        slots:
          name: path.name
      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 I created by mistake?
      - Is it possible to delete a release tag?
      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'