# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for External Reports API
  version: 1.0.0
extends: openapi/profound-reports-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: 62
- target: $.paths['/v1/reports/citations'].post
  update:
    x-apievangelist-phrasing:
      intent: Report which sources AI answers cite
      effect: read
      questions:
      - Which websites do AI answers cite most in my category?
      - Can I limit a citations report to pages that mention my brand?
      - What is my citation share over a date range?
      instructions:
      - text: Report citation {metrics} for category {category_id} from {start_date} to {end_date}.
        slots:
          metrics: requestBody.metrics
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Break down cited domains in category {category_id} by {dimensions} between {start_date} and {end_date}, measuring {metrics}.
        slots:
          dimensions: requestBody.dimensions
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          metrics: requestBody.metrics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/citations/stream'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream the v1 citations report
      effect: read
      questions:
      - Can I stream a big citations report row by row rather than paginate it?
      - Does the streaming citations export honor the same filters as the regular report?
      instructions:
      - text: Stream citation {metrics} rows for category {category_id}, {start_date} to {end_date}.
        slots:
          metrics: requestBody.metrics
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Open a v1 cited-sources stream for category {category_id} over {start_date}–{end_date} with filters {filters} and metrics {metrics}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          filters: requestBody.filters
          metrics: requestBody.metrics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/visibility'].post
  update:
    x-apievangelist-phrasing:
      intent: Report brand visibility in AI answers
      effect: read
      questions:
      - How visible is my brand in AI-generated answers compared with competitors?
      - Can I track my visibility score week over week for a category?
      instructions:
      - text: Report visibility {metrics} for category {category_id} from {start_date} to {end_date}.
        slots:
          metrics: requestBody.metrics
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Show brand visibility in category {category_id} by {date_interval} between {start_date} and {end_date}, measuring {metrics}.
        slots:
          date_interval: requestBody.date_interval
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          metrics: requestBody.metrics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/visibility/stream'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream the v1 visibility report
      effect: read
      questions:
      - Is there a streaming version of the original visibility report?
      - Can I export a long visibility history as a stream?
      instructions:
      - text: Stream visibility {metrics} for category {category_id}, {start_date} through {end_date}.
        slots:
          metrics: requestBody.metrics
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Open a v1 brand-presence stream for category {category_id} over {start_date}–{end_date} split by {dimensions} with metrics {metrics}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          dimensions: requestBody.dimensions
          metrics: requestBody.metrics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/sentiment'].post
  update:
    x-apievangelist-phrasing:
      intent: Report sentiment toward brands in AI answers
      effect: read
      questions:
      - Do AI answers talk about my brand positively or negatively?
      - Can I see sentiment trends for my category over time?
      instructions:
      - text: Report sentiment {metrics} for category {category_id} from {start_date} to {end_date}.
        slots:
          metrics: requestBody.metrics
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Break down v1 tone of AI mentions in category {category_id} by {dimensions}, {start_date} to {end_date}, metrics {metrics}.
        slots:
          dimensions: requestBody.dimensions
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          metrics: requestBody.metrics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/sentiment/stream'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream the v1 sentiment report
      effect: read
      questions:
      - Can I stream the original sentiment report rather than wait for one big response?
      - How do I export months of sentiment rows without paging?
      instructions:
      - text: Stream sentiment {metrics} for category {category_id}, {start_date} through {end_date}.
        slots:
          metrics: requestBody.metrics
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Open a v1 tone stream for category {category_id} across {start_date}–{end_date} with filters {filters} and metrics {metrics}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          filters: requestBody.filters
          metrics: requestBody.metrics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/sentiment-v2'].post
  update:
    x-apievangelist-phrasing:
      intent: Report sentiment for one named brand
      effect: read
      questions:
      - What's the sentiment toward one specific brand by name, compared with a prior period?
      - Can I bucket a single brand's sentiment by week on the sentiment-v2 route?
      instructions:
      - text: Report sentiment {metrics} for brand {asset_name} in category {category_id} from {start_date} to {end_date}.
        slots:
          metrics: requestBody.metrics
          asset_name: requestBody.asset_name
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Compare {asset_name} sentiment {metrics} in {category_id}, {start_date}–{end_date} vs {comparison_start_date}–{comparison_end_date}, by {date_bucket}.
        slots:
          asset_name: requestBody.asset_name
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          comparison_start_date: requestBody.comparison_start_date
          comparison_end_date: requestBody.comparison_end_date
          date_bucket: requestBody.date_bucket
          metrics: requestBody.metrics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/web-search-results'].post
  update:
    x-apievangelist-phrasing:
      intent: Report web search results behind AI answers
      effect: read
      questions:
      - Which web search results do AI engines pull up for my category's prompts?
      - Can I count how often a domain appears in AI web searches?
      instructions:
      - text: Report web search result {metrics} for category {category_id} from {start_date} to {end_date}.
        slots:
          metrics: requestBody.metrics
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Show the search-engine results AI fetched in category {category_id} by {dimensions}, {start_date} to {end_date}, metrics {metrics}.
        slots:
          dimensions: requestBody.dimensions
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          metrics: requestBody.metrics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/web-search-results/stream'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream the web search results report
      effect: read
      questions:
      - Can I stream all the web search results behind AI answers?
      - Is there a streaming export of retrieved search results for a long date range?
      instructions:
      - text: Stream web search result {metrics} for category {category_id}, {start_date} through {end_date}.
        slots:
          metrics: requestBody.metrics
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Open a stream of retrieved search listings for category {category_id} over {start_date}–{end_date} with filters {filters} and metrics {metrics}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          filters: requestBody.filters
          metrics: requestBody.metrics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/referrals'].post
  update:
    x-apievangelist-phrasing:
      intent: Report daily human referrals from AI
      effect: read
      questions:
      - How much daily referral traffic are AI assistants sending to my site?
      - Can I get day-level referral numbers across a long period efficiently?
      instructions:
      - text: Report daily referral {metrics} for {domain} since {start_date}.
        slots:
          metrics: requestBody.metrics
          domain: requestBody.domain
          start_date: requestBody.start_date
      - text: Pull day-by-day referral {metrics} for {domain} between {start_date} and {end_date}.
        slots:
          domain: requestBody.domain
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          metrics: requestBody.metrics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/bots'].post
  update:
    x-apievangelist-phrasing:
      intent: Report daily AI bot traffic to a domain
      effect: read
      questions:
      - How many AI crawler visits did my site get each day?
      - Can I see daily counts of training versus indexing bot events over a long date range?
      instructions:
      - text: Report daily bot {metrics} for {domain} since {start_date}.
        slots:
          metrics: requestBody.metrics
          domain: requestBody.domain
          start_date: requestBody.start_date
      - text: Pull the day-level crawler {metrics} for {domain} from {start_date} to {end_date}.
        slots:
          domain: requestBody.domain
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          metrics: requestBody.metrics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/query-fanouts'].post
  update:
    x-apievangelist-phrasing:
      intent: Report AI query fan-outs
      effect: read
      questions:
      - What follow-up searches do AI engines fan out to when answering my prompts?
      - Can I count the sub-queries generated per prompt in a category?
      instructions:
      - text: Report query fan-out {metrics} for category {category_id} from {start_date} to {end_date}.
        slots:
          metrics: requestBody.metrics
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Show the sub-searches AI ran in category {category_id} grouped by {dimensions}, {start_date} to {end_date}, using the v1 fan-out report with metrics {metrics}.
        slots:
          dimensions: requestBody.dimensions
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          metrics: requestBody.metrics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/shopping/visibility'].post
  update:
    x-apievangelist-phrasing:
      intent: Report brand visibility in AI shopping results
      effect: read
      questions:
      - How often does my brand show up in AI shopping recommendations?
      - Can I rank brands by shopping visibility against a previous period?
      instructions:
      - text: Show how often brands appear in AI shopping results for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Rank brands in AI shopping for category {category_id} by {rank_by}, {start_date} to {end_date}, versus {comparison_start_date}–{comparison_end_date}.
        slots:
          category_id: requestBody.category_id
          rank_by: requestBody.rank_by
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          comparison_start_date: requestBody.comparison_start_date
          comparison_end_date: requestBody.comparison_end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/shopping/item-visibility'].post
  update:
    x-apievangelist-phrasing:
      intent: Report product visibility in AI shopping
      effect: read
      questions:
      - Which of my products appear in AI shopping carousels, and how often?
      - Can I compare one target product against its competing items?
      instructions:
      - text: Report item-level shopping visibility for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Compare product {target_product} with up to {competitor_limit} rival items in category {category_id}, {start_date}–{end_date}.
        slots:
          target_product: requestBody.target_product
          competitor_limit: requestBody.competitor_limit
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/shopping/merchant-distribution'].post
  update:
    x-apievangelist-phrasing:
      intent: Report which merchants AI shopping shows
      effect: read
      questions:
      - Which retailers get surfaced most in AI shopping answers for my category?
      - Can I look up how often one merchant appears?
      instructions:
      - text: Show the merchant distribution for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Find how retailer {search_merchant} is spread across AI shopping in category {category_id}, {start_date}–{end_date}.
        slots:
          search_merchant: requestBody.search_merchant
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/shopping/merchant-visibility-by-brand'].post
  update:
    x-apievangelist-phrasing:
      intent: Report merchant visibility for each brand
      effect: read
      questions:
      - Which stores carry my brand when AI recommends products?
      - Can I see merchant visibility for just one brand?
      instructions:
      - text: Show merchant visibility by brand in category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: List which retailers surface brand {search_brand} in category {category_id}, {start_date}–{end_date}.
        slots:
          search_brand: requestBody.search_brand
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/shopping/merchant-by-items'].post
  update:
    x-apievangelist-phrasing:
      intent: Report merchants offering each product
      effect: read
      questions:
      - Which merchants does AI shopping list for a particular product?
      - Can I break merchants down item by item?
      instructions:
      - text: Show merchants by item in category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: List the sellers shown for product {product_name} in category {category_id}, {start_date}–{end_date}.
        slots:
          product_name: requestBody.product_name
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/shopping/all-items-with-merchants'].post
  update:
    x-apievangelist-phrasing:
      intent: List all shopping items with their merchants
      effect: read
      questions:
      - Can I get the full catalog of products AI shopping showed, each with its merchants?
      - Is it possible to sort every shopping item by rank?
      instructions:
      - text: List every shopping item and its merchants for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Dump all products with sellers in category {category_id}, {start_date}–{end_date}, ranked by {rank_by} in {sort_order} order.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          rank_by: requestBody.rank_by
          sort_order: requestBody.sort_order
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/shopping/trigger-rate'].post
  update:
    x-apievangelist-phrasing:
      intent: Report how often prompts trigger shopping
      effect: read
      questions:
      - What percentage of my prompts make AI show shopping results?
      - Has the shopping trigger rate changed versus last month?
      instructions:
      - text: Report the shopping trigger rate for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Compare prompts producing product cards in {category_id}, {start_date}–{end_date} vs {comparison_start_date}–{comparison_end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          comparison_start_date: requestBody.comparison_start_date
          comparison_end_date: requestBody.comparison_end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/shopping/triggered-prompts'].post
  update:
    x-apievangelist-phrasing:
      intent: List prompts that triggered shopping results
      effect: read
      questions:
      - Which exact prompts caused AI to show shopping results?
      - Can I exclude certain topics when listing shopping-triggering prompts?
      instructions:
      - text: List prompts that triggered shopping in category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Show which questions led to product listings in category {category_id}, {start_date}–{end_date}, excluding topics {exclude_topic_ids}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          exclude_topic_ids: requestBody.exclude_topic_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/shopping/triggered-topics'].post
  update:
    x-apievangelist-phrasing:
      intent: List topics that triggered shopping results
      effect: read
      questions:
      - Which topics are most likely to trigger AI shopping results?
      - Can I include untagged prompts when ranking shopping-triggering topics?
      instructions:
      - text: List topics that triggered shopping in category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Rank subject areas by shopping activation in category {category_id}, {start_date}–{end_date}, including untagged {include_no_tag}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          include_no_tag: requestBody.include_no_tag
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/shopping/merchant-share'].post
  update:
    x-apievangelist-phrasing:
      intent: Report merchant share for target brands
      effect: read
      questions:
      - What share of AI shopping placements does each merchant hold for my brands?
      - Can I calculate merchant share for a specific set of brands?
      instructions:
      - text: Report merchant share in category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Calculate each retailer's slice of placements for brands {target_asset_names} in category {category_id}, {start_date}–{end_date}.
        slots:
          target_asset_names: requestBody.target_asset_names
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/shopping/product-merchant-urls'].post
  update:
    x-apievangelist-phrasing:
      intent: Get merchant URLs for named products
      effect: read
      questions:
      - Which merchant links does AI shopping give for my products?
      - Can I get the store URLs for a list of product names?
      instructions:
      - text: Get merchant URLs for products {product_names} in category {category_id} from {start_date} to {end_date}.
        slots:
          product_names: requestBody.product_names
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Show the store links listed for {product_names} in category {category_id}, {start_date}–{end_date}.
        slots:
          product_names: requestBody.product_names
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/shopping/executions'].post
  update:
    x-apievangelist-phrasing:
      intent: List individual shopping prompt executions
      effect: read
      questions:
      - Can I see each individual prompt run that produced shopping results?
      - Is it possible to filter shopping executions by analysis type?
      instructions:
      - text: List shopping executions for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Show each shopping run in category {category_id}, {start_date}–{end_date}, with analysis types {analysis_types}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          analysis_types: requestBody.analysis_types
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/accuracy/overview'].post
  update:
    x-apievangelist-phrasing:
      intent: Get an overview of AI answer accuracy
      effect: read
      questions:
      - How accurately do AI answers describe my brand overall?
      - Has answer accuracy improved compared with the previous period?
      instructions:
      - text: Give me the accuracy overview for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Summarize answer correctness in category {category_id}, {start_date}–{end_date}, bucketed by {date_bucket}, grouped by {group_by}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          date_bucket: requestBody.date_bucket
          group_by: requestBody.group_by
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/accuracy/breakdown'].post
  update:
    x-apievangelist-phrasing:
      intent: Break down AI answer accuracy by dimension
      effect: read
      questions:
      - Which platforms or topics have the least accurate answers about us?
      - Can I split accuracy by region or persona and sort the results?
      instructions:
      - text: Break down accuracy by {breakdown_by} for category {category_id} from {start_date} to {end_date}.
        slots:
          breakdown_by: requestBody.breakdown_by
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Split correctness rates in category {category_id}, {start_date}–{end_date}, by {breakdown_by} sorted on {sort_by}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          breakdown_by: requestBody.breakdown_by
          sort_by: requestBody.sort_by
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/accuracy/citation-analysis'].post
  update:
    x-apievangelist-phrasing:
      intent: Analyze accuracy for one cited URL
      effect: read
      questions:
      - Is a specific cited page leading AI to say inaccurate things about us?
      - Can I check accuracy for answers that cite one particular URL?
      instructions:
      - text: Analyze accuracy for cited URL {clean_href} in category {category_id} from {start_date} to {end_date}.
        slots:
          clean_href: requestBody.clean_href
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Check whether page {clean_href} drives wrong answers in category {category_id}, {start_date}–{end_date}.
        slots:
          clean_href: requestBody.clean_href
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/accuracy/topic-ids'].post
  update:
    x-apievangelist-phrasing:
      intent: List topics with accuracy data
      effect: read
      questions:
      - Which topics have fact-check accuracy data in a date range?
      - Where can I get the topic IDs to filter accuracy reports by?
      instructions:
      - text: List the topic IDs with accuracy data in category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Which topics were fact-checked in category {category_id} between {start_date} and {end_date}? Get their IDs.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/accuracy/inaccurate-themes'].post
  update:
    x-apievangelist-phrasing:
      intent: List recurring themes of inaccurate answers
      effect: read
      questions:
      - What recurring themes show up in AI's wrong answers about my brand?
      - Can I search inaccurate themes by keyword?
      instructions:
      - text: List inaccurate themes for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Find misinformation themes matching {search_query} in category {category_id}, {start_date}–{end_date}.
        slots:
          search_query: requestBody.search_query
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/accuracy/inaccurate-clusters'].post
  update:
    x-apievangelist-phrasing:
      intent: List clusters of similar inaccurate claims
      effect: read
      questions:
      - How are similar wrong claims about us grouped into clusters?
      - Can I see the inaccurate claim clusters under one theme, with the models involved?
      instructions:
      - text: List inaccurate claim clusters for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Show the error clusters within theme {theme_id} in category {category_id}, {start_date}–{end_date}, including models {include_models}.
        slots:
          theme_id: requestBody.theme_id
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          include_models: requestBody.include_models
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/accuracy/inaccuracy-drivers'].post
  update:
    x-apievangelist-phrasing:
      intent: Find what drives inaccurate AI answers
      effect: read
      questions:
      - What's driving AI to give inaccurate answers about my company?
      - Can I narrow the inaccuracy drivers to certain platforms?
      instructions:
      - text: Show the inaccuracy drivers for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Identify the top {limit} causes of wrong answers on platforms {platform_ids} in category {category_id}, {start_date}–{end_date}.
        slots:
          limit: requestBody.limit
          platform_ids: requestBody.platform_ids
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/accuracy/top-inaccurate-claims'].post
  update:
    x-apievangelist-phrasing:
      intent: List the most common inaccurate claims
      effect: read
      questions:
      - What are the most frequent false statements AI makes about us?
      - Can I get just the top few inaccurate claims for one persona?
      instructions:
      - text: List the top inaccurate claims for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Give me the {limit} most repeated false statements for personas {persona_ids} in category {category_id}, {start_date}–{end_date}.
        slots:
          limit: requestBody.limit
          persona_ids: requestBody.persona_ids
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/accuracy/claim-breakdown'].post
  update:
    x-apievangelist-phrasing:
      intent: Break down one inaccurate claim cluster
      effect: read
      questions:
      - Can I drill into a single cluster of inaccurate claims to see its breakdown?
      - Where does one specific false claim cluster appear most?
      instructions:
      - text: Break down claim cluster {cluster_id} in category {category_id} from {start_date} to {end_date}.
        slots:
          cluster_id: requestBody.cluster_id
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Drill into wrong-claim group {cluster_id} for category {category_id}, {start_date}–{end_date}.
        slots:
          cluster_id: requestBody.cluster_id
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/accuracy/claim-citations'].post
  update:
    x-apievangelist-phrasing:
      intent: List sources cited by an inaccurate claim cluster
      effect: read
      questions:
      - Which sources are cited alongside a cluster of inaccurate claims?
      - Can I search the citations behind one false claim group?
      instructions:
      - text: List citations for claim cluster {cluster_id} in category {category_id} from {start_date} to {end_date}.
        slots:
          cluster_id: requestBody.cluster_id
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Find sources matching {search_query} behind wrong-claim group {cluster_id}, category {category_id}, {start_date}–{end_date}.
        slots:
          search_query: requestBody.search_query
          cluster_id: requestBody.cluster_id
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/accuracy/cluster-example-runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Show example answers for a claim cluster
      effect: read
      questions:
      - Can I see real AI answers that contained a particular inaccurate claim?
      - How do I page through example runs for one claim cluster?
      instructions:
      - text: Show example runs for claim cluster {cluster_id} in category {category_id} from {start_date} to {end_date}.
        slots:
          cluster_id: requestBody.cluster_id
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Pull {limit} sample responses containing error group {cluster_id}, category {category_id}, {start_date}–{end_date}.
        slots:
          limit: requestBody.limit
          cluster_id: requestBody.cluster_id
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/accuracy/cluster-verification-pairs'].post
  update:
    x-apievangelist-phrasing:
      intent: Get verification pairs for a claim cluster
      effect: read
      questions:
      - How was a cluster of claims verified against the facts?
      - Can I see the claim-versus-evidence pairs behind one inaccurate cluster?
      instructions:
      - text: Get verification pairs for claim cluster {cluster_id} in category {category_id}.
        slots:
          cluster_id: requestBody.cluster_id
          category_id: requestBody.category_id
      - text: Show the claim and evidence pairings used to verify group {cluster_id} in category {category_id}.
        slots:
          cluster_id: requestBody.cluster_id
          category_id: requestBody.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/reports/accuracy/factcheck-setup-status'].post
  update:
    x-apievangelist-phrasing:
      intent: Check fact-check setup status for a category
      effect: read
      questions:
      - Is fact-checking set up for my category yet?
      - Why might accuracy reports be empty for a category?
      instructions:
      - text: Check the fact-check setup status for category {category_id}.
        slots:
          category_id: requestBody.category_id
      - text: Is accuracy tracking configured for category {category_id}? Confirm it.
        slots:
          category_id: requestBody.category_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/referrals'].post
  update:
    x-apievangelist-phrasing:
      intent: Report hourly human referrals from AI
      effect: read
      questions:
      - Which hours of the day bring the most AI-referred visitors to my site?
      - Is there a referral report that supports hourly, quarterly or relative-week intervals?
      instructions:
      - text: Show hourly referral {metrics} for {domain} from {start_date}.
        slots:
          metrics: requestBody.metrics
          domain: requestBody.domain
          start_date: requestBody.start_date
      - text: Get v2 referral {metrics} for {domain} at {date_interval} intervals in timezone {timezone} from {start_date}.
        slots:
          domain: requestBody.domain
          date_interval: requestBody.date_interval
          timezone: requestBody.timezone
          start_date: requestBody.start_date
          metrics: requestBody.metrics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/bots'].post
  update:
    x-apievangelist-phrasing:
      intent: Report hourly AI bot traffic to a domain
      effect: read
      questions:
      - Which AI bots hit my site hour by hour, and on which paths?
      - Can I break bot visits down by bot provider and bot type in my own timezone?
      instructions:
      - text: Show hourly bot {metrics} for {domain} starting {start_date}, grouped by {dimensions}.
        slots:
          metrics: requestBody.metrics
          domain: requestBody.domain
          start_date: requestBody.start_date
          dimensions: requestBody.dimensions
      - text: Get v2 bot {metrics} for {domain} from {start_date} at {date_interval} granularity in timezone {timezone}.
        slots:
          domain: requestBody.domain
          start_date: requestBody.start_date
          date_interval: requestBody.date_interval
          timezone: requestBody.timezone
          metrics: requestBody.metrics
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/visibility'].post
  update:
    x-apievangelist-phrasing:
      intent: Query brand visibility (v2, cursor-paged)
      effect: read
      questions:
      - Is there a newer visibility report that lets me pick which brands to compare?
      - Can I page through v2 visibility results with a cursor?
      instructions:
      - text: Query v2 visibility for category {category_id} from {start_date} to {end_date} for assets {assets}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          assets: requestBody.assets
      - text: Group v2 brand presence in category {category_id} by {group_by} at {interval} intervals, {start_date}–{end_date}, from cursor {cursor}.
        slots:
          category_id: requestBody.category_id
          group_by: requestBody.group_by
          interval: requestBody.interval
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          cursor: requestBody.cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/visibility/stream'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream brand visibility (v2)
      effect: read
      questions:
      - Can I stream the v2 visibility data instead of paging with a cursor?
      - How do I export all v2 visibility rows for a brand set in one stream?
      instructions:
      - text: Stream v2 visibility for category {category_id} from {start_date} through {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Open a v2 presence stream for assets {assets} in category {category_id}, {start_date}–{end_date}, scope {scope}.
        slots:
          assets: requestBody.assets
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          scope: requestBody.scope
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/citations'].post
  update:
    x-apievangelist-phrasing:
      intent: Query cited sources (v2, cursor-paged)
      effect: read
      questions:
      - Can the newer citations report rank cited domains or pages as different entities?
      - How do I page through v2 citation results?
      instructions:
      - text: Query v2 citations for category {category_id} from {start_date} to {end_date} by entity {entity}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          entity: requestBody.entity
      - text: Group v2 cited sources in category {category_id} by {group_by}, {start_date}–{end_date}, {limit} rows from cursor {cursor}.
        slots:
          category_id: requestBody.category_id
          group_by: requestBody.group_by
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          limit: requestBody.limit
          cursor: requestBody.cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/citations/stream'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream cited sources (v2)
      effect: read
      questions:
      - Is there a streaming version of the v2 citations report?
      - Can I stream every v2 citation row for a long date range?
      instructions:
      - text: Stream v2 citations for category {category_id} from {start_date} through {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Open a v2 referenced-sources stream for category {category_id}, {start_date}–{end_date}, entity {entity}, at {interval} intervals.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          entity: requestBody.entity
          interval: requestBody.interval
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/sentiment'].post
  update:
    x-apievangelist-phrasing:
      intent: Query brand sentiment (v2, cursor-paged)
      effect: read
      questions:
      - Can the v2 sentiment report show which websites were cited in positive or negative answers?
      - How do I compare a brand's v2 sentiment against an earlier window?
      instructions:
      - text: Query v2 sentiment for asset {asset} in category {category_id} from {start_date} to {end_date}.
        slots:
          asset: requestBody.asset
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Compare v2 tone for {asset} in {category_id}, {start_date}–{end_date} vs {comparison_start_date}–{comparison_end_date}, cited sites {include_cited_websites}.
        slots:
          asset: requestBody.asset
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          comparison_start_date: requestBody.comparison_start_date
          comparison_end_date: requestBody.comparison_end_date
          include_cited_websites: requestBody.include_cited_websites
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/sentiment/stream'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream brand sentiment (v2)
      effect: read
      questions:
      - Can I stream v2 sentiment rows for a brand rather than page them?
      - Is there a streaming export of the newer per-asset sentiment report?
      instructions:
      - text: Stream v2 sentiment for asset {asset} in category {category_id} from {start_date} through {end_date}.
        slots:
          asset: requestBody.asset
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Open a v2 tone stream for brand {asset}, category {category_id}, {start_date}–{end_date}, grouped by {group_by}.
        slots:
          asset: requestBody.asset
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          group_by: requestBody.group_by
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/query-fanouts'].post
  update:
    x-apievangelist-phrasing:
      intent: Query AI query fan-outs (v2, cursor-paged)
      effect: read
      questions:
      - Is there a newer fan-out report I can page with a cursor?
      - Can I sort the v2 sub-query results by a metric?
      instructions:
      - text: Query v2 fan-outs for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Group v2 follow-up searches in category {category_id} by {group_by}, sorted by {sort}, {start_date}–{end_date}, from cursor {cursor}.
        slots:
          category_id: requestBody.category_id
          group_by: requestBody.group_by
          sort: requestBody.sort
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          cursor: requestBody.cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/query-fanouts/stream'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream AI query fan-outs (v2)
      effect: read
      questions:
      - Can I stream every fan-out sub-query for a category?
      - Is there a streaming export for the v2 fan-out data?
      instructions:
      - text: Stream v2 fan-outs for category {category_id} from {start_date} through {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Open a stream of AI sub-searches in category {category_id}, {start_date}–{end_date}, filtered by {filter}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          filter: requestBody.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/factcheck'].post
  update:
    x-apievangelist-phrasing:
      intent: Query fact-check accuracy scores
      effect: read
      questions:
      - What fact-check scores did AI answers get for my category?
      - Can I group fact-check scores by platform or topic?
      instructions:
      - text: Query fact-check scores for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Group factcheck scoring in category {category_id} by {group_by}, {start_date}–{end_date}, {limit} per page.
        slots:
          category_id: requestBody.category_id
          group_by: requestBody.group_by
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          limit: requestBody.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/factcheck/stream'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream fact-check accuracy scores
      effect: read
      questions:
      - Can I stream fact-check scores rather than paging through them?
      - Is there a streaming export of factcheck scoring for a long period?
      instructions:
      - text: Stream fact-check scores for category {category_id} from {start_date} through {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Open a factcheck scoring stream for category {category_id}, {start_date}–{end_date}, filtered by {filter}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          filter: requestBody.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/factcheck/claims'].post
  update:
    x-apievangelist-phrasing:
      intent: Query fact-checked claims
      effect: read
      questions:
      - Which individual claims in AI answers were fact-checked, and what was the verdict?
      - Can I page through fact-checked claims for one topic?
      instructions:
      - text: Query fact-checked claims for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: List verified statements in category {category_id}, {start_date}–{end_date}, filtered by {filter}, from cursor {cursor}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          filter: requestBody.filter
          cursor: requestBody.cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/factcheck/claims/stream'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream fact-checked claims
      effect: read
      questions:
      - Can I stream all the fact-checked claims for my category?
      - Is there a streaming export of claim-level fact-check verdicts?
      instructions:
      - text: Stream fact-checked claims for category {category_id} from {start_date} through {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Open a stream of claim verdicts in category {category_id}, {start_date}–{end_date}, including {include}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          include: requestBody.include
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/social/youtube/channels'].post
  update:
    x-apievangelist-phrasing:
      intent: Rank YouTube channels cited by AI
      effect: read
      questions:
      - Which YouTube channels get cited in AI answers for my category?
      - Can I rank the video categories those cited channels publish in?
      instructions:
      - text: Rank cited YouTube channels for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Group cited YouTube creators in category {category_id} by {group_by} at {interval} intervals, {start_date}–{end_date}.
        slots:
          category_id: requestBody.category_id
          group_by: requestBody.group_by
          interval: requestBody.interval
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/social/youtube/videos'].post
  update:
    x-apievangelist-phrasing:
      intent: Rank YouTube videos cited by AI
      effect: read
      questions:
      - Which specific YouTube videos do AI answers cite in my category?
      - Can I rank cited videos for just one channel?
      instructions:
      - text: Rank cited YouTube videos for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: List the top {limit} referenced YouTube clips in category {category_id}, {start_date}–{end_date}, filtered by {filter}.
        slots:
          limit: requestBody.limit
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          filter: requestBody.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/social/youtube/summary'].post
  update:
    x-apievangelist-phrasing:
      intent: Summarize YouTube's share of AI citations
      effect: read
      questions:
      - How much of the YouTube citations in my category do the channel and video rankings cover?
      - What share of youtube.com citations are attributed?
      instructions:
      - text: Summarize YouTube citation coverage for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Report how much of youtube.com the rankings account for in category {category_id}, {start_date}–{end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/shopping/brands'].post
  update:
    x-apievangelist-phrasing:
      intent: Query brands in AI shopping (v2)
      effect: read
      questions:
      - Which brands lead AI shopping results in the newer v2 report?
      - Can I page v2 shopping brand results for selected assets?
      instructions:
      - text: Query v2 shopping brands for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Group v2 shopping brand placements for assets {assets} in category {category_id} by {group_by}, {start_date}–{end_date}.
        slots:
          assets: requestBody.assets
          category_id: requestBody.category_id
          group_by: requestBody.group_by
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/shopping/brands/stream'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream brands in AI shopping (v2)
      effect: read
      questions:
      - Can I stream the v2 shopping brand data?
      - Is there a streaming export of brand placements in AI shopping?
      instructions:
      - text: Stream v2 shopping brands for category {category_id} from {start_date} through {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Open a brand-placement stream for AI shopping in category {category_id}, {start_date}–{end_date}, scope {scope}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          scope: requestBody.scope
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/shopping/products'].post
  update:
    x-apievangelist-phrasing:
      intent: Query products in AI shopping (v2)
      effect: read
      questions:
      - Which products does AI shopping recommend in the v2 product report?
      - Can I benchmark one product against competitors and include merchants?
      instructions:
      - text: Query v2 shopping products for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Benchmark product {target_product} against {competitor_limit} competitors in v2 shopping for category {category_id}, {start_date}–{end_date}.
        slots:
          target_product: requestBody.target_product
          competitor_limit: requestBody.competitor_limit
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/shopping/products/stream'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream products in AI shopping (v2)
      effect: read
      questions:
      - Can I stream v2 shopping product rows?
      - Is there a streaming export of recommended products with their merchants?
      instructions:
      - text: Stream v2 shopping products for category {category_id} from {start_date} through {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Open an item stream for AI shopping in category {category_id}, {start_date}–{end_date}, with merchants {include_merchants}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          include_merchants: requestBody.include_merchants
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/shopping/merchants'].post
  update:
    x-apievangelist-phrasing:
      intent: Query merchants in AI shopping (v2)
      effect: read
      questions:
      - Which merchants appear most in the v2 shopping merchant report?
      - Can I group v2 merchant results over time intervals?
      instructions:
      - text: Query v2 shopping merchants for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Group v2 retailer appearances in category {category_id} by {group_by} at {interval}, {start_date}–{end_date}.
        slots:
          category_id: requestBody.category_id
          group_by: requestBody.group_by
          interval: requestBody.interval
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/shopping/merchants/stream'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream merchants in AI shopping (v2)
      effect: read
      questions:
      - Can I stream v2 shopping merchant data?
      - Is there a streaming export of the retailers AI shopping surfaces?
      instructions:
      - text: Stream v2 shopping merchants for category {category_id} from {start_date} through {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Open a retailer stream for AI shopping in category {category_id}, {start_date}–{end_date}, filtered by {filter}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          filter: requestBody.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/shopping/trigger-rate'].post
  update:
    x-apievangelist-phrasing:
      intent: Query shopping trigger rate (v2)
      effect: read
      questions:
      - What's the v2 shopping trigger rate for my category?
      - Can I group the v2 trigger rate by platform or topic?
      instructions:
      - text: Query the v2 shopping trigger rate for category {category_id} from {start_date} to {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Group v2 shopping activation rates in category {category_id} by {group_by}, {start_date}–{end_date}, at {interval}.
        slots:
          category_id: requestBody.category_id
          group_by: requestBody.group_by
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          interval: requestBody.interval
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/reports/shopping/trigger-rate/stream'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream shopping trigger rate (v2)
      effect: read
      questions:
      - Can I stream the v2 shopping trigger rate?
      - Is there a streaming export of how often prompts trigger product results?
      instructions:
      - text: Stream the v2 shopping trigger rate for category {category_id} from {start_date} through {end_date}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      - text: Open an activation-rate stream for AI shopping in category {category_id}, {start_date}–{end_date}, filtered by {filter}.
        slots:
          category_id: requestBody.category_id
          start_date: requestBody.start_date
          end_date: requestBody.end_date
          filter: requestBody.filter
      method: generated
      generated: '2026-10-01'