API Evangelist conversational phrasing for Hint Health Membership API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Hint Health Membership API
  version: 1.0.0
extends: openapi/hint-health-membership-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: 9
- target: $.paths['/provider/memberships/{id}/bill'].post
  update:
    x-apievangelist-phrasing:
      intent: Bill a membership from a start date
      effect: write
      questions:
      - How do I generate a bill for a patient's membership starting on a specific date?
      - Can I trigger billing on a membership manually instead of waiting for the cycle?
      instructions:
      - text: Bill membership {id} starting {start_date}.
        slots:
          id: path.id
          start_date: requestBody.start_date
      - text: Run billing on membership {id} from {start_date} onward.
        slots:
          id: path.id
          start_date: requestBody.start_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/provider/memberships/{id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a patient membership
      effect: destructive
      questions:
      - How do I cancel a patient's membership with an end date and a reason?
      - Can I record a custom cancellation reason when a member leaves the practice?
      instructions:
      - text: Cancel membership {id} effective {end_date} because of {cancellation_reason}.
        slots:
          id: path.id
          end_date: requestBody.end_date
          cancellation_reason: requestBody.cancellation_reason
      - text: End membership {id} on {end_date} with reason {cancellation_reason} and note {cancellation_reason_other}.
        slots:
          id: path.id
          end_date: requestBody.end_date
          cancellation_reason: requestBody.cancellation_reason
          cancellation_reason_other: requestBody.cancellation_reason_other
      method: generated
      generated: '2026-10-01'
- target: $.paths['/provider/memberships/{id}/confirm'].post
  update:
    x-apievangelist-phrasing:
      intent: Confirm an unconfirmed membership
      effect: write
      questions:
      - How do I confirm a membership that is still waiting for confirmation?
      - What turns an unconfirmed membership into a confirmed one?
      instructions:
      - text: Confirm membership {id}.
        slots:
          id: path.id
      - text: Mark pending membership {id} as confirmed.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/provider/memberships'].get
  update:
    x-apievangelist-phrasing:
      intent: List the practice's memberships
      effect: read
      questions:
      - Which memberships does my practice have right now?
      - Can I list only memberships updated or created after a certain date?
      instructions:
      - text: List all memberships at the practice.
      - text: List memberships updated since {updated_at}.
        slots:
          updated_at: query.updated_at
      - text: Show memberships created on or after {created_at}.
        slots:
          created_at: query.created_at
      method: generated
      generated: '2026-10-01'
- target: $.paths['/provider/memberships'].post
  update:
    x-apievangelist-phrasing:
      intent: Enroll patients in a membership plan
      effect: write
      questions:
      - How do I enroll a patient in a membership plan with Hint?
      - Can I set a fixed monthly rate or registration fee when creating a membership?
      - What do I need to start a new membership for a family of patients?
      instructions:
      - text: Create a membership on plan {plan} for {membership_patients} starting {start_date}, billed every {period_in_months} months.
        slots:
          plan: requestBody.plan
          membership_patients: requestBody.membership_patients
          start_date: requestBody.start_date
          period_in_months: requestBody.period_in_months
      - text: Enroll {membership_patients} in plan {plan} from {start_date} for {period_in_months}-month periods at {fixed_period_rate_in_cents} cents.
        slots:
          membership_patients: requestBody.membership_patients
          plan: requestBody.plan
          start_date: requestBody.start_date
          period_in_months: requestBody.period_in_months
          fixed_period_rate_in_cents: requestBody.fixed_period_rate_in_cents
      method: generated
      generated: '2026-10-01'
- target: $.paths['/provider/memberships/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up one membership and its status
      effect: read
      questions:
      - What is the current status of a specific membership, active, unpaid or ended?
      - Can I see the enrollment status of one patient's membership?
      instructions:
      - text: Show membership {id}.
        slots:
          id: path.id
      - text: Get the status and enrollment details of membership {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/provider/memberships/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a membership record
      effect: destructive
      questions:
      - How do I delete a membership that was created by mistake?
      - Is deleting a membership different from cancelling it?
      instructions:
      - text: Delete membership {id}.
        slots:
          id: path.id
      - text: Permanently remove membership record {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/provider/memberships/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change an existing membership's plan or terms
      effect: write
      questions:
      - How do I switch an existing membership to a different plan?
      - Can I change the billing period or rate on a membership that already exists?
      instructions:
      - text: Update membership {id} to plan {plan} for {membership_patients} from {start_date} with {period_in_months}-month periods.
        slots:
          id: path.id
          plan: requestBody.plan
          membership_patients: requestBody.membership_patients
          start_date: requestBody.start_date
          period_in_months: requestBody.period_in_months
      - text: Set membership {id} to end {end_date} on plan {plan} for {membership_patients}, start {start_date}, {period_in_months}-month periods.
        slots:
          id: path.id
          end_date: requestBody.end_date
          plan: requestBody.plan
          membership_patients: requestBody.membership_patients
          start_date: requestBody.start_date
          period_in_months: requestBody.period_in_months
      method: generated
      generated: '2026-10-01'
- target: $.paths['/provider/memberships/new'].get
  update:
    x-apievangelist-phrasing:
      intent: Build a default membership draft for an owner
      effect: read
      questions:
      - Can I get a pre-filled default membership for a patient before actually creating it?
      - What defaults would a new membership have for a given owner?
      instructions:
      - text: Build a default membership template for owner {owner}.
        slots:
          owner: query.owner
      - text: Show the default new-membership values for patient {owner}.
        slots:
          owner: query.owner
      method: generated
      generated: '2026-10-01'