# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Statsig Holdouts API
  version: 1.0.0
extends: openapi/statsig-holdouts-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: 13
- target: $.paths['/holdouts'].get
  update:
    x-apievangelist-phrasing:
      intent: List holdout groups
      effect: read
      questions:
      - Which holdout groups are set up in my Statsig project?
      - What holdouts are we using to measure long-term impact?
      instructions:
      - text: List all holdouts in my project.
      - text: Show me every holdout group we have.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/holdouts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a holdout group
      effect: write
      questions:
      - How do I hold back a group of users to measure the long-term impact of features?
      - Can a holdout cover specific feature gates?
      - What share of users can I put into a new holdout?
      instructions:
      - text: Create a holdout named {name}.
        slots:
          name: requestBody.name
      - text: Create holdout {name} holding back {passPercentage} percent of users from gates {gateIDs}.
        slots:
          name: requestBody.name
          passPercentage: requestBody.passPercentage
          gateIDs: requestBody.gateIDs
      method: generated
      generated: '2026-09-26'
- target: $.paths['/console/v1/holdouts'].get
  update:
    x-apievangelist-phrasing:
      intent: Filter and page through holdouts
      effect: read
      questions:
      - Can I filter holdouts by who created them or by tag?
      - Which holdouts carry a particular tag?
      instructions:
      - text: List holdouts created by {creatorName}.
        slots:
          creatorName: query.creatorName
      - text: Find holdouts tagged {tags}, page {page} with {limit} per page.
        slots:
          tags: query.tags
          page: query.page
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/holdouts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a holdout for a team and unit type
      effect: write
      questions:
      - Can I create a holdout keyed on a custom unit ID type instead of user ID?
      - Is it possible to assign a new holdout to a specific team when I create it?
      instructions:
      - text: Create holdout {name} for team {teamID}.
        slots:
          name: requestBody.name
          teamID: requestBody.teamID
      - text: Set up a holdout called {name} using unit type {idType}, described as {description}.
        slots:
          name: requestBody.name
          idType: requestBody.idType
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/holdouts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one holdout's details
      effect: read
      questions:
      - What gates and experiments does a given holdout apply to?
      - What pass percentage is a specific holdout using right now?
      instructions:
      - text: Show me the details of holdout {id}.
        slots:
          id: path.id
      - text: Look up holdout {id} and tell me whether it is enabled.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/holdouts/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Replace a holdout's full configuration
      effect: write
      questions:
      - How do I overwrite every setting on a holdout in one request?
      - Must I send all holdout fields when doing a full update?
      instructions:
      - text: 'Fully replace holdout {id}: enabled {isEnabled}, pass {passPercentage} percent, gates {gateIDs}, experiments {experimentIDs}, layers {layerIDs}.'
        slots:
          id: path.id
          isEnabled: requestBody.isEnabled
          passPercentage: requestBody.passPercentage
          gateIDs: requestBody.gateIDs
          experimentIDs: requestBody.experimentIDs
          layerIDs: requestBody.layerIDs
      - text: Rewrite holdout {id} as global {isGlobal}, targeting gate {targetingGateID}, with description {description}.
        slots:
          id: path.id
          isGlobal: requestBody.isGlobal
          targetingGateID: requestBody.targetingGateID
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/holdouts/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a holdout
      effect: destructive
      questions:
      - Can I permanently remove a holdout we no longer need?
      - What happens to a holdout once I delete it?
      instructions:
      - text: Delete holdout {id}.
        slots:
          id: path.id
      - text: Remove the holdout with ID {id} from the project for good.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/holdouts/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change selected holdout settings
      effect: write
      questions:
      - Can I change just the pass percentage on a holdout without resending everything?
      - Is there a way to switch a holdout off and leave its other settings alone?
      instructions:
      - text: Set the pass percentage on holdout {id} to {passPercentage}.
        slots:
          id: path.id
          passPercentage: requestBody.passPercentage
      - text: Disable holdout {id} by setting enabled to {isEnabled}.
        slots:
          id: path.id
          isEnabled: requestBody.isEnabled
      - text: Add monitoring metrics {monitoringMetrics} to holdout {id}.
        slots:
          id: path.id
          monitoringMetrics: requestBody.monitoringMetrics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/holdouts/{id}/overrides'].get
  update:
    x-apievangelist-phrasing:
      intent: View a holdout's overrides
      effect: read
      questions:
      - Which IDs are forced into or out of a holdout?
      - Are there manual overrides on this holdout?
      instructions:
      - text: Show the overrides on holdout {id}.
        slots:
          id: path.id
      - text: List which unit IDs are overridden in holdout {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/holdouts/{id}/overrides'].post
  update:
    x-apievangelist-phrasing:
      intent: Replace a holdout's override list
      effect: write
      questions:
      - How do I reset the whole override list on a holdout?
      - Can I swap out every holdout override in a single call?
      instructions:
      - text: Replace all overrides on holdout {id} with a new set.
        slots:
          id: path.id
      - text: Overwrite the override list for holdout {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/holdouts/{id}/overrides'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove IDs from a holdout's overrides
      effect: destructive
      questions:
      - Can I take specific IDs off a holdout's override list?
      - What's the way to drop a few overridden users from a holdout?
      instructions:
      - text: Remove selected IDs from the overrides on holdout {id}.
        slots:
          id: path.id
      - text: Drop these users from holdout {id}'s override list.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/holdouts/{id}/overrides'].patch
  update:
    x-apievangelist-phrasing:
      intent: Add IDs to a holdout's overrides
      effect: write
      questions:
      - Can I append more IDs to a holdout's overrides without replacing the existing ones?
      - Is it possible to force an extra user into a holdout?
      instructions:
      - text: Add these IDs to the overrides on holdout {id}.
        slots:
          id: path.id
      - text: Append new override entries to holdout {id}, keeping the existing ones.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/console/v1/holdouts/{id}/pulse_results'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a holdout's Pulse results
      effect: read
      questions:
      - What is the long-term impact measured by a holdout so far?
      - Can I read holdout Pulse results with CUPED variance reduction applied?
      - Which confidence interval can I request for holdout results?
      instructions:
      - text: Get the Pulse results for holdout {id}.
        slots:
          id: path.id
      - text: Show Pulse results for holdout {id} with CUPED {cuped} at {confidence} percent confidence.
        slots:
          id: path.id
          cuped: query.cuped
          confidence: query.confidence
      method: generated
      generated: '2026-10-01'