# 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) Flag custom properties API
  version: 1.0.0
extends: openapi/cloudbees-flag-custom-properties-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: 8
- target: $.paths['/v2/applications/{applicationId}/custom-properties'].get
  update:
    x-apievangelist-phrasing:
      intent: List custom properties in an application
      effect: read
      questions:
      - Which custom properties can I use in flag targeting for my application?
      - What custom properties have been defined so far?
      instructions:
      - text: List the custom properties in application {applicationId}.
        slots:
          applicationId: path.applicationId
      - text: Show all targeting properties defined for app {applicationId}.
        slots:
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/applications/{applicationId}/custom-properties'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom property for targeting
      effect: write
      questions:
      - How do I add a new custom property to target flags on, like a user's plan?
      - Which data types can a custom property have?
      instructions:
      - text: Create a custom property named {name} of type {type} in app {applicationId}.
        slots:
          name: requestBody.name
          type: requestBody.type
          applicationId: path.applicationId
      - text: Add custom property {name} to application {applicationId} described as {description}.
        slots:
          name: requestBody.name
          applicationId: path.applicationId
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/applications/{applicationId}/custom-properties/by-name/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a custom property by name
      effect: read
      questions:
      - Can I fetch a custom property if I only know its name?
      - What type is the custom property called 'country'?
      instructions:
      - text: Find the custom property named {name} in application {applicationId}.
        slots:
          name: path.name
          applicationId: path.applicationId
      - text: Look up custom property {name} by name in app {applicationId}.
        slots:
          name: path.name
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/applications/{applicationId}/custom-properties/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property by ID
      effect: read
      questions:
      - How do I retrieve a custom property when I have its ID?
      - What description and type does a given custom property ID have?
      instructions:
      - text: Get custom property {id} in application {applicationId}.
        slots:
          id: path.id
          applicationId: path.applicationId
      - text: Show the details of custom property ID {id} for app {applicationId}.
        slots:
          id: path.id
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/applications/{applicationId}/custom-properties/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a custom property's settings
      effect: write
      questions:
      - How do I change the type or description of an existing custom property?
      - Are fields I leave out reset when I update a custom property?
      instructions:
      - text: Update custom property {id} in app {applicationId} to type {type}.
        slots:
          id: path.id
          applicationId: path.applicationId
          type: requestBody.type
      - text: Rename existing custom property {id} in application {applicationId} to {name}.
        slots:
          id: path.id
          applicationId: path.applicationId
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/applications/{applicationId}/custom-properties/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom property
      effect: destructive
      questions:
      - How do I permanently remove a custom property I no longer use?
      - Can a deleted custom property be recovered?
      instructions:
      - text: Delete custom property {id} from application {applicationId}.
        slots:
          id: path.id
          applicationId: path.applicationId
      - text: Permanently remove custom property {id} in app {applicationId}.
        slots:
          id: path.id
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/applications/{applicationId}/custom-properties/{id}/flag-usage-per-environment'].get
  update:
    x-apievangelist-phrasing:
      intent: See which flags use a custom property
      effect: read
      questions:
      - Which feature flags reference a custom property, per environment?
      - Is a custom property still used by any flags before I delete it?
      instructions:
      - text: Show which flags use custom property {id} in each environment of app {applicationId}.
        slots:
          id: path.id
          applicationId: path.applicationId
      - text: List per-environment flag usage of custom property {id} in application {applicationId}.
        slots:
          id: path.id
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/applications/{applicationId}/custom-properties/{id}/target-group-usage'].get
  update:
    x-apievangelist-phrasing:
      intent: See which target groups use a custom property
      effect: read
      questions:
      - Which target groups rely on a particular custom property?
      - What target groups would be affected if I change a custom property?
      instructions:
      - text: List the target groups that reference custom property {id} in app {applicationId}.
        slots:
          id: path.id
          applicationId: path.applicationId
      - text: Show target group usage for custom property {id} in application {applicationId}.
        slots:
          id: path.id
          applicationId: path.applicationId
      method: generated
      generated: '2026-09-26'