# 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 Issue Tracker API
  version: 1.0.0
extends: openapi/atlassian-issue-tracker-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: 33
- target: $.paths['/repositories/{workspace}/{repo_slug}/components'].get
  update:
    x-apievangelist-phrasing:
      intent: List issue tracker components in a repository
      effect: read
      questions:
      - What components are defined in my Bitbucket repository's issue tracker?
      - Can I see every component I can file repo issues against?
      instructions:
      - text: List the issue tracker components in {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show me which components exist for issues in repo {repo_slug}.
        slots:
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/components/{component_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one issue tracker component
      effect: read
      questions:
      - How do I look up a single issue tracker component by its id?
      - What details does a repo's issue component record hold?
      instructions:
      - text: Get issue tracker component {component_id} in {workspace}/{repo_slug}.
        slots:
          component_id: path.component_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Fetch the details of component {component_id} from the repo's issue tracker.
        slots:
          component_id: path.component_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues'].get
  update:
    x-apievangelist-phrasing:
      intent: List issues in a repository's issue tracker
      effect: read
      questions:
      - Which issues are open in my repository's issue tracker?
      - Can I pull every issue filed against a Bitbucket repo?
      instructions:
      - text: List all issues in the {workspace}/{repo_slug} issue tracker.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show me the issues filed on repository {repo_slug}.
        slots:
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an issue in a repository
      effect: write
      questions:
      - How do I file a new bug in a repository's issue tracker?
      - Can I set priority and kind when I open a repo issue?
      - Who is recorded as the reporter when an issue is created through the API?
      instructions:
      - text: Open a new issue titled {title} in {workspace}/{repo_slug}.
        slots:
          title: requestBody.title
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: File a {kind} issue with priority {priority} called {title} in repo {repo_slug}.
        slots:
          kind: requestBody.kind
          priority: requestBody.priority
          title: requestBody.title
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/export'].post
  update:
    x-apievangelist-phrasing:
      intent: Start an export of a repository's issues
      effect: write
      questions:
      - How do I export all the issues in a repo to a zip archive?
      - Can the issue export include attachments and email me when it's done?
      instructions:
      - text: Start an issue export for {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Kick off an export of repo {repo_slug} issues with attachments set to {include_attachments}.
        slots:
          repo_slug: path.repo_slug
          include_attachments: requestBody.include_attachments
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/export/{repo_name}-issues-{task_id}.zip'].get
  update:
    x-apievangelist-phrasing:
      intent: Check an issue export job and download its zip
      effect: read
      questions:
      - Is my repository issue export finished yet?
      - Where do I download the zip file once an issue export completes?
      instructions:
      - text: Check the status of issue export task {task_id} for {repo_name} in {workspace}/{repo_slug}.
        slots:
          task_id: path.task_id
          repo_name: path.repo_name
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Download the finished issue export zip for task {task_id}.
        slots:
          task_id: path.task_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/import'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of an issue import
      effect: read
      questions:
      - Has my issue import into the repository started or finished?
      - What progress does the current issue import job report?
      instructions:
      - text: Check the issue import status for {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Tell me how far along the issue import is in repo {repo_slug}.
        slots:
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import issues from a zip, replacing existing ones
      effect: destructive
      questions:
      - How do I import an exported issue zip into a repository?
      - Does importing issues delete the issues already in the tracker?
      instructions:
      - text: Import the issue archive into {workspace}/{repo_slug}, replacing its current issues.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Upload an issue export zip to repo {repo_slug} to restore its issues.
        slots:
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single repository issue
      effect: read
      questions:
      - How can I see the details of one repo issue by number?
      - What does a single issue record in the tracker contain?
      instructions:
      - text: Get issue {issue_id} from {workspace}/{repo_slug}.
        slots:
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Show me the title, state and assignee of issue #{issue_id}.'
        slots:
          issue_id: path.issue_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a repository issue's fields
      effect: write
      questions:
      - How do I change the title or assignee of an existing repo issue?
      - Can I edit an issue's priority after it was filed?
      instructions:
      - text: Update issue {issue_id} in {workspace}/{repo_slug} with a new title.
        slots:
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Edit the fields of issue #{issue_id} directly.'
        slots:
          issue_id: path.issue_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a repository issue
      effect: destructive
      questions:
      - How do I permanently delete an issue from a repo's tracker?
      - What access do I need to remove an issue?
      instructions:
      - text: Delete issue {issue_id} from {workspace}/{repo_slug}.
        slots:
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Remove issue #{issue_id} from the tracker.'
        slots:
          issue_id: path.issue_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/attachments'].get
  update:
    x-apievangelist-phrasing:
      intent: List attachments on a repository issue
      effect: read
      questions:
      - Which files are attached to this repo issue?
      - Can I get attachment metadata for an issue without downloading the files?
      instructions:
      - text: List the attachments on issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Show me the files uploaded to issue #{issue_id}, ordered by upload date.'
        slots:
          issue_id: path.issue_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/attachments'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a file attachment to an issue
      effect: write
      questions:
      - How do I attach a log file to a repo issue?
      - What happens if I upload a file with the same name as an existing issue attachment?
      instructions:
      - text: Upload an attachment to issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Attach this screenshot to issue #{issue_id}.'
        slots:
          issue_id: path.issue_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/attachments/{path}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an issue attachment's contents
      effect: read
      questions:
      - How do I download the raw file attached to a repo issue?
      - Does fetching an issue attachment return a one-time redirect link?
      instructions:
      - text: Download attachment {path} from issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          path: path.path
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Get the contents of the file {path} attached to issue #{issue_id}.'
        slots:
          path: path.path
          issue_id: path.issue_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/attachments/{path}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an attachment from an issue
      effect: destructive
      questions:
      - How do I remove a file I attached to a repo issue by mistake?
      - Can an issue attachment be deleted by its file name?
      instructions:
      - text: Delete attachment {path} from issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          path: path.path
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Remove the file {path} from issue #{issue_id}.'
        slots:
          path: path.path
          issue_id: path.issue_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/changes'].get
  update:
    x-apievangelist-phrasing:
      intent: List the change history of an issue
      effect: read
      questions:
      - What edits have been made to this repo issue over time?
      - Can I filter an issue's change log, for example to state changes only?
      instructions:
      - text: List the change history of issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Show changes on issue #{issue_id} matching {q}, sorted by {sort}.'
        slots:
          issue_id: path.issue_id
          q: query.q
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/changes'].post
  update:
    x-apievangelist-phrasing:
      intent: Change an issue's state through a change record
      effect: write
      questions:
      - How do I resolve a repo issue and leave a message explaining why?
      - Can I change an issue's state and assignee in one recorded change?
      instructions:
      - text: Post a change to issue {issue_id} in {workspace}/{repo_slug} with message {message}.
        slots:
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
          message: requestBody.message
      - text: 'Record a state change on issue #{issue_id} using changes {changes}.'
        slots:
          issue_id: path.issue_id
          changes: requestBody.changes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/changes/{change_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one change record on an issue
      effect: read
      questions:
      - How do I see exactly what one recorded change did to an issue?
      - Can I look up a single issue change by its change id?
      instructions:
      - text: Get change {change_id} on issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          change_id: path.change_id
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Show me change record {change_id} for issue #{issue_id}.'
        slots:
          change_id: path.change_id
          issue_id: path.issue_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments on a repository issue
      effect: read
      questions:
      - What has everyone said in the comments on this repo issue?
      - Can I filter the comments on an issue with a query?
      instructions:
      - text: List the comments on issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Find comments on issue #{issue_id} matching {q}.'
        slots:
          issue_id: path.issue_id
          q: query.q
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/comments'].post
  update:
    x-apievangelist-phrasing:
      intent: Comment on a repository issue
      effect: write
      questions:
      - How do I add a comment to a repo issue?
      - Can an agent post a reply on an issue in the tracker?
      instructions:
      - text: Add a comment to issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Post a new comment on issue #{issue_id} saying the fix is deployed.'
        slots:
          issue_id: path.issue_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/comments/{comment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one comment on a repository issue
      effect: read
      questions:
      - How do I fetch a single issue comment by its id?
      - What does one comment on a repo issue look like?
      instructions:
      - text: Get comment {comment_id} on issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          comment_id: path.comment_id
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show me issue comment {comment_id}.
        slots:
          comment_id: path.comment_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/comments/{comment_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a comment on a repository issue
      effect: write
      questions:
      - Can I fix a typo in a comment I already left on an issue?
      - Which part of an issue comment is editable?
      instructions:
      - text: Edit comment {comment_id} on issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          comment_id: path.comment_id
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Rewrite the text of my existing issue comment {comment_id}.
        slots:
          comment_id: path.comment_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/comments/{comment_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a comment on a repository issue
      effect: destructive
      questions:
      - How do I delete a comment from a repo issue?
      - Can I remove someone's comment on an issue I manage?
      instructions:
      - text: Delete comment {comment_id} on issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          comment_id: path.comment_id
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Remove issue comment {comment_id}.
        slots:
          comment_id: path.comment_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/vote'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether I voted for an issue
      effect: read
      questions:
      - Have I already voted for this repo issue?
      - What response tells me my vote is on an issue?
      instructions:
      - text: Check if I have voted for issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Tell me whether my vote is recorded on issue #{issue_id}.'
        slots:
          issue_id: path.issue_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/vote'].put
  update:
    x-apievangelist-phrasing:
      intent: Vote for an issue
      effect: write
      questions:
      - How do I upvote a repo issue I care about?
      - Can I cast a vote on an issue through the API?
      instructions:
      - text: Vote for issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Add my vote to issue #{issue_id}.'
        slots:
          issue_id: path.issue_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/vote'].delete
  update:
    x-apievangelist-phrasing:
      intent: Retract my vote on an issue
      effect: destructive
      questions:
      - How do I take back a vote I cast on a repo issue?
      - Can I unvote an issue once it's fixed?
      instructions:
      - text: Retract my vote on issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Remove my vote from issue #{issue_id}.'
        slots:
          issue_id: path.issue_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/watch'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether I'm watching an issue
      effect: read
      questions:
      - Am I currently watching this repo issue?
      - Will I get notified about updates on this issue?
      instructions:
      - text: Check if I am watching issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Tell me whether I follow issue #{issue_id}.'
        slots:
          issue_id: path.issue_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/watch'].put
  update:
    x-apievangelist-phrasing:
      intent: Start watching an issue
      effect: write
      questions:
      - How do I subscribe to updates on a repo issue?
      - Can I follow an issue so I hear about new activity?
      instructions:
      - text: Start watching issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Subscribe me to issue #{issue_id}.'
        slots:
          issue_id: path.issue_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/issues/{issue_id}/watch'].delete
  update:
    x-apievangelist-phrasing:
      intent: Stop watching an issue
      effect: destructive
      questions:
      - How do I unsubscribe from a noisy repo issue?
      - Can I stop getting updates for an issue I was following?
      instructions:
      - text: Stop watching issue {issue_id} in {workspace}/{repo_slug}.
        slots:
          issue_id: path.issue_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: 'Unsubscribe me from issue #{issue_id}.'
        slots:
          issue_id: path.issue_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/milestones'].get
  update:
    x-apievangelist-phrasing:
      intent: List milestones in a repository's issue tracker
      effect: read
      questions:
      - What milestones are defined for issues in my repo?
      - Can I list the milestones I can assign repo issues to?
      instructions:
      - text: List the milestones in {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show me all issue milestones for repo {repo_slug}.
        slots:
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/milestones/{milestone_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one issue tracker milestone
      effect: read
      questions:
      - How do I look up a single repo milestone by id?
      - What details are stored on an issue tracker milestone?
      instructions:
      - text: Get milestone {milestone_id} in {workspace}/{repo_slug}.
        slots:
          milestone_id: path.milestone_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show me the details of milestone {milestone_id}.
        slots:
          milestone_id: path.milestone_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List versions defined in a repository's issue tracker
      effect: read
      questions:
      - Which versions can I tag repo issues with?
      - What release versions are defined in my repository's issue tracker?
      instructions:
      - text: List the issue tracker versions in {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show all versions defined for issues in repo {repo_slug}.
        slots:
          repo_slug: path.repo_slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/versions/{version_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one issue tracker version
      effect: read
      questions:
      - How do I fetch a single repo issue-tracker version by its id?
      - What does a version object in a repo's issue tracker contain?
      instructions:
      - text: Get issue tracker version {version_id} in {workspace}/{repo_slug}.
        slots:
          version_id: path.version_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show me repo issue version {version_id}.
        slots:
          version_id: path.version_id
      method: generated
      generated: '2026-10-01'