# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Segments API
  version: 1.0.0
extends: openapi/activecampaign-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: 6
- target: $.paths['/segmentsV2'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a contact segment
      effect: write
      questions:
      - How do I build a new segment of contacts from conditions?
      - Can I create a segment through the API that the segment builder understands?
      instructions:
      - text: 'Create a segment with this definition: {data}.'
        slots:
          data: requestBody.data
      - text: Build a new contact segment.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segmentsV2/{segmentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a segment's current definition
      effect: read
      questions:
      - What conditions make up a segment right now?
      - Can I fetch the current definition of a segment by ID?
      instructions:
      - text: Show segment {segmentId}.
        slots:
          segmentId: path.segmentId
      - text: Get the current conditions of segment {segmentId}.
        slots:
          segmentId: path.segmentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segmentsV2/{segmentId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a segment
      effect: write
      questions:
      - Can I change the conditions of an existing segment?
      - How do I edit a segment I already built?
      instructions:
      - text: Update segment {segmentId} with definition {data}.
        slots:
          segmentId: path.segmentId
          data: requestBody.data
      - text: Edit the conditions on segment {segmentId}.
        slots:
          segmentId: path.segmentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segmentsV2/{segmentId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a segment and its history
      effect: destructive
      questions:
      - What happens to a segment's past versions when I delete it?
      - How do I permanently remove a segment?
      instructions:
      - text: Delete segment {segmentId} including its historic versions.
        slots:
          segmentId: path.segmentId
      - text: Remove segment {segmentId} entirely.
        slots:
          segmentId: path.segmentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segmentsV2/{segmentId}/createdDate/{timestamp}'].get
  update:
    x-apievangelist-phrasing:
      intent: See a segment as it was at a past time
      effect: read
      questions:
      - What did a segment's conditions look like last month?
      - Can I view an older version of a segment at a specific timestamp?
      instructions:
      - text: Show segment {segmentId} as it existed at {timestamp}.
        slots:
          segmentId: path.segmentId
          timestamp: path.timestamp
      - text: Get the historic definition of segment {segmentId} from {timestamp}.
        slots:
          segmentId: path.segmentId
          timestamp: path.timestamp
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segmentsV2/{segmentId}/createdDate/{timestamp}'].put
  update:
    x-apievangelist-phrasing:
      intent: Revert a segment to an earlier version
      effect: write
      questions:
      - Can I undo changes to a segment by rolling it back?
      - How do I restore a segment to how it looked on a past date?
      instructions:
      - text: Revert segment {segmentId} to its definition at {timestamp}.
        slots:
          segmentId: path.segmentId
          timestamp: path.timestamp
      - text: Roll back segment {segmentId} to the version from {timestamp}.
        slots:
          segmentId: path.segmentId
          timestamp: path.timestamp
      method: generated
      generated: '2026-09-26'