# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Overview Discoveries API
  version: 1.0.0
extends: openapi/aftership-discoveries-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: 4
- target: $.paths['/discoveries/recommend'].post
  update:
    x-apievangelist-phrasing:
      intent: Recommend products to a shopper
      effect: read
      questions:
      - How do I show 'you may also like' product recommendations in my store?
      - Can I get recommendations based on specific products a shopper viewed?
      - Is it possible to exclude certain products from recommendations?
      instructions:
      - text: Recommend products of type {type} for store {store}.
        slots:
          type: requestBody.type
          store: header.as-store-id
      - text: Get {limit} {type} recommendations related to products {products}.
        slots:
          limit: requestBody.limit
          type: requestBody.type
          products: requestBody.products
      method: generated
      generated: '2026-09-26'
- target: $.paths['/discoveries/suggest'].post
  update:
    x-apievangelist-phrasing:
      intent: Suggest search queries as a shopper types
      effect: read
      questions:
      - Can I show autocomplete suggestions while a shopper types in my store search box?
      - What query suggestions come back for a partial search term?
      instructions:
      - text: Suggest search queries for {query} in store {store}.
        slots:
          query: requestBody.query
          store: header.as-store-id
      - text: Autocomplete {query} with up to {limit} suggestions.
        slots:
          query: requestBody.query
          limit: requestBody.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/discoveries/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search a store's products by text or image
      effect: read
      questions:
      - How do I search my store catalog by keyword?
      - Can shoppers search products using an image instead of text?
      - Can I sort and facet product search results?
      instructions:
      - text: Search store {store} for products matching {query}.
        slots:
          store: header.as-store-id
          query: requestBody.query
      - text: Find products that look like the image at {image_url}.
        slots:
          image_url: requestBody.image_url
      - text: Search products for {query} sorted by {sort}, page {page}.
        slots:
          query: requestBody.query
          sort: requestBody.sort
          page: requestBody.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/discoveries/tagging'].post
  update:
    x-apievangelist-phrasing:
      intent: Predict a product's category and tags
      effect: read
      questions:
      - Can AI suggest a category and tags for a product I'm listing?
      - How do I auto-tag a product for a specific e-commerce platform?
      instructions:
      - text: Predict the category and tags for product {product} on {platform}.
        slots:
          product: requestBody.product
          platform: requestBody.platform
      - text: Auto-tag {product} for the {platform} platform.
        slots:
          product: requestBody.product
          platform: requestBody.platform
      method: generated
      generated: '2026-09-26'