# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Showpad Usergroups API
  version: 1.0.0
extends: openapi/showpad-user-groups-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-02'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 20
- target: $.paths['/usergroups.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List user groups
      effect: read
      questions:
      - Which user groups exist in our Showpad organization?
      - Can I list only the groups synced from our identity provider?
      instructions:
      - text: List all user groups.
      - text: Find user groups named {name}.
        slots:
          name: query.name
      - text: List user groups with synced set to {isSynced}.
        slots:
          isSynced: query.isSynced
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user group
      effect: write
      questions:
      - How do I create a new user group for a team?
      - Can I attach content profiles when creating a group?
      instructions:
      - text: Create a user group called {name}.
        slots:
          name: requestBody.name
      - text: Create group {name} with content profiles {contentProfiles}.
        slots:
          name: requestBody.name
          contentProfiles: requestBody.contentProfiles
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/count.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Count user groups
      effect: read
      questions:
      - How many user groups do we have?
      - What's the number of synced groups?
      instructions:
      - text: Count all user groups.
      - text: Count the groups with synced set to {isSynced}.
        slots:
          isSynced: query.isSynced
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/description.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Describe the user group data model
      effect: read
      questions:
      - What fields does a user group object have?
      - Where can I see the API calls supported for user groups?
      instructions:
      - text: Describe the user group model and its available API calls.
      - text: Show me the property definitions for the usergroup resource.
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/{id1}/divisions/{id2}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Link or unlink a group and division via GET
      effect: write
      questions:
      - Is there a GET override for adding or removing a user group's division access?
      - Can I toggle a group's division assignment with the method parameter?
      instructions:
      - text: Use method {method} to change the link between user group {id1} and division {id2}.
        slots:
          method: query.method
          id1: path.id1
          id2: path.id2
      - text: Through GET, apply {method} to group {id1}'s access to division {id2}.
        slots:
          method: query.method
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/{id1}/divisions/{id2}/link.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Give a user group access to a division
      effect: write
      questions:
      - How do I give a user group access to a division?
      - Can I connect an existing group to an existing division by ID?
      instructions:
      - text: Link user group {id1} to division {id2}.
        slots:
          id1: path.id1
          id2: path.id2
      - text: Grant group {id1} access to division {id2}.
        slots:
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/{id1}/divisions/{id2}/unlink.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove a user group from a division
      effect: write
      questions:
      - How do I revoke a user group's access to a division?
      - Can I disconnect a group from a division without deleting either?
      instructions:
      - text: Unlink user group {id1} from division {id2}.
        slots:
          id1: path.id1
          id2: path.id2
      - text: Take division {id2} away from group {id1}.
        slots:
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/{id1}/users/{id2}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Link or unlink a group member via GET
      effect: write
      questions:
      - Is there a GET override for adding or removing a member of a user group?
      - Can I change someone's group membership with the method query parameter?
      instructions:
      - text: For member {id2} of group {id1}, send method {method} on the membership endpoint.
        slots:
          method: query.method
          id1: path.id1
          id2: path.id2
      - text: Through GET with method {method}, add or remove person {id2} in group {id1}.
        slots:
          method: query.method
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/{id1}/users/{id2}/link.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an existing user to a group
      effect: write
      questions:
      - How do I add an existing user to a user group?
      - Can I put someone into a group by their user ID?
      instructions:
      - text: Link user {id2} to user group {id1}.
        slots:
          id1: path.id1
          id2: path.id2
      - text: Add existing user {id2} to group {id1}.
        slots:
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/{id1}/users/{id2}/unlink.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove a user from a group
      effect: write
      questions:
      - How do I remove a person from a user group?
      - Can I take a user out of a group without deactivating them?
      instructions:
      - text: Unlink user {id2} from user group {id1}.
        slots:
          id1: path.id1
          id2: path.id2
      - text: Remove user {id2} from group {id1}.
        slots:
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/{id}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user group
      effect: read
      questions:
      - How do I fetch one user group's details?
      - What does a single user group record include?
      instructions:
      - text: Get user group {id}.
        slots:
          id: path.id
      - text: Show the details of group {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/{id}.json'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a user group (PUT)
      effect: write
      questions:
      - How do I rename a user group with a PUT request?
      - Can I change a group's content profiles with PUT?
      instructions:
      - text: PUT an update renaming user group {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Using PUT, set group {id}'s content profiles to {contentProfiles}.
        slots:
          id: path.id
          contentProfiles: requestBody.contentProfiles
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/{id}.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a user group (POST)
      effect: write
      questions:
      - Can I update a user group with POST instead of PUT?
      - Is there a POST variant for changing a group's description or sync flag?
      instructions:
      - text: Via POST, set group {id}'s description to {description}.
        slots:
          id: path.id
          description: requestBody.description
      - text: Using the POST update, set synced to {isSynced} on user group {id}.
        slots:
          id: path.id
          isSynced: requestBody.isSynced
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/{id}.json'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user group
      effect: destructive
      questions:
      - How do I delete a user group?
      - What happens when I remove a group we no longer need?
      instructions:
      - text: Delete user group {id}.
        slots:
          id: path.id
      - text: Remove group {id} from Showpad.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/{id}/divisions.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user group's divisions
      effect: read
      questions:
      - Which divisions can a given user group access?
      - Can I see only the divisions with asset sharing enabled for a group?
      instructions:
      - text: List the divisions of user group {id}.
        slots:
          id: path.id
      - text: Show divisions of group {id} with asset sharing {hasDivisionAssetSharingEnabled}.
        slots:
          id: path.id
          hasDivisionAssetSharingEnabled: query.hasDivisionAssetSharingEnabled
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/{id}/divisions.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a division for a user group
      effect: write
      questions:
      - How do I create a new division and attach it to a user group?
      - Can I enable division asset sharing on a division I create for a group?
      instructions:
      - text: Create division {name} for user group {id}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Add a new division {name} to group {id} with asset sharing {hasDivisionAssetSharingEnabled}.
        slots:
          id: path.id
          name: requestBody.name
          hasDivisionAssetSharingEnabled: requestBody.hasDivisionAssetSharingEnabled
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/{id}/link.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Link related resources to a user group
      effect: write
      questions:
      - How do I attach several related resources to a user group with a Link list?
      - Can I connect one group to multiple resources at once?
      instructions:
      - text: Link the resources {Link} to user group {id}.
        slots:
          id: path.id
          Link: requestBody.Link
      - text: Attach {Link} to group {id} as related resources.
        slots:
          id: path.id
          Link: requestBody.Link
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/{id}/unlink.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Unlink related resources from a user group
      effect: write
      questions:
      - How do I detach a list of resources from a user group?
      - Can I remove several resource links from a group in one call?
      instructions:
      - text: Unlink the resources {Link} from user group {id}.
        slots:
          id: path.id
          Link: requestBody.Link
      - text: Detach {Link} from group {id}.
        slots:
          id: path.id
          Link: requestBody.Link
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/{id}/users.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List members of a user group
      effect: read
      questions:
      - Who are the members of a specific user group?
      - Can I list only the active or invited members of a group?
      instructions:
      - text: List the users in user group {id}.
        slots:
          id: path.id
      - text: Show members of group {id} with active set to {isActive}.
        slots:
          id: path.id
          isActive: query.isActive
      method: generated
      generated: '2026-10-02'
- target: $.paths['/usergroups/{id}/users.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new user inside a group
      effect: write
      questions:
      - How do I create a new user and put them in a group in one step?
      - What details does a new group member need?
      instructions:
      - text: Create user {userName} ({firstName} {lastName}, {email}) in group {id} with language {language} and active {isActive}.
        slots:
          id: path.id
          userName: requestBody.userName
          firstName: requestBody.firstName
          lastName: requestBody.lastName
          email: requestBody.email
          language: requestBody.language
          isActive: requestBody.isActive
      - text: Add a brand-new user with email {email} to user group {id}.
        slots:
          id: path.id
          email: requestBody.email
      method: generated
      generated: '2026-10-02'