# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for dotCMS REST Experiment API
  version: 1.0.0
extends: openapi/dotcms-experiment-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: 18
- target: $.paths['/api/v1/experiments/{experimentId}/variants'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a variant to an A/B experiment
      effect: write
      questions:
      - How do I add another variant to an experiment I'm setting up?
      - Can I describe what a new experiment variant changes?
      instructions:
      - text: Add a variant to experiment {experimentId}.
        slots:
          experimentId: path.experimentId
      - text: Add variant {description} to experiment {experimentId}.
        slots:
          description: requestBody.description
          experimentId: path.experimentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments/{experimentId}/_archive'].put
  update:
    x-apievangelist-phrasing:
      intent: Archive an experiment
      effect: write
      questions:
      - How do I archive an experiment that's finished?
      - Can old A/B tests be archived rather than deleted?
      instructions:
      - text: Archive experiment {experimentId}.
        slots:
          experimentId: path.experimentId
      - text: Move experiment {experimentId} to the archive.
        slots:
          experimentId: path.experimentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments/scheduled/{experimentId}/_cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a scheduled experiment
      effect: destructive
      questions:
      - Can I cancel an experiment that is scheduled but hasn't started yet?
      - How do I call off a scheduled A/B test?
      instructions:
      - text: Cancel scheduled experiment {experimentId}.
        slots:
          experimentId: path.experimentId
      - text: Call off the scheduled run of experiment {experimentId}.
        slots:
          experimentId: path.experimentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments'].get
  update:
    x-apievangelist-phrasing:
      intent: List experiments
      effect: read
      questions:
      - Which A/B experiments are set up in dotCMS?
      - Can I list the experiments running on one particular page?
      - How do I find experiments by status, like only running ones?
      instructions:
      - text: List all experiments.
      - text: List experiments on page {pageId}.
        slots:
          pageId: query.pageId
      - text: Show experiments with status {status}.
        slots:
          status: query.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an A/B experiment
      effect: write
      questions:
      - How do I set up a new A/B test on a page in dotCMS?
      - Can I set traffic allocation and goals when creating an experiment?
      instructions:
      - text: Create experiment {name} on page {pageId}.
        slots:
          name: requestBody.name
          pageId: requestBody.pageId
      - text: Create experiment {name} for page {pageId} sending {trafficAllocation} percent of traffic.
        slots:
          name: requestBody.name
          pageId: requestBody.pageId
          trafficAllocation: requestBody.trafficAllocation
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments/{experimentId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an experiment
      effect: destructive
      questions:
      - How do I permanently delete an experiment?
      - Can I remove an A/B test I created by mistake?
      instructions:
      - text: Delete experiment {experimentId}.
        slots:
          experimentId: path.experimentId
      - text: Remove experiment {experimentId} entirely.
        slots:
          experimentId: path.experimentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments/{experimentId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an experiment's settings
      effect: write
      questions:
      - Can I change the traffic split or goals of an existing experiment?
      - How do I rename or reschedule an experiment?
      instructions:
      - text: Rename experiment {experimentId} to {name}.
        slots:
          experimentId: path.experimentId
          name: requestBody.name
      - text: Change experiment {experimentId} traffic allocation to {trafficAllocation}.
        slots:
          experimentId: path.experimentId
          trafficAllocation: requestBody.trafficAllocation
      - text: Update the schedule of experiment {experimentId} to {scheduling}.
        slots:
          experimentId: path.experimentId
          scheduling: requestBody.scheduling
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments/{experimentId}/goals/primary'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an experiment's primary goal
      effect: destructive
      questions:
      - How do I clear the primary goal of an experiment?
      - Can I remove the goal I set on an A/B test?
      instructions:
      - text: Delete the primary goal of experiment {experimentId}.
        slots:
          experimentId: path.experimentId
      - text: Clear the goal on experiment {experimentId}.
        slots:
          experimentId: path.experimentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments/{experimentId}/targetingConditions/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a targeting condition from an experiment
      effect: destructive
      questions:
      - How do I drop one audience targeting condition from an experiment?
      - Can I delete a single targeting rule on an A/B test?
      instructions:
      - text: Delete targeting condition {id} from experiment {experimentId}.
        slots:
          id: path.id
          experimentId: path.experimentId
      - text: Remove rule {id} from the targeting of experiment {experimentId}.
        slots:
          id: path.id
          experimentId: path.experimentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments/{experimentId}/variants/{name}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an experiment variant's description
      effect: write
      questions:
      - Can I edit the description of an existing experiment variant?
      - How do I relabel a variant in my A/B test?
      instructions:
      - text: Update variant {name} of experiment {experimentId} with description {description}.
        slots:
          name: path.name
          experimentId: path.experimentId
          description: requestBody.description
      - text: Relabel variant {name} in experiment {experimentId}.
        slots:
          name: path.name
          experimentId: path.experimentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments/{experimentId}/variants/{name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a variant from an experiment
      effect: destructive
      questions:
      - How do I remove a variant from an experiment?
      - Can I delete one arm of an A/B test before it starts?
      instructions:
      - text: Delete variant {name} from experiment {experimentId}.
        slots:
          name: path.name
          experimentId: path.experimentId
      - text: Remove the {name} variant of experiment {experimentId}.
        slots:
          name: path.name
          experimentId: path.experimentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments/{experimentId}/_end'].post
  update:
    x-apievangelist-phrasing:
      intent: End a running experiment
      effect: destructive
      questions:
      - How do I stop an experiment that's currently running?
      - Can I end an A/B test early?
      instructions:
      - text: End experiment {experimentId}.
        slots:
          experimentId: path.experimentId
      - text: Stop running experiment {experimentId} now.
        slots:
          experimentId: path.experimentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an experiment's details
      effect: read
      questions:
      - What are the settings of a specific experiment?
      - Can I look up one experiment's variants and goals?
      instructions:
      - text: Get experiment {id}.
        slots:
          id: path.id
      - text: Show the configuration of experiment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments/{id}/results'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an experiment's results
      effect: read
      questions:
      - Which variant is winning my A/B test?
      - Where do I see the results and conversion numbers for an experiment?
      instructions:
      - text: Get the results of experiment {id}.
        slots:
          id: path.id
      - text: Show how the variants of experiment {id} are performing.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments/health'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the experiments feature health
      effect: read
      questions:
      - Is the experiments service healthy and configured?
      - Can I verify the A/B testing feature is working before creating a test?
      instructions:
      - text: Run the experiments health check.
      - text: Check whether experiments are available on this instance.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments/isUserIncluded'].post
  update:
    x-apievangelist-phrasing:
      intent: Check if the visitor is in running experiments
      effect: read
      questions:
      - Is the current visitor included in any running experiment?
      - Can I check experiment inclusion while excluding certain experiments?
      instructions:
      - text: Check whether the current user is included in any running experiment.
      - text: Check experiment inclusion for this user, excluding {exclude}.
        slots:
          exclude: requestBody.exclude
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments/{experimentId}/variants/{name}/_promote'].put
  update:
    x-apievangelist-phrasing:
      intent: Promote a winning variant
      effect: write
      questions:
      - How do I make a winning variant the page's real content?
      - Can I promote one experiment variant to production?
      instructions:
      - text: Promote variant {name} of experiment {experimentId}.
        slots:
          name: path.name
          experimentId: path.experimentId
      - text: Make variant {name} from experiment {experimentId} the live version.
        slots:
          name: path.name
          experimentId: path.experimentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/experiments/{experimentId}/_start'].post
  update:
    x-apievangelist-phrasing:
      intent: Start an experiment
      effect: write
      questions:
      - How do I launch an experiment once it's configured?
      - Can I start an A/B test right away?
      instructions:
      - text: Start experiment {experimentId}.
        slots:
          experimentId: path.experimentId
      - text: Launch experiment {experimentId} now.
        slots:
          experimentId: path.experimentId
      method: generated
      generated: '2026-09-26'