# 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 Dimensions API
  version: 1.0.0
extends: openapi/matomo-customdimensions-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: 6
- target: $.paths['/index.php?module=API&method=CustomDimensions.getCustomDimension'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the report for a custom dimension
      effect: read
      questions:
      - What values did visitors have for my custom dimension, like membership tier, last month?
      - Can I get the report for a custom dimension that's been deactivated?
      instructions:
      - text: Get the report for custom dimension {idDimension} on site {idSite} for {period} {date}.
        slots:
          idDimension: query.idDimension
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show a flat report of dimension {idDimension} values for {date}.
        slots:
          idDimension: query.idDimension
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomDimensions.configureNewCustomDimension'].get
  update:
    x-apievangelist-phrasing:
      intent: Create a new custom dimension
      effect: write
      questions:
      - How do I add a custom dimension to track something like user type?
      - Can custom dimensions be deleted later, or are slots used up for good?
      instructions:
      - text: Create a {scope}-scoped custom dimension named {name} on site {idSite}, active {active}.
        slots:
          scope: query.scope
          name: query.name
          idSite: query.idSite
          active: query.active
      - text: Add custom dimension {name} with scope {scope} and extraction rules {extractions}, active {active}.
        slots:
          name: query.name
          scope: query.scope
          extractions: query.extractions
          active: query.active
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomDimensions.configureExistingCustomDimension'].get
  update:
    x-apievangelist-phrasing:
      intent: Update an existing custom dimension
      effect: write
      questions:
      - Do I need to resend every value when I update a custom dimension?
      - Can I deactivate or rename a custom dimension I already configured?
      instructions:
      - text: Rename custom dimension {idDimension} on site {idSite} to {name}, keeping active {active}.
        slots:
          idDimension: query.idDimension
          idSite: query.idSite
          name: query.name
          active: query.active
      - text: Set existing dimension {idDimension} active to {active} with name {name}.
        slots:
          idDimension: query.idDimension
          active: query.active
          name: query.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomDimensions.getConfiguredCustomDimensions'].get
  update:
    x-apievangelist-phrasing:
      intent: List configured custom dimensions
      effect: read
      questions:
      - Which custom dimensions are set up on my site?
      - Can I see every configured custom dimension with its scope?
      instructions:
      - text: List the configured custom dimensions for site {idSite}.
        slots:
          idSite: query.idSite
      - text: Show every custom dimension defined on website {idSite}.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomDimensions.getAvailableScopes'].get
  update:
    x-apievangelist-phrasing:
      intent: List scopes and remaining dimension slots
      effect: read
      questions:
      - How many custom dimension slots do I have left on a site?
      - Which scopes, like visit or action, can a custom dimension use?
      instructions:
      - text: Show the available scopes and remaining slots for site {idSite}.
        slots:
          idSite: query.idSite
      - text: Check whether site {idSite} has room for another custom dimension.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=CustomDimensions.getAvailableExtractionDimensions'].get
  update:
    x-apievangelist-phrasing:
      intent: List dimensions usable in extraction rules
      effect: read
      questions:
      - What can a custom dimension extract its value from, like the page URL?
      - Which dimensions are supported in extraction rules?
      instructions:
      - text: List the dimensions I can use in custom dimension extraction rules.
      - text: Show the sources a value can be extracted from.
      method: generated
      generated: '2026-10-01'