# 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 Events API
  version: 1.0.0
extends: openapi/matomo-events-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 9
- target: $.paths['/index.php?module=API&method=Events.getCategory'].get
  update:
    x-apievangelist-phrasing:
      intent: Report events by category
      effect: read
      questions:
      - Which event categories were triggered most on my site?
      - Can I see tracked events grouped by category with a secondary dimension?
      instructions:
      - text: Show event metrics by category for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Report event categories for site {idSite} in {date} ({period}) split by {secondaryDimension}.
        slots:
          idSite: query.idSite
          date: query.date
          period: query.period
          secondaryDimension: query.secondaryDimension
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Events.getAction'].get
  update:
    x-apievangelist-phrasing:
      intent: Report events by action
      effect: read
      questions:
      - Which event actions, like play or download, happen most often?
      - What are the top tracked event actions for last month?
      instructions:
      - text: Show event metrics by action for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Report event actions for site {idSite} in {date} ({period}) split by {secondaryDimension}.
        slots:
          idSite: query.idSite
          date: query.date
          period: query.period
          secondaryDimension: query.secondaryDimension
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Events.getName'].get
  update:
    x-apievangelist-phrasing:
      intent: Report events by name
      effect: read
      questions:
      - Which event names were recorded most on my site?
      - What events by name did visitors trigger in a given week?
      instructions:
      - text: Show event metrics by name for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Report event names for site {idSite} in {date} ({period}) split by {secondaryDimension}.
        slots:
          idSite: query.idSite
          date: query.date
          period: query.period
          secondaryDimension: query.secondaryDimension
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Events.getActionFromCategoryId'].get
  update:
    x-apievangelist-phrasing:
      intent: Drill into the actions within an event category
      effect: read
      questions:
      - Which actions happened inside one particular event category?
      - Can I expand a category row to see its event actions?
      instructions:
      - text: List event actions under category row {idSubtable} for site {idSite}, {period} {date}.
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Expand event category {idSubtable} on site {idSite} into its actions for {date} ({period}).
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          date: query.date
          period: query.period
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Events.getNameFromCategoryId'].get
  update:
    x-apievangelist-phrasing:
      intent: Drill into the names within an event category
      effect: read
      questions:
      - Which event names were recorded inside one event category?
      - Can I expand a category row to see its event names?
      instructions:
      - text: List event names under category row {idSubtable} for site {idSite}, {period} {date}.
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Expand event category {idSubtable} on site {idSite} into its names for {date} ({period}).
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          date: query.date
          period: query.period
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Events.getCategoryFromActionId'].get
  update:
    x-apievangelist-phrasing:
      intent: Drill into the categories for an event action
      effect: read
      questions:
      - Which event categories does a particular event action appear in?
      - Can I expand an action row to see its categories?
      instructions:
      - text: List event categories under action row {idSubtable} for site {idSite}, {period} {date}.
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Expand event action {idSubtable} on site {idSite} into its categories for {date} ({period}).
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          date: query.date
          period: query.period
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Events.getNameFromActionId'].get
  update:
    x-apievangelist-phrasing:
      intent: Drill into the names for an event action
      effect: read
      questions:
      - Which event names were recorded with one particular action?
      - Can I expand an action row to see its event names?
      instructions:
      - text: List event names under action row {idSubtable} for site {idSite}, {period} {date}.
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Expand event action {idSubtable} on site {idSite} into its names for {date} ({period}).
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          date: query.date
          period: query.period
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Events.getActionFromNameId'].get
  update:
    x-apievangelist-phrasing:
      intent: Drill into the actions for an event name
      effect: read
      questions:
      - Which actions were recorded with one particular event name?
      - Can I expand an event name row to see its actions?
      instructions:
      - text: List event actions under name row {idSubtable} for site {idSite}, {period} {date}.
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Expand event name {idSubtable} on site {idSite} into its actions for {date} ({period}).
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          date: query.date
          period: query.period
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Events.getCategoryFromNameId'].get
  update:
    x-apievangelist-phrasing:
      intent: Drill into the categories for an event name
      effect: read
      questions:
      - Which categories does one particular event name fall under?
      - Can I expand an event name row to see its categories?
      instructions:
      - text: List event categories under name row {idSubtable} for site {idSite}, {period} {date}.
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Expand event name {idSubtable} on site {idSite} into its categories for {date} ({period}).
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          date: query.date
          period: query.period
      method: generated
      generated: '2026-10-01'