# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely Feature Experimentation Variable Definitions API
  version: 1.0.0
extends: openapi/optimizely-variable-definitions-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: 6
- target: $.paths['/projects/{project_id}/flags/{flag_key}/variable_definitions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a flag's variable definitions
      effect: read
      questions:
      - Which variables are defined on my feature flag?
      - Can I page through and sort a flag's variable definitions?
      instructions:
      - text: List variable definitions for flag {flag_key} in project {project_id}.
        slots:
          flag_key: path.flag_key
          project_id: path.project_id
      - text: Show {per_page} variable definitions per page for flag {flag_key}, sorted by {sort}.
        slots:
          per_page: query.per_page
          flag_key: path.flag_key
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/flags/{flag_key}/variable_definitions'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a variable to a feature flag
      effect: write
      questions:
      - How do I add a new variable to a feature flag?
      - What data types can a flag variable definition use, and does it need a default value?
      instructions:
      - text: Add a {type} variable {key} with default {default_value} to flag {flag_key} in project {project_id}.
        slots:
          type: requestBody.type
          key: requestBody.key
          default_value: requestBody.default_value
          flag_key: path.flag_key
          project_id: path.project_id
      - text: Create variable definition {key} of type {type} defaulting to {default_value}.
        slots:
          key: requestBody.key
          type: requestBody.type
          default_value: requestBody.default_value
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/flags/{flag_key}/variable_definitions'].patch
  update:
    x-apievangelist-phrasing:
      intent: Bulk update a flag's variable definitions
      effect: write
      questions:
      - Can I change several variable definitions on a flag with one JSON patch?
      - Are read-only fields ignored when I patch variable definitions?
      instructions:
      - text: Apply a JSON patch to the variable definitions of flag {flag_key} in project {project_id}.
        slots:
          flag_key: path.flag_key
          project_id: path.project_id
      - text: Bulk edit the variables on flag {flag_key}.
        slots:
          flag_key: path.flag_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/flags/{flag_key}/variable_definitions/brainstorm'].post
  update:
    x-apievangelist-phrasing:
      intent: Brainstorm flag variables with AI
      effect: write
      questions:
      - Can AI suggest variable definitions for my feature flag?
      - How do I get a chat-style brainstorm of variables for a flag?
      instructions:
      - text: Brainstorm variable definitions for flag {flag_key} in project {project_id} from this conversation {interactions}.
        slots:
          flag_key: path.flag_key
          project_id: path.project_id
          interactions: requestBody.interactions
      - text: Ask AI to suggest variables for flag {flag_key}.
        slots:
          flag_key: path.flag_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/flags/{flag_key}/variable_definitions/{variable_definition_key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one flag variable definition
      effect: read
      questions:
      - What type and default value does a particular flag variable have?
      - Can I look up a single variable definition by its key?
      instructions:
      - text: Get variable {variable_definition_key} on flag {flag_key} in project {project_id}.
        slots:
          variable_definition_key: path.variable_definition_key
          flag_key: path.flag_key
          project_id: path.project_id
      - text: Show the definition of flag variable {variable_definition_key}.
        slots:
          variable_definition_key: path.variable_definition_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/projects/{project_id}/flags/{flag_key}/variable_definitions/{variable_definition_key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a flag variable definition
      effect: destructive
      questions:
      - How do I remove a variable from a feature flag?
      - Is deleting a variable definition permanent?
      instructions:
      - text: Delete variable {variable_definition_key} from flag {flag_key} in project {project_id}.
        slots:
          variable_definition_key: path.variable_definition_key
          flag_key: path.flag_key
          project_id: path.project_id
      - text: Permanently remove flag variable {variable_definition_key}.
        slots:
          variable_definition_key: path.variable_definition_key
      method: generated
      generated: '2026-09-26'