# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for stax-api Item API
  version: 1.0.0
extends: openapi/stax-item-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['/item'].get
  update:
    x-apievangelist-phrasing:
      intent: List catalog items
      effect: read
      questions:
      - What products and services are in my merchant catalog?
      - Can I filter my catalog to only active, taxable items?
      - Which catalog items are services rather than physical goods?
      instructions:
      - text: List every item in my catalog.
      - text: Find catalog items named {name}.
        slots:
          name: query.name
      - text: Show catalog items with item code {code}.
        slots:
          code: query.code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/item'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an item to the catalog
      effect: write
      questions:
      - How do I add a new product to my Stax catalog?
      - Can I mark a new catalog item as a service or a discount when I create it?
      instructions:
      - text: Add catalog item {item} priced at {price}.
        slots:
          item: requestBody.item
          price: requestBody.price
      - text: Create catalog item {item} with code {code}, category {category} and {in_stock} in stock.
        slots:
          item: requestBody.item
          code: requestBody.code
          category: requestBody.category
          in_stock: requestBody.in_stock
      method: generated
      generated: '2026-09-26'
- target: $.paths['/item/{id}/decrement'].put
  update:
    x-apievangelist-phrasing:
      intent: Decrease an item's stock
      effect: write
      questions:
      - Can I reduce the stock count of an item after selling some offline?
      - Is there a way to subtract units from a catalog item's inventory?
      instructions:
      - text: Decrease stock of item {id} by {quantity}.
        slots:
          id: path.id
          quantity: query.quantity
      - text: Take {quantity} units out of inventory for item {id}.
        slots:
          quantity: query.quantity
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/item/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a catalog item
      effect: read
      questions:
      - What price and stock level does a specific catalog item have?
      - Can I fetch one catalog item by its ID?
      instructions:
      - text: Get catalog item {id}.
        slots:
          id: path.id
      - text: Show the price and stock for item {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/item/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a catalog item
      effect: write
      questions:
      - Can I change the price of an existing product in my catalog?
      - Is it possible to set a low-stock alert on an item I already have?
      instructions:
      - text: Update item {id} ({item}) to price {price}.
        slots:
          id: path.id
          item: requestBody.item
          price: requestBody.price
      - text: Set a low stock alert of {low_stock_alert} on existing item {id} named {item}.
        slots:
          low_stock_alert: requestBody.low_stock_alert
          id: path.id
          item: requestBody.item
      method: generated
      generated: '2026-09-26'
- target: $.paths['/item/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a catalog item
      effect: destructive
      questions:
      - Can I remove a product I no longer sell from my catalog?
      - What is involved in deleting an item from the catalog?
      instructions:
      - text: Delete catalog item {id}.
        slots:
          id: path.id
      - text: Remove item {id} from my product catalog.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/item/{id}/increment'].put
  update:
    x-apievangelist-phrasing:
      intent: Increase an item's stock
      effect: write
      questions:
      - Can I add units to an item's inventory when a new shipment arrives?
      - Is there a way to restock a catalog item by a set quantity?
      instructions:
      - text: Increase stock of item {id} by {quantity}.
        slots:
          id: path.id
          quantity: query.quantity
      - text: Restock item {id} with {quantity} more units.
        slots:
          id: path.id
          quantity: query.quantity
      method: generated
      generated: '2026-09-26'
- target: $.paths['/item/code'].get
  update:
    x-apievangelist-phrasing:
      intent: List item codes
      effect: read
      questions:
      - Which merchant-side item codes am I using across my catalog?
      - Can I get just the list of item codes without the full items?
      instructions:
      - text: List all the item codes in my catalog.
      - text: Show me the SKU-style codes I use to track items.
      method: generated
      generated: '2026-09-26'