# 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 Form Analytics API
  version: 1.0.0
extends: openapi/matomo-formanalytics-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: 26
- target: $.paths['/index.php?module=API&method=FormAnalytics.addForm'].get
  update:
    x-apievangelist-phrasing:
      intent: Start tracking a new form
      effect: write
      questions:
      - How do I set up a new form to track in Matomo Form Analytics?
      - Can a tracked form count as converted when a goal is reached?
      instructions:
      - text: Add a form named {name} to site {idSite}.
        slots:
          name: query.name
          idSite: query.idSite
      - text: Create form {name} on site {idSite} linked to goal {idGoal}.
        slots:
          name: query.name
          idSite: query.idSite
          idGoal: query.idGoal
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.updateForm'].get
  update:
    x-apievangelist-phrasing:
      intent: Edit a tracked form's settings
      effect: write
      questions:
      - Can I rename a form I'm already tracking or change its matching rules?
      - How do I change which goal an existing tracked form converts on?
      instructions:
      - text: Rename form {idForm} on site {idSite} to {name}.
        slots:
          idForm: query.idForm
          idSite: query.idSite
          name: query.name
      - text: Update existing form {idForm} on site {idSite}, keeping name {name}, with new page rules {matchPageRules}.
        slots:
          idForm: query.idForm
          idSite: query.idSite
          name: query.name
          matchPageRules: query.matchPageRules
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getForm'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one tracked form's configuration
      effect: read
      questions:
      - What rules and settings does a specific tracked form have?
      - Can I look up a single form by its ID?
      instructions:
      - text: Get the configuration of form {idForm} on site {idSite}.
        slots:
          idForm: query.idForm
          idSite: query.idSite
      - text: Show me the settings for tracked form {idForm} (site {idSite}).
        slots:
          idForm: query.idForm
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getForms'].get
  update:
    x-apievangelist-phrasing:
      intent: List all tracked forms on a site
      effect: read
      questions:
      - Which forms are being tracked on my website?
      - Can I list every form configured for an app or site?
      instructions:
      - text: List all tracked forms for site {idSite}.
        slots:
          idSite: query.idSite
      - text: Show every form configured on site {idSite}, regardless of status.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getFormsByStatuses'].get
  update:
    x-apievangelist-phrasing:
      intent: List tracked forms by status
      effect: read
      questions:
      - Can I see only the archived forms, or only the running ones?
      - How do I filter my tracked forms by status?
      instructions:
      - text: List forms on site {idSite} with status {statuses}.
        slots:
          idSite: query.idSite
          statuses: query.statuses
      - text: Show only the {statuses} forms for site {idSite}.
        slots:
          statuses: query.statuses
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.deleteForm'].get
  update:
    x-apievangelist-phrasing:
      intent: Delete a tracked form
      effect: destructive
      questions:
      - How do I delete a form I no longer want to track?
      - Can a tracked form be removed entirely rather than archived?
      instructions:
      - text: Delete form {idForm} from site {idSite}.
        slots:
          idForm: query.idForm
          idSite: query.idSite
      - text: Permanently remove tracked form {idForm} on site {idSite}.
        slots:
          idForm: query.idForm
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.archiveForm'].get
  update:
    x-apievangelist-phrasing:
      intent: Archive a tracked form
      effect: write
      questions:
      - Can I archive a form to stop tracking it without deleting it?
      - What's the way to retire an old form but keep it around?
      instructions:
      - text: Archive form {idForm} on site {idSite}.
        slots:
          idForm: query.idForm
          idSite: query.idSite
      - text: Move form {idForm} for site {idSite} to archived status.
        slots:
          idForm: query.idForm
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.get'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the form overview report
      effect: read
      questions:
      - How are my forms performing overall in terms of starts, submissions and conversions?
      - Can I get the overview metrics for one form for last month?
      instructions:
      - text: Get the form overview report for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show overview metrics for form {idForm} on site {idSite}, {period} {date}.
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getSummary'].get
  update:
    x-apievangelist-phrasing:
      intent: Compare all forms side by side for a period
      effect: read
      questions:
      - Which of my forms converts best this week?
      - Can I get one row of metrics per form for a period?
      instructions:
      - text: Get the per-form summary for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Compare every form on site {idSite} for {period} {date} in one table.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getEntryFields'].get
  update:
    x-apievangelist-phrasing:
      intent: See which fields users start a form with
      effect: read
      questions:
      - Which field do visitors usually interact with first on my form?
      - Do people start my form at the top field or somewhere else?
      instructions:
      - text: Get the entry fields report for form {idForm} on site {idSite}, {period} {date}.
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show which fields people begin form {idForm} with (site {idSite}, {period} {date}).
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getDropOffFields'].get
  update:
    x-apievangelist-phrasing:
      intent: Find the fields where users abandon a form
      effect: read
      questions:
      - At which field do visitors give up on my form?
      - What's causing people to abandon my signup form?
      instructions:
      - text: Get the drop-off fields for form {idForm} on site {idSite}, {period} {date}.
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show where visitors abandoned form {idForm} on site {idSite} during {period} {date}.
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getPageUrls'].get
  update:
    x-apievangelist-phrasing:
      intent: Compare a form's performance per page
      effect: read
      questions:
      - My form is embedded on several pages, which page converts it best?
      - Can I break a form's metrics down by the page URL it appeared on?
      instructions:
      - text: Break down form {idForm} metrics by page URL for site {idSite}, {period} {date}.
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show how form {idForm} performs on each page it's embedded on (site {idSite}, {period} {date}).
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getFieldTimings'].get
  update:
    x-apievangelist-phrasing:
      intent: See how long users spend on each field
      effect: read
      questions:
      - Which form fields take visitors the longest to fill in?
      - How long do people hesitate before typing into a field?
      instructions:
      - text: Get field timings for form {idForm} on site {idSite}, {period} {date}.
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show time spent and hesitation per field of form {idForm} (site {idSite}, {period} {date}).
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getFieldSize'].get
  update:
    x-apievangelist-phrasing:
      intent: See how much users type into text fields
      effect: read
      questions:
      - How many characters do visitors typically type into my text fields?
      - Is my comment box being used for long answers or short ones?
      instructions:
      - text: Get the field size report for form {idForm} on site {idSite}, {period} {date}.
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show average typed characters per text field in form {idForm} (site {idSite}, {period} {date}).
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getUneededFields'].get
  update:
    x-apievangelist-phrasing:
      intent: Find fields users leave blank
      effect: read
      questions:
      - Which fields do people usually leave empty when they submit my form?
      - Are there form fields I could probably remove?
      instructions:
      - text: Get the unneeded fields report for form {idForm} on site {idSite}, {period} {date}.
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show fields left blank on submission of form {idForm} (site {idSite}, {period} {date}).
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getMostUsedFields'].get
  update:
    x-apievangelist-phrasing:
      intent: See which form fields get the most interaction
      effect: read
      questions:
      - Which fields on my form are interacted with and changed most often?
      - What are the busiest fields in a form?
      instructions:
      - text: Get the most used fields of form {idForm} on site {idSite}, {period} {date}.
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Rank fields of form {idForm} by interactions (site {idSite}, {period} {date}).
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getFieldCorrections'].get
  update:
    x-apievangelist-phrasing:
      intent: See which fields users correct most
      effect: read
      questions:
      - Which fields make visitors hit backspace or refocus the most?
      - Where are people making mistakes and fixing them in my form?
      instructions:
      - text: Get the field corrections report for form {idForm} on site {idSite}, {period} {date}.
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show the most corrected fields in form {idForm} (site {idSite}, {period} {date}).
        slots:
          idForm: query.idForm
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.updateFormFieldDisplayName'].get
  update:
    x-apievangelist-phrasing:
      intent: Set friendly display names for form fields
      effect: write
      questions:
      - Can I give my form fields readable labels instead of their raw HTML names?
      - How do I rename how a field shows up in form reports?
      instructions:
      - text: Set field display names {fields} for form {idForm} on site {idSite}.
        slots:
          fields: query.fields
          idForm: query.idForm
          idSite: query.idSite
      - text: Label the fields of form {idForm} on site {idSite} with friendly names.
        slots:
          idForm: query.idForm
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getCounters'].get
  update:
    x-apievangelist-phrasing:
      intent: Get real-time form counters
      effect: read
      questions:
      - How are my forms doing in the last 30 minutes?
      - Can I see live form activity counts for a site right now?
      instructions:
      - text: Get form counters for site {idSite} over the last {lastMinutes} minutes.
        slots:
          idSite: query.idSite
          lastMinutes: query.lastMinutes
      - text: Show real-time form starts and submissions on site {idSite} for the past {lastMinutes} minutes.
        slots:
          idSite: query.idSite
          lastMinutes: query.lastMinutes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getCurrentMostPopularForms'].get
  update:
    x-apievangelist-phrasing:
      intent: See the most popular forms right now
      effect: read
      questions:
      - Which forms are getting the most use right this moment?
      - Can I see the top few forms by activity over the last hour?
      instructions:
      - text: List the most popular forms on site {idSite} over the last {lastMinutes} minutes.
        slots:
          idSite: query.idSite
          lastMinutes: query.lastMinutes
      - text: Show the top {filter_limit} forms by live activity on site {idSite} in the past {lastMinutes} minutes.
        slots:
          filter_limit: query.filter_limit
          idSite: query.idSite
          lastMinutes: query.lastMinutes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getAutoCreationSettings'].get
  update:
    x-apievangelist-phrasing:
      intent: Check form auto-creation settings
      effect: read
      questions:
      - Are forms created automatically when they're detected on my site?
      - What are the auto-creation settings for forms on a site?
      instructions:
      - text: Get the form auto-creation settings for site {idSite}.
        slots:
          idSite: query.idSite
      - text: Tell me whether site {idSite} auto-creates forms.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getAvailableStatuses'].get
  update:
    x-apievangelist-phrasing:
      intent: List valid form statuses
      effect: read
      questions:
      - What statuses can a tracked form have?
      - Which status values can I filter forms by?
      instructions:
      - text: List the valid form statuses.
      - text: Show me every status a tracked form can be in.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getAllGoals'].get
  update:
    x-apievangelist-phrasing:
      intent: List a site's goals for form conversion
      effect: read
      questions:
      - Which goals could I link a form's conversion to?
      - What goals are configured on this site?
      instructions:
      - text: List all goals configured for site {idSite}.
        slots:
          idSite: query.idSite
      - text: Show the goals on site {idSite} I can use as form conversions.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getAvailableFormRules'].get
  update:
    x-apievangelist-phrasing:
      intent: List form-matching rule patterns
      effect: read
      questions:
      - What patterns can I use to identify which HTML form to track?
      - Can a form be matched by its ID or name attribute?
      instructions:
      - text: List the available form matching rule patterns.
      - text: Show the rule types for identifying a form element.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getAvailablePageRules'].get
  update:
    x-apievangelist-phrasing:
      intent: List page rule patterns for forms
      effect: read
      questions:
      - What page URL patterns can restrict where a form is tracked?
      - Which rule patterns are available for a form's conversion page?
      instructions:
      - text: List the available page rule patterns for configuring a form.
      - text: Show the URL-matching patterns I can use in form page rules.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=FormAnalytics.getAvailableConversionRuleOptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List form conversion rule options
      effect: read
      questions:
      - What options are there for deciding when a form counts as converted?
      - Can a form conversion be based on a goal instead of a submit?
      instructions:
      - text: List the available form conversion rule options.
      - text: Show the choices for how form conversions are counted.
      method: generated
      generated: '2026-10-01'