# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Identity Platform Groups Service API
  version: 1.0.0
extends: openapi/canonical-groupsservice-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/v0/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List identity platform groups
      effect: read
      questions:
      - What groups exist in the identity platform admin?
      - Can I see every group defined for access control?
      instructions:
      - text: List all groups.
      - text: Show me every group in the identity platform.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a group
      effect: write
      questions:
      - How do I add a new group in the identity admin?
      - Can I choose the ID when creating a group?
      instructions:
      - text: Create a group called {name}.
        slots:
          name: requestBody.name
      - text: Add a new group {name} with ID {id}.
        slots:
          name: requestBody.name
          id: requestBody.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/groups/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group
      effect: read
      questions:
      - What are the details of a particular group?
      - Can I fetch a single group by its ID?
      instructions:
      - text: Show group {id}.
        slots:
          id: path.id
      - text: Look up the group with ID {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/groups/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a group
      effect: destructive
      questions:
      - How do I delete a group I no longer need?
      - Can I remove a whole group from the identity platform?
      instructions:
      - text: Delete group {id}.
        slots:
          id: path.id
      - text: Remove the group {id} entirely.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/groups/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or update a group
      effect: write
      questions:
      - Can I rename an existing group?
      - How would I change a group's details after creating it?
      instructions:
      - text: Rename group {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Update the name on group {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/groups/{id}/entitlements'].get
  update:
    x-apievangelist-phrasing:
      intent: List a group's entitlements
      effect: read
      questions:
      - What entitlements has a group been granted?
      - Can I page through a group's entitlements with a pagination token?
      instructions:
      - text: List the entitlements of group {id}.
        slots:
          id: path.id
      - text: Show the next page of entitlements for group {id} using token {X-Token-Pagination}.
        slots:
          id: path.id
          X-Token-Pagination: header.X-Token-Pagination
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/groups/{id}/entitlements'].patch
  update:
    x-apievangelist-phrasing:
      intent: Grant or change a group's entitlements
      effect: write
      questions:
      - How do I give a group new entitlements?
      - Can I add several entitlements to a group in one call?
      instructions:
      - text: Apply entitlement updates {updates} to group {id}.
        slots:
          updates: requestBody.updates
          id: path.id
      - text: Grant group {id} the entitlements in {updates}.
        slots:
          id: path.id
          updates: requestBody.updates
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/groups/{id}/entitlements/{entitlementId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove one entitlement from a group
      effect: destructive
      questions:
      - How do I revoke a single entitlement from a group?
      - Can I take away one permission from a group without touching the others?
      instructions:
      - text: Remove entitlement {entitlementId} from group {id}.
        slots:
          entitlementId: path.entitlementId
          id: path.id
      - text: Revoke group {id}'s entitlement {entitlementId}.
        slots:
          id: path.id
          entitlementId: path.entitlementId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/groups/{id}/identities'].get
  update:
    x-apievangelist-phrasing:
      intent: List the members of a group
      effect: read
      questions:
      - Which users and identities belong to a group?
      - Who is a member of a specific group?
      instructions:
      - text: List the identities in group {id}.
        slots:
          id: path.id
      - text: Show me who belongs to group {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/groups/{id}/identities'].patch
  update:
    x-apievangelist-phrasing:
      intent: Add identities to a group
      effect: write
      questions:
      - How do I add users to a group?
      - Can I put several identities into a group at once?
      instructions:
      - text: Add identities {identities} to group {id}.
        slots:
          identities: requestBody.identities
          id: path.id
      - text: Update group {id}'s membership with {identities}.
        slots:
          id: path.id
          identities: requestBody.identities
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/groups/{id}/identities/{identityId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a member from a group
      effect: destructive
      questions:
      - How do I take a user out of a group?
      - Can I remove one identity from a group's membership?
      instructions:
      - text: Remove identity {identityId} from group {id}.
        slots:
          identityId: path.identityId
          id: path.id
      - text: Kick member {identityId} out of group {id}.
        slots:
          identityId: path.identityId
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/groups/{id}/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List a group's roles
      effect: read
      questions:
      - Which roles are assigned to a group?
      - What roles does a particular group carry?
      instructions:
      - text: List the roles assigned to group {id}.
        slots:
          id: path.id
      - text: Show group {id}'s roles.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/groups/{id}/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign roles to a group
      effect: write
      questions:
      - How do I assign roles to a group?
      - Can I give a group several roles in one request?
      instructions:
      - text: Assign roles {roles} to group {id}.
        slots:
          roles: requestBody.roles
          id: path.id
      - text: Give group {id} the roles {roles}.
        slots:
          id: path.id
          roles: requestBody.roles
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/groups/{id}/roles/{roleId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a role from a group
      effect: destructive
      questions:
      - How do I unassign a role from a group?
      - Can I strip one role off a group and keep its others?
      instructions:
      - text: Remove role {roleId} from group {id}.
        slots:
          roleId: path.roleId
          id: path.id
      - text: Unassign role {roleId} from group {id}.
        slots:
          roleId: path.roleId
          id: path.id
      method: generated
      generated: '2026-09-26'