# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely Holdouts API
  version: 1.0.0
extends: openapi/optimizely-holdouts-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['/projects/{project_id}/holdouts'].get
  update:
    x-apievangelist-phrasing:
      intent: List holdouts in a project
      effect: read
      questions:
      - Which holdouts are currently running in my Optimizely project?
      - Can I filter holdouts to draft or concluded ones only?
      - Is it possible to search holdouts by name or key?
      instructions:
      - text: List holdouts in project {project_id}.
        slots:
          project_id: path.project_id
      - text: Show holdouts in project {project_id} with status {status}.
        slots:
          project_id: path.project_id
          status: query.status
      - text: Search holdouts in project {project_id} for {query}, sorted by {sort}.
        slots:
          project_id: path.project_id
          query: query.query
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/holdouts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a holdout control group
      effect: write
      questions:
      - How do I reserve a slice of traffic as a baseline that sees no experiments?
      - What traffic allocation units does a new holdout use, percent or basis points?
      - Can a holdout be scoped to all experiments or just some?
      instructions:
      - text: Create holdout {name} with key {key} in project {project_id}.
        slots:
          name: requestBody.name
          key: requestBody.key
          project_id: path.project_id
      - text: Create holdout {name} ({key}) in project {project_id} holding back {traffic_allocation} basis points in {environment_key}.
        slots:
          name: requestBody.name
          key: requestBody.key
          project_id: path.project_id
          traffic_allocation: requestBody.traffic_allocation
          environment_key: requestBody.environment_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/holdouts/{holdout_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a holdout's configuration
      effect: read
      questions:
      - What traffic allocation and status does a specific holdout have?
      - Can I see the audience conditions and metrics configured on one holdout?
      instructions:
      - text: Fetch holdout {holdout_id} in project {project_id}.
        slots:
          holdout_id: path.holdout_id
          project_id: path.project_id
      - text: Show the configuration of holdout {holdout_id} in project {project_id}.
        slots:
          holdout_id: path.holdout_id
          project_id: path.project_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/holdouts/{holdout_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a holdout with JSON Patch
      effect: write
      questions:
      - How do I move a holdout from draft to running?
      - Can I change a holdout's traffic allocation without replacing the whole thing?
      instructions:
      - text: Patch holdout {holdout_id} in project {project_id} to set its status to running.
        slots:
          holdout_id: path.holdout_id
          project_id: path.project_id
      - text: Conclude holdout {holdout_id} in project {project_id} with a JSON Patch.
        slots:
          holdout_id: path.holdout_id
          project_id: path.project_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/holdouts/{holdout_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a holdout
      effect: destructive
      questions:
      - Can I recover a holdout's metric history after deleting it?
      - How do I permanently remove a holdout I no longer need?
      instructions:
      - text: Permanently delete holdout {holdout_id} from project {project_id}.
        slots:
          holdout_id: path.holdout_id
          project_id: path.project_id
      - text: Remove holdout {holdout_id} in project {project_id} and all its data.
        slots:
          holdout_id: path.holdout_id
          project_id: path.project_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/holdouts/{holdout_id}/experiments'].get
  update:
    x-apievangelist-phrasing:
      intent: List experiments connected to a holdout
      effect: read
      questions:
      - Which experiments are affected by a particular holdout?
      - Can I see start and end times of experiments linked to a holdout?
      instructions:
      - text: List experiments connected to holdout {holdout_id} in project {project_id}.
        slots:
          holdout_id: path.holdout_id
          project_id: path.project_id
      - text: Show the experiments and deployed variations tied to holdout {holdout_id} in project {project_id}.
        slots:
          holdout_id: path.holdout_id
          project_id: path.project_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/export/projects/{project_id}/holdouts/{holdout_id}/results/csv'].get
  update:
    x-apievangelist-phrasing:
      intent: Export holdout results as CSV
      effect: read
      questions:
      - How do I download a holdout's results as a spreadsheet?
      - Can I segment exported holdout results by device or browser?
      instructions:
      - text: Export results for holdout {holdout_id} in project {project_id} as CSV.
        slots:
          holdout_id: path.holdout_id
          project_id: path.project_id
      - text: Download holdout {holdout_id} results in project {project_id} segmented by device {device}.
        slots:
          holdout_id: path.holdout_id
          project_id: path.project_id
          device: query.device
      - text: Get CSV results of holdout {holdout_id} in project {project_id} for attribute {attribute_id} equal to {attribute_value}.
        slots:
          holdout_id: path.holdout_id
          project_id: path.project_id
          attribute_id: query.attribute_id
          attribute_value: query.attribute_value
      method: generated
      generated: '2026-09-26'