# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Authorization API v1.1 Groups API
  version: 1.0.0
extends: openapi/here-groups-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: 15
- target: $.paths['/groups/{groupId}/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List the roles tied to a group
      effect: read
      questions:
      - Which roles are associated with a particular group?
      - Who is the group admin role holder for this group?
      instructions:
      - text: List the roles for group {groupId}.
        slots:
          groupId: path.groupId
      - text: Show the role assignments on group {groupId}.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: Find groups in my realm
      effect: read
      questions:
      - What groups exist in my HERE organization realm?
      - Can I search the realm's groups by name with free text?
      instructions:
      - text: List all groups in my realm.
      - text: Search the realm's groups for {q}.
        slots:
          q: query.q
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new group
      effect: write
      questions:
      - How do I create a group to share access among several users and apps?
      - Does the person who creates a group automatically become its admin?
      instructions:
      - text: Create a group called {name}.
        slots:
          name: requestBody.name
      - text: Create a new group {name} described as {description}.
        slots:
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{groupId}'].get
  update:
    x-apievangelist-phrasing:
      intent: View a single group
      effect: read
      questions:
      - What is the name and description of a specific group?
      - Can I look up a group by its HRN?
      instructions:
      - text: Show me group {groupId}.
        slots:
          groupId: path.groupId
      - text: Get the details of the group with HRN {groupId}.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{groupId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Rename or redescribe a group
      effect: write
      questions:
      - How do I rename an existing group?
      - Can I change a group's description after it was created?
      instructions:
      - text: Rename group {groupId} to {name}.
        slots:
          groupId: path.groupId
          name: requestBody.name
      - text: Update existing 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['/groups/{groupId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a group
      effect: destructive
      questions:
      - How do I delete a group we no longer use?
      - Can a group be removed entirely by its HRN?
      instructions:
      - text: Delete group {groupId}.
        slots:
          groupId: path.groupId
      - text: Permanently remove the group {groupId} from the realm.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{groupId}/policies'].get
  update:
    x-apievangelist-phrasing:
      intent: List policies attached to a group
      effect: read
      questions:
      - Which policies are attached to this group?
      - What access policies does a group carry?
      instructions:
      - text: List the policies attached to group {groupId}.
        slots:
          groupId: path.groupId
      - text: Show group {groupId}'s policies.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{groupId}/policies/{policy}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List permissions in a group's policy
      effect: read
      questions:
      - What unscoped permissions does one specific policy give a group?
      - Can I break down a group's policy into its individual permissions?
      instructions:
      - text: List the permissions inside policy {policy} on group {groupId}.
        slots:
          policy: path.policy
          groupId: path.groupId
      - text: Break down what policy {policy} grants group {groupId}.
        slots:
          policy: path.policy
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{groupId}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a group's permissions
      effect: read
      questions:
      - What unscoped permissions has a group been assigned overall?
      - Can I filter a group's permissions to one service?
      instructions:
      - text: Show all permissions assigned to group {groupId}.
        slots:
          groupId: path.groupId
      - text: List group {groupId}'s permissions for service {serviceId}.
        slots:
          groupId: path.groupId
          serviceId: query.serviceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{groupId}/members'].get
  update:
    x-apievangelist-phrasing:
      intent: List the members of a group
      effect: read
      questions:
      - Who belongs to this group?
      - Can I list only the apps in a group, not the users?
      instructions:
      - text: List the members of group {groupId}.
        slots:
          groupId: path.groupId
      - text: Show only the {entityType} members of group {groupId}.
        slots:
          entityType: query.entityType
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{groupId}/members/me'].delete
  update:
    x-apievangelist-phrasing:
      intent: Leave a group yourself
      effect: destructive
      questions:
      - How do I remove myself from a group?
      - Do I lose my group admin role when I leave a group?
      instructions:
      - text: Take me out of group {groupId}.
        slots:
          groupId: path.groupId
      - text: Have my account leave group {groupId}.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{groupId}/members/{member}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check one member of a group
      effect: read
      questions:
      - Is a particular user or app a member of this group?
      - Can I fetch a single group member's record?
      instructions:
      - text: Check whether {member} is in group {groupId}.
        slots:
          member: path.member
          groupId: path.groupId
      - text: Show member {member} of group {groupId}.
        slots:
          member: path.member
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{groupId}/members/{member}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a member to a group
      effect: write
      questions:
      - How do I add a user or app to a group?
      - Can I put an app into a group so it inherits the group's access?
      instructions:
      - text: Add {member} to group {groupId}.
        slots:
          member: path.member
          groupId: path.groupId
      - text: Put app {member} into group {groupId}.
        slots:
          member: path.member
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{groupId}/members/{member}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a member from a group
      effect: destructive
      questions:
      - How do I remove another user from a group I administer?
      - Does removing someone from a group also strip their admin role there?
      instructions:
      - text: Remove {member} from group {groupId}.
        slots:
          member: path.member
          groupId: path.groupId
      - text: Kick app {member} out of group {groupId}.
        slots:
          member: path.member
          groupId: path.groupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/me'].get
  update:
    x-apievangelist-phrasing:
      intent: List the groups I belong to
      effect: read
      questions:
      - Which groups am I a member of?
      - Can my app see the groups it has been added to?
      instructions:
      - text: List my groups.
      - text: Show the first {count} groups I belong to.
        slots:
          count: query.count
      method: generated
      generated: '2026-09-26'