# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely Experiments API
  version: 1.0.0
extends: openapi/optimizely-experiments-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: 21
- target: $.paths['/api/v1/admin/Experiments'].get
  update:
    x-apievangelist-phrasing:
      intent: List commerce content experiments
      effect: read
      questions:
      - Which A/B content experiments are set up in my Configured Commerce admin?
      - Can I filter the commerce admin experiments list by status or website?
      - How many content experiments does the commerce back office hold right now?
      instructions:
      - text: List all content experiments in the commerce admin.
      - text: List commerce admin experiments matching the OData filter {filter}.
        slots:
          filter: query.$filter
      - text: Show the first {top} commerce content experiments sorted by {orderby}.
        slots:
          top: query.$top
          orderby: query.$orderby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Experiments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a commerce content experiment
      effect: write
      questions:
      - How do I set up a new A/B content experiment on my commerce storefront?
      - Can I split traffic across up to three content variants plus the original?
      - What end condition and metric must a new commerce content experiment have?
      instructions:
      - text: Create a commerce content experiment named {name} measuring {metric} that ends on {endCondition}.
        slots:
          name: requestBody.name
          metric: requestBody.metric
          endCondition: requestBody.endCondition
      - text: Start a storefront content experiment {name} described as {description} with status {status}.
        slots:
          name: requestBody.name
          description: requestBody.description
          status: requestBody.status
      - text: Create content experiment {name} on website {websiteId} with {variant1Allocation} of traffic to variant 1.
        slots:
          name: requestBody.name
          websiteId: requestBody.websiteId
          variant1Allocation: requestBody.variant1Allocation
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Experiments({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a commerce content experiment
      effect: read
      questions:
      - What allocation and variants does one commerce content experiment use?
      - Can I pull a single commerce admin experiment record by its GUID?
      instructions:
      - text: Get commerce content experiment {id}.
        slots:
          id: path.id
      - text: Show the variant allocations of commerce admin experiment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Experiments({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a commerce content experiment
      effect: write
      questions:
      - How do I overwrite a commerce content experiment with a complete new definition?
      - Does replacing a commerce admin experiment reset the fields I omit?
      instructions:
      - text: Replace commerce content experiment {id} with a full record named {name} measuring {metric}.
        slots:
          id: path.id
          name: requestBody.name
          metric: requestBody.metric
      - text: Overwrite every field of commerce experiment {id}, setting status {status}.
        slots:
          id: path.id
          status: requestBody.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Experiments({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a commerce content experiment
      effect: destructive
      questions:
      - Can I remove one commerce content experiment by its ID?
      - Is there a way to guard deleting a commerce experiment with an ETag?
      instructions:
      - text: Delete commerce content experiment {id}.
        slots:
          id: path.id
      - text: Delete commerce admin experiment {id} only if its ETag is {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Experiments({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a commerce content experiment
      effect: write
      questions:
      - How do I pause a running commerce content experiment without resending everything?
      - Can I change just the traffic split on an existing commerce experiment?
      instructions:
      - text: Set isPaused to {isPaused} on commerce content experiment {id}.
        slots:
          id: path.id
          isPaused: requestBody.isPaused
      - text: Change the included traffic allocation of commerce experiment {id} to {includedAllocation}.
        slots:
          id: path.id
          includedAllocation: requestBody.includedAllocation
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Experiments/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a blank commerce experiment template
      effect: read
      questions:
      - What default values does a new commerce content experiment start with?
      - Can I fetch an empty experiment template before building one in the commerce admin?
      instructions:
      - text: Fetch the default template for a commerce content experiment.
      - text: Show me the starting values for a new commerce admin experiment.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Experiments/Default.end'].post
  update:
    x-apievangelist-phrasing:
      intent: End a commerce content experiment
      effect: destructive
      questions:
      - How do I stop a commerce content experiment by passing its experiment ID?
      - Can I end an A/B content test early through the commerce admin?
      instructions:
      - text: End commerce content experiment {experimentId}.
        slots:
          experimentId: requestBody.experimentId
      - text: Finish the storefront A/B test {experimentId} now via the Default.end action.
        slots:
          experimentId: requestBody.experimentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/experiments/end'].post
  update:
    x-apievangelist-phrasing:
      intent: Call the route-style experiment end endpoint
      effect: destructive
      questions:
      - Is there a lowercase experiments/end route that takes no declared parameters?
      - What does the parameterless experiments end route in the commerce admin do?
      instructions:
      - text: Call the route-style experiments/end endpoint in the commerce admin.
      - text: Invoke the parameterless end route for commerce experiments.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/experiments/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete commerce content experiments
      effect: destructive
      questions:
      - Can I delete several commerce content experiments in one call?
      - How do I remove a batch of commerce admin experiments by a list of IDs?
      instructions:
      - text: Bulk delete the commerce content experiments with IDs {ids}.
        slots:
          ids: query.ids
      - text: 'Remove these commerce admin experiments together: {ids}.'
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/experiments({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a commerce experiment
      effect: read
      questions:
      - Can I read one custom property stored on a commerce content experiment?
      - What extra custom fields are attached to a given commerce experiment?
      instructions:
      - text: Get custom property {custompropertyKey} on commerce experiment {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Show the custom property {custompropertyKey} of commerce content experiment {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/experiments({key})/participants({experimentparticipantKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a participant in a commerce experiment
      effect: read
      questions:
      - Can I look up one visitor who participated in a commerce content experiment?
      - Which variant was a specific participant bucketed into for a commerce experiment?
      instructions:
      - text: Get participant {experimentparticipantKey} of commerce experiment {key}.
        slots:
          experimentparticipantKey: path.experimentparticipantKey
          key: path.key
      - text: Show participant record {experimentparticipantKey} in content experiment {key}.
        slots:
          experimentparticipantKey: path.experimentparticipantKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/experiments'].get
  update:
    x-apievangelist-phrasing:
      intent: List experiments in a project
      effect: read
      questions:
      - Which experiments exist in my Optimizely Web Experimentation project?
      - Can I page through a project's experiments a set number at a time?
      instructions:
      - text: List the experiments in project {project_id}.
        slots:
          project_id: query.project_id
      - text: Show page {page} of experiments in project {project_id}, {per_page} per page.
        slots:
          page: query.page
          project_id: query.project_id
          per_page: query.per_page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/experiments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an experiment in a project
      effect: write
      questions:
      - How do I add a new experiment to a Web Experimentation project?
      - Can I set a description and status when creating a project experiment?
      instructions:
      - text: Create an experiment named {name} in project {project_id}.
        slots:
          name: requestBody.name
          project_id: requestBody.project_id
      - text: Add experiment {name} to project {project_id} with description {description}.
        slots:
          name: requestBody.name
          project_id: requestBody.project_id
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/experiments/{experiment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a project experiment's details
      effect: read
      questions:
      - What are the full details of a specific experiment in my project?
      - Can I retrieve one Web Experimentation experiment by its experiment ID?
      instructions:
      - text: Get experiment {experiment_id}.
        slots:
          experiment_id: path.experiment_id
      - text: Show the full configuration of experiment {experiment_id}.
        slots:
          experiment_id: path.experiment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/experiments/{experiment_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive or delete a project experiment
      effect: destructive
      questions:
      - How do I archive an experiment I no longer need in my project?
      - Can I permanently delete a Web Experimentation experiment?
      instructions:
      - text: Archive experiment {experiment_id}.
        slots:
          experiment_id: path.experiment_id
      - text: Delete project experiment {experiment_id}.
        slots:
          experiment_id: path.experiment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/experiments/{experiment_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a project experiment
      effect: write
      questions:
      - Can I rename an existing experiment in my Web Experimentation project?
      - How do I change the status of a project experiment?
      instructions:
      - text: Rename experiment {experiment_id} to {name}.
        slots:
          experiment_id: path.experiment_id
          name: requestBody.name
      - text: Set the status of experiment {experiment_id} to {status}.
        slots:
          experiment_id: path.experiment_id
          status: requestBody.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/experiments/{experiment_id}/results'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an experiment's statistical results
      effect: read
      questions:
      - Is my experiment's winning variation statistically significant yet?
      - What conversion rates and confidence intervals did Stats Engine compute for an experiment?
      instructions:
      - text: Get the results for experiment {experiment_id}.
        slots:
          experiment_id: path.experiment_id
      - text: Show conversion rates and significance for experiment {experiment_id}.
        slots:
          experiment_id: path.experiment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/experiments/{experiment_id}/results/share'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a shareable experiment results link
      effect: read
      questions:
      - Can I share an experiment's results page with someone who has no Optimizely account?
      - Is there a read-only public link to an experiment's results?
      instructions:
      - text: Get a shareable results link for experiment {experiment_id}.
        slots:
          experiment_id: path.experiment_id
      - text: Create a read-only link to the results page of experiment {experiment_id}.
        slots:
          experiment_id: path.experiment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/experiments/{experiment_id}/timeseries'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an experiment's results over time
      effect: read
      questions:
      - How have an experiment's results trended day by day?
      - Can I see an experiment's results time series for mobile devices only?
      - What did the results look like between two dates compared with a chosen baseline variation?
      instructions:
      - text: Get the results time series for experiment {experiment_id}.
        slots:
          experiment_id: path.experiment_id
      - text: Show experiment {experiment_id}'s results over time from {start_time} to {end_time}.
        slots:
          experiment_id: path.experiment_id
          start_time: query.start_time
          end_time: query.end_time
      - text: Chart experiment {experiment_id} over time for device {device} only.
        slots:
          experiment_id: path.experiment_id
          device: query.device
      method: generated
      generated: '2026-09-26'
- target: $.paths['/export/experiments/{experiment_id}/results/csv'].get
  update:
    x-apievangelist-phrasing:
      intent: Export experiment results as CSV
      effect: read
      questions:
      - Can I download an experiment's results as a CSV file?
      - How do I export experiment results for a single browser to a spreadsheet?
      instructions:
      - text: Export the results of experiment {experiment_id} as CSV.
        slots:
          experiment_id: path.experiment_id
      - text: Download a CSV of experiment {experiment_id} results against baseline variation {baseline_variation_id}.
        slots:
          experiment_id: path.experiment_id
          baseline_variation_id: query.baseline_variation_id
      method: generated
      generated: '2026-09-26'