# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Common Room Segments API
  version: 1.0.0
extends: openapi/common-room-segments-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: 5
- target: $.paths['/segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List all segments in a room
      effect: read
      questions:
      - What segments exist in our Common Room room?
      - Can I get a list of every segment we've built?
      instructions:
      - text: List all segments in our room.
      - text: Show me every segment we have.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/segments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new segment
      effect: write
      questions:
      - How do I create a new segment in our community?
      - Can a new segment hold organizations or custom objects instead of contacts?
      instructions:
      - text: Create a segment named {name}.
        slots:
          name: requestBody.name
      - text: Create segment {name} described as {description} for {entityType} records.
        slots:
          name: requestBody.name
          description: requestBody.description
          entityType: requestBody.entityType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/segments/{id}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: List the statuses available in a segment
      effect: read
      questions:
      - Which statuses can contacts have inside a particular segment?
      - How do I find the status IDs defined for a segment?
      instructions:
      - text: List all statuses for segment {id}.
        slots:
          id: path.id
      - text: Get the status options configured on segment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/segments/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one segment by its ID
      effect: read
      questions:
      - Can I look up a single segment's details from its s_ ID?
      - How many records are in a specific segment, and what's its URL?
      instructions:
      - text: Get segment {id}.
        slots:
          id: path.id
      - text: Fetch segment {id} with its {cols}.
        slots:
          id: path.id
          cols: query.cols
      method: generated
      generated: '2026-10-01'
- target: $.paths['/segments/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add existing contacts to a segment
      effect: write
      questions:
      - How do I add contacts to a segment using their email addresses?
      - Can I add people to a segment by GitHub, Twitter or LinkedIn handle?
      - Is it possible to set a status when adding contacts to a segment?
      instructions:
      - text: Add the contacts with {socialType} values {value} to segment {id}.
        slots:
          socialType: requestBody.socialType
          value: requestBody.value
          id: path.id
      - text: Add {socialType} contacts {value} to segment {id} with status {statusId}.
        slots:
          socialType: requestBody.socialType
          value: requestBody.value
          id: path.id
          statusId: requestBody.statusId
      method: generated
      generated: '2026-10-01'