# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Bitbucket Repositories API
  version: 1.0.0
extends: openapi/bitbucket-repositories-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: 30
- target: $.paths['/repositories'].get
  update:
    x-apievangelist-phrasing:
      intent: List all public repositories (deprecated)
      effect: read
      questions:
      - Can I browse every public repository on Bitbucket, not just one workspace's?
      - Is there a global public-repository listing I can page through by creation date?
      instructions:
      - text: List public repositories across all of Bitbucket created after {after}.
        slots:
          after: query.after
      - text: Search all public repositories site-wide with the older global endpoint using filter {q}.
        slots:
          q: query.q
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}'].get
  update:
    x-apievangelist-phrasing:
      intent: List repositories in a workspace
      effect: read
      questions:
      - What repositories does a workspace own?
      - Can I list only the repos in a workspace where I am an admin?
      instructions:
      - text: List all repositories in workspace {workspace}.
        slots:
          workspace: path.workspace
      - text: Show repos in {workspace} where my role is {role}, sorted by {sort}.
        slots:
          workspace: path.workspace
          role: query.role
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a repository
      effect: read
      questions:
      - What is a repository's main branch, language and privacy setting?
      - How do I fetch the details of a single repo?
      instructions:
      - text: Get repository {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show me the settings and metadata of repo {repo_slug} in workspace {workspace}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a repository's settings
      effect: write
      questions:
      - Can I rename a repository or change its description through the API?
      - How do I make an existing repo private or change its fork policy?
      instructions:
      - text: Update the description of {workspace}/{repo_slug} to {description}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
          description: requestBody.description
      - text: Set repo {repo_slug} in workspace {workspace} to private {is_private} with fork policy {fork_policy}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
          is_private: requestBody.is_private
          fork_policy: requestBody.fork_policy
      - text: Move existing repository {repo_slug} in {workspace} into project {project}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
          project: requestBody.project
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a repository
      effect: write
      questions:
      - How do I create a new git repository in a workspace?
      - Can I put a new repo straight into a project and make it private when I create it?
      instructions:
      - text: Create a new repository {repo_slug} in workspace {workspace}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
      - text: Create private repo {repo_slug} in {workspace} under project {project} with is_private {is_private}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
          project: requestBody.project
          is_private: requestBody.is_private
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a repository
      effect: destructive
      questions:
      - How do I permanently delete a repository? Do its forks survive?
      - Can I leave a redirect to a new location when I delete a repo?
      instructions:
      - text: Delete repository {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Delete repo {repo_slug} in workspace {workspace} and redirect visitors to {redirect_to}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
          redirect_to: query.redirect_to
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/filehistory/{commit}/{path}'].get
  update:
    x-apievangelist-phrasing:
      intent: List commits that changed a file
      effect: read
      questions:
      - Which commits modified a specific file, newest first?
      - Can I follow a file's history across renames?
      instructions:
      - text: List the commits that changed {path} as of {commit} in {workspace}/{repo_slug}.
        slots:
          path: path.path
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show the history of file {path} from revision {commit} in repo {repo_slug}, workspace {workspace}, following renames {renames}.
        slots:
          path: path.path
          commit: path.commit
          repo_slug: path.repo_slug
          workspace: path.workspace
          renames: query.renames
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/forks'].get
  update:
    x-apievangelist-phrasing:
      intent: List forks of a repository
      effect: read
      questions:
      - Who has forked a repository?
      - How many forks does a repo have, and where do they live?
      instructions:
      - text: List the forks of {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show every fork of repo {repo_slug} in workspace {workspace}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/forks'].post
  update:
    x-apievangelist-phrasing:
      intent: Fork a repository
      effect: write
      questions:
      - How do I fork a repository into my own workspace?
      - Can I give a fork a different name from the original repo?
      instructions:
      - text: Fork {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Fork repo {repo_slug} from workspace {workspace} under the new name {name}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/hooks'].get
  update:
    x-apievangelist-phrasing:
      intent: List a repository's webhooks
      effect: read
      questions:
      - What webhooks are installed on a repository?
      - Which URLs does this repo send event notifications to?
      instructions:
      - text: List the webhooks on {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show every webhook subscription installed on repo {repo_slug} in workspace {workspace}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/hooks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a webhook on a repository
      effect: write
      questions:
      - How do I get a callback whenever someone pushes to a repository?
      - Can I subscribe a URL to pull request events on one repo?
      instructions:
      - text: Create a webhook on {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Add a push-event webhook to repo {repo_slug} in workspace {workspace}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/hooks/{uid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a repository webhook
      effect: read
      questions:
      - Which events and URL is a specific repo webhook configured with?
      - Is a given webhook on this repository still active?
      instructions:
      - text: Get webhook {uid} on {workspace}/{repo_slug}.
        slots:
          uid: path.uid
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show the configuration of repo webhook {uid} in repo {repo_slug}, workspace {workspace}.
        slots:
          uid: path.uid
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/hooks/{uid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a repository webhook
      effect: write
      questions:
      - Can I change the URL or events of a webhook already on a repo?
      - How do I pause a repository webhook without deleting it?
      instructions:
      - text: Update webhook {uid} on {workspace}/{repo_slug}.
        slots:
          uid: path.uid
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Deactivate repo webhook {uid} on repo {repo_slug}, workspace {workspace}.
        slots:
          uid: path.uid
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/hooks/{uid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a repository webhook
      effect: destructive
      questions:
      - How do I remove a webhook from a repository for good?
      - Can I delete a repo webhook that points to a retired endpoint?
      instructions:
      - text: Delete webhook {uid} from {workspace}/{repo_slug}.
        slots:
          uid: path.uid
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Remove repo webhook {uid} on repo {repo_slug}, workspace {workspace}.
        slots:
          uid: path.uid
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/override-settings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get which repo settings override the project
      effect: read
      questions:
      - Does a repository inherit its settings from its project or override them?
      - Which settings on this repo are customized instead of inherited?
      instructions:
      - text: Show the settings inheritance state for {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Tell me which settings repo {repo_slug} in workspace {workspace} overrides from its project.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/override-settings'].put
  update:
    x-apievangelist-phrasing:
      intent: Set which repo settings override the project
      effect: write
      questions:
      - How do I make a repository stop inheriting a setting from its project?
      - Can I switch a repo back to using its project's settings?
      instructions:
      - text: Set the settings inheritance state for {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Make repo {repo_slug} in workspace {workspace} inherit its project settings again.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/permissions-config/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List group permissions on a repository
      effect: read
      questions:
      - Which groups have explicit access to a repository?
      - What permission level does each group hold on this repo?
      instructions:
      - text: List explicit group permissions on {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show which groups can access repo {repo_slug} in workspace {workspace}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/permissions-config/groups/{group_slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one group's permission on a repository
      effect: read
      questions:
      - What access does a particular group have to a repository?
      - Does a given group have write or admin on this repo?
      instructions:
      - text: Get group {group_slug}'s permission on {workspace}/{repo_slug}.
        slots:
          group_slug: path.group_slug
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show the access level of group {group_slug} for repo {repo_slug}, workspace {workspace}.
        slots:
          group_slug: path.group_slug
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/permissions-config/groups/{group_slug}'].put
  update:
    x-apievangelist-phrasing:
      intent: Grant or change a group's repo permission
      effect: write
      questions:
      - How do I give a team group write access to a repository?
      - Can I downgrade a group's access on a repo to read only?
      instructions:
      - text: Give group {group_slug} {permission} access to {workspace}/{repo_slug}.
        slots:
          group_slug: path.group_slug
          permission: requestBody.permission
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Set group {group_slug}'s permission on repo {repo_slug}, workspace {workspace}, to {permission}.
        slots:
          group_slug: path.group_slug
          repo_slug: path.repo_slug
          workspace: path.workspace
          permission: requestBody.permission
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/permissions-config/groups/{group_slug}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a group's access to a repository
      effect: destructive
      questions:
      - How do I revoke a group's explicit access to a repository?
      - Can I take a team group off a repo entirely?
      instructions:
      - text: Remove group {group_slug}'s permission on {workspace}/{repo_slug}.
        slots:
          group_slug: path.group_slug
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Revoke group {group_slug}'s explicit access to repo {repo_slug} in workspace {workspace}.
        slots:
          group_slug: path.group_slug
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/permissions-config/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List user permissions on a repository
      effect: read
      questions:
      - Which individual users have explicit access to a repository?
      - What permission does each person hold on this repo?
      instructions:
      - text: List explicit user permissions on {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show which individual users can access repo {repo_slug} in workspace {workspace}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/permissions-config/users/{selected_user_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one user's permission on a repository
      effect: read
      questions:
      - What access does a specific person have to a repository?
      - Does a given user hold admin on this repo explicitly?
      instructions:
      - text: Get user {selected_user_id}'s permission on {workspace}/{repo_slug}.
        slots:
          selected_user_id: path.selected_user_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show the access level of user {selected_user_id} for repo {repo_slug}, workspace {workspace}.
        slots:
          selected_user_id: path.selected_user_id
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/permissions-config/users/{selected_user_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Grant or change a user's repo permission
      effect: write
      questions:
      - How do I give a workspace member admin rights on one repository?
      - Can I grant explicit repo access to the workspace owner?
      instructions:
      - text: Give user {selected_user_id} {permission} access to {workspace}/{repo_slug}.
        slots:
          selected_user_id: path.selected_user_id
          permission: requestBody.permission
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Set user {selected_user_id}'s permission on repo {repo_slug}, workspace {workspace}, to {permission}.
        slots:
          selected_user_id: path.selected_user_id
          repo_slug: path.repo_slug
          workspace: path.workspace
          permission: requestBody.permission
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/permissions-config/users/{selected_user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a user's access to a repository
      effect: destructive
      questions:
      - How do I revoke one person's explicit access to a repository?
      - Can I remove a departing contractor from a single repo?
      instructions:
      - text: Remove user {selected_user_id}'s permission on {workspace}/{repo_slug}.
        slots:
          selected_user_id: path.selected_user_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Revoke user {selected_user_id}'s explicit access to repo {repo_slug} in workspace {workspace}.
        slots:
          selected_user_id: path.selected_user_id
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/src'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse the root of the main branch
      effect: read
      questions:
      - What files sit at the top level of a repository's main branch?
      - Can I get the root directory listing as metadata instead of raw content?
      instructions:
      - text: List the root directory of the main branch in {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show top-level files on the default branch of repo {repo_slug}, workspace {workspace}, in format {format}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
          format: query.format
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/src'].post
  update:
    x-apievangelist-phrasing:
      intent: Commit files by uploading them
      effect: write
      questions:
      - Can I commit a file to a repository without cloning it?
      - How do I upload a change to a specific branch with my own commit message?
      instructions:
      - text: Commit an uploaded file to {workspace}/{repo_slug} with message {message}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
          message: query.message
      - text: Upload files to branch {branch} of repo {repo_slug} in {workspace} as a commit by {author} with message {message}.
        slots:
          branch: query.branch
          repo_slug: path.repo_slug
          workspace: path.workspace
          author: query.author
          message: query.message
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/src/{commit}/{path}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a file or directory at a revision
      effect: read
      questions:
      - How do I read the contents of a file as it was at a specific commit?
      - Can I list a directory recursively up to a certain depth?
      instructions:
      - text: Get {path} at revision {commit} in {workspace}/{repo_slug}.
        slots:
          path: path.path
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: List directory {path} at {commit} in repo {repo_slug}, workspace {workspace}, to depth {max_depth}.
        slots:
          path: path.path
          commit: path.commit
          repo_slug: path.repo_slug
          workspace: path.workspace
          max_depth: query.max_depth
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/watchers'].get
  update:
    x-apievangelist-phrasing:
      intent: List a repository's watchers
      effect: read
      questions:
      - Who is watching a repository for updates?
      - How many people follow this repo?
      instructions:
      - text: List the watchers of {workspace}/{repo_slug}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show who watches repo {repo_slug} in workspace {workspace}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/user/permissions/repositories'].get
  update:
    x-apievangelist-phrasing:
      intent: List my repo permissions everywhere (deprecated)
      effect: read
      questions:
      - Which repositories can I access across all my workspaces, and at what level?
      - Is there an older, non-workspace endpoint for my repository permissions?
      instructions:
      - text: List my explicit repository permissions across all workspaces.
      - text: Show my repository access everywhere using the deprecated global endpoint, filtered by {q}.
        slots:
          q: query.q
      method: generated
      generated: '2026-10-01'
- target: $.paths['/user/workspaces/{workspace}/permissions/repositories'].get
  update:
    x-apievangelist-phrasing:
      intent: List my repo permissions in one workspace
      effect: read
      questions:
      - What is my effective permission on each repository in a workspace?
      - Which repos in a given workspace can I write to?
      instructions:
      - text: List my repository permissions in workspace {workspace}.
        slots:
          workspace: path.workspace
      - text: Show the repos in {workspace} where my access matches {q}.
        slots:
          workspace: path.workspace
          q: query.q
      method: generated
      generated: '2026-10-01'