# 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 Predictive Segments API
  version: 1.0.0
extends: openapi/treasure-data-predictive-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: 21
- target: $.paths['/audiences/{audienceId}/predictive_segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List predictive scoring models
      effect: read
      questions:
      - What predictive scoring models exist on my parent segment?
      - Where can I see all predictive segments for a parent segment?
      instructions:
      - text: List predictive scoring models in parent segment {audienceId}.
        slots:
          audienceId: path.audienceId
      - text: Show all predictive segments on parent segment {audienceId}.
        slots:
          audienceId: path.audienceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/predictive_segments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a predictive scoring model (legacy)
      effect: write
      questions:
      - How do I set up a predictive scoring model in legacy Audience Studio?
      - Can I choose which columns a predictive model uses as features?
      instructions:
      - text: Create predictive model {name} in parent segment {audienceId} from base segment {baseSegmentId}.
        slots:
          name: requestBody.name
          audienceId: path.audienceId
          baseSegmentId: requestBody.baseSegmentId
      - text: Set up a legacy predictive model {name} in parent segment {audienceId} scoring segment {scoredSegmentId}.
        slots:
          name: requestBody.name
          audienceId: path.audienceId
          scoredSegmentId: requestBody.scoredSegmentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/predictive_segments/{predictiveSegmentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a predictive model's statistics (legacy)
      effect: read
      questions:
      - Where can I see the accuracy statistics of a predictive model in legacy Audience Studio?
      - What does a single predictive scoring model report about itself under its parent segment?
      instructions:
      - text: Show the statistics of predictive model {predictiveSegmentId} in parent segment {audienceId}.
        slots:
          predictiveSegmentId: path.predictiveSegmentId
          audienceId: path.audienceId
      - text: Get legacy predictive model {predictiveSegmentId} from audience {audienceId}.
        slots:
          predictiveSegmentId: path.predictiveSegmentId
          audienceId: path.audienceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/audiences/{audienceId}/predictive_segments/{predictiveSegmentId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a predictive scoring model (legacy)
      effect: destructive
      questions:
      - How do I delete a predictive scoring model?
      - Can I remove a predictive segment I no longer need?
      instructions:
      - text: Delete predictive model {predictiveSegmentId} from parent segment {audienceId}.
        slots:
          predictiveSegmentId: path.predictiveSegmentId
          audienceId: path.audienceId
      - text: Remove legacy predictive segment {predictiveSegmentId} in parent segment {audienceId}.
        slots:
          predictiveSegmentId: path.predictiveSegmentId
          audienceId: path.audienceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/predictive_segments/{predictiveSegmentId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a predictive scoring model (legacy)
      effect: write
      questions:
      - Can I change the grade thresholds on a predictive model?
      - How do I edit the feature columns of an existing predictive model?
      instructions:
      - text: Update grade thresholds of predictive model {predictiveSegmentId} in parent segment {audienceId} to {gradeThresholds}.
        slots:
          predictiveSegmentId: path.predictiveSegmentId
          audienceId: path.audienceId
          gradeThresholds: requestBody.gradeThresholds
      - text: Rename predictive model {predictiveSegmentId} in parent segment {audienceId} to {name}.
        slots:
          predictiveSegmentId: path.predictiveSegmentId
          audienceId: path.audienceId
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/predictive_segments/{predictiveSegmentId}/executions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a predictive model's runs (legacy)
      effect: read
      questions:
      - Did the last training run of my legacy predictive model succeed?
      - Which executions has a predictive model in a parent segment gone through?
      instructions:
      - text: List executions of predictive model {predictiveSegmentId} in parent segment {audienceId}.
        slots:
          predictiveSegmentId: path.predictiveSegmentId
          audienceId: path.audienceId
      - text: Show run status history for legacy model {predictiveSegmentId} in audience {audienceId}.
        slots:
          predictiveSegmentId: path.predictiveSegmentId
          audienceId: path.audienceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/audiences/{audienceId}/predictive_segments/guess_rule_async'].get
  update:
    x-apievangelist-phrasing:
      intent: Get guessed rules for a segment (legacy)
      effect: read
      questions:
      - Can Treasure Data suggest segment rules for a predictive model in legacy Audience Studio?
      - What rules does the guesser propose for a given segment in a parent segment?
      instructions:
      - text: Get guessed predictive rules for segment {segmentId} in parent segment {audienceId}.
        slots:
          segmentId: query.segmentId
          audienceId: path.audienceId
      - text: Suggest rules for segment {segmentId} under audience {audienceId} using the legacy guesser.
        slots:
          segmentId: query.segmentId
          audienceId: path.audienceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/audiences/{audienceId}/predictive_segments/{predictiveSegmentId}/model/columns'].get
  update:
    x-apievangelist-phrasing:
      intent: List columns of a predictive model (legacy)
      effect: read
      questions:
      - Which columns does a legacy predictive model read from the parent segment?
      - Can I cap how many model columns come back?
      instructions:
      - text: List the columns used by predictive model {predictiveSegmentId} in parent segment {audienceId}.
        slots:
          predictiveSegmentId: path.predictiveSegmentId
          audienceId: path.audienceId
      - text: Show the first {limit} columns of legacy model {predictiveSegmentId} in audience {audienceId}.
        slots:
          limit: query.limit
          predictiveSegmentId: path.predictiveSegmentId
          audienceId: path.audienceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/audiences/{audienceId}/predictive_segments/{predictiveSegmentId}/model/features'].get
  update:
    x-apievangelist-phrasing:
      intent: List features of a predictive model (legacy)
      effect: read
      questions:
      - Which features matter most in my legacy predictive model?
      - What feature importance does a predictive model under a parent segment report?
      instructions:
      - text: List the features of predictive model {predictiveSegmentId} in parent segment {audienceId}.
        slots:
          predictiveSegmentId: path.predictiveSegmentId
          audienceId: path.audienceId
      - text: Show the top {limit} features of legacy model {predictiveSegmentId} in audience {audienceId}.
        slots:
          limit: query.limit
          predictiveSegmentId: path.predictiveSegmentId
          audienceId: path.audienceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/audiences/{audienceId}/predictive_segments/{predictiveSegmentId}/score_histogram'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a predictive model's score histogram
      effect: read
      questions:
      - What does the score distribution of my predictive model look like?
      - Can I include the positive training samples in the score histogram?
      instructions:
      - text: Show the score histogram of predictive model {predictiveSegmentId} in parent segment {audienceId}.
        slots:
          predictiveSegmentId: path.predictiveSegmentId
          audienceId: path.audienceId
      - text: Get the histogram for model {predictiveSegmentId} in audience {audienceId} with positive training set {with_positive_train}.
        slots:
          predictiveSegmentId: path.predictiveSegmentId
          audienceId: path.audienceId
          with_positive_train: query.with_positive_train
      method: generated
      generated: '2026-10-01'
- target: $.paths['/audiences/{audienceId}/predictive_segments/{predictiveSegmentId}/run'].post
  update:
    x-apievangelist-phrasing:
      intent: Train a predictive scoring model (legacy)
      effect: write
      questions:
      - How do I train a predictive scoring model?
      - Can I retrain a predictive model after changing its features?
      instructions:
      - text: Train predictive model {predictiveSegmentId} in parent segment {audienceId}.
        slots:
          predictiveSegmentId: path.predictiveSegmentId
          audienceId: path.audienceId
      - text: Retrain legacy predictive model {predictiveSegmentId} of parent segment {audienceId}.
        slots:
          predictiveSegmentId: path.predictiveSegmentId
          audienceId: path.audienceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/entities/segments/{id}/predictive_segments/guess_rule_async'].get
  update:
    x-apievangelist-phrasing:
      intent: Get suggested predictive rules for a segment
      effect: read
      questions:
      - Can I get suggested predictive scoring rules for a segment by its entity ID?
      - What scoring rules does the entities API guess for one segment?
      instructions:
      - text: Get predictive scoring rules guessed for segment {id}.
        slots:
          id: path.id
      - text: Suggest predictive rules for entities segment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/predictive_segments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a predictive scoring model
      effect: write
      questions:
      - Can I create a predictive scoring model through the entities API?
      - What attributes define a new predictive model in the current Audience Studio?
      instructions:
      - text: Create a predictive scoring model with attributes {attributes}.
        slots:
          attributes: requestBody.attributes
      - text: Create a predictive model with attributes {attributes} linked to {relationships} via the entities API.
        slots:
          attributes: requestBody.attributes
          relationships: requestBody.relationships
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/predictive_segments/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a predictive scoring model by ID
      effect: read
      questions:
      - Can I fetch one predictive scoring model by its entity ID alone?
      - How is a predictive model configured, looked up by ID?
      instructions:
      - text: Get predictive scoring model {id}.
        slots:
          id: path.id
      - text: Show the entities-API predictive model {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/predictive_segments/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a predictive scoring model
      effect: destructive
      questions:
      - Can I delete a predictive model by its entity ID?
      - What removes a predictive scoring model in the current Audience Studio?
      instructions:
      - text: Delete predictive scoring model {id}.
        slots:
          id: path.id
      - text: Remove entities-API predictive model {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/predictive_segments/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a predictive scoring model
      effect: write
      questions:
      - Can I patch a predictive model's settings using only its ID?
      - Which attributes of an entities-API predictive model can I change?
      instructions:
      - text: Update predictive scoring model {id} with attributes {attributes}.
        slots:
          id: path.id
          attributes: requestBody.attributes
      - text: Patch entities-API predictive model {id} to {attributes}.
        slots:
          id: path.id
          attributes: requestBody.attributes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/predictive_segments/{id}/run'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a predictive scoring model
      effect: write
      questions:
      - Can I kick off a predictive model run by its entity ID?
      - What starts scoring for a predictive model in the current Audience Studio?
      instructions:
      - text: Run predictive scoring model {id}.
        slots:
          id: path.id
      - text: Start scoring with entities-API predictive model {id} now.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/predictive_segments/{id}/executions'].get
  update:
    x-apievangelist-phrasing:
      intent: List runs of a predictive scoring model
      effect: read
      questions:
      - Which runs has a predictive model gone through, looked up by its entity ID?
      - Has my entities-API predictive model finished its latest execution?
      instructions:
      - text: List executions of predictive scoring model {id}.
        slots:
          id: path.id
      - text: Show the run history of entities-API predictive model {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/predictive_segments/{id}/model/features'].get
  update:
    x-apievangelist-phrasing:
      intent: List features of a predictive scoring model
      effect: read
      questions:
      - Which features does a predictive model use, fetched by entity ID?
      - Can I limit how many model features the entities API returns?
      instructions:
      - text: List the features of predictive scoring model {id}.
        slots:
          id: path.id
      - text: Show the top {limit} features of entities-API predictive model {id}.
        slots:
          limit: query.limit
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/predictive_segments/{id}/model/columns'].get
  update:
    x-apievangelist-phrasing:
      intent: List columns of a predictive scoring model
      effect: read
      questions:
      - Which columns feed a predictive model, fetched by entity ID?
      - Can I limit how many model columns the entities API returns?
      instructions:
      - text: List the columns of predictive scoring model {id}.
        slots:
          id: path.id
      - text: Show {limit} columns of entities-API predictive model {id}.
        slots:
          limit: query.limit
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/predictive_segments/{id}/model/score'].get
  update:
    x-apievangelist-phrasing:
      intent: Get scores of a predictive scoring model
      effect: read
      questions:
      - What scores did a predictive model produce?
      - Can I see the scoring results of an entities-API predictive model?
      instructions:
      - text: Get the scores of predictive scoring model {id}.
        slots:
          id: path.id
      - text: Show the model score output for predictive model {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'