API Evangelist conversational phrasing for Third-party Segment API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Third-party Segment API
  version: 1.0.0
extends: openapi/talon-one-segment-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: 13
- target: $.paths['/segment/customer_profile/{customerProfileId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Upsert a customer profile via Segment (deprecated v1)
      effect: write
      questions:
      - Is the original v1 Segment customer profile upsert still supported?
      - What did the first Segment profile endpoint do with attributesInfo?
      instructions:
      - text: Upsert customer profile {customerProfileId} with attributes {attributes} via the deprecated v1 Segment endpoint on {destination-hostname}.
        slots:
          customerProfileId: path.customerProfileId
          attributes: requestBody.attributes
          destination-hostname: header.destination-hostname
      - text: Use the legacy v1 Segment profile upsert for {customerProfileId} on host {destination-hostname}.
        slots:
          customerProfileId: path.customerProfileId
          destination-hostname: header.destination-hostname
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/customer_profile_v2/{customerProfileId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Upsert a customer profile via Segment (deprecated v2)
      effect: write
      questions:
      - What was the deprecated customer_profile_v2 Segment endpoint used for?
      - Could the old v2 Segment upsert change a profile's audiences as well as attributes?
      instructions:
      - text: Upsert profile {customerProfileId} with audience changes {audiencesChanges} using the deprecated customer_profile_v2 Segment route on {destination-hostname}.
        slots:
          customerProfileId: path.customerProfileId
          audiencesChanges: requestBody.audiencesChanges
          destination-hostname: header.destination-hostname
      - text: Call the legacy customer_profile_v2 Segment upsert for {customerProfileId} on {destination-hostname}.
        slots:
          customerProfileId: path.customerProfileId
          destination-hostname: header.destination-hostname
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/v2/customer_profiles/{customerProfileId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update or create a customer profile from Segment
      effect: write
      questions:
      - What is the current way to sync a Segment identify call into a customer profile?
      - Can I skip attributes that don't exist yet when updating a profile from Segment?
      instructions:
      - text: Update customer profile {customerProfileId} from Segment with attributes {attributes} on {destination-hostname}.
        slots:
          customerProfileId: path.customerProfileId
          attributes: requestBody.attributes
          destination-hostname: header.destination-hostname
      - text: 'Sync Segment profile {customerProfileId} to {destination-hostname}, skipping unknown attributes: {skipNonExistingAttributes}.'
        slots:
          customerProfileId: path.customerProfileId
          destination-hostname: header.destination-hostname
          skipNonExistingAttributes: query.skipNonExistingAttributes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/customer_profiles/{customerProfileId}/audiences'].put
  update:
    x-apievangelist-phrasing:
      intent: Change one profile's audiences from Segment
      effect: write
      questions:
      - Can I add a single customer to Segment audiences using the Segment audience ID?
      - Does changing one profile's audiences from Segment trigger rules?
      instructions:
      - text: Update the audiences of profile {customerProfileId} with {data} from Segment on {destination-hostname}.
        slots:
          customerProfileId: path.customerProfileId
          data: requestBody.data
          destination-hostname: header.destination-hostname
      - text: Remove customer {customerProfileId} from the Segment audiences in {data} via {destination-hostname}.
        slots:
          customerProfileId: path.customerProfileId
          data: requestBody.data
          destination-hostname: header.destination-hostname
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/customer_profiles/audiences'].put
  update:
    x-apievangelist-phrasing:
      intent: Update audiences for many profiles from Segment
      effect: write
      questions:
      - Can I update audience membership for a batch of customers coming from Segment?
      - Are missing customer profiles created when I bulk update audiences from Segment?
      instructions:
      - text: Bulk update audiences for multiple profiles with {data} from Segment on {destination-hostname}.
        slots:
          data: requestBody.data
          destination-hostname: header.destination-hostname
      - text: Apply Segment audience changes {data} to many customer profiles via the v1 bulk route on {destination-hostname}.
        slots:
          data: requestBody.data
          destination-hostname: header.destination-hostname
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/v2/customer_profiles/audiences'].put
  update:
    x-apievangelist-phrasing:
      intent: Update audiences for many profiles by external ID
      effect: write
      questions:
      - Can I bulk update audiences using the audience ID from the third-party integration?
      - What's the v2 bulk route for Segment audience changes keyed by external ID?
      instructions:
      - text: Bulk update audiences by external audience ID with {data} on {destination-hostname}.
        slots:
          data: requestBody.data
          destination-hostname: header.destination-hostname
      - text: Apply externally identified audience changes {data} to many profiles via the v2 Segment route on {destination-hostname}.
        slots:
          data: requestBody.data
          destination-hostname: header.destination-hostname
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/event'].put
  update:
    x-apievangelist-phrasing:
      intent: Track a custom event from Segment (deprecated v1)
      effect: write
      questions:
      - How did the deprecated v1 Segment track event endpoint work?
      - Which fields did the original Segment event call require?
      instructions:
      - text: Send event {eventType} of type {type} for profile {customerProfileId} through the deprecated v1 Segment event route on {destination-hostname}.
        slots:
          eventType: requestBody.eventType
          type: requestBody.type
          customerProfileId: requestBody.customerProfileId
          destination-hostname: header.destination-hostname
      - text: Use the legacy Segment event endpoint to track {eventType} ({type}) for {customerProfileId} on {destination-hostname}.
        slots:
          eventType: requestBody.eventType
          type: requestBody.type
          customerProfileId: requestBody.customerProfileId
          destination-hostname: header.destination-hostname
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/v2/events'].put
  update:
    x-apievangelist-phrasing:
      intent: Track a custom event from Segment
      effect: write
      questions:
      - How do I trigger promotion rules from a Segment track call?
      - Does the custom event need to exist in the Campaign Manager before Segment sends it?
      instructions:
      - text: Track Segment event {eventType} for customer {customerProfileId} on {destination-hostname}.
        slots:
          eventType: requestBody.eventType
          customerProfileId: requestBody.customerProfileId
          destination-hostname: header.destination-hostname
      - text: Send event {eventType} with attributes {eventAttributes} from Segment to {destination-hostname}.
        slots:
          eventType: requestBody.eventType
          eventAttributes: requestBody.eventAttributes
          destination-hostname: header.destination-hostname
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/audiences'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an audience from Segment
      effect: write
      questions:
      - How do I bring a Segment audience over so I can target it in rules?
      - What does creating the first audience unlock in the Rule Builder?
      instructions:
      - text: Create audience {audienceName} with Segment ID {audienceId} on {destination-hostname}.
        slots:
          audienceName: requestBody.audienceName
          audienceId: requestBody.audienceId
          destination-hostname: header.destination-hostname
      - text: Register the new Segment audience {audienceId} named {audienceName} via {destination-hostname}.
        slots:
          audienceId: requestBody.audienceId
          audienceName: requestBody.audienceName
          destination-hostname: header.destination-hostname
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/audiences/{audienceId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename a Segment audience
      effect: write
      questions:
      - Can I rename an audience that came from Segment?
      - What is required to update an existing Segment audience?
      instructions:
      - text: Rename Segment audience {audienceId} to {audienceName} on {destination-hostname}.
        slots:
          audienceId: path.audienceId
          audienceName: requestBody.audienceName
          destination-hostname: header.destination-hostname
      - text: Update existing Segment audience {audienceId} with name {audienceName} via {destination-hostname}.
        slots:
          audienceId: path.audienceId
          audienceName: requestBody.audienceName
          destination-hostname: header.destination-hostname
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/audiences/{audienceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Segment audience
      effect: destructive
      questions:
      - Does deleting a Segment audience also remove its customer associations?
      - How can I drop an audience that Segment created?
      instructions:
      - text: Delete Segment audience {audienceId} on {destination-hostname}.
        slots:
          audienceId: path.audienceId
          destination-hostname: header.destination-hostname
      - text: Remove the Segment-synced audience {audienceId} and its memberships via {destination-hostname}.
        slots:
          audienceId: path.audienceId
          destination-hostname: header.destination-hostname
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/customer_sessions/{customerSessionId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a customer session from Segment (deprecated v1)
      effect: write
      questions:
      - What did the deprecated v1 Segment customer session endpoint accept?
      - Could the legacy Segment session update send its response to a callback URL?
      instructions:
      - text: Update session {customerSessionId} with {customerSession} via the deprecated v1 Segment session route on {destination-hostname}.
        slots:
          customerSessionId: path.customerSessionId
          customerSession: requestBody.customerSession
          destination-hostname: header.destination-hostname
      - text: Use the legacy Segment session endpoint for {customerSessionId} on {destination-hostname}, calling back to {X-Callback-Destination-URI}.
        slots:
          customerSessionId: path.customerSessionId
          destination-hostname: header.destination-hostname
          X-Callback-Destination-URI: header.X-Callback-Destination-URI
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/v2/customer_sessions/{customerSessionId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update or create a customer session from Segment
      effect: write
      questions:
      - How do I send a Segment cart to get the promotions that apply to it?
      - Can Segment session updates include coupon codes and loyalty cards?
      - Is it possible to receive the session response asynchronously at a callback URL?
      instructions:
      - text: Update Segment session {customerSessionId} with cart items {cartItems} on {destination-hostname}.
        slots:
          customerSessionId: path.customerSessionId
          cartItems: requestBody.cartItems
          destination-hostname: header.destination-hostname
      - text: Apply coupon codes {couponCodes} to Segment session {customerSessionId} for profile {profileId} on {destination-hostname}.
        slots:
          couponCodes: requestBody.couponCodes
          customerSessionId: path.customerSessionId
          profileId: requestBody.profileId
          destination-hostname: header.destination-hostname
      - text: Set Segment session {customerSessionId} to state {state} on {destination-hostname}.
        slots:
          customerSessionId: path.customerSessionId
          state: requestBody.state
          destination-hostname: header.destination-hostname
      method: generated
      generated: '2026-09-26'