# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Showpad Users API
  version: 1.0.0
extends: openapi/showpad-users-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: 29
- target: $.paths['/users.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List users with filters (v3)
      effect: read
      questions:
      - Which users in our Showpad instance are still only invited and haven't activated yet?
      - Can I filter the older v3 user list by last name, language or user type?
      - What's the way to page through every user with sorting on the v3 endpoint?
      instructions:
      - text: List v3 users whose email is {email}.
        slots:
          email: query.email
      - text: Show users of type {userType} with active status {isActive}, {limit} at a time, using the v3 users list.
        slots:
          userType: query.userType
          limit: query.limit
          isActive: query.isActive
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new user
      effect: write
      questions:
      - How do I add a new salesperson as a user in Showpad?
      - Which fields are mandatory when creating a user account?
      - Can I send the welcome mail automatically when a new user is created?
      instructions:
      - text: Create a user {firstName} {lastName} with email {email}, username {userName}, language {language}, active {isActive}.
        slots:
          firstName: requestBody.firstName
          lastName: requestBody.lastName
          email: requestBody.email
          userName: requestBody.userName
          language: requestBody.language
          isActive: requestBody.isActive
      - text: Add new user {email} reporting to manager {managerId} and email them on creation via {sendMailToUser}.
        slots:
          email: requestBody.email
          managerId: requestBody.managerId
          sendMailToUser: requestBody.sendMailToUser
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/count.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Count users
      effect: read
      questions:
      - How many users do we have in total?
      - What is the number of active users with a content license?
      instructions:
      - text: Count the users where isActive is {isActive}.
        slots:
          isActive: query.isActive
      - text: Give me a headcount of users of type {userType}.
        slots:
          userType: query.userType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/description.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Describe the User model and its APIs
      effect: read
      questions:
      - What fields does the User model have and which user APIs are available?
      - Is there a self-describing schema for the user resource?
      instructions:
      - text: Show me the User model description and available user endpoints.
      - text: Fetch the metadata describing the user resource.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/invite.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Resend invites to all pending users
      effect: write
      questions:
      - How can I nudge everyone who still has a pending invitation?
      - Is there a bulk way to resend all outstanding user invitations?
      instructions:
      - text: Send invites to every user with a pending invitation.
      - text: Re-invite all users who never accepted their invite.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/me.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the current API user
      effect: read
      questions:
      - Who am I authenticated as when calling the API?
      - What account details belong to the token I'm using right now?
      instructions:
      - text: Show my own user profile for the current API token.
      - text: Get the current user's details with only the fields {fields}.
        slots:
          fields: query.fields
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/me/recommendations.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get recommendations for the current user
      effect: read
      questions:
      - What content recommendations does Showpad have for me?
      - Can I narrow my personal recommendations to a particular recommendation type?
      instructions:
      - text: Show my recommendations of type {recommendationsType}.
        slots:
          recommendationsType: query.recommendationsType
      - text: List the recommendations made for me.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/me/tickets.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get tickets for the current user
      effect: read
      questions:
      - Which tickets are assigned to me?
      - Where can I see my own open tickets?
      instructions:
      - text: List my tickets.
      - text: Get the tickets for the current user filtered by type {recommendationsType}.
        slots:
          recommendationsType: query.recommendationsType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id1}/usergroups/{id2}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Link or unlink a user and group via GET method
      effect: write
      questions:
      - Is there a single GET call that can either link or unlink a user and a user group?
      - Can I toggle a user's group membership by passing a method parameter?
      instructions:
      - text: Use method {method} to link or unlink user {id1} with user group {id2} through the combined GET call.
        slots:
          method: query.method
          id1: path.id1
          id2: path.id2
      - text: Run the method-switched membership call {method} for user {id1} and group {id2}.
        slots:
          method: query.method
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id1}/usergroups/{id2}/link.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a user to a user group
      effect: write
      questions:
      - How do I put an existing user into an existing user group?
      - Can I link a user to a group by their two IDs?
      instructions:
      - text: Link user {id1} to user group {id2}.
        slots:
          id1: path.id1
          id2: path.id2
      - text: Make user {id1} a member of group {id2}.
        slots:
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id1}/usergroups/{id2}/unlink.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove a user from a user group
      effect: destructive
      questions:
      - How do I take a user out of a user group?
      - Can I unlink one user from one group without deleting either?
      instructions:
      - text: Unlink user {id1} from user group {id2}.
        slots:
          id1: path.id1
          id2: path.id2
      - text: Drop user {id1}'s membership in group {id2}.
        slots:
          id1: path.id1
          id2: path.id2
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a user (v3)
      effect: read
      questions:
      - How do I look up a single user's full record on the older v3 endpoint?
      - Can I expand related data when fetching one user by ID in v3?
      instructions:
      - text: Get user {id} from the v3 users endpoint.
        slots:
          id: path.id
      - text: Fetch v3 user {id} with expanded {expand}.
        slots:
          id: path.id
          expand: query.expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}.json'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a user with PUT
      effect: write
      questions:
      - How do I change a user's email or name with a PUT request?
      - Can I deactivate a user by updating isActive via PUT?
      instructions:
      - text: PUT an update to user {id} setting their email to {email}.
        slots:
          id: path.id
          email: requestBody.email
      - text: Using PUT, set user {id} active status to {isActive}.
        slots:
          id: path.id
          isActive: requestBody.isActive
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a user with POST
      effect: write
      questions:
      - Is there a POST alternative for updating a user's profile when PUT isn't available?
      - Can I change a user's timezone or phone using a POST update?
      instructions:
      - text: Via the POST update call, set user {id}'s timezone to {timezone}.
        slots:
          id: path.id
          timezone: requestBody.timezone
      - text: POST a change of manager for user {id} to {managerId}.
        slots:
          id: path.id
          managerId: requestBody.managerId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}.json'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user
      effect: destructive
      questions:
      - How do I permanently remove a user account?
      - What happens when I delete a user by ID?
      instructions:
      - text: Delete user {id}.
        slots:
          id: path.id
      - text: Remove the user account with ID {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/channels.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's channels
      effect: read
      questions:
      - Which channels does a given user have?
      - Can I see only a user's personal channels or hide template channels?
      instructions:
      - text: List the channels belonging to user {id}.
        slots:
          id: path.id
      - text: Show user {id}'s channels named {name}.
        slots:
          id: path.id
          name: query.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/divisionpermissions.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's division permissions
      effect: read
      questions:
      - What division-level rights has a particular user been granted?
      - Can I check whether a user can manage assets in their divisions?
      instructions:
      - text: List division permissions for user {id}.
        slots:
          id: path.id
      - text: Show user {id}'s division permissions where manageUsers is {manageUsers}.
        slots:
          id: path.id
          manageUsers: query.manageUsers
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/divisionpermissions.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant a user a division permission
      effect: write
      questions:
      - How do I give a user admin rights in a specific division?
      - Can a division permission granted to a user expire automatically?
      instructions:
      - text: Give user {id} a permission in division {divisionId} for user {userId}.
        slots:
          id: path.id
          divisionId: requestBody.divisionId
          userId: requestBody.userId
      - text: Grant user {userId} asset management in division {divisionId} through user {id}, expiring {expiredAt}.
        slots:
          userId: requestBody.userId
          divisionId: requestBody.divisionId
          id: path.id
          expiredAt: requestBody.expiredAt
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/divisions.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List the divisions a user belongs to
      effect: read
      questions:
      - Which divisions is this user a member of?
      - Can I find a user's divisions that have asset sharing turned on?
      instructions:
      - text: List the divisions for user {id}.
        slots:
          id: path.id
      - text: Show user {id}'s divisions named {name}.
        slots:
          id: path.id
          name: query.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/email-preferences.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's email preferences
      effect: read
      questions:
      - Which email notifications is a user subscribed to?
      - Where do I read someone's current email subscription settings?
      instructions:
      - text: Show the email preferences for user {id}.
        slots:
          id: path.id
      - text: Get user {id}'s notification email settings.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/email-preferences.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Change a user's email preferences
      effect: write
      questions:
      - How do I turn off comment or mention emails for a user?
      - Can I unsubscribe someone from insights digest emails?
      instructions:
      - text: Set comment email subscriptions for user {id} to {commentsSubscriptionEnabled}.
        slots:
          id: path.id
          commentsSubscriptionEnabled: requestBody.commentsSubscriptionEnabled
      - text: Update user {id} so mentions emails are {mentionsSubscriptionEnabled} and insights emails are {insightsSubscriptionEnabled}.
        slots:
          id: path.id
          mentionsSubscriptionEnabled: requestBody.mentionsSubscriptionEnabled
          insightsSubscriptionEnabled: requestBody.insightsSubscriptionEnabled
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/externalservices.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's external services
      effect: read
      questions:
      - Which external services are connected to a user's account?
      - Can I filter a user's connected integrations by type?
      instructions:
      - text: List external services connected for user {id}.
        slots:
          id: path.id
      - text: Show user {id}'s external services of type {type}.
        slots:
          id: path.id
          type: query.type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/invite.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Send an invitation email to one user
      effect: write
      questions:
      - How do I resend the invitation email to just one person?
      - Can I invite a single user rather than everyone pending?
      instructions:
      - text: Send an invitation email to user {id}.
        slots:
          id: path.id
      - text: Re-invite only user {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/link.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Link a user to related resources via Link body
      effect: write
      questions:
      - How do I attach related resources to a user using a Link reference?
      - Is there a generic link call for associating things with a user record?
      instructions:
      - text: Link user {id} to the resource referenced by {Link}.
        slots:
          id: path.id
          Link: requestBody.Link
      - text: Attach {Link} to user record {id}.
        slots:
          Link: requestBody.Link
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/unlink.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Unlink related resources from a user
      effect: destructive
      questions:
      - How do I detach a linked resource from a user?
      - Can I remove a Link association from a user without deleting the user?
      instructions:
      - text: Unlink {Link} from user {id}.
        slots:
          Link: requestBody.Link
          id: path.id
      - text: Detach the linked resource {Link} from user record {id}.
        slots:
          Link: requestBody.Link
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/usergroups.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's user groups
      effect: read
      questions:
      - Which user groups does a given person belong to?
      - Can I see only the synced groups a user is in?
      instructions:
      - text: List the user groups of user {id}.
        slots:
          id: path.id
      - text: Show groups for user {id} where isSynced is {isSynced}.
        slots:
          id: path.id
          isSynced: query.isSynced
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{id}/usergroups.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user group for a user
      effect: write
      questions:
      - How do I create a new group and add a user to it in one step?
      - Can I give the new group a description and external ID when adding it to a user?
      instructions:
      - text: Create a user group named {name} for user {id}.
        slots:
          name: requestBody.name
          id: path.id
      - text: Add a new group {name} described as {description} to user {id}.
        slots:
          name: requestBody.name
          description: requestBody.description
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users (v4)
      effect: read
      questions:
      - What's the newer v4 way to list users?
      - Can I look up several users at once by a list of emails?
      instructions:
      - text: Using the v4 API, list users with emails {emails}.
        slots:
          emails: query.emails
      - text: Get the v4 users with IDs {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a user (v4)
      effect: read
      questions:
      - How do I fetch one user's details with the v4 API?
      - What does the v4 user object contain?
      instructions:
      - text: Retrieve v4 user {userId}.
        slots:
          userId: path.userId
      - text: Get the details of user {userId} from the v4 endpoint.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-10-01'