# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Matomo Reporting API for plugin Insights API
  version: 1.0.0
extends: openapi/matomo-insights-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: 5
- target: $.paths['/index.php?module=API&method=Insights.canGenerateInsights'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if insights can run for a period
      effect: read
      questions:
      - Can insights be generated for a yearly period, or only shorter ones?
      - Is this date and period combination supported for insights?
      instructions:
      - text: Check whether insights can be generated for {period} {date}.
        slots:
          period: query.period
          date: query.date
      - text: Confirm insights support for period {period} on {date}.
        slots:
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Insights.getInsightsOverview'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an insights overview across reports
      effect: read
      questions:
      - What notable changes happened across my main reports this week in Matomo?
      - Can I get a quick overview of what grew or dropped compared to the previous period?
      instructions:
      - text: Get the insights overview for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Summarize the key growth and decline insights on site {idSite} for {period} {date}, segment {segment}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
          segment: query.segment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Insights.getMoversAndShakersOverview'].get
  update:
    x-apievangelist-phrasing:
      intent: Get movers and shakers across reports
      effect: read
      questions:
      - Which pages, referrers or countries moved the needle most across all reports?
      - Is there an overview of the biggest movers and shakers for my site?
      instructions:
      - text: Get the movers and shakers overview for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show the biggest outsized changes across all reports on site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Insights.getMoversAndShakers'].get
  update:
    x-apievangelist-phrasing:
      intent: Find movers and shakers in one report
      effect: read
      questions:
      - In a single report, which rows changed far more than the site average?
      - Can I limit how many increasers and decreasers are returned for one report?
      instructions:
      - text: Find movers and shakers in report {reportUniqueId} for site {idSite}, {period} {date}.
        slots:
          reportUniqueId: query.reportUniqueId
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show the top {limitIncreaser} risers in report {reportUniqueId} for site {idSite}, {period} {date}.
        slots:
          limitIncreaser: query.limitIncreaser
          reportUniqueId: query.reportUniqueId
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Insights.getInsights'].get
  update:
    x-apievangelist-phrasing:
      intent: Compare a report against another period
      effect: read
      questions:
      - Which rows of a report grew by more than 20% versus the previous period?
      - Can I ignore small changes and only see rows with meaningful growth?
      - Can I compare a report to several periods back, not just the previous one?
      instructions:
      - text: Generate insights for report {reportUniqueId} on site {idSite}, {period} {date}.
        slots:
          reportUniqueId: query.reportUniqueId
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show rows of {reportUniqueId} on site {idSite} ({period} {date}) with at least {minGrowthPercent}% growth.
        slots:
          reportUniqueId: query.reportUniqueId
          idSite: query.idSite
          period: query.period
          date: query.date
          minGrowthPercent: query.minGrowthPercent
      - text: Compare report {reportUniqueId} for site {idSite}, {period} {date}, against {comparedToXPeriods} periods earlier.
        slots:
          reportUniqueId: query.reportUniqueId
          idSite: query.idSite
          period: query.period
          date: query.date
          comparedToXPeriods: query.comparedToXPeriods
      method: generated
      generated: '2026-10-01'