# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Things Stack — Identity Server User Registry API
  version: 1.0.0
extends: openapi/the-things-network-userregistry-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: 9
- target: $.paths['/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List all users on the network
      effect: read
      questions:
      - Can an admin list every user registered on The Things Stack network?
      - Is it possible to include deleted users when listing network accounts?
      instructions:
      - text: List all users on the network.
      - text: 'List network users, {limit} per page, including deleted: {deleted}.'
        slots:
          limit: query.limit
          deleted: query.deleted
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a new user account
      effect: write
      questions:
      - How do I register a new user on the network?
      - Can I sign someone up using an invitation token?
      instructions:
      - text: Register user {user}.
        slots:
          user: requestBody.user
      - text: Sign up user {user} with invitation token {invitation_token}.
        slots:
          user: requestBody.user
          invitation_token: requestBody.invitation_token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user.ids.user_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a user's profile
      effect: write
      questions:
      - How do I change a user's name, email or other profile fields?
      - Can this profile update change a password too?
      instructions:
      - text: Update profile fields {field_mask} of user {user_id}.
        slots:
          field_mask: requestBody.field_mask
          user_id: path.user.ids.user_id
      - text: Change user {user_id}'s profile to {user}.
        slots:
          user_id: path.user.ids.user_id
          user: requestBody.user
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_ids.user_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's profile
      effect: read
      questions:
      - What profile details are stored for a specific user?
      - Can I look up a user by email as well as by user ID?
      instructions:
      - text: Show user {user_id}.
        slots:
          user_id: path.user_ids.user_id
      - text: Look up the profile of user {user_id} with email {email}.
        slots:
          user_id: path.user_ids.user_id
          email: query.user_ids.email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_ids.user_id}/password'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a user's password
      effect: write
      questions:
      - How do I change my password on The Things Stack?
      - Can I sign out all other sessions when I change a password?
      instructions:
      - text: Change the password of user {user_id} from {old} to {new}.
        slots:
          user_id: path.user_ids.user_id
          old: requestBody.old
          new: requestBody.new
      - text: 'Set a new password {new} for user {user_id} and revoke all access: {revoke_all_access}.'
        slots:
          new: requestBody.new
          user_id: path.user_ids.user_id
          revoke_all_access: requestBody.revoke_all_access
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_ids.user_id}/temporary_password'].post
  update:
    x-apievangelist-phrasing:
      intent: Email a temporary password for a forgotten one
      effect: write
      questions:
      - What do I do if a user forgot their password?
      - Is the temporary password sent to the user's email address?
      instructions:
      - text: Send a temporary password to user {user_id}.
        slots:
          user_id: path.user_ids.user_id
      - text: Start a forgotten-password reset for user {user_id} at {email}.
        slots:
          user_id: path.user_ids.user_id
          email: query.user_ids.email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user account
      effect: destructive
      questions:
      - How do I delete a user account from the network?
      - Does deleting a user make their user ID available again?
      instructions:
      - text: Delete user {user_id}.
        slots:
          user_id: path.user_id
      - text: Soft-delete the account of user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/purge'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently purge a user account
      effect: destructive
      questions:
      - Can I purge a user so their ID can be reused?
      - What cleanup remains in external integrations after a user is purged?
      instructions:
      - text: Purge user {user_id} permanently.
        slots:
          user_id: path.user_id
      - text: Release user ID {user_id} for reuse by purging it.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a deleted user account
      effect: write
      questions:
      - Can a recently deleted user account be brought back?
      - For how long after deletion can a user be restored?
      instructions:
      - text: Restore deleted user {user_id}.
        slots:
          user_id: path.user_id
      - text: Undelete the account of user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'