# 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 Attribute Values API
  version: 1.0.0
extends: openapi/optimizely-attribute-values-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: 15
- target: $.paths['/api/v1/admin/AttributeValues'].get
  update:
    x-apievangelist-phrasing:
      intent: List product attribute values
      effect: read
      questions:
      - What attribute values, like Red or Large, exist in my commerce catalog?
      - Can I filter attribute values to only active ones for a given attribute type?
      instructions:
      - text: List all attribute values.
      - text: List attribute values where {filter}, sorted by {orderby}.
        slots:
          filter: query.$filter
          orderby: query.$orderby
      - text: Return the first {top} attribute values with a total count.
        slots:
          top: query.$top
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/AttributeValues'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an attribute value
      effect: write
      questions:
      - How do I add a new option such as Navy to an existing product attribute?
      - Can I set the display sort order when creating an attribute value?
      instructions:
      - text: Create attribute value {value} under attribute type {attributeTypeId}.
        slots:
          value: requestBody.value
          attributeTypeId: requestBody.attributeTypeId
      - text: Add attribute value {value} with sort order {sortOrder}.
        slots:
          value: requestBody.value
          sortOrder: requestBody.sortOrder
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/AttributeValues({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an attribute value by id
      effect: read
      questions:
      - Can I look up a single attribute value record by its id?
      - Which attribute type does a particular attribute value belong to?
      instructions:
      - text: Get attribute value {id}.
        slots:
          id: path.id
      - text: Fetch attribute value {id} with {expand} expanded.
        slots:
          id: path.id
          expand: query.$expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/AttributeValues({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace an attribute value
      effect: write
      questions:
      - Is there a way to overwrite every field of an attribute value in one call?
      - What must I send to fully replace an existing attribute value record?
      instructions:
      - text: Replace attribute value {id} with value {value}.
        slots:
          id: path.id
          value: requestBody.value
      - text: Overwrite the whole attribute value record {id} with value {value} and active flag {isActive}.
        slots:
          id: path.id
          value: requestBody.value
          isActive: requestBody.isActive
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/AttributeValues({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an attribute value
      effect: destructive
      questions:
      - Can I permanently delete one attribute value by its id?
      - Does deleting a single attribute value support an If-Match ETag check?
      instructions:
      - text: Delete attribute value {id}.
        slots:
          id: path.id
      - text: Delete attribute value {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/AttributeValues({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update fields on an attribute value
      effect: write
      questions:
      - How do I deactivate an attribute value without resending the whole record?
      - Can I just change the sort position of one attribute value?
      instructions:
      - text: Set attribute value {id} active flag to {isActive}.
        slots:
          id: path.id
          isActive: requestBody.isActive
      - text: Change the sort order of attribute value {id} to {sortOrder}.
        slots:
          id: path.id
          sortOrder: requestBody.sortOrder
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/AttributeValues/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a blank attribute value template
      effect: read
      questions:
      - What default fields does a new attribute value start with?
      - Is there an empty attribute value template I can fill in before creating one?
      instructions:
      - text: Get the default attribute value template.
      - text: Show me the default values for a new attribute value.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/AttributeValues/Default.archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive attribute values via the archive action
      effect: write
      questions:
      - Can I archive attribute values with the POST archive action instead of deleting them?
      - How do I retire several attribute values through the Default.archive operation?
      instructions:
      - text: Archive attribute values {ids} using the archive action.
        slots:
          ids: query.ids
      - text: Run the POST archive action on attribute values {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/attributevalues/forproduct(productId={productId})'].get
  update:
    x-apievangelist-phrasing:
      intent: List attribute values available for a product
      effect: read
      questions:
      - Which attribute values can be assigned to a specific product?
      - Can I include or exclude archived values when listing a product's available attribute values?
      instructions:
      - text: List attribute values available for product {productId}.
        slots:
          productId: path.productId
      - text: Show attribute values for product {productId} with archive filter {archiveFilter}.
        slots:
          productId: path.productId
          archiveFilter: query.archiveFilter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/attributevalues/archive'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive attribute values via the archive route
      effect: destructive
      questions:
      - Is there a DELETE route that archives a batch of attribute values by id?
      - Can I send a list of ids to the attribute values archive endpoint?
      instructions:
      - text: Archive attribute values {ids} through the DELETE archive route.
        slots:
          ids: query.ids
      - text: Send ids {ids} to the attribute values archive route.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/attributevalues/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete attribute values
      effect: destructive
      questions:
      - Can I permanently delete many attribute values in one request?
      - How do I remove a list of attribute values by their ids all at once?
      instructions:
      - text: Bulk delete attribute values {ids}.
        slots:
          ids: query.ids
      - text: Permanently remove the attribute values with ids {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/attributevalues({key})/badges({badgeKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a badge linked to an attribute value
      effect: read
      questions:
      - Which badge is attached to a particular attribute value?
      - Can I fetch one badge through the attribute value it is linked to?
      instructions:
      - text: Get badge {badgeKey} on attribute value {key}.
        slots:
          badgeKey: path.badgeKey
          key: path.key
      - text: Show the badge {badgeKey} linked to attribute value {key} with only {select}.
        slots:
          badgeKey: path.badgeKey
          key: path.key
          select: query.$select
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/attributevalues({key})/categories({categoryKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a category linked to an attribute value
      effect: read
      questions:
      - Which catalog category is associated with a given attribute value?
      - Can I read one category through its attribute value relationship?
      instructions:
      - text: Get category {categoryKey} for attribute value {key}.
        slots:
          categoryKey: path.categoryKey
          key: path.key
      - text: Fetch category {categoryKey} under attribute value {key} expanding {expand}.
        slots:
          categoryKey: path.categoryKey
          key: path.key
          expand: query.$expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/attributevalues({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property of an attribute value
      effect: read
      questions:
      - What custom property values are stored on an attribute value?
      - Can I read one extension field from an attribute value?
      instructions:
      - text: Get custom property {custompropertyKey} of attribute value {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Read the custom field {custompropertyKey} on attribute value {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/attributevalues({key})/products({productKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a product tagged with an attribute value
      effect: read
      questions:
      - Is a specific product tagged with this attribute value?
      - Can I fetch one product through the attribute value it carries?
      instructions:
      - text: Get product {productKey} under attribute value {key}.
        slots:
          productKey: path.productKey
          key: path.key
      - text: Show product {productKey} linked to attribute value {key} with {expand} expanded.
        slots:
          productKey: path.productKey
          key: path.key
          expand: query.$expand
      method: generated
      generated: '2026-09-26'