# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Bitbucket Snippets API
  version: 1.0.0
extends: openapi/bitbucket-snippets-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['/snippets'].get
  update:
    x-apievangelist-phrasing:
      intent: List snippets I can see (deprecated)
      effect: read
      questions:
      - Which code snippets can I access across every workspace?
      - Can I list only the snippets I own using the older global endpoint?
      instructions:
      - text: List all snippets I can access across workspaces.
      - text: Show snippets everywhere where my role is {role}, using the deprecated global listing.
        slots:
          role: query.role
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a snippet under my account
      effect: write
      questions:
      - How do I share a quick code snippet from my own account?
      - Can I make a new personal snippet private?
      instructions:
      - text: Create a snippet titled {title} under my own account.
        slots:
          title: requestBody.title
      - text: Create a personal private snippet {title} with is_private {is_private}.
        slots:
          title: requestBody.title
          is_private: requestBody.is_private
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}'].get
  update:
    x-apievangelist-phrasing:
      intent: List snippets owned by a workspace
      effect: read
      questions:
      - What snippets does a particular workspace own?
      - Can I filter a workspace's snippets to ones I contribute to?
      instructions:
      - text: List the snippets owned by workspace {workspace}.
        slots:
          workspace: path.workspace
      - text: Show snippets in {workspace} where my role is {role}.
        slots:
          workspace: path.workspace
          role: query.role
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a snippet in a workspace
      effect: write
      questions:
      - How do I create a snippet that belongs to a team workspace instead of me?
      - Can I add a private snippet straight into a shared workspace?
      instructions:
      - text: Create a snippet titled {title} in workspace {workspace}.
        slots:
          title: requestBody.title
          workspace: path.workspace
      - text: Add private snippet {title} to team workspace {workspace} with is_private {is_private}.
        slots:
          title: requestBody.title
          workspace: path.workspace
          is_private: requestBody.is_private
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a snippet
      effect: read
      questions:
      - What files and title does a specific snippet have at its latest version?
      - How do I fetch a single snippet by its id?
      instructions:
      - text: Get snippet {encoded_id} in workspace {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Show the current version of snippet {encoded_id} owned by {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a snippet
      effect: write
      questions:
      - How do I edit the files or title of an existing snippet?
      - Can I change a snippet's contents in place at its latest version?
      instructions:
      - text: Update snippet {encoded_id} in workspace {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Edit the latest version of snippet {encoded_id} owned by {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a snippet
      effect: destructive
      questions:
      - How do I permanently delete a snippet?
      - Can I remove a snippet I shared by mistake?
      instructions:
      - text: Delete snippet {encoded_id} from workspace {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Permanently remove snippet {encoded_id} owned by {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments on a snippet
      effect: read
      questions:
      - What have people said in the comments on a snippet?
      - Can I read a snippet's discussion thread in order?
      instructions:
      - text: List comments on snippet {encoded_id} in workspace {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Show the discussion on snippet {encoded_id} owned by {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/comments'].post
  update:
    x-apievangelist-phrasing:
      intent: Comment on a snippet
      effect: write
      questions:
      - How do I leave feedback on someone's snippet?
      - Can I post a threaded reply to an existing snippet comment?
      instructions:
      - text: Add a comment to snippet {encoded_id} in workspace {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Reply in the thread on snippet {encoded_id} owned by {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/comments/{comment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one comment on a snippet
      effect: read
      questions:
      - How can I fetch a single snippet comment by its id?
      - What did a specific comment on a snippet say?
      instructions:
      - text: Get comment {comment_id} on snippet {encoded_id} in workspace {workspace}.
        slots:
          comment_id: path.comment_id
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Show snippet comment {comment_id} from {encoded_id} owned by {workspace}.
        slots:
          comment_id: path.comment_id
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/comments/{comment_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a comment on a snippet
      effect: write
      questions:
      - Can I fix a comment I posted on a snippet?
      - Who is allowed to edit a snippet comment?
      instructions:
      - text: Edit comment {comment_id} on snippet {encoded_id} in workspace {workspace}.
        slots:
          comment_id: path.comment_id
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Rewrite my snippet comment {comment_id} on {encoded_id} owned by {workspace}.
        slots:
          comment_id: path.comment_id
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/comments/{comment_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a comment on a snippet
      effect: destructive
      questions:
      - How do I remove a comment from a snippet?
      - Can a workspace admin delete someone else's snippet comment?
      instructions:
      - text: Delete comment {comment_id} from snippet {encoded_id} in workspace {workspace}.
        slots:
          comment_id: path.comment_id
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Remove snippet comment {comment_id} on {encoded_id} owned by {workspace}.
        slots:
          comment_id: path.comment_id
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/commits'].get
  update:
    x-apievangelist-phrasing:
      intent: List a snippet's change history
      effect: read
      questions:
      - How many times has a snippet been edited, and by whom?
      - Can I see every commit made to a snippet?
      instructions:
      - text: List the commits on snippet {encoded_id} in workspace {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Show the edit history of snippet {encoded_id} owned by {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/commits/{revision}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one commit made to a snippet
      effect: read
      questions:
      - What did a particular commit change on a snippet?
      - Who authored a given snippet commit and when?
      instructions:
      - text: Get commit {revision} of snippet {encoded_id} in workspace {workspace}.
        slots:
          revision: path.revision
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Show the commit details for revision {revision} on snippet {encoded_id} owned by {workspace}.
        slots:
          revision: path.revision
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/files/{path}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a snippet file's raw content at HEAD
      effect: read
      questions:
      - How do I download the latest raw contents of one file in a snippet?
      - Is there a shortcut to a snippet's current file without fetching the snippet first?
      instructions:
      - text: Download the latest raw file {path} from snippet {encoded_id} in workspace {workspace}.
        slots:
          path: path.path
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Get the current contents of {path} in snippet {encoded_id} owned by {workspace}.
        slots:
          path: path.path
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/watch'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether I'm watching a snippet
      effect: read
      questions:
      - Am I already following a snippet for updates?
      - Does a 404 on the snippet watch check mean I am not watching it?
      instructions:
      - text: Check whether I am watching snippet {encoded_id} in workspace {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Tell me if I follow snippet {encoded_id} owned by {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/watch'].put
  update:
    x-apievangelist-phrasing:
      intent: Watch a snippet
      effect: write
      questions:
      - How do I get notified when a snippet changes?
      - Can I start following a teammate's snippet?
      instructions:
      - text: Start watching snippet {encoded_id} in workspace {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Subscribe me to changes on snippet {encoded_id} owned by {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/watch'].delete
  update:
    x-apievangelist-phrasing:
      intent: Stop watching a snippet
      effect: destructive
      questions:
      - How do I stop notifications for a snippet?
      - Can I unfollow a snippet I no longer use?
      instructions:
      - text: Stop watching snippet {encoded_id} in workspace {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Unsubscribe me from snippet {encoded_id} owned by {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/watchers'].get
  update:
    x-apievangelist-phrasing:
      intent: List users watching a snippet
      effect: read
      questions:
      - Who is following a snippet?
      - How many people watch this snippet?
      instructions:
      - text: List the watchers of snippet {encoded_id} in workspace {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Show who follows snippet {encoded_id} owned by {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/{node_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a snippet as of an older revision
      effect: read
      questions:
      - What did a snippet look like at an earlier revision?
      - Can I retrieve a snippet pinned to a specific node id?
      instructions:
      - text: Get snippet {encoded_id} in workspace {workspace} as it was at revision {node_id}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
          node_id: path.node_id
      - text: Show the older version {node_id} of snippet {encoded_id} owned by {workspace}.
        slots:
          node_id: path.node_id
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/{node_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a snippet at an explicit revision
      effect: write
      questions:
      - Can I update a snippet only if it is still at the revision I last saw?
      - Why does updating a snippet at an older revision fail?
      instructions:
      - text: Update snippet {encoded_id} in workspace {workspace} at tip revision {node_id}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
          node_id: path.node_id
      - text: Edit snippet {encoded_id} owned by {workspace}, guarding on head revision {node_id}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
          node_id: path.node_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/{node_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a snippet via its latest revision URL
      effect: destructive
      questions:
      - Can I delete a snippet only if it has not changed since a given revision?
      - What happens if I try to delete a snippet using an older revision id?
      instructions:
      - text: Delete snippet {encoded_id} in workspace {workspace} if its latest revision is {node_id}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
          node_id: path.node_id
      - text: Remove snippet {encoded_id} owned by {workspace} using versioned URL {node_id}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
          node_id: path.node_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/{node_id}/files/{path}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a snippet file's raw content at a revision
      effect: read
      questions:
      - How do I download a snippet file as it was at an older revision?
      - Can I fetch raw file contents from a specific version of a snippet?
      instructions:
      - text: Download file {path} from snippet {encoded_id} in workspace {workspace} at revision {node_id}.
        slots:
          path: path.path
          encoded_id: path.encoded_id
          workspace: path.workspace
          node_id: path.node_id
      - text: Get raw {path} of snippet {encoded_id} owned by {workspace} as of version {node_id}.
        slots:
          path: path.path
          encoded_id: path.encoded_id
          workspace: path.workspace
          node_id: path.node_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/{revision}/diff'].get
  update:
    x-apievangelist-phrasing:
      intent: Diff a snippet revision against its parent
      effect: read
      questions:
      - What lines changed in a snippet between a revision and the one before it?
      - Can I limit a snippet diff to a single file?
      instructions:
      - text: Show the diff of revision {revision} on snippet {encoded_id} in workspace {workspace}.
        slots:
          revision: path.revision
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Diff snippet {encoded_id} owned by {workspace} at {revision} for file {path} only.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
          revision: path.revision
          path: query.path
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/{revision}/patch'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a snippet revision as a patch
      effect: read
      questions:
      - Can I export a snippet change as a git patch with commit metadata?
      - Is there a patch-formatted version of a snippet revision?
      instructions:
      - text: Get the patch for revision {revision} of snippet {encoded_id} in workspace {workspace}.
        slots:
          revision: path.revision
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Export snippet {encoded_id} owned by {workspace} at {revision} as a git patch.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
          revision: path.revision
      method: generated
      generated: '2026-10-01'