# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Product Catalog - Public Variant Data Operations API
  version: 1.0.0
extends: openapi/mapp-variant-data-operations-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['/api/product-catalog/v1/catalogs/{catalogId}/variants'].get
  update:
    x-apievangelist-phrasing:
      intent: List catalog variants page by page
      effect: read
      questions:
      - How do I page through every variant in a product catalog?
      - Can I list only variants modified within a date range?
      - Why can't I send lastId and firstId together when paging variants?
      instructions:
      - text: List variants in catalog {catalogId}, {size} per page.
        slots:
          catalogId: path.catalogId
          size: query.size
      - text: List variants in catalog {catalogId} changed since {fromModifiedTimestamp}.
        slots:
          catalogId: path.catalogId
          fromModifiedTimestamp: query.fromModifiedTimestamp
      - text: Get the next page of catalog {catalogId} after variant {lastId}.
        slots:
          catalogId: path.catalogId
          lastId: query.lastId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/product-catalog/v1/catalogs/{catalogId}/variants'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a variant without overwriting data
      effect: write
      questions:
      - Can I add a product variant and only fill in fields that are missing?
      - Does adding a variant that already exists change its current values?
      instructions:
      - text: Add variant {variant_id} to catalog {catalogId}.
        slots:
          variant_id: requestBody.variant_id
          catalogId: path.catalogId
      - text: Add variant {variant_id} in catalog {catalogId} priced {price} {currency}, keeping existing values.
        slots:
          variant_id: requestBody.variant_id
          catalogId: path.catalogId
          price: requestBody.price
          currency: requestBody.currency
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/product-catalog/v1/catalogs/{catalogId}/variants/{variantId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one variant from a catalog
      effect: read
      questions:
      - What data does the catalog hold for a single variant ID?
      - Can I see only the enriched layer of one variant's data?
      instructions:
      - text: Get variant {variantId} from catalog {catalogId}.
        slots:
          variantId: path.variantId
          catalogId: path.catalogId
      - text: Show variant {variantId} in catalog {catalogId} from the {catalogType} layer.
        slots:
          variantId: path.variantId
          catalogId: path.catalogId
          catalogType: query.catalogType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/product-catalog/v1/catalogs/{catalogId}/variants/{variantId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or fully replace a variant
      effect: write
      questions:
      - How do I completely overwrite a variant's data with a new payload?
      - Will PUT on a variant create it if it doesn't exist?
      instructions:
      - text: Replace variant {variantId} in catalog {catalogId} with this full record.
        slots:
          variantId: path.variantId
          catalogId: path.catalogId
      - text: Overwrite variant {variantId} in catalog {catalogId} with title {variant_title} and price {price}.
        slots:
          variantId: path.variantId
          catalogId: path.catalogId
          variant_title: requestBody.variant_title
          price: requestBody.price
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/product-catalog/v1/catalogs/{catalogId}/variants/{variantId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one variant
      effect: destructive
      questions:
      - How do I remove a single variant, including its enriched data?
      - Does deleting a variant also wipe its enriched attributes?
      instructions:
      - text: Delete variant {variantId} from catalog {catalogId}.
        slots:
          variantId: path.variantId
          catalogId: path.catalogId
      - text: Remove variant {variantId} and all its data from catalog {catalogId}.
        slots:
          variantId: path.variantId
          catalogId: path.catalogId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/product-catalog/v1/catalogs/{catalogId}/variants/{variantId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change selected fields on a variant
      effect: write
      questions:
      - Can I change just the price of one variant and leave the rest untouched?
      - What happens if I patch a variant that doesn't exist?
      instructions:
      - text: Set the price of variant {variantId} in catalog {catalogId} to {price}.
        slots:
          variantId: path.variantId
          catalogId: path.catalogId
          price: requestBody.price
      - text: Mark variant {variantId} in catalog {catalogId} as {availability}.
        slots:
          variantId: path.variantId
          catalogId: path.catalogId
          availability: requestBody.availability
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/product-catalog/v1/catalogs/{catalogId}/variants/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Wipe every variant from a catalog
      effect: destructive
      questions:
      - Is there a way to clear an entire product catalog's contents?
      - Can emptying a catalog of all variants be undone?
      instructions:
      - text: Delete all variants in catalog {catalogId}.
        slots:
          catalogId: path.catalogId
      - text: Empty catalog {catalogId} completely.
        slots:
          catalogId: path.catalogId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/product-catalog/v1/catalogs/{catalogId}/variants/{variantId}/attributes'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove named attributes from a variant
      effect: destructive
      questions:
      - Can I strip a few attributes off a variant without deleting it?
      - Which call removes only certain fields, like color, from a variant?
      instructions:
      - text: Delete the color and material attributes from variant {variantId} in catalog {catalogId}.
        slots:
          variantId: path.variantId
          catalogId: path.catalogId
      - text: Strip the listed attributes from variant {variantId} in catalog {catalogId}.
        slots:
          variantId: path.variantId
          catalogId: path.catalogId
      method: generated
      generated: '2026-09-26'