API Evangelist conversational phrasing for CloudBees Unify API (Current) Flags API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for CloudBees Unify API (Current) Flags API
  version: 1.0.0
extends: openapi/cloudbees-flags-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: 9
- target: $.paths['/v2/applications/{applicationId}/flags'].get
  update:
    x-apievangelist-phrasing:
      intent: List feature flags in an application
      effect: read
      questions:
      - Which feature flags exist in my application?
      - Can I see whether each flag is on or off in specific environments when listing them?
      instructions:
      - text: List the feature flags in application {applicationId}.
        slots:
          applicationId: path.applicationId
      - text: List flags in app {applicationId} with their on/off state for environments {configStateEnvs}.
        slots:
          applicationId: path.applicationId
          configStateEnvs: query.configStateEnvs
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/applications/{applicationId}/flags'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a feature flag
      effect: write
      questions:
      - How do I create a new feature flag in CloudBees?
      - Can I create a string flag with a fixed set of variants?
      - How do I mark a new flag as permanent so it isn't flagged as stale?
      instructions:
      - text: Create a Boolean flag named {name} in application {applicationId}.
        slots:
          name: requestBody.name
          applicationId: path.applicationId
      - text: Create flag {name} of type {flagType} in app {applicationId} with variants {variants}.
        slots:
          name: requestBody.name
          flagType: requestBody.flagType
          applicationId: path.applicationId
          variants: requestBody.variants
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/applications/{applicationId}/flags/by-name/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a feature flag by name
      effect: read
      questions:
      - Can I fetch a feature flag if I only know its name?
      - What type and variants does the flag named 'new-checkout' have?
      instructions:
      - text: Find the flag named {name} in application {applicationId}.
        slots:
          name: path.name
          applicationId: path.applicationId
      - text: Look up feature flag {name} by name in app {applicationId}.
        slots:
          name: path.name
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/applications/{applicationId}/flags/labels'].get
  update:
    x-apievangelist-phrasing:
      intent: List labels used on feature flags
      effect: read
      questions:
      - What labels are used across the flags in my application?
      - Which tags can I filter my flags by?
      instructions:
      - text: List the flag labels in application {applicationId}.
        slots:
          applicationId: path.applicationId
      - text: Show every label attached to flags in app {applicationId}.
        slots:
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/applications/{applicationId}/flags/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a feature flag by ID
      effect: read
      questions:
      - How do I retrieve a feature flag when I have its ID?
      - What labels and description does a given flag ID have?
      instructions:
      - text: Get feature flag {id} in application {applicationId}.
        slots:
          id: path.id
          applicationId: path.applicationId
      - text: Show the details of flag ID {id} in app {applicationId}.
        slots:
          id: path.id
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/applications/{applicationId}/flags/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a feature flag's definition
      effect: write
      questions:
      - How do I change a flag's description or labels?
      - Can I mark an existing flag as permanent?
      instructions:
      - text: Update the description of flag {id} in app {applicationId} to {description}.
        slots:
          id: path.id
          applicationId: path.applicationId
          description: requestBody.description
      - text: Set labels {labels} on existing flag {id} in application {applicationId}.
        slots:
          labels: requestBody.labels
          id: path.id
          applicationId: path.applicationId
      - text: 'Mark flag {id} in app {applicationId} as permanent: {isPermanent}.'
        slots:
          id: path.id
          applicationId: path.applicationId
          isPermanent: requestBody.isPermanent
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/applications/{applicationId}/flags/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a feature flag
      effect: destructive
      questions:
      - How do I permanently delete a feature flag and its configurations?
      - Does deleting a flag also remove its environment configurations?
      instructions:
      - text: Delete feature flag {id} from application {applicationId}.
        slots:
          id: path.id
          applicationId: path.applicationId
      - text: Permanently remove flag {id} and all its configurations in app {applicationId}.
        slots:
          id: path.id
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/applications/{applicationId}/flags/{id}/configuration-state'].get
  update:
    x-apievangelist-phrasing:
      intent: Check where a flag is enabled
      effect: read
      questions:
      - In which environments is a particular flag switched on?
      - Can I see a single flag's on/off state across all environments?
      instructions:
      - text: Show whether flag {id} is enabled in each environment of app {applicationId}.
        slots:
          id: path.id
          applicationId: path.applicationId
      - text: Get the per-environment on/off state of flag {id} in application {applicationId}.
        slots:
          id: path.id
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/applications/{applicationId}/flags/{id}/flag-usage-per-environment'].get
  update:
    x-apievangelist-phrasing:
      intent: See which target groups a flag uses
      effect: read
      questions:
      - Which target groups does a feature flag reference in each environment?
      - What audiences is a given flag targeting across environments?
      instructions:
      - text: List the target groups flag {id} uses, per environment, in app {applicationId}.
        slots:
          id: path.id
          applicationId: path.applicationId
      - text: Show target group usage by environment for flag {id} in application {applicationId}.
        slots:
          id: path.id
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'