# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Platform - Access Management User Groups V2 API
  version: 1.0.0
extends: openapi/onetrust-user-groups-v2-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 14
- target: $.paths['/api/access/v2/user-groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List user groups
      effect: read
      questions:
      - Which user groups exist in my OneTrust access settings?
      - Can I filter and sort the list of user groups page by page?
      instructions:
      - text: List all user groups in my account.
      - text: List user groups matching filter {filters}, sorted by {sort}.
        slots:
          filters: query.filters
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/access/v2/user-groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user group
      effect: write
      questions:
      - What do I need to set up a new user group for access management?
      - Can a new user group be given a description when it is created?
      instructions:
      - text: Create a user group named {name}.
        slots:
          name: requestBody.name
      - text: Create a new user group called {name} described as {description}.
        slots:
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/access/v2/user-groups/{groupId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user group
      effect: read
      questions:
      - Where can I see the name and description of one specific user group?
      - Can I look up a single user group by its ID?
      instructions:
      - text: Show me user group {groupId}.
        slots:
          groupId: path.groupId
      - text: Fetch the details of the user group with ID {groupId}.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/access/v2/user-groups/{groupId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename or re-describe a user group
      effect: write
      questions:
      - Can I rename an existing user group?
      - How can I change the description on a user group I already created?
      instructions:
      - text: Rename user group {groupId} to {name}.
        slots:
          groupId: path.groupId
          name: requestBody.name
      - text: Update user group {groupId} with name {name} and description {description}.
        slots:
          groupId: path.groupId
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/access/v2/user-groups/{groupId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user group
      effect: destructive
      questions:
      - Can I permanently delete a user group I no longer need?
      - What happens when a whole user group is removed from access management?
      instructions:
      - text: Delete user group {groupId}.
        slots:
          groupId: path.groupId
      - text: Remove the user group with ID {groupId} entirely.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/access/v2/user-groups/{groupId}/access-levels'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user group's roles
      effect: read
      questions:
      - Which roles and organizations does a user group currently have?
      - Can I see what access levels are granted to a user group?
      instructions:
      - text: List the roles assigned to user group {groupId}.
        slots:
          groupId: path.groupId
      - text: Show the access levels for group {groupId}.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/access/v2/user-groups/{groupId}/access-levels'].put
  update:
    x-apievangelist-phrasing:
      intent: Swap a role on a user group
      effect: write
      questions:
      - Can I replace one role on a user group with a different role and organization?
      - How do I change a user group's role from one organization to another?
      instructions:
      - text: On user group {groupId}, replace role {currentRoleId} in org {currentOrganizationId} with role {newRoleId} in org {newOrganizationId}.
        slots:
          groupId: path.groupId
          currentRoleId: requestBody.currentRoleId
          currentOrganizationId: requestBody.currentOrganizationId
          newRoleId: requestBody.newRoleId
          newOrganizationId: requestBody.newOrganizationId
      - text: Swap group {groupId}'s role {currentRoleId} for {newRoleId}.
        slots:
          groupId: path.groupId
          currentRoleId: requestBody.currentRoleId
          newRoleId: requestBody.newRoleId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/access/v2/user-groups/{groupId}/access-levels'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a role to a user group
      effect: write
      questions:
      - Can I grant an additional role to a user group for a specific organization?
      - What is needed to give a user group a new access level?
      instructions:
      - text: Grant role {roleId} in organization {organizationId} to user group {groupId}.
        slots:
          roleId: requestBody.roleId
          organizationId: requestBody.organizationId
          groupId: path.groupId
      - text: Add role {roleId} to group {groupId}.
        slots:
          roleId: requestBody.roleId
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/access/v2/user-groups/{groupId}/access-levels'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove roles from a user group
      effect: destructive
      questions:
      - Can I strip the roles off a user group without deleting the group?
      - Is it possible to revoke a user group's access levels?
      instructions:
      - text: Remove the roles from user group {groupId}.
        slots:
          groupId: path.groupId
      - text: Revoke all access levels on group {groupId}.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/access/v2/user-groups/{groupId}/members'].get
  update:
    x-apievangelist-phrasing:
      intent: List users in a user group
      effect: read
      questions:
      - Who are the members of a particular user group?
      - Can I page through the users that belong to a group?
      instructions:
      - text: List the members of user group {groupId}.
        slots:
          groupId: path.groupId
      - text: Show page {page} of users in group {groupId}.
        slots:
          page: query.page
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/access/v2/user-groups/{groupId}/members'].post
  update:
    x-apievangelist-phrasing:
      intent: Add many users to a user group
      effect: write
      questions:
      - Can I add several users to a user group in one bulk call?
      - What is the fastest way to put a batch of people into a group?
      instructions:
      - text: Add users {members} to user group {groupId} in bulk.
        slots:
          members: requestBody.members
          groupId: path.groupId
      - text: Bulk-add a list of members to group {groupId}.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/access/v2/user-groups/{groupId}/members'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove many users from a user group
      effect: destructive
      questions:
      - Can I bulk-remove several users from a group at once?
      - Is there a way to take a batch of people out of a user group together?
      instructions:
      - text: Remove users {members} from user group {groupId} in bulk.
        slots:
          members: requestBody.members
          groupId: path.groupId
      - text: Bulk-remove a list of members from group {groupId}.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/access/v2/user-groups/{groupId}/members/{memberId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add one user to a user group
      effect: write
      questions:
      - Can I add a single user to a user group?
      - What does it take to put just one person into a group?
      instructions:
      - text: Add user {memberId} to user group {groupId}.
        slots:
          memberId: path.memberId
          groupId: path.groupId
      - text: Put member {memberId} into group {groupId}.
        slots:
          memberId: path.memberId
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/access/v2/user-groups/{groupId}/members/{memberId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove one user from a user group
      effect: destructive
      questions:
      - Can I take a single person out of a user group?
      - Does removing one member from a group delete the user account?
      instructions:
      - text: Remove user {memberId} from user group {groupId}.
        slots:
          memberId: path.memberId
          groupId: path.groupId
      - text: Drop member {memberId} from group {groupId}.
        slots:
          memberId: path.memberId
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'