# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Bitbucket Workspaces API
  version: 1.0.0
extends: openapi/bitbucket-workspaces-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: 18
- target: $.paths['/user/permissions/workspaces'].get
  update:
    x-apievangelist-phrasing:
      intent: List my workspace permissions (deprecated)
      effect: read
      questions:
      - Which workspaces am I in and what is my permission in each, via the older permissions endpoint?
      - Can I filter my workspace memberships to ones where I am owner?
      instructions:
      - text: List my workspace memberships and permission levels using the deprecated permissions endpoint.
      - text: Show workspaces where my permission matches {q}, sorted by {sort}.
        slots:
          q: query.q
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/user/workspaces'].get
  update:
    x-apievangelist-phrasing:
      intent: List workspaces I can access
      effect: read
      questions:
      - What workspaces can I access, and am I an admin in any of them?
      - Can I list only the workspaces where I have administrator rights?
      instructions:
      - text: List every workspace I can access.
      - text: Show only workspaces where administrator is {administrator}.
        slots:
          administrator: query.administrator
      method: generated
      generated: '2026-10-01'
- target: $.paths['/user/workspaces/{workspace}/permission'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my role in a workspace
      effect: read
      questions:
      - What is my highest level of access in a particular workspace?
      - Am I an owner or a regular member of a given workspace?
      instructions:
      - text: Get my effective permission in workspace {workspace}.
        slots:
          workspace: path.workspace
      - text: Tell me whether I am owner, collaborator or member of {workspace}.
        slots:
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces'].get
  update:
    x-apievangelist-phrasing:
      intent: List my workspaces (deprecated endpoint)
      effect: read
      questions:
      - Is there an older endpoint that lists workspaces filtered by my role?
      - Can I search my workspaces by name using the legacy listing?
      instructions:
      - text: List workspaces where my role is {role} using the legacy endpoint.
        slots:
          role: query.role
      - text: Search my workspaces with filter {q} via the deprecated listing.
        slots:
          q: query.q
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a workspace
      effect: read
      questions:
      - What are the name, UUID and privacy of a workspace?
      - How do I look up a single workspace by its slug?
      instructions:
      - text: Get workspace {workspace}.
        slots:
          workspace: path.workspace
      - text: Show the details of the workspace {workspace}.
        slots:
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/hooks'].get
  update:
    x-apievangelist-phrasing:
      intent: List a workspace's webhooks
      effect: read
      questions:
      - What webhooks fire for every repository in a workspace?
      - Which workspace-level event subscriptions are installed?
      instructions:
      - text: List the webhooks installed on workspace {workspace}.
        slots:
          workspace: path.workspace
      - text: Show all workspace-level webhook subscriptions for {workspace}.
        slots:
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/hooks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a workspace-wide webhook
      effect: write
      questions:
      - How do I get one webhook that fires for events in all repos of a workspace?
      - Can I subscribe a URL to pushes across an entire workspace?
      instructions:
      - text: Create a webhook on workspace {workspace}.
        slots:
          workspace: path.workspace
      - text: Add a workspace-wide push webhook covering every repo in {workspace}.
        slots:
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/hooks/{uid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a workspace webhook
      effect: read
      questions:
      - Which events and URL does a given workspace webhook use?
      - Is a specific workspace-level webhook still active?
      instructions:
      - text: Get webhook {uid} on workspace {workspace}.
        slots:
          uid: path.uid
          workspace: path.workspace
      - text: Show the configuration of workspace webhook {uid} in {workspace}.
        slots:
          uid: path.uid
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/hooks/{uid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a workspace webhook
      effect: write
      questions:
      - Can I change the URL or events of a workspace-level webhook?
      - How do I pause a workspace webhook without deleting it?
      instructions:
      - text: Update webhook {uid} on workspace {workspace}.
        slots:
          uid: path.uid
          workspace: path.workspace
      - text: Deactivate workspace webhook {uid} in {workspace}.
        slots:
          uid: path.uid
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/hooks/{uid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a workspace webhook
      effect: destructive
      questions:
      - How do I remove a webhook that fires for a whole workspace?
      - Can I delete a workspace-level webhook pointing at a retired service?
      instructions:
      - text: Delete webhook {uid} from workspace {workspace}.
        slots:
          uid: path.uid
          workspace: path.workspace
      - text: Remove workspace webhook {uid} in {workspace}.
        slots:
          uid: path.uid
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/members'].get
  update:
    x-apievangelist-phrasing:
      intent: List members of a workspace
      effect: read
      questions:
      - Who belongs to a workspace?
      - Can an admin find a workspace member by their email address?
      instructions:
      - text: List the members of workspace {workspace}.
        slots:
          workspace: path.workspace
      - text: Show everyone who belongs to {workspace}.
        slots:
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/members/{member}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's membership in a workspace
      effect: read
      questions:
      - Is a particular person a member of a workspace?
      - How do I fetch one user's workspace membership record?
      instructions:
      - text: Get the membership of {member} in workspace {workspace}.
        slots:
          member: path.member
          workspace: path.workspace
      - text: Check whether user {member} belongs to {workspace}.
        slots:
          member: path.member
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List member permission levels in a workspace
      effect: read
      questions:
      - Who are the owners versus regular members of a workspace?
      - Can I filter workspace members down to just the owners?
      instructions:
      - text: List members and their permission levels in workspace {workspace}.
        slots:
          workspace: path.workspace
      - text: Show members of {workspace} whose permission matches {q}.
        slots:
          workspace: path.workspace
          q: query.q
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/permissions/repositories'].get
  update:
    x-apievangelist-phrasing:
      intent: List repo permissions across a workspace
      effect: read
      questions:
      - Who has what access to every repository in a workspace?
      - Can I audit admin access across all of a workspace's repos at once?
      instructions:
      - text: List all repository permissions across workspace {workspace}.
        slots:
          workspace: path.workspace
      - text: Audit repo access in {workspace} filtered by {q}.
        slots:
          workspace: path.workspace
          q: query.q
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/permissions/repositories/{repo_slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: List user permissions on one repo in a workspace
      effect: read
      questions:
      - What is each user's effective access to one specific repository?
      - Who has write access to a given repo, including via groups?
      instructions:
      - text: List each user's effective permission on repo {repo_slug} in workspace {workspace}.
        slots:
          repo_slug: path.repo_slug
          workspace: path.workspace
      - text: Show who can access {workspace}/{repo_slug} filtered by {q}.
        slots:
          workspace: path.workspace
          repo_slug: path.repo_slug
          q: query.q
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects'].get
  update:
    x-apievangelist-phrasing:
      intent: List projects in a workspace
      effect: read
      questions:
      - What projects are set up in a workspace?
      - How are a workspace's repositories grouped into projects?
      instructions:
      - text: List the projects in workspace {workspace}.
        slots:
          workspace: path.workspace
      - text: Show every project defined in {workspace}.
        slots:
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/projects/{project_key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a project in a workspace
      effect: read
      questions:
      - What are the name and description of a project with a given key?
      - How do I look up one project in a workspace?
      instructions:
      - text: Get project {project_key} in workspace {workspace}.
        slots:
          project_key: path.project_key
          workspace: path.workspace
      - text: Show the details of project {project_key} in {workspace}.
        slots:
          project_key: path.project_key
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace}/pullrequests/{selected_user}'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's pull requests across a workspace
      effect: read
      questions:
      - What pull requests has a given person authored across every repo in a workspace?
      - Can I see one developer's merged PRs workspace-wide, not just in one repository?
      instructions:
      - text: List open pull requests authored by {selected_user} across workspace {workspace}.
        slots:
          selected_user: path.selected_user
          workspace: path.workspace
      - text: Show {state} PRs by user {selected_user} in every repository of {workspace}.
        slots:
          state: query.state
          selected_user: path.selected_user
          workspace: path.workspace
      method: generated
      generated: '2026-10-01'