API Evangelist conversational phrasing for Matomo Index.php API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Matomo Index.php API
  version: 1.0.0
extends: openapi/matomo-index-php-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: 19
- target: $.paths['/index.php?module=API&method=API.getMatomoVersion'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the installed Matomo version
      effect: read
      questions:
      - Which Matomo version is this server running?
      - Is my analytics instance up to date with the latest release number?
      instructions:
      - text: Tell me the installed Matomo version.
      - text: Check what release of the analytics software this instance runs.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=API.getPhpVersion'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the server's PHP version
      effect: read
      questions:
      - What PHP version is the analytics server using?
      - Can I check the PHP runtime before upgrading a plugin?
      instructions:
      - text: Report the PHP runtime version on the server.
      - text: Show the PHP version information.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=API.getIpFromHeader'].get
  update:
    x-apievangelist-phrasing:
      intent: See the IP address the server detects for me
      effect: read
      questions:
      - What IP address does the server think I'm calling from?
      - Is my proxy setup passing through the real client IP?
      instructions:
      - text: Show the IP address detected for my request.
      - text: Check which client IP the server reads from the headers.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=API.getSegmentsMetadata'].get
  update:
    x-apievangelist-phrasing:
      intent: List all available segment dimensions
      effect: read
      questions:
      - Which dimensions can I segment my reports by?
      - What segment names and operators are available for a given site?
      instructions:
      - text: List metadata for every available segment.
      - text: Show the segments available for sites {idSites}.
        slots:
          idSites: query.idSites
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=API.getMetadata'].get
  update:
    x-apievangelist-phrasing:
      intent: Describe a single API report method
      effect: read
      questions:
      - What metrics and dimensions does a specific report method return?
      - Can I get the documentation metadata for one module and action?
      instructions:
      - text: Get metadata for report {apiModule}.{apiAction} on site {idSite}.
        slots:
          apiModule: query.apiModule
          apiAction: query.apiAction
          idSite: query.idSite
      - text: Describe the {apiModule}.{apiAction} report for site {idSite} in {language}.
        slots:
          apiModule: query.apiModule
          apiAction: query.apiAction
          idSite: query.idSite
          language: query.language
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=API.getReportMetadata'].get
  update:
    x-apievangelist-phrasing:
      intent: List metadata for all available reports
      effect: read
      questions:
      - What reports can I pull from this analytics instance?
      - Is there a catalog of every report with its metrics and dimensions?
      instructions:
      - text: List metadata for all available reports.
      - text: Show the full report catalog for site {idSite}.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=API.getProcessedReport'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a formatted report with metadata
      effect: read
      questions:
      - Can I fetch a report already formatted, with processed metrics and column labels?
      - How do I get a report's data plus its metadata in one response?
      instructions:
      - text: Get the processed {apiModule}.{apiAction} report for site {idSite}, {period} {date}.
        slots:
          apiModule: query.apiModule
          apiAction: query.apiAction
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Fetch the formatted {apiModule}.{apiAction} report for site {idSite}, {period} {date}, segmented by {segment}.
        slots:
          apiModule: query.apiModule
          apiAction: query.apiAction
          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=API.getReportPagesMetadata'].get
  update:
    x-apievangelist-phrasing:
      intent: List the dashboard UI pages and their widgets
      effect: read
      questions:
      - Which pages does the reporting UI have, and what widgets sit on each?
      - Can I see the menu structure of reporting pages for a site?
      instructions:
      - text: List the UI report pages and their widgets for site {idSite}.
        slots:
          idSite: query.idSite
      - text: Show the reporting page layout for site {idSite}.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=API.getWidgetMetadata'].get
  update:
    x-apievangelist-phrasing:
      intent: List all widgets available in the UI
      effect: read
      questions:
      - What widgets can be added to a dashboard?
      - Can I get a list of every embeddable widget for a site?
      instructions:
      - text: List all available widgets for site {idSite}.
        slots:
          idSite: query.idSite
      - text: Show the widget catalog I can embed for site {idSite}.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=API.get'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a combined key-metrics report
      effect: read
      questions:
      - Can I get visits, actions, goals and other headline numbers in one combined call?
      - What's the overall summary of my site's metrics for yesterday?
      instructions:
      - text: Get the combined key metrics for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Pull only columns {columns} from the combined summary for site {idSite}, {period} {date}.
        slots:
          columns: query.columns
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=API.getRowEvolution'].get
  update:
    x-apievangelist-phrasing:
      intent: Track one report row over time
      effect: read
      questions:
      - How has traffic to one specific page changed over the last 30 days?
      - Can I chart a single row of a report as a time series?
      instructions:
      - text: Show the evolution of {label} in {apiModule}.{apiAction} for site {idSite}, {period} {date}.
        slots:
          label: query.label
          apiModule: query.apiModule
          apiAction: query.apiAction
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Plot metric {column} over time for row {label} of {apiModule}.{apiAction}, site {idSite}, {period} {date}.
        slots:
          column: query.column
          label: query.label
          apiModule: query.apiModule
          apiAction: query.apiAction
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=API.getBulkRequest'].get
  update:
    x-apievangelist-phrasing:
      intent: Run several API requests in one call
      effect: read
      questions:
      - Can I batch several report queries into a single HTTP call?
      - Is there a way to reduce round trips when pulling many reports?
      instructions:
      - text: 'Run these API requests together in one bulk call: {urls}.'
        slots:
          urls: query.urls
      - text: Batch the report queries {urls} and return all results.
        slots:
          urls: query.urls
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=API.isPluginActivated'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether a plugin is activated
      effect: read
      questions:
      - Is a particular plugin turned on in this instance?
      - Can I check if a premium feature plugin is active before calling it?
      instructions:
      - text: Check whether plugin {pluginName} is activated.
        slots:
          pluginName: query.pluginName
      - text: Tell me if the {pluginName} plugin is enabled.
        slots:
          pluginName: query.pluginName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=API.getSuggestedValuesForSegment'].get
  update:
    x-apievangelist-phrasing:
      intent: Get suggested values for a segment
      effect: read
      questions:
      - What values have recently been seen for a segment like browser or country?
      - Can I get autocomplete suggestions when building a segment?
      instructions:
      - text: Suggest values for segment {segmentName} on site {idSite}.
        slots:
          segmentName: query.segmentName
          idSite: query.idSite
      - text: List recent values seen for {segmentName} on site {idSite}.
        slots:
          segmentName: query.segmentName
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=API.getPagesComparisonsDisabledFor'].get
  update:
    x-apievangelist-phrasing:
      intent: List report pages where comparison is disabled
      effect: read
      questions:
      - On which report pages can't I compare periods or segments?
      - Which category and subcategory pages have comparison features turned off?
      instructions:
      - text: List report pages where comparison features are disabled.
      - text: Show category.subcategory pairs that don't support comparisons.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=API.getGlossaryReports'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the glossary of reports
      effect: read
      questions:
      - Where can I read plain explanations of what each report means?
      - Is there a glossary describing every report for a site?
      instructions:
      - text: Get the report glossary for site {idSite}.
        slots:
          idSite: query.idSite
      - text: Show definitions for every report on site {idSite}.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=API.getGlossaryMetrics'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the glossary of metrics
      effect: read
      questions:
      - What does bounce rate or avg. time on page actually mean here?
      - Is there a glossary that defines each metric?
      instructions:
      - text: Get the metrics glossary for site {idSite}.
        slots:
          idSite: query.idSite
      - text: Show definitions for every metric on site {idSite}.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php'].get
  update:
    x-apievangelist-phrasing:
      intent: Call any Reporting API method by name
      effect: read
      questions:
      - How do I call any reporting method, like VisitsSummary.get, through the single endpoint?
      - Can I pass the method name as a parameter to fetch any report with a GET request?
      instructions:
      - text: Call reporting method {method} with module {module} for site {idSite}, {period} {date}.
        slots:
          method: query.method
          module: query.module
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Run {method} via the generic GET endpoint (module {module}) in {format} format.
        slots:
          method: query.method
          module: query.module
          format: query.format
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php'].post
  update:
    x-apievangelist-phrasing:
      intent: Call a Reporting API method via POST
      effect: read
      questions:
      - Can I send my auth token in the request body instead of the URL?
      - Is there a POST version of the generic reporting endpoint?
      instructions:
      - text: POST to reporting method {method} (module {module}) with token {token_auth} in the body.
        slots:
          method: query.method
          module: query.module
          token_auth: requestBody.token_auth
      - text: Call {method} with module {module} by POST for site {idSite}, {period} {date}.
        slots:
          method: query.method
          module: query.module
          idSite: requestBody.idSite
          period: requestBody.period
          date: requestBody.date
      method: generated
      generated: '2026-10-01'