# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Boom Segments API
  version: 1.0.0
extends: openapi/boom-ai-segments-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: 10
- target: $.paths['/api/v1/segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List my audience segments
      effect: read
      questions:
      - Which audience segments does my organization have?
      - Are archived segments included when I list my segments?
      instructions:
      - text: List my active segments.
      - text: Show the next page of segments after cursor {cursor}.
        slots:
          cursor: query.cursor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/segments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an audience segment
      effect: write
      questions:
      - How do I save a new audience of people based on attributes and events?
      - Can a new segment re-evaluate itself every day at a set hour?
      - Is a segment's slug changeable after I create it?
      instructions:
      - text: Create segment {name} with slug {slug} using filter {filterExpression}.
        slots:
          name: requestBody.name
          slug: requestBody.slug
          filterExpression: requestBody.filterExpression
      - text: Save a new segment {name} ({slug}) for {filterExpression} that evaluates daily at hour {dailyEvaluationHour}.
        slots:
          name: requestBody.name
          slug: requestBody.slug
          filterExpression: requestBody.filterExpression
          dailyEvaluationHour: requestBody.dailyEvaluationHour
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/segments/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a segment and its member count
      effect: read
      questions:
      - How many people are in a given segment right now?
      - What filter and settings does one segment use?
      instructions:
      - text: Show segment {slug}.
        slots:
          slug: path.slug
      - text: Get the live member count for segment {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/segments/{slug}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a segment
      effect: destructive
      questions:
      - What happens to journeys triggered by a segment when I delete it?
      - How do I remove a segment I no longer need?
      instructions:
      - text: Delete segment {slug}.
        slots:
          slug: path.slug
      - text: Remove segment {slug} and disconnect its journey triggers.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/segments/{slug}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a segment's filter or settings
      effect: write
      questions:
      - If I change a segment's filter, does its membership update right away?
      - Can I switch an existing segment to skip weekend evaluations?
      instructions:
      - text: Change the filter on segment {slug} to {filterExpression}.
        slots:
          slug: path.slug
          filterExpression: requestBody.filterExpression
      - text: Rename segment {slug} to {name}.
        slots:
          slug: path.slug
          name: requestBody.name
      - text: Set segment {slug} to re-evaluate on cadence {evaluationCadence}.
        slots:
          slug: path.slug
          evaluationCadence: requestBody.evaluationCadence
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/segments/{slug}/evaluate'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-evaluate a segment's membership now
      effect: write
      questions:
      - Can I refresh who is in a segment immediately instead of waiting for its schedule?
      - How long does an on-demand segment evaluation take?
      instructions:
      - text: Evaluate segment {slug} now.
        slots:
          slug: path.slug
      - text: Recompute membership for segment {slug} right away.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/segments/{slug}/members'].get
  update:
    x-apievangelist-phrasing:
      intent: List the people in a segment
      effect: read
      questions:
      - Who exactly is in a segment?
      - Can I page through a large segment's members?
      instructions:
      - text: List the members of segment {slug}.
        slots:
          slug: path.slug
      - text: Show {limit} members of segment {slug}.
        slots:
          slug: path.slug
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/segments/catalog'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the segment filter catalog
      effect: read
      questions:
      - What attributes, related data and computed variables can I filter a segment on?
      - Which operators work with each filterable field when building a segment?
      instructions:
      - text: Show me everything I can filter segments on.
      - text: Get the segment filter catalog with tokens and operators.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/segments/preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Count people matching a filter
      effect: read
      questions:
      - How many people would a filter match before I save it as a segment?
      - Can I size an audience without creating anything?
      instructions:
      - text: Preview how many people match {filterExpression}.
        slots:
          filterExpression: requestBody.filterExpression
      - text: 'Count the current audience for this filter: {filterExpression}.'
        slots:
          filterExpression: requestBody.filterExpression
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/segments/validate'].post
  update:
    x-apievangelist-phrasing:
      intent: Validate a segment filter
      effect: read
      questions:
      - Is my segment filter expression valid, and which field is wrong if not?
      - Can I check a filter against my live catalog without saving it?
      instructions:
      - text: Validate the segment filter {filterExpression}.
        slots:
          filterExpression: requestBody.filterExpression
      - text: 'Check this filter for errors before I save it: {filterExpression}.'
        slots:
          filterExpression: requestBody.filterExpression
      method: generated
      generated: '2026-09-26'