# 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 Snippets API
  version: 1.0.0
extends: openapi/atlassian-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 access
      effect: read
      questions:
      - How do I see every Bitbucket snippet I have access to across my workspaces?
      - Can I narrow my snippet list to only the ones I own or contributed to?
      instructions:
      - text: List all the snippets I can see.
      - text: List my snippets where my role is {role}.
        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 create a new code snippet under my own Bitbucket account?
      - Can a personal snippet hold several files and be marked private?
      instructions:
      - text: Create a private snippet in my personal account titled {title}.
        slots:
          title: requestBody.title
      - text: Make a new snippet on my own account called {title} with privacy set to {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:
      - Which snippets does a specific workspace own?
      - Can I filter a workspace's snippets by my role in them?
      instructions:
      - text: List the snippets owned by workspace {workspace}.
        slots:
          workspace: path.workspace
      - text: Show snippets in {workspace} where I am {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 rather than my account?
      - What do I need to add a new shared snippet to a workspace?
      instructions:
      - text: Create a snippet titled {title} in workspace {workspace}.
        slots:
          title: requestBody.title
          workspace: path.workspace
      - text: Add a new workspace snippet to {workspace}.
        slots:
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a snippet's current version
      effect: read
      questions:
      - How do I fetch the current contents and metadata of one snippet?
      - Can I retrieve a snippet as multipart to get its files in one response?
      instructions:
      - text: Get snippet {encoded_id} in workspace {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Show me the latest version of snippet {encoded_id}.
        slots:
          encoded_id: path.encoded_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a snippet's title or files
      effect: write
      questions:
      - How do I rename a snippet or add and remove its files?
      - Do properties I leave out stay unchanged when I update a snippet?
      instructions:
      - text: Update snippet {encoded_id} in {workspace} with my new files.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Change the title of the current snippet {encoded_id}.
        slots:
          encoded_id: path.encoded_id
      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 regardless of its revision?
      - What happens when I remove a snippet from a workspace?
      instructions:
      - text: Delete snippet {encoded_id} from workspace {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Remove the snippet {encoded_id} entirely.
        slots:
          encoded_id: path.encoded_id
      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:
      - How do I read all the comments people left on a snippet?
      - What order are snippet comments returned in by default?
      instructions:
      - text: List the comments on snippet {encoded_id} in {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Show the discussion on snippet {encoded_id}.
        slots:
          encoded_id: path.encoded_id
      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 post a comment on someone's snippet?
      - Can I reply in a thread to an existing snippet comment?
      instructions:
      - text: Add a comment to snippet {encoded_id} in {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Post a new comment on snippet {encoded_id}.
        slots:
          encoded_id: path.encoded_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/comments/{comment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one snippet comment
      effect: read
      questions:
      - How do I look up a single comment on a snippet by its id?
      - Can I fetch just one snippet comment instead of the whole thread?
      instructions:
      - text: Get comment {comment_id} on snippet {encoded_id}.
        slots:
          comment_id: path.comment_id
          encoded_id: path.encoded_id
      - text: Show snippet comment {comment_id} in workspace {workspace}.
        slots:
          comment_id: path.comment_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 snippet comment
      effect: write
      questions:
      - How do I edit a comment I left on a snippet?
      - Who is allowed to change a snippet comment after posting?
      instructions:
      - text: Edit my comment {comment_id} on snippet {encoded_id}.
        slots:
          comment_id: path.comment_id
          encoded_id: path.encoded_id
      - text: Update snippet comment {comment_id} in {workspace} with new text.
        slots:
          comment_id: path.comment_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 snippet comment
      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}.
        slots:
          comment_id: path.comment_id
          encoded_id: path.encoded_id
      - text: Remove snippet comment {comment_id} in workspace {workspace}.
        slots:
          comment_id: path.comment_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 commit history
      effect: read
      questions:
      - How do I see the history of changes made to a snippet?
      - What commits have been made on this snippet over time?
      instructions:
      - text: List the commits on snippet {encoded_id} in {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Show the change history of snippet {encoded_id}.
        slots:
          encoded_id: path.encoded_id
      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:
      - How do I inspect a single past commit on a snippet?
      - What changed in one specific snippet commit?
      instructions:
      - text: Get commit {revision} of snippet {encoded_id}.
        slots:
          revision: path.revision
          encoded_id: path.encoded_id
      - text: Show snippet change {revision} in workspace {workspace}.
        slots:
          revision: path.revision
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/files/{path}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a snippet file at its latest version
      effect: read
      questions:
      - How do I grab the raw latest contents of a file in a snippet without fetching the snippet first?
      - Is there a shortcut to a snippet file's current raw text?
      instructions:
      - text: Download the latest {path} from snippet {encoded_id}.
        slots:
          path: path.path
          encoded_id: path.encoded_id
      - text: Get the current raw file {path} in snippet {encoded_id} of {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 if I watch a snippet
      effect: read
      questions:
      - Am I currently watching this snippet?
      - How can I tell whether I'm subscribed to updates on a snippet?
      instructions:
      - text: Check whether I'm watching snippet {encoded_id}.
        slots:
          encoded_id: path.encoded_id
      - text: Tell me if I follow snippet {encoded_id} in {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: Start watching a snippet
      effect: write
      questions:
      - How do I subscribe to updates on a snippet?
      - Can I follow a snippet so I get notified about it?
      instructions:
      - text: Watch snippet {encoded_id} in {workspace}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
      - text: Start following snippet {encoded_id}.
        slots:
          encoded_id: path.encoded_id
      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 unsubscribe from a snippet I'm watching?
      - Can I stop getting updates about a snippet?
      instructions:
      - text: Stop watching snippet {encoded_id}.
        slots:
          encoded_id: path.encoded_id
      - text: Unfollow snippet {encoded_id} in workspace {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 a snippet's watchers
      effect: read
      questions:
      - Who is watching this snippet?
      - Which users follow a given snippet?
      instructions:
      - text: List the users watching snippet {encoded_id}.
        slots:
          encoded_id: path.encoded_id
      - text: Show the watchers of snippet {encoded_id} in {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:
      - How do I see what a snippet looked like at an earlier revision?
      - Can I retrieve an old version of a snippet's files?
      instructions:
      - text: Get snippet {encoded_id} as it was at revision {node_id}.
        slots:
          encoded_id: path.encoded_id
          node_id: path.node_id
      - text: Show the {node_id} version of snippet {encoded_id} in {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 pinned to a revision
      effect: write
      questions:
      - How do I update a snippet only if it is still at the revision I last saw?
      - Why does updating an older snippet revision return a 405?
      instructions:
      - text: Update snippet {encoded_id} at revision {node_id}, failing if it has moved on.
        slots:
          encoded_id: path.encoded_id
          node_id: path.node_id
      - text: Save changes to snippet {encoded_id} in {workspace} against tip 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 only if at a revision
      effect: destructive
      questions:
      - How do I delete a snippet only when nobody has changed it since a given commit?
      - Why does deleting a snippet via an older commit URL fail?
      instructions:
      - text: Delete snippet {encoded_id} only if its latest revision is {node_id}.
        slots:
          encoded_id: path.encoded_id
          node_id: path.node_id
      - text: Remove snippet {encoded_id} in {workspace} pinned to 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}/files/{path}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a snippet file at a revision
      effect: read
      questions:
      - How do I download a snippet file as it was at a specific revision?
      - What content type comes back when I fetch a raw file from an older snippet version?
      instructions:
      - text: Download file {path} from snippet {encoded_id} at revision {node_id}.
        slots:
          path: path.path
          encoded_id: path.encoded_id
          node_id: path.node_id
      - text: Get the raw {path} of snippet {encoded_id} in {workspace} at 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: Get a snippet commit's diff
      effect: read
      questions:
      - How do I see the diff a snippet commit introduced against its parent?
      - Can I limit a snippet diff to just one file?
      instructions:
      - text: Show the diff for snippet {encoded_id} in {workspace} at revision {revision}.
        slots:
          encoded_id: path.encoded_id
          workspace: path.workspace
          revision: path.revision
      - text: Diff only file {path} in snippet {encoded_id} at {revision}.
        slots:
          path: query.path
          encoded_id: path.encoded_id
          revision: path.revision
      method: generated
      generated: '2026-10-01'
- target: $.paths['/snippets/{workspace}/{encoded_id}/{revision}/patch'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a snippet commit as a patch
      effect: read
      questions:
      - How do I get a git-style patch with author and message for a snippet commit?
      - Can I export a snippet commit as a patch that includes its commit header?
      instructions:
      - text: Get the patch for snippet {encoded_id} at revision {revision}.
        slots:
          encoded_id: path.encoded_id
          revision: path.revision
      - text: Export revision {revision} of snippet {encoded_id} in {workspace} as a patch.
        slots:
          revision: path.revision
          encoded_id: path.encoded_id
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'