# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Mapp Fashion Items API
  version: 1.0.0
extends: openapi/mapp-items-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: 5
- target: $.paths['/items/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details about a garment
      effect: read
      questions:
      - What information is available about a specific garment in the catalog?
      - Can I look up an item by our own SKU rather than a Dressipi ID?
      instructions:
      - text: Get the details for garment {id}.
        slots:
          id: path.id
      - text: Look up item {id} using identifier type {identifier_type}.
        slots:
          id: path.id
          identifier_type: query.identifier_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/items/top'].get
  update:
    x-apievangelist-phrasing:
      intent: Get top personalized item picks for a user
      effect: read
      questions:
      - Which items should I show a shopper on the homepage based on their profile?
      - Which department are general curated picks currently available for?
      instructions:
      - text: Get the top curated item recommendations for this user.
      - text: Show top picks for the {department} department, excluding {excluded_ids}.
        slots:
          department: query.department
          excluded_ids: query.excluded_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/items/{id}/complementary'].get
  update:
    x-apievangelist-phrasing:
      intent: Get items that complete a look with source items
      effect: read
      questions:
      - What products go well with the items a customer is viewing?
      - Can I get complementary outfit suggestions for several source items?
      instructions:
      - text: Get complementary items and outfits for item {id}.
        slots:
          id: path.id
      - text: Suggest pieces that complete the look for {id}, excluding {excluded_ids}.
        slots:
          id: path.id
          excluded_ids: query.excluded_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/items/{id}/related'].get
  update:
    x-apievangelist-phrasing:
      intent: Get similar items or outfits for one garment
      effect: read
      questions:
      - Which similar products can I show on a product detail page?
      - Can I cap how many similar items come back for one garment?
      - Is it possible to limit similar-item results to certain stores?
      instructions:
      - text: Get similar items and outfits for garment {id}.
        slots:
          id: path.id
      - text: Show up to {max_similar_items} items similar to {id}.
        slots:
          max_similar_items: query.max_similar_items
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/items/basket'].get
  update:
    x-apievangelist-phrasing:
      intent: Get recommendations based on a shopper's basket
      effect: read
      questions:
      - What should I recommend at checkout given what's in the cart?
      - Can basket recommendations work when the basket is empty?
      instructions:
      - text: Recommend items for a basket containing {ids}.
        slots:
          ids: query.ids
      - text: Get up to {max_items} basket-based recommendations for items {ids}.
        slots:
          max_items: query.max_items
          ids: query.ids
      method: generated
      generated: '2026-09-26'