# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for cdp-api Segments API
  version: 1.0.0
extends: openapi/treasure-data-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: 16
- target: $.paths['/audiences/{audienceId}/segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List segments in a parent segment
      effect: read
      questions:
      - What segments exist in my parent segment?
      - Where can I see all segments built on one parent segment?
      instructions:
      - text: List segments in parent segment {audienceId}.
        slots:
          audienceId: path.audienceId
      - text: Show every segment built on parent segment {audienceId}.
        slots:
          audienceId: path.audienceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/segments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a segment
      effect: write
      questions:
      - How do I create a new customer segment with a rule in Treasure Data?
      - Can I put a new segment into a specific folder when I create it?
      instructions:
      - text: Create segment {name} in parent segment {audienceId} with rule {rule}.
        slots:
          name: requestBody.name
          audienceId: path.audienceId
          rule: requestBody.rule
      - text: Create segment {name} in parent segment {audienceId} inside folder {segmentFolderId}.
        slots:
          name: requestBody.name
          audienceId: path.audienceId
          segmentFolderId: requestBody.segmentFolderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/folders/{folderId}/segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List segments in a folder
      effect: read
      questions:
      - Which segments are stored in one particular segment folder?
      - Can I browse segments folder by folder?
      instructions:
      - text: List segments in folder {folderId} of parent segment {audienceId}.
        slots:
          folderId: path.folderId
          audienceId: path.audienceId
      - text: Show the segments stored in segment folder {folderId}, parent segment {audienceId}.
        slots:
          folderId: path.folderId
          audienceId: path.audienceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/segments/query'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate the SQL for a segment rule
      effect: read
      questions:
      - Can I see the SQL that a segment rule translates to?
      - How do I turn a segment rule into a query I can run myself?
      instructions:
      - text: Get the SQL for rule {rule} in parent segment {audienceId}.
        slots:
          rule: requestBody.rule
          audienceId: path.audienceId
      - text: Translate segment rule {rule} for parent segment {audienceId} into SQL.
        slots:
          rule: requestBody.rule
          audienceId: path.audienceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/segments/queries'].post
  update:
    x-apievangelist-phrasing:
      intent: Count profiles matching segment rules
      effect: read
      questions:
      - How many profiles would a set of segment rules match before I save it?
      - Can I preview a segment's population size from its rules?
      instructions:
      - text: Count profiles in parent segment {audienceId} that match rule {rule}.
        slots:
          audienceId: path.audienceId
          rule: requestBody.rule
      - text: Preview how many profiles rule {rule} would include in parent segment {audienceId}.
        slots:
          rule: requestBody.rule
          audienceId: path.audienceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/segments/{segmentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a segment by ID
      effect: read
      questions:
      - How do I see a segment's rule and settings?
      - Can I fetch one segment's definition by its ID?
      instructions:
      - text: Show segment {segmentId} in parent segment {audienceId}.
        slots:
          segmentId: path.segmentId
          audienceId: path.audienceId
      - text: Get the rule and settings of segment {segmentId} in parent segment {audienceId}.
        slots:
          segmentId: path.segmentId
          audienceId: path.audienceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/segments/{segmentId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a segment
      effect: write
      questions:
      - Can I change the rule of a segment that already exists?
      - How do I move an existing segment to another folder?
      instructions:
      - text: Update the rule of segment {segmentId} in parent segment {audienceId} to {rule}.
        slots:
          segmentId: path.segmentId
          audienceId: path.audienceId
          rule: requestBody.rule
      - text: Rename segment {segmentId} in parent segment {audienceId} to {name}.
        slots:
          segmentId: path.segmentId
          audienceId: path.audienceId
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/segments/{segmentId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a segment (legacy Audience Studio)
      effect: destructive
      questions:
      - How do I delete a segment in legacy Audience Studio?
      - Can I permanently remove a segment I no longer use?
      instructions:
      - text: Delete segment {segmentId} from parent segment {audienceId}.
        slots:
          segmentId: path.segmentId
          audienceId: path.audienceId
      - text: Remove legacy segment {segmentId} in parent segment {audienceId}.
        slots:
          segmentId: path.segmentId
          audienceId: path.audienceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/segments/queries/{queryId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of a segment query
      effect: read
      questions:
      - Has my segment population query finished yet?
      - What's the status of a segment rule query I started?
      instructions:
      - text: Check status of segment query {queryId} in parent segment {audienceId}.
        slots:
          queryId: path.queryId
          audienceId: path.audienceId
      - text: Tell me if segment query {queryId} in parent segment {audienceId} has finished.
        slots:
          queryId: path.queryId
          audienceId: path.audienceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/segments/queries/{queryId}/kill'].post
  update:
    x-apievangelist-phrasing:
      intent: Kill a running segment query
      effect: destructive
      questions:
      - Can I stop a segment query that's still running?
      - How do I cancel a slow segment population count?
      instructions:
      - text: Kill segment query {queryId} in parent segment {audienceId}.
        slots:
          queryId: path.queryId
          audienceId: path.audienceId
      - text: Cancel running segment query {queryId} for parent segment {audienceId}.
        slots:
          queryId: path.queryId
          audienceId: path.audienceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/segments/queries/{queryId}/customers'].get
  update:
    x-apievangelist-phrasing:
      intent: List profiles returned by a segment query
      effect: read
      questions:
      - How do I see the actual customer profiles a segment query returned?
      - Can I page through the profiles from a segment query result?
      instructions:
      - text: List profiles from segment query {queryId} in parent segment {audienceId}.
        slots:
          queryId: path.queryId
          audienceId: path.audienceId
      - text: Show page {page} of profiles for segment query {queryId} in parent segment {audienceId}.
        slots:
          page: query.page
          queryId: path.queryId
          audienceId: path.audienceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/segments/{segmentId}/statistics'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a segment's daily population history
      effect: read
      questions:
      - How has a segment's population changed day by day?
      - Can I get segment population history between two dates?
      instructions:
      - text: Show population history of segment {segmentId} in parent segment {audienceId}.
        slots:
          segmentId: path.segmentId
          audienceId: path.audienceId
      - text: Get population stats for segment {segmentId} (parent segment {audienceId}) from {from} to {to}.
        slots:
          segmentId: path.segmentId
          audienceId: path.audienceId
          from: query.from
          to: query.to
      method: generated
      generated: '2026-09-26'
- target: $.paths['/entities/segments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a segment via the entities API
      effect: write
      questions:
      - Can I create a segment through the entities API instead of the parent segment path?
      - What attributes define a segment created as an entity?
      instructions:
      - text: Create an entities-API segment with attributes {attributes}.
        slots:
          attributes: requestBody.attributes
      - text: Create a segment entity with attributes {attributes} linked to {relationships}.
        slots:
          attributes: requestBody.attributes
          relationships: requestBody.relationships
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/segments/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a segment by entity ID
      effect: read
      questions:
      - Can I fetch a segment using only its entity ID?
      - What does the entities API return for a single segment?
      instructions:
      - text: Get entities-API segment {id}.
        slots:
          id: path.id
      - text: Fetch segment entity {id} by ID alone.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/segments/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a segment via the entities API
      effect: destructive
      questions:
      - Can I delete a segment by its entity ID in the current Audience Studio?
      - What removes a segment through the entities API?
      instructions:
      - text: Delete entities-API segment {id}.
        slots:
          id: path.id
      - text: Remove segment entity {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/segments/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a segment via the entities API
      effect: write
      questions:
      - Can I patch a segment's attributes with only its entity ID?
      - Which segment fields can the entities API change?
      instructions:
      - text: Patch entities-API segment {id} with attributes {attributes}.
        slots:
          id: path.id
          attributes: requestBody.attributes
      - text: Update segment entity {id} to {attributes}.
        slots:
          id: path.id
          attributes: requestBody.attributes
      method: generated
      generated: '2026-10-01'