# 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 Goals API
  version: 1.0.0
extends: openapi/matomo-goals-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: 11
- target: $.paths['/index.php?module=API&method=Goals.getGoal'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single goal
      effect: read
      questions:
      - What pattern and revenue are set on one particular goal?
      - Can I look up a goal's configuration by its ID?
      instructions:
      - text: Get goal {idGoal} on site {idSite}.
        slots:
          idGoal: query.idGoal
          idSite: query.idSite
      - text: Show the match rule configured for goal {idGoal}.
        slots:
          idGoal: query.idGoal
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Goals.getGoals'].get
  update:
    x-apievangelist-phrasing:
      intent: List goals for websites
      effect: read
      questions:
      - Which conversion goals are set up on my website?
      - Can I list goals across several sites, sorted by name?
      instructions:
      - text: List all goals for site {idSite}.
        slots:
          idSite: query.idSite
      - text: Show the goals defined on sites {idSite} ordered by name.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Goals.addGoal'].get
  update:
    x-apievangelist-phrasing:
      intent: Create a conversion goal
      effect: write
      questions:
      - How do I track a conversion when someone visits a thank-you page?
      - Can a goal assign revenue or allow several conversions per visit?
      instructions:
      - text: Create goal {name} on site {idSite} matching {matchAttribute} with {patternType} pattern {pattern}.
        slots:
          name: query.name
          idSite: query.idSite
          matchAttribute: query.matchAttribute
          patternType: query.patternType
          pattern: query.pattern
      - text: Add a goal called {name} worth {revenue} that triggers on {matchAttribute} {pattern} using {patternType} matching.
        slots:
          name: query.name
          revenue: query.revenue
          matchAttribute: query.matchAttribute
          pattern: query.pattern
          patternType: query.patternType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Goals.updateGoal'].get
  update:
    x-apievangelist-phrasing:
      intent: Update an existing goal
      effect: write
      questions:
      - Will editing a goal reprocess conversions that were already recorded?
      - Can I change the URL pattern on a goal I already have?
      instructions:
      - text: Update goal {idGoal} on site {idSite} to name {name}, matching {matchAttribute} {patternType} {pattern}.
        slots:
          idGoal: query.idGoal
          idSite: query.idSite
          name: query.name
          matchAttribute: query.matchAttribute
          patternType: query.patternType
          pattern: query.pattern
      - text: Change the revenue of existing goal {idGoal} to {revenue}.
        slots:
          idGoal: query.idGoal
          revenue: query.revenue
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Goals.deleteGoal'].get
  update:
    x-apievangelist-phrasing:
      intent: Delete a goal
      effect: destructive
      questions:
      - How do I remove a goal I no longer track?
      - Is deleting a goal a soft delete?
      instructions:
      - text: Delete goal {idGoal} from site {idSite}.
        slots:
          idGoal: query.idGoal
          idSite: query.idSite
      - text: Remove goal {idGoal}.
        slots:
          idGoal: query.idGoal
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Goals.getItemsSku'].get
  update:
    x-apievangelist-phrasing:
      intent: Report ecommerce sales by product SKU
      effect: read
      questions:
      - Which product SKUs sold the most last month?
      - Can I see abandoned cart items grouped by SKU?
      instructions:
      - text: Show ecommerce product metrics by SKU for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: List SKUs left in abandoned carts on site {idSite} on {date}.
        slots:
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Goals.getItemsName'].get
  update:
    x-apievangelist-phrasing:
      intent: Report ecommerce sales by product name
      effect: read
      questions:
      - What are my best-selling products by name?
      - Can I compare product revenue grouped by product name for a period?
      instructions:
      - text: Show ecommerce product metrics by product name for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Rank products by name for store site {idSite} on {date}.
        slots:
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Goals.getItemsCategory'].get
  update:
    x-apievangelist-phrasing:
      intent: Report ecommerce sales by product category
      effect: read
      questions:
      - Which product categories bring in the most revenue?
      - Can I see abandoned cart totals per product category?
      instructions:
      - text: Show ecommerce product metrics by category for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Break down sales by product category for site {idSite} on {date}.
        slots:
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Goals.get'].get
  update:
    x-apievangelist-phrasing:
      intent: Get goal and ecommerce conversion metrics
      effect: read
      questions:
      - What's my overall conversion rate and goal revenue for this month?
      - Can I compare conversions from new versus returning visitors?
      - How many conversions did one specific goal get in a period?
      instructions:
      - text: Get goal conversion metrics for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show conversions and revenue for goal {idGoal} on site {idSite} on {date}.
        slots:
          idGoal: query.idGoal
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Goals.getDaysToConversion'].get
  update:
    x-apievangelist-phrasing:
      intent: Report days from first visit to conversion
      effect: read
      questions:
      - How many days does it usually take a visitor to convert?
      - Can I see time-to-conversion in days for a particular goal?
      instructions:
      - text: Show conversions grouped by days to convert for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Break down days-to-conversion for goal {idGoal} on {date}.
        slots:
          idGoal: query.idGoal
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Goals.getVisitsUntilConversion'].get
  update:
    x-apievangelist-phrasing:
      intent: Report visits needed before conversion
      effect: read
      questions:
      - How many visits do people make before they convert?
      - Can I see visits-to-conversion for one goal only?
      instructions:
      - text: Show conversions grouped by number of visits for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Break down visits-until-conversion for goal {idGoal} on {date}.
        slots:
          idGoal: query.idGoal
          date: query.date
      method: generated
      generated: '2026-10-01'