API Evangelist conversational phrasing for Flagsmith Feature states API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Flagsmith Feature states API
  version: 1.0.0
extends: openapi/flagsmith-feature-states-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: 17
- target: $.paths['/api/v1/environment-feature-versions/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an environment feature version by ID
      effect: read
      questions:
      - Can I look up a feature version without knowing its environment or feature?
      - What does a specific environment feature version contain?
      instructions:
      - text: Fetch environment feature version {id} directly by its ID.
        slots:
          id: path.id
      - text: Show me the details of feature version {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_api_key}/featurestates/'].get
  update:
    x-apievangelist-phrasing:
      intent: List feature states in an environment
      effect: read
      questions:
      - How do I see every flag state set in one environment using its environment key?
      - Can I filter an environment's feature states by feature name?
      - Which feature states in an environment have identity overrides?
      instructions:
      - text: List the feature states in environment {environment_api_key}.
        slots:
          environment_api_key: path.environment_api_key
      - text: Show the feature states for feature named {feature_name} in environment {environment_api_key}.
        slots:
          feature_name: query.feature_name
          environment_api_key: path.environment_api_key
      - text: List feature states in environment {environment_api_key} that have any identity override.
        slots:
          environment_api_key: path.environment_api_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_api_key}/featurestates/'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a feature state via the deprecated environment path
      effect: write
      questions:
      - Is there still an environment-scoped endpoint for creating feature states, even though it is deprecated?
      - How did older integrations add a feature state under an environment API key?
      instructions:
      - text: Using the deprecated environment-scoped endpoint, create a feature state for feature {feature} in environment {environment_api_key}.
        slots:
          feature: requestBody.feature
          environment_api_key: path.environment_api_key
      - text: Via the legacy environment path, add an enabled state {enabled} for feature {feature} in environment {environment_api_key}.
        slots:
          enabled: requestBody.enabled
          feature: requestBody.feature
          environment_api_key: path.environment_api_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_api_key}/featurestates/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one feature state in an environment
      effect: read
      questions:
      - How do I read a single feature state inside an environment by its ID?
      - What value and enabled status does a given feature state have in this environment?
      instructions:
      - text: Get feature state {id} in environment {environment_api_key}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
      - text: Show whether feature state {id} is enabled in environment {environment_api_key}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_api_key}/featurestates/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a feature state from an environment
      effect: destructive
      questions:
      - How do I remove a feature state from an environment by its environment key?
      - Can I delete a single feature state that is scoped to an environment?
      instructions:
      - text: Delete feature state {id} from environment {environment_api_key}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
      - text: Remove the environment feature state {id} under key {environment_api_key}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_api_key}/featurestates/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Toggle a feature state in an environment
      effect: write
      questions:
      - How do I switch a flag on or off in an environment using its environment key?
      - Can I flip the enabled status of one feature state under an environment?
      instructions:
      - text: Set feature state {id} in environment {environment_api_key} to enabled {enabled}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
          enabled: requestBody.enabled
      - text: Turn off feature state {id} in environment {environment_api_key}.
        slots:
          id: path.id
          environment_api_key: path.environment_api_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_pk}/features/{feature_pk}/versions/{environment_feature_version_pk}/featurestates/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a feature state from a feature version
      effect: destructive
      questions:
      - How do I remove a feature state from a specific versioned change of a feature?
      - Can I delete a segment or override state inside a draft feature version?
      instructions:
      - text: Delete feature state {id} from version {environment_feature_version_pk} of feature {feature_pk} in environment {environment_pk}.
        slots:
          id: path.id
          environment_feature_version_pk: path.environment_feature_version_pk
          feature_pk: path.feature_pk
          environment_pk: path.environment_pk
      - text: Remove state {id} from feature {feature_pk}'s version {environment_feature_version_pk} in environment {environment_pk}.
        slots:
          id: path.id
          feature_pk: path.feature_pk
          environment_feature_version_pk: path.environment_feature_version_pk
          environment_pk: path.environment_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/environments/{environment_pk}/features/{feature_pk}/versions/{environment_feature_version_pk}/featurestates/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit a feature state inside a feature version
      effect: write
      questions:
      - How do I change the value of a feature state within a versioned feature change?
      - Can I enable a flag inside a draft version before publishing it?
      instructions:
      - text: In version {environment_feature_version_pk} of feature {feature_pk} in environment {environment_pk}, set state {id} value to {feature_state_value}.
        slots:
          environment_feature_version_pk: path.environment_feature_version_pk
          feature_pk: path.feature_pk
          environment_pk: path.environment_pk
          id: path.id
          feature_state_value: requestBody.feature_state_value
      - text: Enable state {id} in feature {feature_pk} version {environment_feature_version_pk} for environment {environment_pk}.
        slots:
          id: path.id
          feature_pk: path.feature_pk
          environment_feature_version_pk: path.environment_feature_version_pk
          environment_pk: path.environment_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/feature-health/{path}'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a feature health event from a provider
      effect: write
      questions:
      - How does a monitoring provider report feature health events to Flagsmith?
      - Where do feature health webhooks from a provider get posted?
      instructions:
      - text: Post a feature health event to the provider webhook path {path}.
        slots:
          path: path.path
      - text: Report a health signal for a feature through feature health endpoint {path}.
        slots:
          path: path.path
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/features/featurestates/'].get
  update:
    x-apievangelist-phrasing:
      intent: List feature states filtered by environment
      effect: read
      questions:
      - How do I list feature states for an environment by its numeric ID rather than its key?
      - Can I filter feature states to one feature segment?
      - Which feature states exist for a particular feature in an environment?
      instructions:
      - text: List feature states for environment ID {environment}.
        slots:
          environment: query.environment
      - text: Show feature states for feature {feature} in environment ID {environment}.
        slots:
          feature: query.feature
          environment: query.environment
      - text: List the feature states tied to feature segment {feature_segment} in environment ID {environment}.
        slots:
          feature_segment: query.feature_segment
          environment: query.environment
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/features/featurestates/'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a feature state
      effect: write
      questions:
      - What is the current way to create a feature state for a feature in an environment?
      - Can I create a feature state that goes live from a future date?
      instructions:
      - text: Create a feature state for feature {feature} in environment {environment}.
        slots:
          feature: requestBody.feature
          environment: requestBody.environment
      - text: Add a feature state for feature {feature} in environment {environment} with value {feature_state_value}, live from {live_from}.
        slots:
          feature: requestBody.feature
          environment: requestBody.environment
          feature_state_value: requestBody.feature_state_value
          live_from: requestBody.live_from
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/features/featurestates/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a feature state by ID
      effect: write
      questions:
      - How do I change a feature state's value when I only have its ID?
      - Can I update the multivariate values on an existing feature state?
      instructions:
      - text: Change the value of feature state {id} to {feature_state_value}.
        slots:
          id: path.id
          feature_state_value: requestBody.feature_state_value
      - text: Update feature state {id} so its enabled flag is {enabled}.
        slots:
          id: path.id
          enabled: requestBody.enabled
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/features/featurestates/get-by-uuid/{uuid}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a feature state by UUID
      effect: read
      questions:
      - Can I look up a feature state using its UUID instead of its numeric ID?
      - What feature state does this UUID refer to?
      instructions:
      - text: Get the feature state with UUID {uuid}.
        slots:
          uuid: path.uuid
      - text: Resolve feature state UUID {uuid} to its details.
        slots:
          uuid: path.uuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/feature-health/events/{id}/dismiss/'].post
  update:
    x-apievangelist-phrasing:
      intent: Dismiss a feature health event
      effect: write
      questions:
      - How do I dismiss a feature health alert that is no longer relevant?
      - Can I give a reason when dismissing a feature health event?
      instructions:
      - text: Dismiss feature health event {id} in project {project_pk} with reason {reason}.
        slots:
          id: path.id
          project_pk: path.project_pk
          reason: requestBody.reason
      - text: Clear health alert {id} for project {project_pk}, noting {reason}.
        slots:
          id: path.id
          project_pk: path.project_pk
          reason: requestBody.reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/feature-health/providers/'].get
  update:
    x-apievangelist-phrasing:
      intent: List a project's feature health providers
      effect: read
      questions:
      - Which feature health providers are connected to my project?
      - What monitoring sources feed feature health for a project?
      instructions:
      - text: List the feature health providers for project {project_pk}.
        slots:
          project_pk: path.project_pk
      - text: Show which health monitoring providers project {project_pk} uses.
        slots:
          project_pk: path.project_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/feature-health/providers/'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a feature health provider to a project
      effect: write
      questions:
      - How do I connect a feature health provider to a project?
      - Can I register a new monitoring source for feature health?
      instructions:
      - text: Add feature health provider {name} to project {project_pk}.
        slots:
          name: requestBody.name
          project_pk: path.project_pk
      - text: Connect the {name} health provider for project {project_pk}.
        slots:
          name: requestBody.name
          project_pk: path.project_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/projects/{project_pk}/feature-health/providers/{name}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a feature health provider from a project
      effect: destructive
      questions:
      - How do I disconnect a feature health provider from my project?
      - Can I stop a monitoring source from reporting feature health?
      instructions:
      - text: Remove feature health provider {name} from project {project_pk}.
        slots:
          name: path.name
          project_pk: path.project_pk
      - text: Disconnect the {name} health provider in project {project_pk}.
        slots:
          name: path.name
          project_pk: path.project_pk
      method: generated
      generated: '2026-09-26'