API Evangelist conversational phrasing for Clerk Com Phone Numbers API

# 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 Phone Numbers API
  version: 1.0.0
extends: openapi/clerk-com-phone-numbers-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: 11
- target: $.paths['/phone_numbers'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a phone number to a user from the backend
      effect: write
      questions:
      - How do I attach a phone number to a user from my server?
      - Can I create a phone number that is already verified and primary for a user?
      instructions:
      - text: Add phone number {phone_number} to user {user_id} via the backend.
        slots:
          phone_number: requestBody.phone_number
          user_id: requestBody.user_id
      - text: Create verified phone {phone_number} for user {user_id} and reserve it for second factor ({reserved_for_second_factor}).
        slots:
          phone_number: requestBody.phone_number
          user_id: requestBody.user_id
          reserved_for_second_factor: requestBody.reserved_for_second_factor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/phone_numbers/{phone_number_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a phone number from the backend
      effect: read
      questions:
      - How do I look up a phone number record by ID on the server?
      - Is a given phone number ID verified, according to the backend API?
      instructions:
      - text: Retrieve phone number {phone_number_id} with the backend API.
        slots:
          phone_number_id: path.phone_number_id
      - text: Look up phone record {phone_number_id} server-side.
        slots:
          phone_number_id: path.phone_number_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/phone_numbers/{phone_number_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user's phone number from the backend
      effect: destructive
      questions:
      - How do I remove a phone number from any user using my secret key?
      - Can an admin delete a user's phone number server-side?
      instructions:
      - text: Delete phone number {phone_number_id} using the backend API.
        slots:
          phone_number_id: path.phone_number_id
      - text: As an admin, remove phone record {phone_number_id} from its user.
        slots:
          phone_number_id: path.phone_number_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/phone_numbers/{phone_number_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a phone number from the backend
      effect: write
      questions:
      - How do I mark a user's phone number as verified or primary from my server?
      - Can the backend change whether a phone number is reserved for second factor?
      instructions:
      - text: Mark phone number {phone_number_id} as verified ({verified}) via the backend.
        slots:
          phone_number_id: path.phone_number_id
          verified: requestBody.verified
      - text: Set backend phone number {phone_number_id} as primary ({primary}).
        slots:
          phone_number_id: path.phone_number_id
          primary: requestBody.primary
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/phone_numbers'].get
  update:
    x-apievangelist-phrasing:
      intent: List the signed-in user's phone numbers
      effect: read
      questions:
      - What phone numbers are on my own account?
      - How does the frontend list the current user's phone numbers?
      instructions:
      - text: List my phone numbers.
      - text: Show the phone numbers on my account for session {_clerk_session_id}.
        slots:
          _clerk_session_id: query._clerk_session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/phone_numbers'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a phone number to my account
      effect: write
      questions:
      - How do I add a new phone number to my own profile?
      - Does a phone number I add myself need to be verified by SMS afterwards?
      instructions:
      - text: Add {phone_number} to my account.
        slots:
          phone_number: requestBody.phone_number
      - text: Add {phone_number} to my profile for two-factor use ({reserved_for_second_factor}).
        slots:
          phone_number: requestBody.phone_number
          reserved_for_second_factor: requestBody.reserved_for_second_factor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/phone_numbers/{phone_number_id}/attempt_verification'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify my phone number with the SMS code
      effect: write
      questions:
      - How do I confirm my phone number with the code I got by text?
      - What do I send to finish phone number verification?
      instructions:
      - text: Verify my phone number {phone_number_id} with code {code}.
        slots:
          phone_number_id: path.phone_number_id
          code: requestBody.code
      - text: Finish verifying my phone {phone_number_id} using the texted code {code}.
        slots:
          phone_number_id: path.phone_number_id
          code: requestBody.code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/phone_numbers/{phone_number_id}/prepare_verification'].post
  update:
    x-apievangelist-phrasing:
      intent: Text a verification code to my phone
      effect: write
      questions:
      - How do I get an SMS verification code sent to a phone number I just added?
      - Can I resend the phone verification text?
      instructions:
      - text: Send a verification SMS to my phone number {phone_number_id} using strategy {strategy}.
        slots:
          phone_number_id: path.phone_number_id
          strategy: requestBody.strategy
      - text: Resend the SMS code for my phone {phone_number_id} with strategy {strategy}.
        slots:
          phone_number_id: path.phone_number_id
          strategy: requestBody.strategy
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/phone_numbers/{phone_number_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one of my phone numbers
      effect: read
      questions:
      - How do I see the details of one phone number on my account?
      - Is my phone number marked as my default second factor?
      instructions:
      - text: Show my phone number {phone_number_id}.
        slots:
          phone_number_id: path.phone_number_id
      - text: Get the properties of my phone {phone_number_id}.
        slots:
          phone_number_id: path.phone_number_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/phone_numbers/{phone_number_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a phone number from my account
      effect: destructive
      questions:
      - How do I delete a phone number from my own profile?
      - Can I remove an old phone number I no longer use from my account?
      instructions:
      - text: Remove phone number {phone_number_id} from my account.
        slots:
          phone_number_id: path.phone_number_id
      - text: Delete my old phone number {phone_number_id}.
        slots:
          phone_number_id: path.phone_number_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/phone_numbers/{phone_number_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change settings on my phone number
      effect: write
      questions:
      - How do I make one of my phone numbers my default second factor?
      - Can I stop using my phone number for two-step verification?
      instructions:
      - text: Make my phone number {phone_number_id} my default second factor ({default_second_factor}).
        slots:
          phone_number_id: path.phone_number_id
          default_second_factor: requestBody.default_second_factor
      - text: Set my phone {phone_number_id} reserved for second factor to {reserved_for_second_factor}.
        slots:
          phone_number_id: path.phone_number_id
          reserved_for_second_factor: requestBody.reserved_for_second_factor
      method: generated
      generated: '2026-09-26'