# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Clerk Com Users API
  version: 1.0.0
extends: openapi/clerk-com-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: 35
- target: $.paths['/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List and filter users
      effect: read
      questions:
      - How do I list every user in my Clerk instance, newest first?
      - Can I filter the user list by email address, username or organization?
      - Which users have been active since a certain date?
      instructions:
      - text: List users whose email address matches {email_address}.
        slots:
          email_address: query.email_address
      - text: Show the users in organization {organization_id}, {limit} at a time.
        slots:
          organization_id: query.organization_id
          limit: query.limit
      - text: List all banned users in the instance.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new user
      effect: write
      questions:
      - How do I create a user account from my backend without a sign-up flow?
      - Can I import a user with an existing password hash when migrating?
      - Are email addresses added when creating a user marked as verified?
      instructions:
      - text: Create a user with email {email_address} and password {password}.
        slots:
          email_address: requestBody.email_address
          password: requestBody.password
      - text: Create user {first_name} {last_name} with username {username}.
        slots:
          first_name: requestBody.first_name
          last_name: requestBody.last_name
          username: requestBody.username
      - text: Add a new user linked to my external ID {external_id}.
        slots:
          external_id: requestBody.external_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count users matching filters
      effect: read
      questions:
      - How many users are signed up in my application?
      - What is the total number of banned users right now?
      - Can I count users created within a date range without listing them?
      instructions:
      - text: Count the users in organization {organization_id}.
        slots:
          organization_id: query.organization_id
      - text: Give me the total number of users matching {query}.
        slots:
          query: query.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a user's details
      effect: read
      questions:
      - How do I look up the full profile of one user by their ID?
      - What details come back for a single user record?
      instructions:
      - text: Fetch the details of user {user_id}.
        slots:
          user_id: path.user_id
      - text: Show me everything stored on user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user
      effect: destructive
      questions:
      - How do I permanently remove a user account through the backend API?
      - Can I delete a user who asked for their account to be erased?
      instructions:
      - text: Delete user {user_id}.
        slots:
          user_id: path.user_id
      - text: Permanently remove the account of user {user_id} from my instance.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a user's attributes
      effect: write
      questions:
      - How do I change a user's name or username from the backend?
      - Can I switch which verified email is a user's primary email?
      - Is it possible to reset a user's password and sign them out of other sessions?
      instructions:
      - text: Change the username of user {user_id} to {username}.
        slots:
          user_id: path.user_id
          username: requestBody.username
      - text: Set email {primary_email_address_id} as the primary email for user {user_id}.
        slots:
          primary_email_address_id: requestBody.primary_email_address_id
          user_id: path.user_id
      - text: Set a new password {password} for user {user_id}.
        slots:
          password: requestBody.password
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/ban'].post
  update:
    x-apievangelist-phrasing:
      intent: Ban a single user
      effect: destructive
      questions:
      - How do I ban one abusive user so they can never sign in again?
      - Does banning a user revoke their active sessions?
      instructions:
      - text: Ban user {user_id}.
        slots:
          user_id: path.user_id
      - text: Block user {user_id} from signing in and revoke their sessions.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/unban'].post
  update:
    x-apievangelist-phrasing:
      intent: Unban a single user
      effect: write
      questions:
      - How do I lift the ban on one user I banned by mistake?
      - Can a banned user be allowed to sign in again?
      instructions:
      - text: Unban user {user_id}.
        slots:
          user_id: path.user_id
      - text: Remove the ban mark from user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/ban'].post
  update:
    x-apievangelist-phrasing:
      intent: Ban multiple users at once
      effect: destructive
      questions:
      - How do I ban a whole batch of spam accounts in one request?
      - Can I ban several users together instead of one at a time?
      instructions:
      - text: 'Ban all of these users at once: {user_ids}.'
        slots:
          user_ids: requestBody.user_ids
      - text: Bulk ban the accounts {user_ids} and revoke their sessions.
        slots:
          user_ids: requestBody.user_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/unban'].post
  update:
    x-apievangelist-phrasing:
      intent: Unban multiple users at once
      effect: write
      questions:
      - How do I lift bans on many users in a single call?
      - Can I bulk unban accounts I banned in a batch?
      instructions:
      - text: 'Unban all of these users at once: {user_ids}.'
        slots:
          user_ids: requestBody.user_ids
      - text: Bulk remove the ban from accounts {user_ids}.
        slots:
          user_ids: requestBody.user_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/lock'].post
  update:
    x-apievangelist-phrasing:
      intent: Lock a user out temporarily
      effect: write
      questions:
      - How do I temporarily lock a user out until the lock expires?
      - Where is the lock duration for locked users configured?
      instructions:
      - text: Lock user {user_id}.
        slots:
          user_id: path.user_id
      - text: Temporarily stop user {user_id} from signing in with a lock.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/unlock'].post
  update:
    x-apievangelist-phrasing:
      intent: Unlock a locked user
      effect: write
      questions:
      - How do I unlock a user before their lock expires?
      - Can I clear a lock on a user account manually?
      instructions:
      - text: Unlock user {user_id}.
        slots:
          user_id: path.user_id
      - text: Remove the sign-in lock from user {user_id} now.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/profile_image'].post
  update:
    x-apievangelist-phrasing:
      intent: Set a user's profile image
      effect: write
      questions:
      - How do I upload a profile picture for a user from the backend?
      - Can I replace a user's avatar with a new image file?
      instructions:
      - text: Upload {file} as the profile image for user {user_id}.
        slots:
          file: requestBody.file
          user_id: path.user_id
      - text: Replace the avatar of user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/profile_image'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a user's profile image
      effect: destructive
      questions:
      - How do I remove an inappropriate profile picture from a user?
      - Can an admin clear a user's avatar back to the default?
      instructions:
      - text: Delete the profile image of user {user_id}.
        slots:
          user_id: path.user_id
      - text: Clear the avatar on user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/metadata'].patch
  update:
    x-apievangelist-phrasing:
      intent: Merge metadata into a user
      effect: write
      questions:
      - How do I add a key to a user's private metadata without overwriting the rest?
      - Does updating user metadata deep-merge nested objects?
      - Can I remove a single metadata key from a user?
      instructions:
      - text: Merge {private_metadata} into the private metadata of user {user_id}.
        slots:
          private_metadata: requestBody.private_metadata
          user_id: path.user_id
      - text: Deep-merge {public_metadata} into user {user_id}'s public metadata.
        slots:
          public_metadata: requestBody.public_metadata
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/billing/subscription'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's billing subscription
      effect: read
      questions:
      - Which plans is a given user currently subscribed to?
      - How do I check a user's subscription payment status?
      instructions:
      - text: Show the billing subscription for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Get the active plans and payment status of user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/billing/credits'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's credit balance
      effect: read
      questions:
      - How much billing credit does a user have left?
      - Can I see a user's credit balance before their next recurring charge?
      instructions:
      - text: Show the credit balance of user {user_id}.
        slots:
          user_id: path.user_id
      - text: Look up how many credits user {user_id} has available right now.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/billing/credits'].post
  update:
    x-apievangelist-phrasing:
      intent: Adjust a user's credit balance
      effect: write
      questions:
      - How do I give a user billing credit as a goodwill gesture?
      - Can I decrease a user's credits, and how are duplicate adjustments prevented?
      instructions:
      - text: Increase user {user_id}'s credits by {amount} with idempotency key {idempotency_key}.
        slots:
          user_id: path.user_id
          amount: requestBody.amount
          idempotency_key: requestBody.idempotency_key
      - text: Apply a {action} of {amount} to user {user_id}'s credit balance with note {note} and key {idempotency_key}.
        slots:
          action: requestBody.action
          amount: requestBody.amount
          user_id: path.user_id
          note: requestBody.note
          idempotency_key: requestBody.idempotency_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/oauth_access_tokens/{provider}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's OAuth provider token
      effect: read
      questions:
      - How do I get the social provider access token for a user who signed in that way?
      - Are expired OAuth access tokens refreshed automatically when I fetch them?
      instructions:
      - text: Get the {provider} OAuth access token for user {user_id}.
        slots:
          provider: path.provider
          user_id: path.user_id
      - text: Fetch user {user_id}'s access token from provider {provider} so I can call that provider's API.
        slots:
          user_id: path.user_id
          provider: path.provider
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/organization_memberships'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's organization memberships
      effect: read
      questions:
      - Which organizations does a particular user belong to?
      - How do I page through all of one user's memberships?
      instructions:
      - text: List the organization memberships of user {user_id}.
        slots:
          user_id: path.user_id
      - text: Show which organizations user {user_id} is a member of.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/organization_invitations'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's organization invitations
      effect: read
      questions:
      - What organization invitations has a particular user received?
      - Can I see only the pending invitations for one user?
      instructions:
      - text: List the organization invitations sent to user {user_id}.
        slots:
          user_id: path.user_id
      - text: Show user {user_id}'s organization invitations with status {status}.
        slots:
          user_id: path.user_id
          status: query.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/verify_password'].post
  update:
    x-apievangelist-phrasing:
      intent: Check a user's password
      effect: read
      questions:
      - How do I confirm a user's password in a custom re-verification step?
      - Can my backend check whether a supplied password matches the user's?
      instructions:
      - text: Check whether {password} is the correct password for user {user_id}.
        slots:
          password: requestBody.password
          user_id: path.user_id
      - text: Verify user {user_id}'s password before this sensitive action.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/verify_totp'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify a user's TOTP or backup code
      effect: write
      questions:
      - How do I verify an authenticator app code for a user in a custom flow?
      - Does verifying a backup code use it up?
      instructions:
      - text: Verify the code {code} for user {user_id}.
        slots:
          code: requestBody.code
          user_id: path.user_id
      - text: Check whether authenticator or backup code {code} is valid for user {user_id}.
        slots:
          code: requestBody.code
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/mfa'].delete
  update:
    x-apievangelist-phrasing:
      intent: Disable all of a user's MFA methods
      effect: destructive
      questions:
      - How do I turn off two-factor authentication for a user who lost their phone?
      - Can I disable SMS and authenticator MFA for a user in one step?
      instructions:
      - text: Disable every MFA method on user {user_id}.
        slots:
          user_id: path.user_id
      - text: Turn off two-factor authentication for user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/backup_code'].delete
  update:
    x-apievangelist-phrasing:
      intent: Disable a user's backup codes
      effect: destructive
      questions:
      - How do I invalidate all of a user's backup codes?
      - Can an admin revoke leaked recovery codes for a user?
      instructions:
      - text: Disable all backup codes for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Invalidate the recovery codes of user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/passkeys/{passkey_identification_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user's passkey
      effect: destructive
      questions:
      - How do I remove a passkey registered by a user?
      - Is the user notified by email when an admin deletes their passkey?
      instructions:
      - text: Delete passkey {passkey_identification_id} from user {user_id}.
        slots:
          passkey_identification_id: path.passkey_identification_id
          user_id: path.user_id
      - text: Remove the passkey {passkey_identification_id} that user {user_id} registered.
        slots:
          passkey_identification_id: path.passkey_identification_id
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/web3_wallets/{web3_wallet_identification_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user's Web3 wallet
      effect: destructive
      questions:
      - How do I unlink a crypto wallet from a user account?
      - Can I delete a Web3 wallet identification from a user?
      instructions:
      - text: Delete Web3 wallet {web3_wallet_identification_id} from user {user_id}.
        slots:
          web3_wallet_identification_id: path.web3_wallet_identification_id
          user_id: path.user_id
      - text: Unlink wallet {web3_wallet_identification_id} from the account of user {user_id}.
        slots:
          web3_wallet_identification_id: path.web3_wallet_identification_id
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/totp'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user's authenticator apps
      effect: destructive
      questions:
      - How do I remove the authenticator app (TOTP) setup from a user?
      - Can I wipe every TOTP a user has enrolled?
      instructions:
      - text: Delete all TOTPs for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Remove the authenticator app enrollment from user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/external_accounts/{external_account_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink a user's external account
      effect: destructive
      questions:
      - How do I disconnect a social login account from a user?
      - Can I delete one linked external account by its ID?
      instructions:
      - text: Delete external account {external_account_id} from user {user_id}.
        slots:
          external_account_id: path.external_account_id
          user_id: path.user_id
      - text: Unlink the social connection {external_account_id} on user {user_id}.
        slots:
          external_account_id: path.external_account_id
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/password/set_compromised'].post
  update:
    x-apievangelist-phrasing:
      intent: Flag a user's password as compromised
      effect: write
      questions:
      - How do I force a user to reset a leaked password on next sign-in?
      - Can I also revoke all sessions when marking a password compromised?
      instructions:
      - text: Mark the password of user {user_id} as compromised.
        slots:
          user_id: path.user_id
      - text: Flag user {user_id}'s password as compromised and set revoke all sessions to {revoke_all_sessions}.
        slots:
          user_id: path.user_id
          revoke_all_sessions: requestBody.revoke_all_sessions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}/password/unset_compromised'].post
  update:
    x-apievangelist-phrasing:
      intent: Clear a compromised-password flag
      effect: write
      questions:
      - How do I stop prompting a user to reset a password I flagged by mistake?
      - Can I undo marking a password as compromised?
      instructions:
      - text: Unmark the password of user {user_id} as compromised.
        slots:
          user_id: path.user_id
      - text: Clear the compromised-password flag on user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/applications/{applicationID}/instances/{envOrInsID}/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users of an application instance
      effect: read
      questions:
      - How do I list the users of one of my applications' production instance via the Platform API?
      - Can I search an instance's users by email or username across applications I manage?
      instructions:
      - text: List the users of application {applicationID} in environment {envOrInsID}.
        slots:
          applicationID: path.applicationID
          envOrInsID: path.envOrInsID
      - text: Search instance {envOrInsID} of application {applicationID} for users matching {query}.
        slots:
          envOrInsID: path.envOrInsID
          applicationID: path.applicationID
          query: query.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/applications/{applicationID}/instances/{envOrInsID}/users/{userID}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user in an application instance
      effect: destructive
      questions:
      - How do I delete a user from a specific application instance through the Platform API?
      - What happens if I delete a platform instance user that was already removed?
      instructions:
      - text: Delete user {userID} from application {applicationID} instance {envOrInsID}.
        slots:
          userID: path.userID
          applicationID: path.applicationID
          envOrInsID: path.envOrInsID
      - text: Remove user {userID} in the {envOrInsID} environment of app {applicationID} via the platform.
        slots:
          userID: path.userID
          envOrInsID: path.envOrInsID
          applicationID: path.applicationID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/applications/{applicationID}/instances/{envOrInsID}/users/{userID}/ban'].post
  update:
    x-apievangelist-phrasing:
      intent: Ban a user in an application instance
      effect: destructive
      questions:
      - How do I ban a user in one of my applications using a Platform API token?
      - Which scope is needed to ban users through the Platform API?
      instructions:
      - text: Ban user {userID} in application {applicationID} instance {envOrInsID}.
        slots:
          userID: path.userID
          applicationID: path.applicationID
          envOrInsID: path.envOrInsID
      - text: Using the platform, block user {userID} from signing into the {envOrInsID} environment of app {applicationID}.
        slots:
          userID: path.userID
          envOrInsID: path.envOrInsID
          applicationID: path.applicationID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/platform/applications/{applicationID}/instances/{envOrInsID}/users/{userID}/unban'].post
  update:
    x-apievangelist-phrasing:
      intent: Unban a user in an application instance
      effect: write
      questions:
      - How do I lift a ban on a user in one of my applications through the Platform API?
      - Can a platform-banned user sign in again after being unbanned?
      instructions:
      - text: Unban user {userID} in application {applicationID} instance {envOrInsID}.
        slots:
          userID: path.userID
          applicationID: path.applicationID
          envOrInsID: path.envOrInsID
      - text: Using the platform, let user {userID} sign back into the {envOrInsID} environment of app {applicationID}.
        slots:
          userID: path.userID
          envOrInsID: path.envOrInsID
          applicationID: path.applicationID
      method: generated
      generated: '2026-09-26'