# 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 User Group API
  version: 1.0.0
extends: openapi/conga-user-group-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: 14
- target: $.paths['/api/user-management/v1/user-groups'].get
  update:
    x-apievangelist-phrasing:
      intent: Search platform user groups in user management
      effect: read
      questions:
      - Which user groups are defined in the platform's user management service?
      - Can I sort user-management groups by name and page through them?
      instructions:
      - text: Search user-management groups matching criteria {criteria}.
        slots:
          criteria: query.criteria
      - text: List platform user groups sorted by {sortField}, page {pageNumber} with {pageSize} per page.
        slots:
          sortField: query.sortField
          pageNumber: query.pageNumber
          pageSize: query.pageSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/user-groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a platform user group
      effect: write
      questions:
      - How do I add a new group in the platform user management service?
      - Can a new user-management group get its own email address for members?
      instructions:
      - text: Create a user-management group named {Name}.
        slots:
          Name: requestBody.Name
      - text: Add platform user group {Name} with group email {Email}.
        slots:
          Name: requestBody.Name
          Email: requestBody.Email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/user-groups/bulk-upsert-userGroups'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update many user groups in one call
      effect: write
      questions:
      - Is there a way to create and update a batch of user groups at once?
      - Can I upsert user groups in bulk and get back the IDs created and updated?
      instructions:
      - text: Bulk upsert this set of user groups.
      - text: Create or update all of these user groups in a single bulk request.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/user-groups/{userGroupId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a platform user group's details
      effect: read
      questions:
      - What are the details of a particular user-management group?
      - Where can I look up one platform user group by its ID?
      instructions:
      - text: Get user-management group {userGroupId}.
        slots:
          userGroupId: path.userGroupId
      - text: Show details for platform user group {userGroupId}.
        slots:
          userGroupId: path.userGroupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/user-groups/{userGroupId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a platform user group
      effect: write
      questions:
      - How do I change the email on a user-management group?
      - Can I turn off emails to members for one platform user group?
      instructions:
      - text: Set the email of user-management group {userGroupId} to {Email}.
        slots:
          userGroupId: path.userGroupId
          Email: requestBody.Email
      - text: Update platform user group {userGroupId} so send-email-to-members is {IsSendEmailToMembers}.
        slots:
          userGroupId: path.userGroupId
          IsSendEmailToMembers: requestBody.IsSendEmailToMembers
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/user-groups/{userGroupId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a platform user group
      effect: destructive
      questions:
      - Can I remove a group from the user management service?
      - What happens when I delete a user-management group by ID?
      instructions:
      - text: Delete user-management group {userGroupId}.
        slots:
          userGroupId: path.userGroupId
      - text: Remove platform user group {userGroupId} from user management.
        slots:
          userGroupId: path.userGroupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/user-group'].get
  update:
    x-apievangelist-phrasing:
      intent: List approval user groups
      effect: read
      questions:
      - What user groups exist for routing approvals?
      - Can I filter user groups to only active ones and page the results?
      instructions:
      - text: List all approval user groups.
      - text: List user groups matching filter {filter}, page {page}, {limit} per page.
        slots:
          filter: query.filter
          page: query.page
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/user-group'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing user group
      effect: write
      questions:
      - Can I rename an approval user group or change its email?
      - How do I stop sending emails to all members of a group?
      instructions:
      - text: Rename user group {id} to {name}.
        slots:
          id: requestBody.Id
          name: requestBody.Name
      - text: Change user group {id}'s email to {email}.
        slots:
          id: requestBody.Id
          email: requestBody.Email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/user-group'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new user group
      effect: write
      questions:
      - How do I set up a new group of approvers?
      - Can a new user group be nested under parent groups?
      instructions:
      - text: Create a user group called {name}.
        slots:
          name: requestBody.Name
      - text: Create user group {name} with email {email} and notify its members.
        slots:
          name: requestBody.Name
          email: requestBody.Email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/user-group/{groupId}/members'].get
  update:
    x-apievangelist-phrasing:
      intent: List members of a user group
      effect: read
      questions:
      - Who belongs to a given approval user group?
      - Can I see just the member list of a group?
      instructions:
      - text: List the members of user group {groupId}.
        slots:
          groupId: path.groupId
      - text: Show who is in group {groupId}.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/user-group/{groupId}/members'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a user or group to a user group
      effect: write
      questions:
      - How do I add someone to an approval user group?
      - Can I add another group as a member of a user group?
      instructions:
      - text: Add {memberType} {memberId} to user group {groupId}.
        slots:
          memberType: requestBody.MemberType
          memberId: requestBody.MemberId
          groupId: path.groupId
      - text: Put user {memberId} into group {groupId} as a {memberType} member.
        slots:
          memberId: requestBody.MemberId
          groupId: path.groupId
          memberType: requestBody.MemberType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/user-group/{groupId}/members/{memberId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a member from a user group
      effect: destructive
      questions:
      - Can I take a person out of an approval group without deleting the group?
      - What's the way to remove one member from a user group?
      instructions:
      - text: Remove member {memberId} from user group {groupId}.
        slots:
          memberId: path.memberId
          groupId: path.groupId
      - text: Delete membership {memberId} in group {groupId}.
        slots:
          memberId: path.memberId
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/user-group/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user group with its members
      effect: read
      questions:
      - What's the name, email and membership of a specific user group?
      - Can I look up one user group by ID including its members?
      instructions:
      - text: Get user group {id} with all of its members.
        slots:
          id: path.id
      - text: Show the name, email and membership of group {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/user-group/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user group
      effect: destructive
      questions:
      - Can I delete an approval user group we no longer use?
      - Is deleting a whole user group reversible?
      instructions:
      - text: Delete user group {id}.
        slots:
          id: path.id
      - text: Remove the entire group {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'