# 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 Sign Ups API
  version: 1.0.0
extends: openapi/clerk-com-signups-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: 7
- target: $.paths['/sign_ups/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a sign-up from the backend
      effect: read
      questions:
      - Can my server look up a sign-up attempt by its ID?
      - What fields has a user filled in on a sign-up so far, seen from the backend?
      instructions:
      - text: Retrieve sign-up {id} using the backend API.
        slots:
          id: path.id
      - text: Show the server-side details of sign-up {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/sign_ups/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Set a sign-up's external ID or custom action
      effect: write
      questions:
      - How do I attach my own external ID to a sign-up from my backend?
      - Can the backend mark a sign-up's custom action as done?
      instructions:
      - text: Set external ID {external_id} on sign-up {id}.
        slots:
          external_id: requestBody.external_id
          id: path.id
      - text: Mark the custom action complete on sign-up {id} from the backend.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/client/sign_ups'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a sign-up on the current client
      effect: write
      questions:
      - How do I register a new user with email and password?
      - Can a sign-up be started from an invitation ticket or a web3 wallet?
      - Does sign-up support capturing legal acceptance and a captcha token?
      instructions:
      - text: Sign up {email_address} with password {password}.
        slots:
          email_address: requestBody.email_address
          password: requestBody.password
      - text: Create a sign-up for {first_name} {last_name} with username {username}.
        slots:
          first_name: requestBody.first_name
          last_name: requestBody.last_name
          username: requestBody.username
      - text: Start a sign-up from invitation ticket {ticket}.
        slots:
          ticket: requestBody.ticket
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/client/sign_ups/{sign_up_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the current client's sign-up
      effect: read
      questions:
      - Which fields are still missing on my in-progress sign-up?
      - Can the browser fetch its own sign-up by ID?
      instructions:
      - text: Get my sign-up {sign_up_id}.
        slots:
          sign_up_id: path.sign_up_id
      - text: Show missing requirements on sign-up {sign_up_id}.
        slots:
          sign_up_id: path.sign_up_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/client/sign_ups/{sign_up_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Add details to an in-progress sign-up
      effect: write
      questions:
      - How do I add a phone number or username to a sign-up already started?
      - Can I fill in missing fields on a sign-up before verifying it?
      instructions:
      - text: Add phone number {phone_number} to sign-up {sign_up_id}.
        slots:
          phone_number: requestBody.phone_number
          sign_up_id: path.sign_up_id
      - text: Set username {username} on in-progress sign-up {sign_up_id}.
        slots:
          username: requestBody.username
          sign_up_id: path.sign_up_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/client/sign_ups/{sign_up_id}/prepare_verification'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a verification code for a sign-up
      effect: write
      questions:
      - How do I send the new user a code to verify their email during sign-up?
      - Can sign-up verification use a phone code or an email link?
      instructions:
      - text: Send a {strategy} verification for sign-up {sign_up_id}.
        slots:
          strategy: requestBody.strategy
          sign_up_id: path.sign_up_id
      - text: Email a verification code for sign-up {sign_up_id}.
        slots:
          sign_up_id: path.sign_up_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/client/sign_ups/{sign_up_id}/attempt_verification'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a sign-up verification code
      effect: write
      questions:
      - How do I complete sign-up with the code the user received?
      - What does a sign-up need to verify a web3 wallet signature?
      instructions:
      - text: Verify sign-up {sign_up_id} with code {code}.
        slots:
          sign_up_id: path.sign_up_id
          code: requestBody.code
      - text: Attempt {strategy} verification on sign-up {sign_up_id} using {code}.
        slots:
          strategy: requestBody.strategy
          sign_up_id: path.sign_up_id
          code: requestBody.code
      method: generated
      generated: '2026-10-01'