API Evangelist conversational phrasing for Scope3 Buyer Product Discovery API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Scope3 Buyer Product Discovery API
  version: 1.0.0
extends: openapi/scope3-product-discovery-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 9
- target: $.paths['/products/query'].post
  update:
    x-apievangelist-phrasing:
      intent: Query products across connected storefronts
      effect: read
      questions:
      - Can I send one product request to all my connected storefronts at once?
      - Is there a way to have proposals screened against my buying instructions across storefronts?
      instructions:
      - text: Query every connected storefront for {buying_mode} products matching brief {brief}.
        slots:
          buying_mode: requestBody.buying_mode
          brief: requestBody.brief
      - text: Run a cross-storefront get_products in {buying_mode} mode with filters {filters}.
        slots:
          buying_mode: requestBody.buying_mode
          filters: requestBody.filters
      method: generated
      generated: '2026-10-01'
- target: $.paths['/media-buys/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Stage products from a multi-storefront query on a campaign
      effect: write
      questions:
      - After querying several storefronts, how do I put the chosen products into a draft campaign cart?
      - Can I execute media buys straight from a cross-storefront product query?
      instructions:
      - text: Stage selections {selections} from product query {query_id} on campaign {campaign} in {mode} mode.
        slots:
          selections: requestBody.selections
          query_id: requestBody.productQueryId
          campaign: requestBody.campaign
          mode: requestBody.mode
      - text: Execute the media buys for {selections} from query {query_id} on campaign {campaign} using mode {mode}.
        slots:
          selections: requestBody.selections
          query_id: requestBody.productQueryId
          campaign: requestBody.campaign
          mode: requestBody.mode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/discovery/discover-products'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a product discovery session for an advertiser
      effect: write
      questions:
      - How do I find ad products that fit my campaign brief and budget?
      - Can I narrow product discovery to certain channels and countries?
      - Can I redeem a seller's proposal code while discovering products?
      instructions:
      - text: Discover products for advertiser {advertiser_id} matching brief {brief}.
        slots:
          advertiser_id: requestBody.advertiserId
          brief: requestBody.brief
      - text: Find {channels} products in {countries} for advertiser {advertiser_id} with a budget of {budget}.
        slots:
          channels: requestBody.channels
          countries: requestBody.countries
          advertiser_id: requestBody.advertiserId
          budget: requestBody.budget
      - text: Redeem proposal code {proposal_code} for advertiser {advertiser_id}.
        slots:
          proposal_code: requestBody.proposalCode
          advertiser_id: requestBody.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/discovery/{discoveryId}/discover-products'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse products in an existing discovery session
      effect: read
      questions:
      - Can I page through more publishers in a discovery session I already started?
      - What new products have arrived in my discovery session since the last revision?
      instructions:
      - text: Browse more products in discovery session {discovery_id}.
        slots:
          discovery_id: path.discoveryId
      - text: Show products from publisher {publisher_domain} in discovery {discovery_id}.
        slots:
          publisher_domain: query.publisherDomain
          discovery_id: path.discoveryId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/discovery/{discoveryId}/products/{productId}/details'].get
  update:
    x-apievangelist-phrasing:
      intent: View full details of a discovered product
      effect: read
      questions:
      - What pricing, delivery windows and creative formats does a discovered product require?
      - Why do I need the sales agent id to see a product's details?
      instructions:
      - text: Show details for product {product_id} in discovery {discovery_id} from sales agent {sales_agent_id}.
        slots:
          product_id: path.productId
          discovery_id: path.discoveryId
          sales_agent_id: query.salesAgentId
      - text: Get the creative format requirements of product {product_id} (discovery {discovery_id}, agent {sales_agent_id}).
        slots:
          product_id: path.productId
          discovery_id: path.discoveryId
          sales_agent_id: query.salesAgentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/discovery/{discoveryId}/products'].get
  update:
    x-apievangelist-phrasing:
      intent: List products selected in a discovery session
      effect: read
      questions:
      - Which products have I picked so far in a discovery session?
      - Can I review my current product selection before building the buy?
      instructions:
      - text: List the products I've selected in discovery {discovery_id}.
        slots:
          discovery_id: path.discoveryId
      - text: Show my current selection for discovery session {discovery_id}.
        slots:
          discovery_id: path.discoveryId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/discovery/{discoveryId}/products'].post
  update:
    x-apievangelist-phrasing:
      intent: Add discovered products to my selection
      effect: write
      questions:
      - How do I add a discovered product to my selection?
      - Can I replace my whole selection with a new set of products?
      instructions:
      - text: Add products {products} to my selection in discovery {discovery_id}.
        slots:
          products: requestBody.products
          discovery_id: path.discoveryId
      - text: Replace the selection in discovery {discovery_id} with {products} for campaign {campaign_id}.
        slots:
          discovery_id: path.discoveryId
          products: requestBody.products
          campaign_id: requestBody.campaignId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/discovery/{discoveryId}/products'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove products from my selection
      effect: destructive
      questions:
      - Can I drop a product I selected by mistake in a discovery session?
      - How do I take several products out of my selection at once?
      instructions:
      - text: Remove products {product_ids} from my selection in discovery {discovery_id}.
        slots:
          product_ids: requestBody.productIds
          discovery_id: path.discoveryId
      - text: Unselect product {product_ids} in discovery session {discovery_id}.
        slots:
          product_ids: requestBody.productIds
          discovery_id: path.discoveryId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/discovery/{discoveryId}/apply-proposal'].post
  update:
    x-apievangelist-phrasing:
      intent: Apply a sales agent's proposal to my selection
      effect: write
      questions:
      - Can a sales agent's proposal add products with suggested budget splits for me?
      - What must I do before I can apply a proposal?
      instructions:
      - text: Apply proposal {proposal_id} to discovery {discovery_id}.
        slots:
          proposal_id: requestBody.proposalId
          discovery_id: path.discoveryId
      - text: Apply proposal {proposal_id} in discovery {discovery_id} with a total budget of {total_budget}.
        slots:
          proposal_id: requestBody.proposalId
          discovery_id: path.discoveryId
          total_budget: requestBody.totalBudget
      method: generated
      generated: '2026-10-01'