# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Attentive API V2 Segments API
  version: 1.0.0
extends: openapi/attentive-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['/v2/bulk/segments/members'].post
  update:
    x-apievangelist-phrasing:
      intent: Add members to a segment in bulk
      effect: write
      questions:
      - How can I load up to 10,000 people into an existing segment at once?
      - Which identifiers can I use to add members to a segment in bulk?
      - Does adding segment members in bulk give me a job ID to track progress?
      instructions:
      - text: Queue a bulk add of {members} into segment {externalId}.
        slots:
          members: requestBody.members
          externalId: requestBody.externalId
      - text: Put this customer list into the {externalId} segment as new members.
        slots:
          externalId: requestBody.externalId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/bulk/segments/members'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove members from a segment in bulk
      effect: destructive
      questions:
      - How can I pull a list of subscribers out of a segment all at once?
      - What identifiers do I need to remove members from a segment in bulk?
      - Do I get a batch job ID back when I bulk remove segment members?
      instructions:
      - text: Queue a bulk removal of {members} from segment {externalId}.
        slots:
          members: requestBody.members
          externalId: requestBody.externalId
      - text: Take this customer list out of the {externalId} segment.
        slots:
          externalId: requestBody.externalId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List segments
      effect: read
      questions:
      - How do I list all my Attentive segments?
      - Can I find segments whose name contains a word?
      - Which segments were updated since last Monday?
      instructions:
      - text: List segments with names matching {name}.
        slots:
          name: query.name
      - text: Show segments updated since {updatedSince}, up to {limit} results.
        slots:
          updatedSince: query.updatedSince
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/segments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a segment
      effect: write
      questions:
      - How do I create a new empty segment for a manual audience upload?
      - Can I give a new segment my own external ID when creating it?
      instructions:
      - text: Create a segment named {name}.
        slots:
          name: requestBody.name
      - text: Create segment {name} with external ID {externalId} and description {description}.
        slots:
          name: requestBody.name
          externalId: requestBody.externalId
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/segments/external/{externalId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a segment by external ID
      effect: read
      questions:
      - How do I fetch the details of one segment using its external ID?
      - What does a single segment record look like when retrieved?
      instructions:
      - text: Get segment {externalId}.
        slots:
          externalId: path.externalId
      - text: Show me the details of the segment with external ID {externalId}.
        slots:
          externalId: path.externalId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/segments/external/{externalId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive a segment
      effect: destructive
      questions:
      - How do I archive a segment I no longer need?
      - Can an archived segment be restored later?
      instructions:
      - text: Archive segment {externalId}.
        slots:
          externalId: path.externalId
      - text: Soft delete the segment with external ID {externalId}.
        slots:
          externalId: path.externalId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/segments/external/{externalId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or redescribe a segment
      effect: write
      questions:
      - How do I rename an existing segment?
      - Can I change only a segment's description without touching its name?
      instructions:
      - text: Rename segment {externalId} to {name}.
        slots:
          externalId: path.externalId
          name: requestBody.name
      - text: Change the description of segment {externalId} to {description}.
        slots:
          externalId: path.externalId
          description: requestBody.description
      method: generated
      generated: '2026-09-26'