# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Groups.group API
  version: 1.0.0
extends: openapi/azure-ad-groups-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: 9
- target: $.paths['/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List groups in the organization
      effect: read
      questions:
      - How do I list all the groups in my Entra ID tenant?
      - Can I search or filter groups by display name when listing them?
      - Why don't dynamic distribution groups show up when I list groups?
      instructions:
      - text: List all groups in the organization.
      - text: Find groups whose display name matches {search}.
        slots:
          search: query.$search
      - text: List groups matching filter {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a group
      effect: write
      questions:
      - How do I create a new security group in Entra ID?
      - What do I need to set to create a Microsoft 365 group with a mail nickname?
      instructions:
      - text: Create a security group called {displayName} with mail nickname {mailNickname}.
        slots:
          displayName: requestBody.displayName
          mailNickname: requestBody.mailNickname
      - text: Create a new group {displayName} described as {description}.
        slots:
          displayName: requestBody.displayName
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/groups/{group-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group by id
      effect: read
      questions:
      - How do I get the properties of a group when I know its object id?
      - Which group properties are returned by default, and how do I ask for others?
      instructions:
      - text: Get group {group}.
        slots:
          group: path.group-id
      - text: Show the display name, mail and visibility of group id {group}.
        slots:
          group: path.group-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/groups/{group-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a group by id
      effect: destructive
      questions:
      - Can a deleted group be restored, and for how long?
      - How do I delete a group using its object id?
      instructions:
      - text: Delete group {group}.
        slots:
          group: path.group-id
      - text: Remove the group with object id {group} from the tenant.
        slots:
          group: path.group-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/groups/{group-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a group by id
      effect: write
      questions:
      - How do I rename a group or change its description using its object id?
      - Can I change a group's visibility after it's been created?
      instructions:
      - text: Rename group {group} to {displayName}.
        slots:
          group: path.group-id
          displayName: requestBody.displayName
      - text: Set the visibility of group id {group} to {visibility}.
        slots:
          group: path.group-id
          visibility: requestBody.visibility
      method: generated
      generated: '2026-10-01'
- target: $.paths['/groups(uniqueName=\'{uniqueName}\')'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group by its unique name
      effect: read
      questions:
      - Can I look up a group by its uniqueName instead of its object id?
      - What does the group with a given unique name look like?
      instructions:
      - text: Get the group with unique name {uniqueName}.
        slots:
          uniqueName: path.uniqueName
      - text: Look up group by unique name {uniqueName} and show its properties.
        slots:
          uniqueName: path.uniqueName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/groups(uniqueName=\'{uniqueName}\')'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a group by its unique name
      effect: destructive
      questions:
      - Is it possible to delete a group addressing it by uniqueName rather than id?
      - What happens to a distribution group when I delete it by unique name?
      instructions:
      - text: Delete the group with unique name {uniqueName}.
        slots:
          uniqueName: path.uniqueName
      - text: Remove group {uniqueName}, identified by its unique name.
        slots:
          uniqueName: path.uniqueName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/groups(uniqueName=\'{uniqueName}\')'].patch
  update:
    x-apievangelist-phrasing:
      intent: Upsert a group by its unique name
      effect: write
      questions:
      - How do I create a group only if one with this unique name doesn't already exist?
      - Can I upsert a group keyed on uniqueName so reruns don't create duplicates?
      instructions:
      - text: Upsert the group with unique name {uniqueName} and display name {displayName}.
        slots:
          uniqueName: path.uniqueName
          displayName: requestBody.displayName
      - text: Create or update group {uniqueName} with description {description}.
        slots:
          uniqueName: path.uniqueName
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/groups/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count groups
      effect: read
      questions:
      - How many groups are there in my organization?
      - Do I need the ConsistencyLevel header to get a group count?
      instructions:
      - text: Count all groups in the tenant.
      - text: Give me the total number of groups.
      method: generated
      generated: '2026-10-01'