API Evangelist conversational phrasing for User Management Role Admin API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for User Management Role Admin API
  version: 1.0.0
extends: openapi/conga-role-admin-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: 12
- target: $.paths['/api/user-management/v1/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List roles as an admin
      effect: read
      questions:
      - Which roles exist in user management, filtered by my criteria?
      - Can I page and sort the admin list of roles?
      instructions:
      - text: List all roles matching {criteria}.
        slots:
          criteria: query.criteria
      - text: Show roles sorted by {sortField}, page {pageNumber}.
        slots:
          sortField: query.sortField
          pageNumber: query.pageNumber
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a role
      effect: write
      questions:
      - How do I create a new user-management role with permission groups?
      - Can I set admin permissions when creating a role?
      instructions:
      - text: Create a role named {Name}.
        slots:
          Name: requestBody.Name
      - text: Create role {Name} with permission groups {PermissionGroups}.
        slots:
          Name: requestBody.Name
          PermissionGroups: requestBody.PermissionGroups
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/roles/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many roles at once
      effect: write
      questions:
      - Can I create several roles in one request?
      - Is there a bulk way to load roles?
      instructions:
      - text: Bulk-create these roles.
      - text: Create multiple roles in a single batch.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/roles/{roleId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a role's details
      effect: read
      questions:
      - What permission groups and settings does a role have?
      - How do I look up one role by its ID?
      instructions:
      - text: Get role {roleId}.
        slots:
          roleId: path.roleId
      - text: Show the details of role {roleId}.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/roles/{roleId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename or redescribe a role
      effect: write
      questions:
      - Can I change a role's name and description?
      - How do I rename an existing role?
      instructions:
      - text: Rename role {roleId} to {Name}.
        slots:
          roleId: path.roleId
          Name: requestBody.Name
      - text: Update role {roleId}'s description to {Description}.
        slots:
          roleId: path.roleId
          Description: requestBody.Description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/roles/{roleId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a role
      effect: destructive
      questions:
      - How do I delete a role I no longer use?
      - What status comes back when a role is deleted?
      instructions:
      - text: Delete role {roleId}.
        slots:
          roleId: path.roleId
      - text: Remove the role with ID {roleId}.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/roles/{roleId}/admin-permissions'].put
  update:
    x-apievangelist-phrasing:
      intent: Grant admin permissions to a role
      effect: write
      questions:
      - How do I give a role additional admin permissions?
      - Does adding admin permissions replace the existing ones on a role?
      instructions:
      - text: Add admin permissions {AdminPermissionNames} to role {roleId}.
        slots:
          AdminPermissionNames: requestBody.AdminPermissionNames
          roleId: path.roleId
      - text: Grant role {roleId} more admin permissions.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/roles/{roleId}/admin-permissions'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove admin permissions from a role
      effect: destructive
      questions:
      - Can I strip specific admin permissions from a role?
      - What's the way to take admin rights away from a role?
      instructions:
      - text: Remove admin permissions {AdminPermissionNames} from role {roleId}.
        slots:
          AdminPermissionNames: requestBody.AdminPermissionNames
          roleId: path.roleId
      - text: Revoke admin permissions on role {roleId}.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/roles/{roleId}/clone'].post
  update:
    x-apievangelist-phrasing:
      intent: Clone a role
      effect: write
      questions:
      - Can I copy an existing role, including its permission groups?
      - How do I create a new role based on another one?
      instructions:
      - text: Clone role {roleId} as {Name}.
        slots:
          roleId: path.roleId
          Name: requestBody.Name
      - text: 'Copy role {roleId}, keeping permission groups: {CopyPermissionGroups}.'
        slots:
          roleId: path.roleId
          CopyPermissionGroups: requestBody.CopyPermissionGroups
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/roles/{roleId}/exists'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether a role exists
      effect: read
      questions:
      - Does a role with this ID exist?
      - Can I verify a role ID is valid before assigning it?
      instructions:
      - text: Check whether role {roleId} exists.
        slots:
          roleId: path.roleId
      - text: Confirm role ID {roleId} is valid.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/roles/{roleId}/permissiongroups'].put
  update:
    x-apievangelist-phrasing:
      intent: Assign permission groups to a role
      effect: write
      questions:
      - How do I add permission groups to a role?
      - Will assigning permission groups keep the ones a role already has?
      instructions:
      - text: Assign permission groups {PermissionGroupNames} to role {roleId}.
        slots:
          PermissionGroupNames: requestBody.PermissionGroupNames
          roleId: path.roleId
      - text: Add more permission groups to role {roleId}.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/roles/{roleId}/permissiongroups'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove permission groups from a role
      effect: destructive
      questions:
      - Can I take permission groups off a role?
      - What errors come back if I remove a permission group a role doesn't have?
      instructions:
      - text: Remove permission groups {PermissionGroupNames} from role {roleId}.
        slots:
          PermissionGroupNames: requestBody.PermissionGroupNames
          roleId: path.roleId
      - text: Unassign permission groups from role {roleId}.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-10-01'