API Evangelist conversational phrasing for Clerk Frontend Sign Ins 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 Frontend Sign Ins API
  version: 1.0.0
extends: openapi/clerk-com-sign-ins-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['/v1/client/sign_ins'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a sign-in on the current client
      effect: write
      questions:
      - How do I start signing a user in with their email or username?
      - Can I identify and verify a sign-in in one request using a password?
      - Is there a way to sign in with a ticket or an OAuth redirect?
      instructions:
      - text: Start a sign-in for {identifier} with the {strategy} strategy.
        slots:
          identifier: requestBody.identifier
          strategy: requestBody.strategy
      - text: Sign in {identifier} using password {password}.
        slots:
          identifier: requestBody.identifier
          password: requestBody.password
      - text: Begin a sign-in from invitation ticket {ticket}.
        slots:
          ticket: requestBody.ticket
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sign_ins/{sign_in_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a sign-in attempt
      effect: read
      questions:
      - What status is my in-progress sign-in attempt in?
      - Can I check whether a sign-in still needs a second factor?
      instructions:
      - text: Get sign-in attempt {sign_in_id}.
        slots:
          sign_in_id: path.sign_in_id
      - text: Show the current status of sign-in {sign_in_id}.
        slots:
          sign_in_id: path.sign_in_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sign_ins/{sign_in_id}/reset_password'].post
  update:
    x-apievangelist-phrasing:
      intent: Reset the password during sign-in
      effect: write
      questions:
      - How does a user set a new password while signing in after a reset code?
      - Can resetting the password also sign the user out of their other sessions?
      instructions:
      - text: Reset the password on sign-in {sign_in_id} to {password}.
        slots:
          sign_in_id: path.sign_in_id
          password: requestBody.password
      - text: Set new password {password} for sign-in {sign_in_id} and end other sessions.
        slots:
          sign_in_id: path.sign_in_id
          password: requestBody.password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sign_ins/{sign_in_id}/prepare_first_factor'].post
  update:
    x-apievangelist-phrasing:
      intent: Send the first-factor code or link for a sign-in
      effect: write
      questions:
      - How do I send a one-time code to the user's email or phone during sign-in?
      - Can the first sign-in step use a passkey or an email link instead of a code?
      instructions:
      - text: Send a first-factor code for sign-in {sign_in_id} using {strategy}.
        slots:
          sign_in_id: path.sign_in_id
          strategy: requestBody.strategy
      - text: Prepare first-factor {strategy} for sign-in {sign_in_id} to email {email_address_id}.
        slots:
          sign_in_id: path.sign_in_id
          strategy: requestBody.strategy
          email_address_id: requestBody.email_address_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sign_ins/{sign_in_id}/attempt_first_factor'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit the first-factor code or password
      effect: write
      questions:
      - How do I complete the first sign-in step with the code the user received?
      - Can a user pass the first factor with just their password?
      instructions:
      - text: Attempt first factor on sign-in {sign_in_id} with {strategy} code {code}.
        slots:
          sign_in_id: path.sign_in_id
          strategy: requestBody.strategy
          code: requestBody.code
      - text: Verify sign-in {sign_in_id} with {strategy} and password {password}.
        slots:
          sign_in_id: path.sign_in_id
          strategy: requestBody.strategy
          password: requestBody.password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sign_ins/{sign_in_id}/prepare_second_factor'].post
  update:
    x-apievangelist-phrasing:
      intent: Send the second-factor code for a sign-in
      effect: write
      questions:
      - How do I send an MFA code by SMS once a sign-in needs a second factor?
      - What starts the two-factor step for a sign-in that says needs_second_factor?
      instructions:
      - text: Send a second-factor code for sign-in {sign_in_id} to phone {phone_number_id}.
        slots:
          sign_in_id: path.sign_in_id
          phone_number_id: requestBody.phone_number_id
      - text: Prepare the MFA step for sign-in {sign_in_id} using {strategy}.
        slots:
          sign_in_id: path.sign_in_id
          strategy: requestBody.strategy
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/client/sign_ins/{sign_in_id}/attempt_second_factor'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit the second-factor code
      effect: write
      questions:
      - How do I finish two-factor sign-in with the user's TOTP or SMS code?
      - Which strategy do I pass along with the code to clear the second factor?
      instructions:
      - text: Complete MFA on sign-in {sign_in_id} with code {code}.
        slots:
          sign_in_id: path.sign_in_id
          code: requestBody.code
      - text: Attempt second factor {strategy} for sign-in {sign_in_id} using {code}.
        slots:
          sign_in_id: path.sign_in_id
          strategy: requestBody.strategy
          code: requestBody.code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/tickets/accept'].get
  update:
    x-apievangelist-phrasing:
      intent: Accept a ticket link such as an invitation
      effect: read
      questions:
      - What happens when a user clicks a ticket link from an invitation email?
      - How is a ticket JWT turned into a redirect with the ticket attached?
      instructions:
      - text: Accept ticket {ticket}.
        slots:
          ticket: query.ticket
      - text: Process the invitation ticket {ticket} and follow its redirect.
        slots:
          ticket: query.ticket
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/verify'].get
  update:
    x-apievangelist-phrasing:
      intent: Complete an email link verification
      effect: write
      questions:
      - How is an email magic link verified when the user clicks it?
      - What does the email link token get checked against?
      instructions:
      - text: Verify the email link with token {token}.
        slots:
          token: query.token
      - text: Complete magic link verification for token {token}.
        slots:
          token: query.token
      method: generated
      generated: '2026-09-26'