API Evangelist conversational phrasing for V1 Lytics 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 V1 Lytics Segment API
  version: 1.0.0
extends: openapi/lytics-segment-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: 13
- target: $.paths['/api/segment'].get
  update:
    x-apievangelist-phrasing:
      intent: List segments
      effect: read
      questions:
      - Which audience segments do I have on the user table?
      - Can I list only valid segments, or segments on the content table?
      instructions:
      - text: List all my segments.
      - text: 'Show segments on table {table} that are valid: {valid}.'
        slots:
          table: query.table
          valid: query.valid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/segment'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a segment from SegmentQL
      effect: write
      questions:
      - How do I create a new audience segment with a SegmentQL filter?
      - Can I build a segment of users with more than five visits in the last 30 days?
      instructions:
      - text: Create a new segment from this SegmentQL filter.
      - text: Save an audience segment with this filter and alias.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/segment/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a segment by id or slug
      effect: read
      questions:
      - Can I fetch a segment by its slug?
      - What's the definition of a particular segment?
      instructions:
      - text: Show segment {id}.
        slots:
          id: path.id
      - text: Fetch the definition of segment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/segment/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a segment
      effect: write
      questions:
      - Can I change the filter or description of an existing segment?
      - How do I edit a segment I've already saved?
      instructions:
      - text: Update segment {id}.
        slots:
          id: path.id
      - text: Change the filter and description of segment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/segment/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a segment
      effect: destructive
      questions:
      - Can I delete a single segment?
      - Is it possible to remove an audience segment I no longer need?
      instructions:
      - text: Delete segment {id}.
        slots:
          id: path.id
      - text: Remove audience segment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/segment/size'].post
  update:
    x-apievangelist-phrasing:
      intent: Size an unsaved SegmentQL query
      effect: read
      questions:
      - How many users would match a SegmentQL filter without saving it?
      - Is the segment sizing call rate limited?
      instructions:
      - text: Estimate the audience size for this SegmentQL filter.
      - text: Count how many users match this unsaved segment.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/segment/validate'].post
  update:
    x-apievangelist-phrasing:
      intent: Validate a segment query
      effect: read
      questions:
      - Can I check that a SegmentQL statement is valid before creating the segment?
      - Will my segment filter parse correctly?
      instructions:
      - text: Validate this SegmentQL statement.
      - text: Check this segment filter for errors.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/segment/sizes'].get
  update:
    x-apievangelist-phrasing:
      intent: Get sizes of several saved segments
      effect: read
      questions:
      - How many users are in each of several saved segments?
      - Can I get sizes for a batch of segment ids at once?
      instructions:
      - text: Get the sizes of segments {ids}.
        slots:
          ids: query.ids
      - text: Report how big saved segments {ids} are.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/segment/{segId}/scan'].get
  update:
    x-apievangelist-phrasing:
      intent: List the users in a segment
      effect: read
      questions:
      - Can I page through the users who are in a segment?
      - Can I sort segment members by a field or most recent visit?
      instructions:
      - text: List the users in segment {segId}.
        slots:
          segId: path.segId
      - text: Scan {limit} members of segment {segId} sorted by {sortfield}.
        slots:
          limit: query.limit
          segId: path.segId
          sortfield: query.sortfield
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/segment/{segId}/scan'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a batch of segments
      effect: destructive
      questions:
      - Can I delete many segments in one request?
      - Can I pass several segment ids to delete together?
      instructions:
      - text: Batch delete segments starting from {segId}.
        slots:
          segId: path.segId
      - text: Delete a batch of segments including {segId}.
        slots:
          segId: path.segId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/segment/{segId}/attribution'].get
  update:
    x-apievangelist-phrasing:
      intent: Get attribution for one segment
      effect: read
      questions:
      - What attribution data is there for a single segment?
      - Can I force a refresh of a segment's attribution?
      instructions:
      - text: Show attribution for segment {segId}.
        slots:
          segId: path.segId
      - text: 'Refresh and fetch attribution for segment {segId}: {refresh}.'
        slots:
          segId: path.segId
          refresh: query.refresh
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/segment/attribution'].get
  update:
    x-apievangelist-phrasing:
      intent: Get attribution for several segments
      effect: read
      questions:
      - Can I fetch attribution for a list of segments together?
      - Can I compare attribution across a batch of segment ids?
      instructions:
      - text: Get attribution for segments {ids}.
        slots:
          ids: query.ids
      - text: 'Compare attribution across segments {ids}, refreshing: {refresh}.'
        slots:
          ids: query.ids
          refresh: query.refresh
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/segment/{segId}/fieldinfo'].get
  update:
    x-apievangelist-phrasing:
      intent: Get field value info for a segment
      effect: read
      questions:
      - Which field values are common among users in one segment?
      - Can I limit segment field info to a few fields?
      instructions:
      - text: Show field info for segment {segId}.
        slots:
          segId: path.segId
      - text: Get values of fields {fields} within segment {segId}.
        slots:
          fields: query.fields
          segId: path.segId
      method: generated
      generated: '2026-10-01'