# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Microsoft Azure Group API
  version: 1.0.0
extends: openapi/microsoft-azure-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: 16
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/workspaces/{workspaceId}/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List groups in an API Management workspace
      effect: read
      questions:
      - Which user groups are defined in an API Management workspace?
      - Can I filter a workspace's groups with an OData expression?
      instructions:
      - text: List the groups in workspace {workspace} of API Management service {service}.
        slots:
          workspace: path.workspaceId
          service: path.serviceName
      - text: List API Management workspace groups matching {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/workspaces/{workspaceId}/groups/{groupId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group in an API Management workspace
      effect: read
      questions:
      - How do I see the details of one group in an APIM workspace?
      - What does a single workspace group record in API Management contain?
      instructions:
      - text: Show group {group} in workspace {workspace} on APIM service {service}.
        slots:
          group: path.groupId
          workspace: path.workspaceId
          service: path.serviceName
      - text: Fetch the definition of workspace group {group}.
        slots:
          group: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/workspaces/{workspaceId}/groups/{groupId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update an APIM workspace group
      effect: write
      questions:
      - Can I add a new developer group to an API Management workspace?
      - Is there one call that creates a workspace group or overwrites it if it exists?
      instructions:
      - text: Create group {group} in workspace {workspace} on APIM service {service}.
        slots:
          group: path.groupId
          workspace: path.workspaceId
          service: path.serviceName
      - text: Create or overwrite workspace group {group} in API Management.
        slots:
          group: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/workspaces/{workspaceId}/groups/{groupId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an APIM workspace group
      effect: destructive
      questions:
      - Can I remove a group from an API Management workspace?
      - Is there a way to drop an unused group from an APIM workspace?
      instructions:
      - text: Delete group {group} from workspace {workspace} on APIM service {service}.
        slots:
          group: path.groupId
          workspace: path.workspaceId
          service: path.serviceName
      - text: Remove the unused workspace group {group}.
        slots:
          group: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/workspaces/{workspaceId}/groups/{groupId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update details of an APIM workspace group
      effect: write
      questions:
      - Can I patch just a few fields on an API Management workspace group?
      - Is there a partial update for a group in an APIM workspace?
      instructions:
      - text: Patch the details of group {group} in workspace {workspace}, service {service}.
        slots:
          group: path.groupId
          workspace: path.workspaceId
          service: path.serviceName
      - text: Apply a partial update to existing workspace group {group}.
        slots:
          group: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/workspaces/{workspaceId}/groups/{groupId}'].head
  update:
    x-apievangelist-phrasing:
      intent: Get the ETag of an APIM workspace group
      effect: read
      questions:
      - How can I check a workspace group's current ETag before updating it?
      - What is the entity version of a group in my APIM workspace?
      instructions:
      - text: Get the ETag of group {group} in workspace {workspace} on service {service}.
        slots:
          group: path.groupId
          workspace: path.workspaceId
          service: path.serviceName
      - text: Check the entity state version of workspace group {group}.
        slots:
          group: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/group'].post
  update:
    x-apievangelist-phrasing:
      intent: Group faces by visual similarity
      effect: read
      questions:
      - Can I cluster a set of detected faces into groups of the same person?
      - Where do faces that resemble no one else end up when faces are grouped?
      instructions:
      - text: Group faces {faceIds} by similarity.
        slots:
          faceIds: requestBody.faceIds
      - text: Cluster detected face IDs {faceIds} into likely same-person groups.
        slots:
          faceIds: requestBody.faceIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenantID}/isMemberOf'].post
  update:
    x-apievangelist-phrasing:
      intent: Check if an object is a member of a group
      effect: read
      questions:
      - How do I check whether a user is in a directory group, even through nesting?
      - Can I test transitive group membership for a service principal?
      instructions:
      - text: Check if member {memberId} belongs to group {groupId} in tenant {tenant}.
        slots:
          memberId: requestBody.memberId
          groupId: requestBody.groupId
          tenant: path.tenantID
      - text: Verify {memberId} is a direct or transitive member of group {groupId}.
        slots:
          memberId: requestBody.memberId
          groupId: requestBody.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenantID}/groups/{groupObjectId}/$links/members/{memberObjectId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a member from a directory group
      effect: destructive
      questions:
      - How do I take a user out of a directory group?
      - Can I remove a single member from an Azure AD group by object ID?
      instructions:
      - text: Remove member {member} from group {group} in tenant {tenant}.
        slots:
          member: path.memberObjectId
          group: path.groupObjectId
          tenant: path.tenantID
      - text: Take {member} out of directory group {group}.
        slots:
          member: path.memberObjectId
          group: path.groupObjectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenantID}/groups/{groupObjectId}/$links/members'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a member to a directory group
      effect: write
      questions:
      - Can I add a user to an Azure AD group?
      - What do I pass to link a new member into a directory group?
      instructions:
      - text: Add the object at {url} as a member of group {group} in tenant {tenant}.
        slots:
          url: requestBody.url
          group: path.groupObjectId
          tenant: path.tenantID
      - text: Put member {url} into directory group {group}.
        slots:
          url: requestBody.url
          group: path.groupObjectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenantID}/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List groups in the directory tenant
      effect: read
      questions:
      - Which directory groups exist in my tenant?
      - Can I narrow the tenant's group list with an OData filter?
      instructions:
      - text: List all groups in tenant {tenant}.
        slots:
          tenant: path.tenantID
      - text: List tenant {tenant} groups matching {filter}.
        slots:
          tenant: path.tenantID
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenantID}/groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a directory group
      effect: write
      questions:
      - How do I create a new security group in the directory?
      - Can I create a mail-enabled directory group with its own mail nickname?
      instructions:
      - text: Create group {displayName} with mail nickname {nick} in tenant {tenant}, securityEnabled {sec}, mailEnabled {mail}.
        slots:
          displayName: requestBody.displayName
          nick: requestBody.mailNickname
          tenant: path.tenantID
          sec: requestBody.securityEnabled
          mail: requestBody.mailEnabled
      - text: Make a security group called {displayName} with nickname {nick} in tenant {tenant}, mail enabled {mail}, security enabled {sec}.
        slots:
          displayName: requestBody.displayName
          nick: requestBody.mailNickname
          tenant: path.tenantID
          mail: requestBody.mailEnabled
          sec: requestBody.securityEnabled
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenantID}/groups/{objectId}/members'].get
  update:
    x-apievangelist-phrasing:
      intent: List the members of a directory group
      effect: read
      questions:
      - Who belongs to a given directory group?
      - Can I list every member object of an Azure AD group?
      instructions:
      - text: List members of group {objectId} in tenant {tenant}.
        slots:
          objectId: path.objectId
          tenant: path.tenantID
      - text: Show who is in directory group {objectId}.
        slots:
          objectId: path.objectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenantID}/groups/{objectId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a directory group
      effect: read
      questions:
      - How can I read a directory group's properties?
      - What information does the directory hold about one group?
      instructions:
      - text: Get group {objectId} from tenant {tenant}.
        slots:
          objectId: path.objectId
          tenant: path.tenantID
      - text: Show the directory record for group {objectId}.
        slots:
          objectId: path.objectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenantID}/groups/{objectId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a directory group
      effect: destructive
      questions:
      - Can I delete a group from my tenant's directory?
      - How do I get rid of a directory group nobody uses anymore?
      instructions:
      - text: Delete group {objectId} from tenant {tenant}.
        slots:
          objectId: path.objectId
          tenant: path.tenantID
      - text: Delete directory group {objectId}.
        slots:
          objectId: path.objectId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{tenantID}/groups/{objectId}/getMemberGroups'].post
  update:
    x-apievangelist-phrasing:
      intent: List groups a group belongs to
      effect: read
      questions:
      - Which groups is a given group itself a member of?
      - Can I limit a group's parent-group lookup to security groups only?
      instructions:
      - text: List the groups that group {objectId} is a member of in tenant {tenant}, security-only {secOnly}.
        slots:
          objectId: path.objectId
          tenant: path.tenantID
          secOnly: requestBody.securityEnabledOnly
      - text: 'Get parent group IDs of group {objectId}, security groups only: {secOnly}.'
        slots:
          objectId: path.objectId
          secOnly: requestBody.securityEnabledOnly
      method: generated
      generated: '2026-09-26'