# 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 Custom Reports API
  version: 1.0.0
extends: openapi/matomo-custom-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: 13
- target: $.paths['/index.php?module=API&method=CustomReports.duplicateCustomReport'].get
  update:
    x-apievangelist-phrasing:
      intent: Copy a custom report to other sites
      effect: write
      questions:
      - Can I copy a custom report I built to my other websites?
      - How do I duplicate a report definition instead of rebuilding it?
      instructions:
      - text: Duplicate custom report {idCustomReport} from site {idSite}.
        slots:
          idCustomReport: query.idCustomReport
          idSite: query.idSite
      - text: Copy custom report {idCustomReport} on site {idSite} to sites {idDestinationSites}.
        slots:
          idCustomReport: query.idCustomReport
          idSite: query.idSite
          idDestinationSites: query.idDestinationSites
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomReports.addCustomReport'].get
  update:
    x-apievangelist-phrasing:
      intent: Create a new custom report
      effect: write
      questions:
      - How do I build my own report combining the dimensions and metrics I choose in Matomo?
      - Can a new custom report be limited by a segment filter?
      instructions:
      - text: Create a {reportType} custom report {name} on site {idSite} with metrics {metricIds}.
        slots:
          reportType: query.reportType
          name: query.name
          idSite: query.idSite
          metricIds: query.metricIds
      - text: 'Build new report {name} for site {idSite}: type {reportType}, metrics {metricIds}, dimensions {dimensionIds}.'
        slots:
          name: query.name
          idSite: query.idSite
          reportType: query.reportType
          metricIds: query.metricIds
          dimensionIds: query.dimensionIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomReports.updateCustomReport'].get
  update:
    x-apievangelist-phrasing:
      intent: Edit an existing custom report
      effect: write
      questions:
      - Can I add a metric to a custom report I already created?
      - What's needed to change the dimensions of an existing custom report?
      instructions:
      - text: 'Update custom report {idCustomReport} on site {idSite}: name {name}, type {reportType}, metrics {metricIds}.'
        slots:
          idCustomReport: query.idCustomReport
          idSite: query.idSite
          name: query.name
          reportType: query.reportType
          metricIds: query.metricIds
      - text: Change existing report {idCustomReport} (site {idSite}) to use segment {segmentFilter}, keeping {name}, {reportType}, {metricIds}.
        slots:
          idCustomReport: query.idCustomReport
          idSite: query.idSite
          segmentFilter: query.segmentFilter
          name: query.name
          reportType: query.reportType
          metricIds: query.metricIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomReports.getConfiguredReports'].get
  update:
    x-apievangelist-phrasing:
      intent: List all custom report definitions on a site
      effect: read
      questions:
      - Which custom reports have been set up for my site?
      - Can I list all custom report configurations without their category info?
      instructions:
      - text: List every custom report configured for site {idSite}.
        slots:
          idSite: query.idSite
      - text: Show all custom report definitions on site {idSite}, skipping category metadata.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomReports.getConfiguredReport'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one custom report's definition
      effect: read
      questions:
      - What dimensions and metrics make up a given custom report?
      - Can I see the setup of one custom report by its ID?
      instructions:
      - text: Get the definition of custom report {idCustomReport} on site {idSite}.
        slots:
          idCustomReport: query.idCustomReport
          idSite: query.idSite
      - text: Show how custom report {idCustomReport} (site {idSite}) is configured.
        slots:
          idCustomReport: query.idCustomReport
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomReports.deleteCustomReport'].get
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom report
      effect: destructive
      questions:
      - How do I get rid of a custom report I no longer need?
      - Is deleting a custom report different from pausing it?
      instructions:
      - text: Delete custom report {idCustomReport} on site {idSite}.
        slots:
          idCustomReport: query.idCustomReport
          idSite: query.idSite
      - text: Permanently remove custom report {idCustomReport} from site {idSite}.
        slots:
          idCustomReport: query.idCustomReport
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomReports.pauseCustomReport'].get
  update:
    x-apievangelist-phrasing:
      intent: Pause a custom report
      effect: write
      questions:
      - Can I temporarily stop a custom report from processing data?
      - Is there a way to pause a report without deleting it?
      instructions:
      - text: Pause custom report {idCustomReport} on site {idSite}.
        slots:
          idCustomReport: query.idCustomReport
          idSite: query.idSite
      - text: Stop archiving custom report {idCustomReport} for site {idSite} for now.
        slots:
          idCustomReport: query.idCustomReport
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomReports.resumeCustomReport'].get
  update:
    x-apievangelist-phrasing:
      intent: Resume a paused custom report
      effect: write
      questions:
      - How do I turn a paused custom report back on?
      - Can a paused report start collecting data again?
      instructions:
      - text: Resume paused custom report {idCustomReport} on site {idSite}.
        slots:
          idCustomReport: query.idCustomReport
          idSite: query.idSite
      - text: Restart processing for custom report {idCustomReport} (site {idSite}).
        slots:
          idCustomReport: query.idCustomReport
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomReports.getAvailableCategories'].get
  update:
    x-apievangelist-phrasing:
      intent: List categories a custom report can live in
      effect: read
      questions:
      - Under which menu categories can I place a custom report?
      - What subcategories are available for custom reports on a site?
      instructions:
      - text: List the categories and subcategories for custom reports on site {idSite}.
        slots:
          idSite: query.idSite
      - text: Show where in the menu a custom report on site {idSite} can go.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomReports.getAvailableReportTypes'].get
  update:
    x-apievangelist-phrasing:
      intent: List custom report types
      effect: read
      questions:
      - What kinds of custom reports can I create, like table or evolution?
      - Which report types are supported for custom reports?
      instructions:
      - text: List the available custom report types.
      - text: Show which report type values I can pass when creating a custom report.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomReports.getAvailableDimensions'].get
  update:
    x-apievangelist-phrasing:
      intent: List dimensions usable in custom reports
      effect: read
      questions:
      - Which dimensions can I break a custom report down by?
      - What dimension IDs are available for custom reports on my site?
      instructions:
      - text: List the dimensions available for custom reports on site {idSite}.
        slots:
          idSite: query.idSite
      - text: Show dimension IDs I can use in a custom report for site {idSite}.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomReports.getAvailableMetrics'].get
  update:
    x-apievangelist-phrasing:
      intent: List metrics usable in custom reports
      effect: read
      questions:
      - Which metrics can I include in a custom report?
      - What metric IDs are allowed for custom reports on a site?
      instructions:
      - text: List the metrics available for custom reports on site {idSite}.
        slots:
          idSite: query.idSite
      - text: Show metric IDs I can add to a custom report for site {idSite}.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomReports.getCustomReport'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom report's data for a period
      effect: read
      questions:
      - What does my custom report show for last week?
      - Can I get a custom report's data flattened instead of nested?
      instructions:
      - text: Get the data of custom report {idCustomReport} for site {idSite}, {period} {date}.
        slots:
          idCustomReport: query.idCustomReport
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Run custom report {idCustomReport} on site {idSite} for {period} {date} with segment {segment}, flattened.
        slots:
          idCustomReport: query.idCustomReport
          idSite: query.idSite
          period: query.period
          date: query.date
          segment: query.segment
      method: generated
      generated: '2026-10-01'