# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Iterable Users API
  version: 1.0.0
extends: openapi/iterable-users-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 30
- target: $.paths['/api/auth/jwts/invalidate'].post
  update:
    x-apievangelist-phrasing:
      intent: Invalidate a user's JWTs
      effect: destructive
      questions:
      - How do I revoke all JWTs issued to a user, say after a password reset?
      - Can I invalidate only tokens issued before a certain time?
      instructions:
      - text: Invalidate all JWTs for {email}.
        slots:
          email: requestBody.email
      - text: Revoke JWTs for user {userId} issued before {issuedBefore}.
        slots:
          userId: requestBody.userId
          issuedBefore: requestBody.issuedBefore
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/bulkUpdate'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk update user profiles under /api
      effect: write
      questions:
      - Can I update many user profiles in one /api request without wiping omitted fields?
      - Will a bulk update create new user fields automatically?
      instructions:
      - text: Bulk update users {users}.
        slots:
          users: requestBody.users
      - text: Bulk update users {users} via /api/users, creating new fields {createNewFields}.
        slots:
          users: requestBody.users
          createNewFields: requestBody.createNewFields
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/bulkUpdateSubscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk overwrite user subscriptions
      effect: write
      questions:
      - Can I update subscription preferences for many users at once?
      - Does the bulk subscription update merge or overwrite existing values?
      instructions:
      - text: Bulk update subscriptions {updateSubscriptionsRequests}.
        slots:
          updateSubscriptionsRequests: requestBody.updateSubscriptionsRequests
      - text: 'Overwrite subscription settings for these users: {updateSubscriptionsRequests}.'
        slots:
          updateSubscriptionsRequests: requestBody.updateSubscriptionsRequests
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/byUserId'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user by userId as a query parameter
      effect: read
      questions:
      - Can I look up a user whose userId has slashes by passing it as a query parameter?
      - Which user lookup takes the userId in the query string?
      instructions:
      - text: Get the user with userId {userId} passed as a query parameter.
        slots:
          userId: query.userId
      - text: Look up user {userId} via /api/users/byUserId?userId=.
        slots:
          userId: query.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/byUserId/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user by userId in the path
      effect: read
      questions:
      - How do I fetch a user's profile by userId with the userId in the /api URL path?
      - What profile data comes back for a userId lookup?
      instructions:
      - text: Get user profile for userId {userId}.
        slots:
          userId: path.userId
      - text: Fetch /api user {userId} by path.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/byUserId/{userId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user by userId
      effect: destructive
      questions:
      - Does deleting a user by userId stop future data collection about them?
      - What happens if several users share the same userId when I delete one?
      instructions:
      - text: Delete user with userId {userId}.
        slots:
          userId: path.userId
      - text: Remove /api user profile {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/disableDevice'].post
  update:
    x-apievangelist-phrasing:
      intent: Disable push to a mobile device
      effect: write
      questions:
      - How do I stop push notifications to one of a user's devices?
      - Can I disable a device token without deleting the user?
      instructions:
      - text: Disable push for device token {token}.
        slots:
          token: requestBody.token
      - text: Turn off pushes to device {token} for {email}.
        slots:
          token: requestBody.token
          email: requestBody.email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/forget'].post
  update:
    x-apievangelist-phrasing:
      intent: Forget a user for GDPR
      effect: destructive
      questions:
      - How do I honor a GDPR erasure request and stop collecting a user's data?
      - Does forgetting a user delete their data permanently?
      instructions:
      - text: Forget {email} for GDPR.
        slots:
          email: requestBody.email
      - text: Erase user {userId} and block future data collection.
        slots:
          userId: requestBody.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/forgotten'].get
  update:
    x-apievangelist-phrasing:
      intent: Get hashed emails of forgotten users
      effect: read
      questions:
      - Which email addresses have been forgotten under GDPR in my project?
      - Can I get a hashed list of forgotten emails to check against my records?
      instructions:
      - text: List hashed emails of forgotten users.
      - text: Export the GDPR-forgotten email hashes.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/forgottenUserIds'].get
  update:
    x-apievangelist-phrasing:
      intent: Get hashed userIds of forgotten users
      effect: read
      questions:
      - Which userIds have been forgotten under GDPR?
      - Can I export hashes of forgotten userIds?
      instructions:
      - text: List hashed userIds of forgotten users.
      - text: Export the GDPR-forgotten userId hashes.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/getByEmail'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user by email as a query parameter
      effect: read
      questions:
      - Can I look up a user whose email has special characters by passing it as a query parameter?
      - Which user lookup takes the email in the query string?
      instructions:
      - text: Get the user with email {email} passed as a query parameter.
        slots:
          email: query.email
      - text: Look up {email} via /api/users/getByEmail.
        slots:
          email: query.email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/getFields'].get
  update:
    x-apievangelist-phrasing:
      intent: Get all user fields in the project
      effect: read
      questions:
      - What user profile fields exist in my /api project?
      - What's the rate limit on listing user fields?
      instructions:
      - text: List all user fields in my project.
      - text: Show user fields from /api/users/getFields.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/getSentMessages'].get
  update:
    x-apievangelist-phrasing:
      intent: Get messages sent to a user
      effect: read
      questions:
      - What messages have we sent to this user recently?
      - Can I filter a user's sent messages by channel and leave out blast campaigns?
      instructions:
      - text: Show messages sent to {email}.
        slots:
          email: query.email
      - text: List up to {limit} {messageMedium} messages sent to user {userId} since {startDateTime}.
        slots:
          limit: query.limit
          messageMedium: query.messageMedium
          userId: query.userId
          startDateTime: query.startDateTime
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/merge'].post
  update:
    x-apievangelist-phrasing:
      intent: Merge two users
      effect: write
      questions:
      - How do I merge a duplicate user into another profile?
      - Can I control how arrays are merged when combining two users?
      instructions:
      - text: Merge {sourceEmail} into {destinationEmail}.
        slots:
          sourceEmail: requestBody.sourceEmail
          destinationEmail: requestBody.destinationEmail
      - text: Merge user {sourceUserId} into user {destinationUserId} with array merge {arrayMerge}.
        slots:
          sourceUserId: requestBody.sourceUserId
          destinationUserId: requestBody.destinationUserId
          arrayMerge: requestBody.arrayMerge
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/registerBrowserToken'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a browser token for web push
      effect: write
      questions:
      - How do I register a browser so a user can receive web push?
      - Can I attach a web push token to a user by userId?
      instructions:
      - text: Register browser token {browserToken} for {email}.
        slots:
          browserToken: requestBody.browserToken
          email: requestBody.email
      - text: Save web push token {browserToken} for user {userId}.
        slots:
          browserToken: requestBody.browserToken
          userId: requestBody.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/registerDeviceToken'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a device token with merged device data
      effect: write
      questions:
      - Does registering a device token under /api merge device data fields?
      - Can I register a push device for a user identified by userId?
      instructions:
      - text: Register device {device} for {email}.
        slots:
          device: requestBody.device
          email: requestBody.email
      - text: Register /api device {device} for user {userId}, preferring userId {preferUserId}.
        slots:
          device: requestBody.device
          userId: requestBody.userId
          preferUserId: requestBody.preferUserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/unforget'].post
  update:
    x-apievangelist-phrasing:
      intent: Resume data collection for a forgotten user
      effect: write
      questions:
      - Can I start collecting data again for a user I forgot under GDPR?
      - Is deleted data restored when I unforget a user?
      instructions:
      - text: Unforget {email}.
        slots:
          email: requestBody.email
      - text: Resume data collection for user {userId}.
        slots:
          userId: requestBody.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/update'].post
  update:
    x-apievangelist-phrasing:
      intent: Update or create a user with merged fields
      effect: write
      questions:
      - Can I update a user's data fields and merge nested objects under /api?
      - Does updating a user create them if they don't exist?
      instructions:
      - text: Update {email} with data {dataFields}.
        slots:
          email: requestBody.email
          dataFields: requestBody.dataFields
      - text: Update /api user {userId} with {dataFields}, merging nested objects {mergeNestedObjects}.
        slots:
          userId: requestBody.userId
          dataFields: requestBody.dataFields
          mergeNestedObjects: requestBody.mergeNestedObjects
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/updateEmail'].post
  update:
    x-apievangelist-phrasing:
      intent: Change a user's email address
      effect: write
      questions:
      - How do I change the email address on a user profile?
      - Can I update an email for a user found by userId?
      instructions:
      - text: Change {currentEmail} to {newEmail}.
        slots:
          currentEmail: requestBody.currentEmail
          newEmail: requestBody.newEmail
      - text: Set user {currentUserId}'s email to {newEmail}.
        slots:
          currentUserId: requestBody.currentUserId
          newEmail: requestBody.newEmail
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/updateSubscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Overwrite a user's subscriptions
      effect: write
      questions:
      - How do I update which email lists and message types a user is subscribed to?
      - Can I unsubscribe a user from a whole channel?
      instructions:
      - text: Set {email}'s email lists to {emailListIds}.
        slots:
          email: requestBody.email
          emailListIds: requestBody.emailListIds
      - text: Unsubscribe {email} from message types {unsubscribedMessageTypeIds}.
        slots:
          email: requestBody.email
          unsubscribedMessageTypeIds: requestBody.unsubscribedMessageTypeIds
      - text: Unsubscribe user {userId} from channels {unsubscribedChannelIds}.
        slots:
          userId: requestBody.userId
          unsubscribedChannelIds: requestBody.unsubscribedChannelIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/{email}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user by email in the path
      effect: read
      questions:
      - Where can I pull up someone's profile when I know their email address?
      - What profile data is returned when I look up an email address?
      instructions:
      - text: Get the /api profile for {email}.
        slots:
          email: path.email
      - text: Fetch user {email} by path.
        slots:
          email: path.email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/users/{email}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user by email
      effect: destructive
      questions:
      - Does deleting a user by email under /api stop future data collection?
      - Can I delete a user profile by email address?
      instructions:
      - text: Delete the /api user {email}.
        slots:
          email: path.email
      - text: Remove user profile {email}.
        slots:
          email: path.email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/update'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a user profile (simple)
      effect: write
      questions:
      - Is there a plain /users/update call to create or update a profile?
      - Can I set data fields on a user with the basic endpoint?
      instructions:
      - text: Using /users/update, set {dataFields} on {email}.
        slots:
          dataFields: requestBody.dataFields
          email: requestBody.email
      - text: Update user {userId} with {dataFields} via the simple endpoint.
        slots:
          userId: requestBody.userId
          dataFields: requestBody.dataFields
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/bulkUpdate'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk update user profiles (simple)
      effect: write
      questions:
      - Can I update many profiles through the plain /users/bulkUpdate path?
      - Which basic call updates a batch of users at once?
      instructions:
      - text: Using /users/bulkUpdate, update users {users}.
        slots:
          users: requestBody.users
      - text: 'Bulk update these profiles with the simple endpoint: {users}.'
        slots:
          users: requestBody.users
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{email}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user by email (simple)
      effect: read
      questions:
      - Is there a plain /users endpoint keyed by email that returns a profile with subscription preferences?
      - Which basic endpoint looks up a user by email?
      instructions:
      - text: Get user {email} from the plain /users endpoint.
        slots:
          email: path.email
      - text: Show the full profile and subscriptions for {email} via the simple endpoint.
        slots:
          email: path.email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{email}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user by email (simple)
      effect: destructive
      questions:
      - Can I delete a user by email through the plain /users path?
      - Which basic call removes a user profile by email?
      instructions:
      - text: Delete user {email} using /users.
        slots:
          email: path.email
      - text: Remove profile {email} with the simple endpoint.
        slots:
          email: path.email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/byUserId/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user by userId (simple)
      effect: read
      questions:
      - Is there a plain /users/byUserId call that returns a profile with subscriptions?
      - Which basic endpoint looks up a user by userId?
      instructions:
      - text: Fetch the profile for user ID {userId} from the plain /users/byUserId path.
        slots:
          userId: path.userId
      - text: Show the full profile for user ID {userId} via the simple endpoint.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/byUserId/{userId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user by userId (simple)
      effect: destructive
      questions:
      - Can I delete a user by userId through the plain /users path?
      - Which basic call removes a profile by userId?
      instructions:
      - text: Delete user ID {userId} using /users/byUserId.
        slots:
          userId: path.userId
      - text: Erase the profile of user ID {userId} via the simple byUserId path.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/getFields'].get
  update:
    x-apievangelist-phrasing:
      intent: Get user fields and types (simple)
      effect: read
      questions:
      - Which user fields and data types are defined, via the plain /users/getFields path?
      - What type is each user field?
      instructions:
      - text: List user fields with their types from the plain /users endpoint.
      - text: Show each user field's data type.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/registerDeviceToken'].post
  update:
    x-apievangelist-phrasing:
      intent: Register an APNs or FCM device token (simple)
      effect: write
      questions:
      - Is there a basic /users/registerDeviceToken call that takes an email?
      - How do I register an APNs or FCM token so a user gets push?
      instructions:
      - text: Using /users/registerDeviceToken, register {device} for {email}.
        slots:
          device: requestBody.device
          email: requestBody.email
      - text: Save APNs or FCM device {device} for {email} via the simple endpoint.
        slots:
          device: requestBody.device
          email: requestBody.email
      method: generated
      generated: '2026-10-01'