# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Platform Functions Custom Segments API
  version: 1.0.0
extends: openapi/punchh-custom-segments-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: 10
- target: $.paths['/api2/dashboard/custom_segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List all custom segments
      effect: read
      questions:
      - What custom segments has my business created?
      - Can I see every custom guest list we've built?
      instructions:
      - text: List all of our custom segments.
      - text: Show the custom segments, including segment {ID}.
        slots:
          ID: path.ID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/custom_segments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an empty custom segment
      effect: write
      questions:
      - How do I create a new custom segment to hold a hand-picked list of guests?
      - Are users added at the time a custom segment is created?
      instructions:
      - text: Create a custom segment named {name}.
        slots:
          name: requestBody.name
      - text: Make a new custom segment {name} described as {description}.
        slots:
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/custom_segments'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom segment
      effect: destructive
      questions:
      - How do I permanently remove a custom segment we no longer use?
      - Can a deleted custom segment be recovered?
      instructions:
      - text: Delete custom segment {custom_segment_id}.
        slots:
          custom_segment_id: query.custom_segment_id
      - text: Remove the custom segment {custom_segment_id} from the database.
        slots:
          custom_segment_id: query.custom_segment_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/custom_segments'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or redescribe a custom segment
      effect: write
      questions:
      - Can I change the name or description of an existing custom segment?
      - What fields of a custom segment can be edited?
      instructions:
      - text: Rename custom segment {custom_segment_id} to {name}.
        slots:
          custom_segment_id: query.custom_segment_id
          name: query.name
      - text: Update the description of custom segment {custom_segment_id} to {description}.
        slots:
          custom_segment_id: query.custom_segment_id
          description: query.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/custom_segments/members'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether a guest is in a custom segment
      effect: read
      questions:
      - Is a particular guest already a member of this custom segment?
      - Can I check segment membership by email instead of user ID?
      instructions:
      - text: Check if {email} belongs to custom segment {custom_segment_id}.
        slots:
          email: query.email
          custom_segment_id: query.custom_segment_id
      - text: Is user {user_id} in custom segment {custom_segment_id}? Look it up.
        slots:
          user_id: query.user_id
          custom_segment_id: query.custom_segment_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/custom_segments/members'].post
  update:
    x-apievangelist-phrasing:
      intent: Add one guest to a custom segment
      effect: write
      questions:
      - How do I add a single guest to a custom segment?
      - If I pass both an email and a user ID when adding a guest, which one wins?
      instructions:
      - text: Add {email} to custom segment {custom_segment_id}.
        slots:
          email: requestBody.email
          custom_segment_id: requestBody.custom_segment_id
      - text: Put user {user_id} into custom segment {custom_segment_id}.
        slots:
          user_id: requestBody.user_id
          custom_segment_id: requestBody.custom_segment_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/custom_segments/members'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove one guest from a custom segment
      effect: destructive
      questions:
      - How do I take a single guest out of a custom segment?
      - Can I remove someone from a segment using just their email?
      instructions:
      - text: Remove {email} from custom segment {custom_segment_id}.
        slots:
          email: query.email
          custom_segment_id: query.custom_segment_id
      - text: Take user {user_id} out of custom segment {custom_segment_id}.
        slots:
          user_id: query.user_id
          custom_segment_id: query.custom_segment_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/custom_segments/members/bulk_add'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk add guests to a segment from a CSV
      effect: write
      questions:
      - Can I upload a CSV of user IDs and emails to fill a custom segment?
      - What columns does the bulk add CSV file need?
      instructions:
      - text: Upload CSV {bulk_guest_activity_file} to add users to custom segment {custom_segment_id} as job {name}.
        slots:
          bulk_guest_activity_file: requestBody.bulk_guest_activity_file
          custom_segment_id: requestBody.custom_segment_id
          name: requestBody.name
      - text: Run a bulk CSV add named {name} into segment {custom_segment_id} from {bulk_guest_activity_file}.
        slots:
          name: requestBody.name
          custom_segment_id: requestBody.custom_segment_id
          bulk_guest_activity_file: requestBody.bulk_guest_activity_file
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/custom_segments/members/bulk_remove'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk remove guests from a segment via CSV
      effect: destructive
      questions:
      - How do I remove many guests from a custom segment at once with a file?
      - Does the bulk removal CSV use the same user_id and email columns?
      instructions:
      - text: Remove the users in CSV {bulk_guest_activity_file} from custom segment {custom_segment_id} as job {name}.
        slots:
          bulk_guest_activity_file: requestBody.bulk_guest_activity_file
          custom_segment_id: requestBody.custom_segment_id
          name: requestBody.name
      - text: Bulk-remove guests from segment {custom_segment_id} using file {bulk_guest_activity_file}, job name {name}.
        slots:
          custom_segment_id: requestBody.custom_segment_id
          bulk_guest_activity_file: requestBody.bulk_guest_activity_file
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api2/dashboard/custom_segments/members/add_users'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk add guests to a list segment by ID or email
      effect: write
      questions:
      - Can I add a list of emails and user IDs to a custom list segment without uploading a file?
      - Which identifiers come back as invalid when adding users in bulk, and can it run asynchronously?
      instructions:
      - text: Add these users {user_identifiers} to custom list segment {custom_segment_id}.
        slots:
          user_identifiers: requestBody.user_identifiers
          custom_segment_id: requestBody.custom_segment_id
      - text: Asynchronously add {user_identifiers} to list segment {custom_segment_id} using method {bulk_method}.
        slots:
          user_identifiers: requestBody.user_identifiers
          custom_segment_id: requestBody.custom_segment_id
          bulk_method: requestBody.bulk_method
      method: generated
      generated: '2026-10-01'