# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Gainsight Users API
  version: 1.0.0
extends: openapi/gainsight-users-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: 16
- target: $.paths['/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List Gainsight users
      effect: read
      questions:
      - Who are the users in my Gainsight instance?
      - Can I page through users by page number?
      instructions:
      - text: List users, page {pageNumber}.
        slots:
          pageNumber: query.pageNumber
      - text: Show all Gainsight users, {pageSize} per page.
        slots:
          pageSize: query.pageSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update a product user
      effect: write
      questions:
      - How do I add an end user to Gainsight PX, or overwrite them if they exist?
      - Can I link a new PX user to an account when creating them?
      instructions:
      - text: Upsert PX user {identifyId} with email {email}.
        slots:
          identifyId: requestBody.identifyId
          email: requestBody.email
      - text: Create or update user {identifyId} on account {accountId} with role {role}.
        slots:
          identifyId: requestBody.identifyId
          accountId: requestBody.accountId
          role: requestBody.role
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Gainsight user
      effect: read
      questions:
      - Where can I look up a Gainsight user by user ID?
      - What details are stored for one user?
      instructions:
      - text: Get user {userId}.
        slots:
          userId: path.userId
      - text: Show the Gainsight user record {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{userId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a user's license or role
      effect: write
      questions:
      - Can I change a Gainsight user's license type or user type?
      - Is it possible to update a user's role and email in Gainsight?
      instructions:
      - text: Set license type {LicenseType} for user {userId}.
        slots:
          LicenseType: requestBody.LicenseType
          userId: path.userId
      - text: Change user {userId}'s role to {Role} and user type to {UserType}.
        slots:
          userId: path.userId
          Role: requestBody.Role
          UserType: requestBody.UserType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{userId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a product user
      effect: destructive
      questions:
      - Can I delete a user from Gainsight PX by user ID?
      - How is a PX user removed?
      instructions:
      - text: Delete user {userId}.
        slots:
          userId: path.userId
      - text: Remove user {userId} from Gainsight PX.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{userId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a product user
      effect: write
      questions:
      - Can I patch just a PX user's title or phone?
      - Can a PX user be moved to a different account?
      instructions:
      - text: Patch user {userId} ({identifyId}) with title {title}.
        slots:
          userId: path.userId
          identifyId: requestBody.identifyId
          title: requestBody.title
      - text: Move PX user {userId} ({identifyId}) to account {accountId}.
        slots:
          userId: path.userId
          identifyId: requestBody.identifyId
          accountId: requestBody.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{userId}/deactivate'].post
  update:
    x-apievangelist-phrasing:
      intent: Deactivate a user
      effect: destructive
      questions:
      - Is there a way to deactivate a user without deleting them?
      - Can I disable a Gainsight user account?
      instructions:
      - text: Deactivate user {userId}.
        slots:
          userId: path.userId
      - text: Disable the account of user {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/users'].get
  update:
    x-apievangelist-phrasing:
      intent: Filter users with the v1 API
      effect: read
      questions:
      - Which users match a filter such as role or last seen date?
      - Does the v1 user listing support sorting and scroll paging?
      instructions:
      - text: Get v1 users matching {filter}.
        slots:
          filter: query.filter
      - text: List v1 users sorted by {sort}.
        slots:
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user with product tag keys
      effect: write
      questions:
      - What does the v1 endpoint require to create a user?
      - Can I set a Salesforce contact ID when creating a v1 user?
      instructions:
      - text: Create v1 user {identifyId} under product key {propertyKeys}.
        slots:
          identifyId: requestBody.identifyId
          propertyKeys: requestBody.propertyKeys
      - text: Add v1 user {identifyId} ({propertyKeys}) with email {email} and account {accountId}.
        slots:
          identifyId: requestBody.identifyId
          propertyKeys: requestBody.propertyKeys
          email: requestBody.email
          accountId: requestBody.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/users/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user whose ID has special characters
      effect: destructive
      questions:
      - How do I delete a user whose identify ID can't go in the URL?
      - Is there a delete that takes the user ID in the request body?
      instructions:
      - text: Delete user {identifyId}, passing the ID in the body.
        slots:
          identifyId: requestBody.identifyId
      - text: Hard-delete ({hardDelete}) body-identified user {identifyId}.
        slots:
          hardDelete: query.hardDelete
          identifyId: requestBody.identifyId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/users/denylist/{identifyId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether a user is denylisted
      effect: read
      questions:
      - Is a given user on the denylist?
      - Are a user's events being ignored by PX?
      instructions:
      - text: Check the denylist flag for user {identifyId}.
        slots:
          identifyId: path.identifyId
      - text: Tell me if user {identifyId} is denied.
        slots:
          identifyId: path.identifyId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/users/denylist/{identifyId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Denylist a user
      effect: write
      questions:
      - Can I make PX ignore all events from a test user?
      - Can I take a user off the denylist?
      instructions:
      - text: Set the denylist flag for user {identifyId} to {denied}.
        slots:
          identifyId: path.identifyId
          denied: requestBody.denied
      - text: Stop recording events from user {identifyId} by setting denied to {denied}.
        slots:
          identifyId: path.identifyId
          denied: requestBody.denied
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/users/update'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a user whose ID has special characters
      effect: write
      questions:
      - How do I update a user whose identify ID can't go in the URL path?
      - Is there a v1 update that takes the user ID in the body?
      instructions:
      - text: Update user {identifyId} (ID in body) with product key {propertyKeys}.
        slots:
          identifyId: requestBody.identifyId
          propertyKeys: requestBody.propertyKeys
      - text: Change the email of body-identified user {identifyId} to {email}, key {propertyKeys}.
        slots:
          identifyId: requestBody.identifyId
          email: requestBody.email
          propertyKeys: requestBody.propertyKeys
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/users/{identifyId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user with the v1 API
      effect: read
      questions:
      - What does a user's full v1 profile contain when fetched by identify ID?
      - Can I see a user's number of visits and last seen date?
      instructions:
      - text: Retrieve v1 user {identifyId}.
        slots:
          identifyId: path.identifyId
      - text: Show visits and last seen date for user {identifyId}.
        slots:
          identifyId: path.identifyId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/users/{identifyId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a user's data by identify ID
      effect: write
      questions:
      - Can I overwrite a v1 user's record using the identify ID in the URL?
      - Can I update a user's title through the v1 API?
      instructions:
      - text: Replace v1 user {identifyId} with body ID {bodyIdentifyId} and product key {propertyKeys}.
        slots:
          identifyId: path.identifyId
          bodyIdentifyId: requestBody.identifyId
          propertyKeys: requestBody.propertyKeys
      - text: Set v1 user {identifyId}'s title to {title} (body ID {bodyIdentifyId}, key {propertyKeys}).
        slots:
          identifyId: path.identifyId
          title: requestBody.title
          bodyIdentifyId: requestBody.identifyId
          propertyKeys: requestBody.propertyKeys
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/users/{identifyId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user by identify ID
      effect: destructive
      questions:
      - If I delete a user and they come back within 7 days, is their history revived?
      - How do I permanently delete a user so they can't be revived?
      instructions:
      - text: Delete v1 user {identifyId}.
        slots:
          identifyId: path.identifyId
      - text: Hard-delete user {identifyId} with hardDelete {hardDelete}.
        slots:
          identifyId: path.identifyId
          hardDelete: query.hardDelete
      method: generated
      generated: '2026-09-26'