# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Reference Segments API
  version: 1.0.0
extends: openapi/beehiiv-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: 7
- target: $.paths['/publications/{publicationId}/segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List a publication's segments
      effect: read
      questions:
      - What subscriber segments have I built?
      - Can I filter segments by type, like only manual or dynamic ones?
      instructions:
      - text: List segments on publication {publication}.
        slots:
          publication: path.publicationId
      - text: Show {type} segments on {publication}.
        slots:
          type: query.type
          publication: path.publicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/segments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a subscriber segment
      effect: write
      questions:
      - How do I build a segment from a list of email addresses?
      - Can I create a dynamic segment that filters subscribers by custom field values?
      instructions:
      - text: Create a segment named {name} on publication {publication} from {input}.
        slots:
          name: requestBody.name
          publication: path.publicationId
          input: requestBody.input
      - text: 'Build a new segment called {name} using this input: {input}.'
        slots:
          name: requestBody.name
          input: requestBody.input
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/segments/{segmentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one segment
      effect: read
      questions:
      - What is the status and size of a specific segment?
      - Can I look up a single segment by its ID?
      instructions:
      - text: Get segment {segment} on publication {publication}.
        slots:
          segment: path.segmentId
          publication: path.publicationId
      - text: Show the status and size of segment {segment} with {expand} expanded.
        slots:
          segment: path.segmentId
          expand: query.expand[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/segments/{segmentId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a segment
      effect: destructive
      questions:
      - How do I remove a segment I no longer need?
      - Does deleting a segment unsubscribe the people in it?
      instructions:
      - text: Delete segment {segment} from publication {publication}.
        slots:
          segment: path.segmentId
          publication: path.publicationId
      - text: Remove segment {segment} without affecting its subscribers.
        slots:
          segment: path.segmentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/segments/{segmentId}/recalculate'].put
  update:
    x-apievangelist-phrasing:
      intent: Recalculate a segment
      effect: write
      questions:
      - How do I refresh a segment so it reflects current subscriber data?
      - Can I force a segment's membership to be recomputed?
      instructions:
      - text: Recalculate segment {segment} on publication {publication}.
        slots:
          segment: path.segmentId
          publication: path.publicationId
      - text: Refresh the membership of segment {segment}.
        slots:
          segment: path.segmentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/segments/{segmentId}/members'].get
  update:
    x-apievangelist-phrasing:
      intent: List a segment's subscribers with full details
      effect: read
      questions:
      - Who is in a segment, with their full subscriber profiles?
      - Can I get segment members along with their custom fields and tags?
      instructions:
      - text: List the full subscriber records in segment {segment} on publication {publication}.
        slots:
          segment: path.segmentId
          publication: path.publicationId
      - text: Show the members of segment {segment} with {expand} included.
        slots:
          segment: path.segmentId
          expand: query.expand[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/segments/{segmentId}/results'].get
  update:
    x-apievangelist-phrasing:
      intent: List only the subscriber IDs in a segment
      effect: read
      questions:
      - Is there a lightweight way to get just the subscription IDs in a segment?
      - How can I count a segment's members without pulling full profiles?
      instructions:
      - text: Get just the subscription IDs in segment {segment} on {publication}.
        slots:
          segment: path.segmentId
          publication: path.publicationId
      - text: Count the subscribers in segment {segment} using only their IDs.
        slots:
          segment: path.segmentId
      method: generated
      generated: '2026-09-26'