# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Admin API V1 Badges API
  version: 1.0.0
extends: openapi/optimizely-badges-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: 11
- target: $.paths['/api/v1/admin/Badges'].get
  update:
    x-apievangelist-phrasing:
      intent: List product badges
      effect: read
      questions:
      - How do I list all the product badges set up in my commerce admin?
      - Can I filter badges by name or sort them by sort order?
      - Which badges are currently shown on product images?
      instructions:
      - text: List all product badges.
      - text: Find badges matching the filter {filter}.
        slots:
          filter: query.$filter
      - text: Show the first {top} badges ordered by {orderby}.
        slots:
          top: query.$top
          orderby: query.$orderby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Badges'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a product badge
      effect: write
      questions:
      - How do I create a new badge like 'Sale' or 'New' for products?
      - Can I schedule a badge to activate and deactivate on set dates?
      instructions:
      - text: Create a badge named {name} that displays {displayText}.
        slots:
          name: requestBody.name
          displayText: requestBody.displayText
      - text: Create badge {name} active from {activateOn} to {deactivateOn}.
        slots:
          name: requestBody.name
          activateOn: requestBody.activateOn
          deactivateOn: requestBody.deactivateOn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Badges({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a product badge
      effect: read
      questions:
      - How do I look up one badge's settings by its ID?
      - What colors and display text does a specific badge use?
      instructions:
      - text: Get badge {id}.
        slots:
          id: path.id
      - text: Show the configuration of badge {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Badges({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a product badge
      effect: write
      questions:
      - How do I overwrite a badge record with a full new definition?
      - Does replacing a badge reset fields I leave out?
      instructions:
      - text: Replace badge {id} with a full definition named {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Overwrite every field of badge {id}, setting display text {displayText}.
        slots:
          id: path.id
          displayText: requestBody.displayText
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Badges({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a product badge
      effect: destructive
      questions:
      - How do I delete one badge by its ID?
      - Can I guard a badge deletion with an ETag match?
      instructions:
      - text: Delete badge {id}.
        slots:
          id: path.id
      - text: Delete badge {id} only if its ETag is {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Badges({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a product badge
      effect: write
      questions:
      - How do I change just the color of an existing badge?
      - Can I update a badge's display text without resending all its fields?
      instructions:
      - text: Change the badge color of badge {id} to {badgeColorHexCode}.
        slots:
          id: path.id
          badgeColorHexCode: requestBody.badgeColorHexCode
      - text: Update the display text on badge {id} to {displayText}.
        slots:
          id: path.id
          displayText: requestBody.displayText
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Badges/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a default badge template
      effect: read
      questions:
      - What default values does a new badge start with?
      - Can I fetch a blank badge template before creating one?
      instructions:
      - text: Fetch the default badge template.
      - text: Show me the default values for a new badge.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/badges/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete product badges
      effect: destructive
      questions:
      - How do I delete several badges at once?
      - Can I remove a batch of badges by passing a list of IDs?
      instructions:
      - text: Bulk delete the badges with IDs {ids}.
        slots:
          ids: query.ids
      - text: 'Remove all of these badges in one call: {ids}.'
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/badges({key})/attributevalues({attributevalueKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an attribute value tied to a badge
      effect: read
      questions:
      - Which attribute values is a badge linked to?
      - Can I look up one attribute value on a badge?
      instructions:
      - text: Get attribute value {attributevalueKey} on badge {key}.
        slots:
          attributevalueKey: path.attributevalueKey
          key: path.key
      - text: Show badge {key}'s linked attribute value {attributevalueKey}.
        slots:
          key: path.key
          attributevalueKey: path.attributevalueKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/badges({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a badge
      effect: read
      questions:
      - How do I read a custom property stored on a badge?
      - Can I fetch one extra property value from a badge record?
      instructions:
      - text: Get custom property {custompropertyKey} on badge {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Show the custom property {custompropertyKey} of badge {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/badges({key})/products({productKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a product assigned to a badge
      effect: read
      questions:
      - Is a particular product assigned to a badge?
      - Can I look up one product linked to a badge?
      instructions:
      - text: Get product {productKey} under badge {key}.
        slots:
          productKey: path.productKey
          key: path.key
      - text: Check whether badge {key} includes product {productKey}.
        slots:
          key: path.key
          productKey: path.productKey
      method: generated
      generated: '2026-09-26'