# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Flagsmith Experimental API
  version: 1.0.0
extends: openapi/flagsmith-experimental-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['/api/__future__/environments/{environment_key}/features/{feature_id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: See what a flag serves in an environment
      effect: read
      questions:
      - What value and on/off state does a flag currently serve in production?
      - Can I see a feature's environment default and its segment overrides together?
      instructions:
      - text: Show what feature {feature_id} serves in environment {environment}.
        slots:
          feature_id: path.feature_id
          environment: path.environment_key
      - text: Read the default and segment overrides of flag {feature_id} in {environment}.
        slots:
          feature_id: path.feature_id
          environment: path.environment_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/__future__/environments/{environment_key}/features/{feature_id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a flag's environment configuration
      effect: write
      questions:
      - Can I reset a flag's whole setup in an environment, dropping overrides I don't resend?
      - What happens to segment overrides I leave out when replacing a flag's configuration?
      instructions:
      - text: Replace feature {feature_id} in {environment} with default {environment_default}, clearing anything omitted.
        slots:
          feature_id: path.feature_id
          environment: path.environment_key
          environment_default: requestBody.environment_default
      - text: 'Reset flag {feature_id} in {environment} to exactly these segment overrides: {segment_overrides}.'
        slots:
          feature_id: path.feature_id
          environment: path.environment_key
          segment_overrides: requestBody.segment_overrides
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/__future__/environments/{environment_key}/features/{feature_id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Adjust part of a flag's environment configuration
      effect: write
      questions:
      - Can I change only a flag's environment default and keep its segment overrides as they are?
      - Is there a way to tweak segment overrides without touching the default value?
      instructions:
      - text: Set only the environment default of feature {feature_id} in {environment} to {environment_default}.
        slots:
          feature_id: path.feature_id
          environment: path.environment_key
          environment_default: requestBody.environment_default
      - text: Update segment overrides {segment_overrides} on flag {feature_id} in {environment}, leaving everything else unchanged.
        slots:
          segment_overrides: requestBody.segment_overrides
          feature_id: path.feature_id
          environment: path.environment_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/__future__/environments/{environment_key}/features/{feature_id}/segment-overrides/{segment_id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a flag's override for one segment
      effect: destructive
      questions:
      - How do I drop one segment's special value for a flag without touching the rest?
      - Can a single segment override be deleted by segment id in the URL?
      instructions:
      - text: Remove the override for segment {segment_id} on feature {feature_id} in {environment}.
        slots:
          segment_id: path.segment_id
          feature_id: path.feature_id
          environment: path.environment_key
      - text: Delete segment {segment_id}'s override from flag {feature_id} in environment {environment}.
        slots:
          segment_id: path.segment_id
          feature_id: path.feature_id
          environment: path.environment_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/experiments/environments/{environment_key}/delete-segment-override/'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a segment override via the experimental endpoint
      effect: destructive
      questions:
      - Can I delete a segment override by passing the feature name instead of its id?
      - What error comes back if the segment override I try to delete doesn't exist?
      instructions:
      - text: Use the experimental endpoint to delete the override of segment {segment} on feature {feature} in {environment}.
        slots:
          segment: requestBody.segment
          feature: requestBody.feature
          environment: path.environment_key
      - text: Drop feature {feature}'s segment {segment} override in environment {environment}, identifying the feature by name.
        slots:
          feature: requestBody.feature
          segment: requestBody.segment
          environment: path.environment_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/experiments/environments/{environment_key}/update-flag-v1/'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a single feature state
      effect: write
      questions:
      - How can I switch one flag on and set its value in an environment in a single call?
      - Can I update just one segment override's value instead of the environment default?
      - What value types does the single-flag update accept?
      instructions:
      - text: Set feature {feature} in {environment} to enabled {enabled} with value {value}.
        slots:
          feature: requestBody.feature
          environment: path.environment_key
          enabled: requestBody.enabled
          value: requestBody.value
      - text: 'Change only segment {segment}''s state for flag {feature} in {environment}: enabled {enabled}, value {value}.'
        slots:
          segment: requestBody.segment
          feature: requestBody.feature
          environment: path.environment_key
          enabled: requestBody.enabled
          value: requestBody.value
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/experiments/environments/{environment_key}/update-flag-v2/'].post
  update:
    x-apievangelist-phrasing:
      intent: Configure a flag's default and overrides at once
      effect: write
      questions:
      - Can I set a flag's environment default and all its segment overrides in one request?
      - Is there a way to set override priority order while updating a whole flag?
      instructions:
      - text: Configure feature {feature} in {environment} with default {environment_default} and overrides {segment_overrides}.
        slots:
          feature: requestBody.feature
          environment: path.environment_key
          environment_default: requestBody.environment_default
          segment_overrides: requestBody.segment_overrides
      - text: Apply a full multi-state update to flag {feature} in {environment}, setting the default to {environment_default}.
        slots:
          feature: requestBody.feature
          environment: path.environment_key
          environment_default: requestBody.environment_default
      method: generated
      generated: '2026-09-26'