API Evangelist conversational phrasing for Knock 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 Knock Users API
  version: 1.0.0
extends: openapi/knock-app-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: 18
- target: $.paths['/v1/users/{user_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user
      effect: read
      questions:
      - How do I look up a user's profile and contact details?
      - Can I fetch one recipient by their user ID?
      instructions:
      - text: Get user {user_id}.
        slots:
          user_id: path.user_id
      - text: Show the profile of user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update a user
      effect: write
      questions:
      - How do I add a new recipient with their email and phone number?
      - Are a user's existing properties merged or overwritten when I identify them again?
      instructions:
      - text: Identify user {user_id} with email {email}.
        slots:
          user_id: path.user_id
          email: requestBody.email
      - text: Update user {user_id}'s phone number to {phone_number} and timezone to {timezone}.
        slots:
          user_id: path.user_id
          phone_number: requestBody.phone_number
          timezone: requestBody.timezone
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user and their data
      effect: destructive
      questions:
      - How do I permanently delete a user and all their notification data?
      - Can a deleted user be restored?
      instructions:
      - text: Delete user {user_id}.
        slots:
          user_id: path.user_id
      - text: Permanently erase user {user_id} and their data.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/preferences/{id}/categories/{key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update one category in a user's preferences (deprecated)
      effect: write
      questions:
      - Can I still change a single category preference for a user through the deprecated endpoint?
      - How do I opt a user out of one notification category?
      instructions:
      - text: Turn off category {key} in user {user_id}'s preference set {id} using the deprecated single-category endpoint.
        slots:
          user_id: path.user_id
          id: path.id
          key: path.key
      - text: Update the single category {key} for user {user_id} in preference set {id}.
        slots:
          user_id: path.user_id
          id: path.id
          key: path.key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/merge'].post
  update:
    x-apievangelist-phrasing:
      intent: Merge two users into one
      effect: write
      questions:
      - How do I combine a duplicate user record into the main one?
      - Which user survives when two users are merged?
      instructions:
      - text: Merge user {from_user_id} into user {user_id}.
        slots:
          from_user_id: requestBody.from_user_id
          user_id: path.user_id
      - text: Fold duplicate {from_user_id} into {user_id}.
        slots:
          from_user_id: requestBody.from_user_id
          user_id: path.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/bulk/preferences'].post
  update:
    x-apievangelist-phrasing:
      intent: Set preferences for many users
      effect: write
      questions:
      - How do I apply the same preference set to thousands of users?
      - Can I bulk set per-tenant preferences for many users?
      instructions:
      - text: Set preferences {preferences} for users {user_ids}.
        slots:
          preferences: requestBody.preferences
          user_ids: requestBody.user_ids
      - text: 'Apply preference set {preferences} to these users in bulk: {user_ids}.'
        slots:
          preferences: requestBody.preferences
          user_ids: requestBody.user_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/bulk/identify'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update many users at once
      effect: write
      questions:
      - How do I import up to 1,000 users in one request?
      - Can I sync users with channel data in bulk?
      instructions:
      - text: Bulk identify users {users}.
        slots:
          users: requestBody.users
      - text: 'Create or update this batch of recipients: {users}.'
        slots:
          users: requestBody.users
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/preferences/{id}/workflows'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a user's workflow preferences (deprecated)
      effect: write
      questions:
      - How do I replace every workflow opt-in in a user's preference set with the deprecated endpoint?
      - Can a user opt out of several workflows in one update?
      instructions:
      - text: Replace the workflows section of user {user_id}'s preference set {id}.
        slots:
          user_id: path.user_id
          id: path.id
      - text: Update every workflow opt-in at once for user {user_id} in preference set {id}.
        slots:
          user_id: path.user_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/preferences/{id}/categories'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a user's category preferences (deprecated)
      effect: write
      questions:
      - How do I replace a user's category preferences all at once?
      - Can I set every category opt-in for a user in one call?
      instructions:
      - text: Replace the categories section of user {user_id}'s preference set {id}.
        slots:
          user_id: path.user_id
          id: path.id
      - text: Update every category opt-in at once for user {user_id} in preference set {id}.
        slots:
          user_id: path.user_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/bulk/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete many users at once
      effect: destructive
      questions:
      - How do I permanently delete a batch of users?
      - How many users can I delete in a single bulk request?
      instructions:
      - text: Bulk delete users {user_ids}.
        slots:
          user_ids: requestBody.user_ids
      - text: 'Permanently erase these users at once: {user_ids}.'
        slots:
          user_ids: requestBody.user_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/preferences/{id}/channel_types/{type}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update one channel type in a user's preferences (deprecated)
      effect: write
      questions:
      - How do I turn off only SMS for a user?
      - Can I toggle a single channel type for a user without touching others?
      instructions:
      - text: Disable channel type {type} in user {user_id}'s preference set {id}.
        slots:
          user_id: path.user_id
          id: path.id
          type: path.type
      - text: Update only the {type} channel type setting for user {user_id} in preference set {id}.
        slots:
          user_id: path.user_id
          id: path.id
          type: path.type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/preferences'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's preference sets
      effect: read
      questions:
      - Which preference sets does a user have, including per-tenant ones?
      - Can I see all of a user's notification preferences?
      instructions:
      - text: List preference sets for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Show every preference set stored for user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users
      effect: read
      questions:
      - Which users exist in this environment?
      - How many users come back per page by default?
      instructions:
      - text: List all users.
      - text: List users including {include}, {page_size} per page.
        slots:
          include: query.include[]
          page_size: query.page_size
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/preferences/{id}/workflows/{key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update one workflow in a user's preferences (deprecated)
      effect: write
      questions:
      - How do I opt a user out of a single workflow?
      - Can I change one workflow preference for a user and leave the rest?
      instructions:
      - text: Turn off workflow {key} in user {user_id}'s preference set {id}.
        slots:
          user_id: path.user_id
          id: path.id
          key: path.key
      - text: Update just the {key} workflow preference for user {user_id} in preference set {id}.
        slots:
          user_id: path.user_id
          id: path.id
          key: path.key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/preferences/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one of a user's preference sets
      effect: read
      questions:
      - How do I read a user's default preference set?
      - Can I get a user's preferences for a specific tenant?
      instructions:
      - text: Get preference set {id} for user {user_id}.
        slots:
          user_id: path.user_id
          id: path.id
      - text: Show user {user_id}'s {id} preferences for tenant {tenant}.
        slots:
          user_id: path.user_id
          id: path.id
          tenant: query.tenant
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/preferences/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace or merge a user's preference set
      effect: write
      questions:
      - How do I save all of a user's notification preferences in one call?
      - Can I merge new preferences rather than replacing the whole set?
      instructions:
      - text: Update preference set {id} for user {user_id}.
        slots:
          user_id: path.user_id
          id: path.id
      - text: Set user {user_id}'s {id} preferences with channel types {channel_types}.
        slots:
          user_id: path.user_id
          id: path.id
          channel_types: requestBody.channel_types
      - text: Merge into user {user_id}'s preference set {id} using strategy {strategy}.
        slots:
          user_id: path.user_id
          id: path.id
          strategy: requestBody.__persistence_strategy__
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/preferences/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user's preference set
      effect: destructive
      questions:
      - How do I remove a preference set from a user entirely?
      - Can I unset a user's per-tenant preferences?
      instructions:
      - text: Delete preference set {id} for user {user_id}.
        slots:
          user_id: path.user_id
          id: path.id
      - text: Unset user {user_id}'s {id} preferences.
        slots:
          user_id: path.user_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/users/{user_id}/preferences/{id}/channel_types'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a user's channel type preferences (deprecated)
      effect: write
      questions:
      - How do I set every channel type preference for a user at once?
      - Can I replace a user's email, SMS and push settings together?
      instructions:
      - text: Replace the channel types section of user {user_id}'s preference set {id}.
        slots:
          user_id: path.user_id
          id: path.id
      - text: Update every channel type setting at once for user {user_id} in preference set {id}.
        slots:
          user_id: path.user_id
          id: path.id
      method: generated
      generated: '2026-10-01'