# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness User API
  version: 1.0.0
extends: openapi/harness-user-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: 20
- target: $.paths['/ng/api/user/add-user-to-groups/{userId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Set which user groups a user belongs to
      effect: write
      questions:
      - How do I put an existing Harness user into a set of user groups?
      - Does adding a user to groups remove them from their other groups?
      instructions:
      - text: Put user {userId} into user groups {userGroupIdsToAdd}, replacing their other non-managed groups.
        slots:
          userId: path.userId
          userGroupIdsToAdd: requestBody.userGroupIdsToAdd
      - text: Reassign user {userId}'s group membership in project {projectIdentifier} to {userGroupIdsToAdd}.
        slots:
          userId: path.userId
          projectIdentifier: query.projectIdentifier
          userGroupIdsToAdd: requestBody.userGroupIdsToAdd
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite users by email to a scope
      effect: write
      questions:
      - Can I invite several people by email to a Harness project at once?
      - Is it possible to give invited users role bindings or user groups as they're added?
      instructions:
      - text: Invite {emails} to my account.
        slots:
          emails: requestBody.emails
      - text: Add {emails} to project {projectIdentifier} and place them in user groups {userGroups}.
        slots:
          emails: requestBody.emails
          projectIdentifier: query.projectIdentifier
          userGroups: requestBody.userGroups
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user/password'].put
  update:
    x-apievangelist-phrasing:
      intent: Change my password
      effect: write
      questions:
      - How do I change my own login password?
      - Do I need to supply my current password to set a new one?
      instructions:
      - text: Change my password from {currentPassword} to {newPassword}.
        slots:
          currentPassword: requestBody.currentPassword
          newPassword: requestBody.newPassword
      - text: Update my login password to {newPassword}.
        slots:
          newPassword: requestBody.newPassword
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user/last-admin'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether a user is the last admin
      effect: read
      questions:
      - Is this user the only admin left in the account?
      - Would removing someone leave a project with no administrator?
      instructions:
      - text: Check whether user {userId} is the last admin in my account.
        slots:
          userId: query.userId
      - text: Tell me if {userId} is the only remaining admin of project {projectIdentifier}.
        slots:
          userId: query.userId
          projectIdentifier: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user/disable-two-factor-auth'].put
  update:
    x-apievangelist-phrasing:
      intent: Turn off two-factor authentication for me
      effect: write
      questions:
      - How do I switch off two-factor authentication on my Harness login?
      - Can I disable 2FA for my own user in an account?
      instructions:
      - text: Disable two-factor authentication for my user in account {accountIdentifier}.
        slots:
          accountIdentifier: query.accountIdentifier
      - text: Turn off my 2FA.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user/endImpersonation/{userId}'].post
  update:
    x-apievangelist-phrasing:
      intent: End an impersonation session
      effect: write
      questions:
      - How do I stop impersonating another user?
      - Can an admin end the impersonation session they started?
      instructions:
      - text: End my impersonation session of user {userId}.
        slots:
          userId: path.userId
      - text: Stop impersonating {userId} and return to my own identity.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user/aggregate/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's details and role assignments
      effect: read
      questions:
      - What roles has a specific user been assigned in a project?
      - Where can I see one user's metadata together with their role assignments?
      instructions:
      - text: Show user {userId}'s details and role assignments.
        slots:
          userId: path.userId
      - text: Get the roles assigned to user {userId} in org {orgIdentifier}.
        slots:
          userId: path.userId
          orgIdentifier: query.orgIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user/aggregate'].post
  update:
    x-apievangelist-phrasing:
      intent: List users with their role assignments
      effect: read
      questions:
      - Who has access to this project, and with which roles?
      - Can I filter the people in a scope by role or resource group?
      instructions:
      - text: List everyone with access to project {projectIdentifier} along with their role assignments.
        slots:
          projectIdentifier: query.projectIdentifier
      - text: Show users who hold role {roleIdentifiers}, including their role assignments.
        slots:
          roleIdentifiers: requestBody.roleIdentifiers
      - text: Search users with role assignments for {searchTerm}.
        slots:
          searchTerm: query.searchTerm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user/two-factor-auth/{authMechanism}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my two-factor auth setup details
      effect: read
      questions:
      - Where do I get the settings needed to set up TOTP two-factor auth for my login?
      - What does the two-factor setup look like for a given auth mechanism?
      instructions:
      - text: Get my two-factor authentication settings for mechanism {authMechanism}.
        slots:
          authMechanism: path.authMechanism
      - text: Fetch the {authMechanism} 2FA setup info for my user.
        slots:
          authMechanism: path.authMechanism
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user/currentUser'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the logged-in user's profile
      effect: read
      questions:
      - Who am I logged in as in Harness?
      - What account details does the API return for the current user?
      instructions:
      - text: Show my own user profile.
      - text: Get the currently logged-in user's info for account {accountIdentifier}.
        slots:
          accountIdentifier: query.accountIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up users in a scope by email or id
      effect: read
      questions:
      - Can I look up several users at once by their email addresses?
      - Which users in an org match a given search term?
      instructions:
      - text: Look up the users with emails {emails}.
        slots:
          emails: requestBody.emails
      - text: Get the basic user records for ids {identifiers}.
        slots:
          identifiers: requestBody.identifiers
      - text: Find users in org {orgIdentifier} matching {searchTerm}.
        slots:
          orgIdentifier: query.orgIdentifier
          searchTerm: requestBody.searchTerm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user/impersonate/{userId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Start impersonating a user
      effect: write
      questions:
      - Can an admin sign in as another user to troubleshoot what they see?
      - Do I have to give a reason when impersonating someone?
      instructions:
      - text: Impersonate user {userId} because {reasonOfImpersonation}.
        slots:
          userId: path.userId
          reasonOfImpersonation: requestBody.reasonOfImpersonation
      - text: Start an impersonation session as {userId} with reason {reasonOfImpersonation}.
        slots:
          userId: path.userId
          reasonOfImpersonation: requestBody.reasonOfImpersonation
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user/{userId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update another user's name or email
      effect: write
      questions:
      - Can I rename a user or change their email by their user id?
      - Which profile fields of a specific user can be edited?
      instructions:
      - text: Change user {userId}'s email to {email}.
        slots:
          userId: path.userId
          email: requestBody.email
      - text: Set user {userId}'s given name to {givenName} and family name to {familyName}.
        slots:
          userId: path.userId
          givenName: requestBody.givenName
          familyName: requestBody.familyName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user/{userId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a user from a scope
      effect: destructive
      questions:
      - How do I take someone off a Harness project?
      - Can I remove a collaborator from an org without deleting their account?
      instructions:
      - text: Remove user {userId} from project {projectIdentifier}.
        slots:
          userId: path.userId
          projectIdentifier: query.projectIdentifier
      - text: Revoke {userId}'s access to my account.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user/reset-two-factor-auth/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Reset a user's two-factor authentication
      effect: write
      questions:
      - What can I do when a user has lost their 2FA device?
      - Can an admin reset two-factor for someone else?
      instructions:
      - text: Reset two-factor authentication for user {userId}.
        slots:
          userId: path.userId
      - text: Clear {userId}'s 2FA so they can enroll again.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user/unlock-user/{userId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Unlock a locked-out user
      effect: write
      questions:
      - How do I unlock a user who got locked out?
      - Can I unlock someone within a specific org or project?
      instructions:
      - text: Unlock user {userId}.
        slots:
          userId: path.userId
      - text: Unlock {userId} in org {orgIdentifier}.
        slots:
          userId: path.userId
          orgIdentifier: query.orgIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user/enable-two-factor-auth'].put
  update:
    x-apievangelist-phrasing:
      intent: Turn on two-factor authentication
      effect: write
      questions:
      - Can I enable TOTP two-factor authentication for a user in an account?
      - What secret key does enabling 2FA expect?
      instructions:
      - text: Enable two-factor auth for {email} using mechanism {mechanism}.
        slots:
          email: requestBody.email
          mechanism: requestBody.mechanism
      - text: Turn on 2FA for user {userId} with TOTP secret {totpSecretKey}.
        slots:
          userId: requestBody.userId
          totpSecretKey: requestBody.totpSecretKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/user'].put
  update:
    x-apievangelist-phrasing:
      intent: Update my user profile record
      effect: write
      questions:
      - How do I change my own display name or preferences?
      - Can I set my default account on my user record?
      instructions:
      - text: Update my display name to {name}.
        slots:
          name: requestBody.name
      - text: Set my default account to {defaultAccountId}.
        slots:
          defaultAccountId: requestBody.defaultAccountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/code/api/v1/user/favorite'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark a code resource as a favorite
      effect: write
      questions:
      - Can I star a repository in Harness Code?
      - Which resource types can be added to my favorites?
      instructions:
      - text: Add {resource_id} to my favorites.
        slots:
          resource_id: requestBody.resource_id
      - text: Favorite {resource_type} {resource_id}.
        slots:
          resource_type: requestBody.resource_type
          resource_id: requestBody.resource_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/code/api/v1/user/favorite/{resource_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unfavorite a code resource
      effect: destructive
      questions:
      - How do I unstar a repo I favorited?
      - Can I remove something from my favorites list?
      instructions:
      - text: Remove {resource_id} from my favorites.
        slots:
          resource_id: path.resource_id
      - text: Unfavorite {resource_type} {resource_id}.
        slots:
          resource_type: query.resource_type
          resource_id: path.resource_id
      method: generated
      generated: '2026-09-26'