API Evangelist conversational phrasing for Segmentation Service Segment definitions API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Segmentation Service Segment definitions API
  version: 1.0.0
extends: openapi/adobe-suite-segment-definitions-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['/segment/definitions'].get
  update:
    x-apievangelist-phrasing:
      intent: List segment definitions
      effect: read
      questions:
      - What audience segment definitions exist in my Experience Platform sandbox?
      - Can I page and sort through all my segment definitions?
      instructions:
      - text: List my segment definitions.
      - text: List {limit} segment definitions per page sorted by {sort}.
        slots:
          limit: query.limit
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/definitions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a segment definition
      effect: write
      questions:
      - How do I define a new audience with a PQL expression?
      - Which fields are required when creating a segment definition?
      instructions:
      - text: Create a segment definition named {name} with expression {expression} on schema {schema}.
        slots:
          name: requestBody.name
          expression: requestBody.expression
          schema: requestBody.schema
      - text: Define a new audience {name} described as {description} using {expression} against {schema}.
        slots:
          name: requestBody.name
          description: requestBody.description
          expression: requestBody.expression
          schema: requestBody.schema
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/definitions/{SEGMENT_ID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one segment definition
      effect: read
      questions:
      - How do I see the expression and settings of a specific segment definition?
      - Can I look up a segment definition by its ID?
      instructions:
      - text: Show segment definition {SEGMENT_ID}.
        slots:
          SEGMENT_ID: path.SEGMENT_ID
      - text: Get the rule behind audience {SEGMENT_ID}.
        slots:
          SEGMENT_ID: path.SEGMENT_ID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/definitions/{SEGMENT_ID}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a segment definition
      effect: destructive
      questions:
      - How do I remove an audience segment definition I no longer need?
      - Can I delete a segment definition by ID?
      instructions:
      - text: Delete segment definition {SEGMENT_ID}.
        slots:
          SEGMENT_ID: path.SEGMENT_ID
      - text: Remove audience definition {SEGMENT_ID} from the sandbox.
        slots:
          SEGMENT_ID: path.SEGMENT_ID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/definitions/{SEGMENT_ID}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Overwrite an existing segment definition
      effect: write
      questions:
      - Can I change the expression of a segment definition that already exists?
      - What happens to the fields I leave out when I update a segment definition?
      instructions:
      - text: Update segment definition {SEGMENT_ID} to use expression {expression}.
        slots:
          SEGMENT_ID: path.SEGMENT_ID
          expression: requestBody.expression
      - text: Overwrite segment {SEGMENT_ID} with name {name}, expression {expression} and schema {schema}.
        slots:
          SEGMENT_ID: path.SEGMENT_ID
          name: requestBody.name
          expression: requestBody.expression
          schema: requestBody.schema
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/definitions/bulk-get'].post
  update:
    x-apievangelist-phrasing:
      intent: Fetch several segment definitions by ID
      effect: read
      questions:
      - Can I retrieve multiple segment definitions in one request?
      - Is there a bulk lookup for segment definitions when I have a list of IDs?
      instructions:
      - text: Fetch the segment definitions {ids}.
        slots:
          ids: requestBody.ids
      - text: 'Bulk get these audience definitions: {ids}.'
        slots:
          ids: requestBody.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/segment/conversion'].post
  update:
    x-apievangelist-phrasing:
      intent: Convert a segment expression between PQL formats
      effect: read
      questions:
      - How do I turn a PQL text expression into its JSON form?
      - Can I convert a segment definition from pql/json back to pql/text?
      instructions:
      - text: Convert the expression {expression} for segment {name} on schema {schema} to the other PQL format.
        slots:
          expression: requestBody.expression
          name: requestBody.name
          schema: requestBody.schema
      - text: Translate segment {name}'s PQL expression {expression} between text and JSON using schema {schema}.
        slots:
          name: requestBody.name
          expression: requestBody.expression
          schema: requestBody.schema
      method: generated
      generated: '2026-09-26'