API Evangelist conversational phrasing for dotCMS REST Users API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for dotCMS REST Users API
  version: 1.0.0
extends: openapi/dotcms-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: 13
- target: $.paths['/api/user/getloggedinuser/{params}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the logged-in user (deprecated endpoint)
      effect: read
      questions:
      - Is there an older endpoint that returns the logged-in user's email and role ID?
      - Which deprecated call returns who is logged in?
      instructions:
      - text: Get the logged-in user from the deprecated legacy endpoint using {params}.
        slots:
          params: path.params
      - text: Call the old getloggedinuser route with {params} to get the userId and roleId.
        slots:
          params: path.params
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/users/activate/{userId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Activate a user account
      effect: write
      questions:
      - How do I re-enable a user who was deactivated?
      - Can I activate a user account by its user ID?
      instructions:
      - text: Activate user {userId}.
        slots:
          userId: path.userId
      - text: Re-enable the account of user {userId} so they can log in again.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/users'].put
  update:
    x-apievangelist-phrasing:
      intent: Update another user's account
      effect: write
      questions:
      - Can an admin change another user's name, email and roles in one request?
      - What permissions do I need to edit someone else's user account?
      instructions:
      - text: Update user {userId} to first name {firstName}, last name {lastName} and email {email}.
        slots:
          userId: requestBody.userId
          firstName: requestBody.firstName
          lastName: requestBody.lastName
          email: requestBody.email
      - text: Change the roles of user {userId} to {roles}, keeping name {firstName} {lastName} and email {email}.
        slots:
          userId: requestBody.userId
          roles: requestBody.roles
          firstName: requestBody.firstName
          lastName: requestBody.lastName
          email: requestBody.email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new user
      effect: write
      questions:
      - How do I add a new editor to dotCMS with a password and roles?
      - Which fields are required to create a user?
      instructions:
      - text: Create user {firstName} {lastName} with email {email} and password {password}.
        slots:
          firstName: requestBody.firstName
          lastName: requestBody.lastName
          email: requestBody.email
          password: requestBody.password
      - text: Add a new user {firstName} {lastName} ({email}) with roles {roles}.
        slots:
          firstName: requestBody.firstName
          lastName: requestBody.lastName
          email: requestBody.email
          roles: requestBody.roles
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/users/deactivate/{userId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Deactivate a user account
      effect: write
      questions:
      - Can I block a user from logging in without deleting their account?
      - How do I deactivate someone who left the team?
      instructions:
      - text: Deactivate user {userId}.
        slots:
          userId: path.userId
      - text: Disable the account of {userId} but keep their content.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/users/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a user by ID
      effect: read
      questions:
      - What details are stored for a specific user?
      - Can I fetch one user's profile by their user ID?
      instructions:
      - text: Get user {userId}.
        slots:
          userId: path.userId
      - text: Show the profile of user {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/users/{userId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user and reassign their content
      effect: destructive
      questions:
      - When I delete a user, what happens to the content they own?
      - Can I delete a user and hand their permissions to someone else?
      instructions:
      - text: Delete user {userId} and reassign their content to {replacementUserId}.
        slots:
          userId: path.userId
          replacementUserId: query.replacementUserId
      - text: Remove the account of {userId}, transferring ownership to user {replacementUserId}.
        slots:
          userId: path.userId
          replacementUserId: query.replacementUserId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/users/filter'].get
  update:
    x-apievangelist-phrasing:
      intent: Search and filter users
      effect: read
      questions:
      - How can I find all users who have a particular role?
      - Can I page through users sorted by name and exclude the anonymous user?
      instructions:
      - text: Search users matching {query}.
        slots:
          query: query.query
      - text: List users with role {roleKey}, {per_page} per page, page {page}.
        slots:
          roleKey: query.roleKey
          per_page: query.per_page
          page: query.page
      - text: Find users sorted by {orderby} in {direction} order.
        slots:
          orderby: query.orderby
          direction: query.direction
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/users/loginas'].post
  update:
    x-apievangelist-phrasing:
      intent: Impersonate another user
      effect: write
      questions:
      - How can an admin log in as another user to reproduce what they see?
      - Do I need to re-enter my password to use Login As?
      instructions:
      - text: Log in as user {userId}, confirming with my password {password}.
        slots:
          userId: requestBody.userId
          password: requestBody.password
      - text: Impersonate {userId} using admin password {password}.
        slots:
          userId: requestBody.userId
          password: requestBody.password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/users/loginAsData'].get
  update:
    x-apievangelist-phrasing:
      intent: List users I can impersonate
      effect: read
      questions:
      - Which users am I allowed to log in as?
      - Can I search the list of users available for Login As?
      instructions:
      - text: List the users I can impersonate.
      - text: Show Login As candidates matching {filter}, page {page}.
        slots:
          filter: query.filter
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/users/logoutas'].put
  update:
    x-apievangelist-phrasing:
      intent: Stop impersonating a user
      effect: write
      questions:
      - How do I get back to my own admin session after Login As?
      - Can I end an impersonation session through the API?
      instructions:
      - text: Stop impersonating and return to my admin account.
      - text: End the current Login As session.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/users/current'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the currently authenticated user
      effect: read
      questions:
      - Who am I logged in as right now?
      - Can I get my own user details from the v1 users API?
      instructions:
      - text: Get my current user details.
      - text: Show the account I'm authenticated as.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/users/current'].put
  update:
    x-apievangelist-phrasing:
      intent: Update my own profile or password
      effect: write
      questions:
      - How do I change my own password?
      - Will changing my own email force me to re-authenticate?
      instructions:
      - text: Change my password from {currentPassword} to {newPassword}.
        slots:
          currentPassword: requestBody.currentPassword
          newPassword: requestBody.newPassword
      - text: Update my profile name to {givenName} {surname}.
        slots:
          givenName: requestBody.givenName
          surname: requestBody.surname
      - text: Change my own email to {email}.
        slots:
          email: requestBody.email
      method: generated
      generated: '2026-09-26'