# 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 Referrers API
  version: 1.0.0
extends: openapi/matomo-referrers-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: 23
- target: $.paths['/index.php?module=API&method=Referrers.get'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the referrer overview report
      effect: read
      questions:
      - How many distinct referrers sent traffic to my site last month?
      - Is there a single overview of all referrer counts and percentages for a period?
      instructions:
      - text: Get the referrer overview for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show the acquisition summary with distinct referrer counts 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=Referrers.getReferrerType'].get
  update:
    x-apievangelist-phrasing:
      intent: Report visits by referrer channel type
      effect: read
      questions:
      - How much of my traffic comes from search versus direct entry versus websites?
      - Can I break visits down by channel type like campaigns and social networks?
      instructions:
      - text: Break down visits by channel type for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show only {typeReferrer} channel visits for site {idSite} on {date}.
        slots:
          typeReferrer: query.typeReferrer
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Referrers.getAll'].get
  update:
    x-apievangelist-phrasing:
      intent: Get all referrers merged in one flat table
      effect: read
      questions:
      - Can I get every referrer, across search, sites, social and campaigns, in one flat list?
      - Is there a flattened table of all my referrer sources for a date range?
      instructions:
      - text: Get one flattened table of all referrers for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Merge every referrer subtable into a single list for site {idSite}.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Referrers.getKeywords'].get
  update:
    x-apievangelist-phrasing:
      intent: Report search keywords that brought visits
      effect: read
      questions:
      - Which search keywords are people using to find my website?
      - What were my top organic search terms last week?
      instructions:
      - text: List the search keywords that brought visitors to site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show a flat keyword report 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=Referrers.getSearchEnginesFromKeywordId'].get
  update:
    x-apievangelist-phrasing:
      intent: Get search engines for one keyword
      effect: read
      questions:
      - Which search engines sent visits for one particular keyword?
      - Can I drill into a keyword row to see the engines behind it?
      instructions:
      - text: Show the search engines behind keyword subtable {idSubtable} for site {idSite} on {date}.
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          date: query.date
      - text: Drill into keyword row {idSubtable} for {period} {date} to list its search engines.
        slots:
          idSubtable: query.idSubtable
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Referrers.getSearchEngines'].get
  update:
    x-apievangelist-phrasing:
      intent: Report search engines that referred visits
      effect: read
      questions:
      - Which search engines send me the most visitors?
      - Can I compare traffic from different search engines over a month?
      instructions:
      - text: List the search engines that referred visits to site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Rank search engine traffic 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=Referrers.getKeywordsFromSearchEngineId'].get
  update:
    x-apievangelist-phrasing:
      intent: Get keywords for one search engine
      effect: read
      questions:
      - What keywords did visitors from one specific search engine type?
      - Can I drill into a search engine row to see its keywords?
      instructions:
      - text: List the keywords for search engine subtable {idSubtable} on site {idSite} for {date}.
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          date: query.date
      - text: Drill into search engine row {idSubtable} for {period} {date} and show its keywords.
        slots:
          idSubtable: query.idSubtable
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Referrers.getCampaigns'].get
  update:
    x-apievangelist-phrasing:
      intent: Report marketing campaigns that drove visits
      effect: read
      questions:
      - Which marketing campaigns drove traffic to my site?
      - How did my campaigns perform in terms of visits last quarter?
      instructions:
      - text: List the campaigns that referred visits to site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show campaign traffic for site {idSite} on {date} with keyword rows expanded.
        slots:
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Referrers.getKeywordsFromCampaignId'].get
  update:
    x-apievangelist-phrasing:
      intent: Get keywords for one campaign
      effect: read
      questions:
      - What campaign keywords were used within one specific campaign?
      - Can I drill into a campaign row to see its keyword values?
      instructions:
      - text: List campaign keywords for campaign subtable {idSubtable} on site {idSite} for {date}.
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          date: query.date
      - text: Drill into campaign row {idSubtable} for {period} {date}.
        slots:
          idSubtable: query.idSubtable
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Referrers.getWebsites'].get
  update:
    x-apievangelist-phrasing:
      intent: Report referring websites
      effect: read
      questions:
      - Which other websites link to mine and send visitors?
      - What were my top referring domains this month?
      instructions:
      - text: List the referring websites for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Rank the external domains sending traffic to site {idSite} on {date}.
        slots:
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Referrers.getUrlsFromWebsiteId'].get
  update:
    x-apievangelist-phrasing:
      intent: Get referring page URLs for one website
      effect: read
      questions:
      - Which exact pages on a referring website linked to me?
      - Can I drill into a referring domain to see the individual URLs?
      instructions:
      - text: List the referrer URLs inside website subtable {idSubtable} for site {idSite} on {date}.
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          date: query.date
      - text: Drill into referring domain row {idSubtable} for {period} {date} to see its linking pages.
        slots:
          idSubtable: query.idSubtable
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Referrers.getSocials'].get
  update:
    x-apievangelist-phrasing:
      intent: Report social network referrers
      effect: read
      questions:
      - Which social networks send me the most visits?
      - How does traffic from social media compare across networks?
      instructions:
      - text: List the social networks that referred visits to site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Compare social media traffic 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=Referrers.getAIAssistants'].get
  update:
    x-apievangelist-phrasing:
      intent: Report AI assistant referrers
      effect: read
      questions:
      - Are AI assistants and chatbots sending visitors to my website?
      - Which AI assistants referred the most visits last month?
      instructions:
      - text: List the AI assistants that referred visits to site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show AI assistant referrals for site {idSite} on {date} split by {secondaryDimension}.
        slots:
          idSite: query.idSite
          date: query.date
          secondaryDimension: query.secondaryDimension
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Referrers.getUrlsForSocial'].get
  update:
    x-apievangelist-phrasing:
      intent: Get referrer URLs for one social network
      effect: read
      questions:
      - Which specific posts or pages on a social network linked to my site?
      - Can I drill into one social network to see individual referring URLs?
      instructions:
      - text: List the referrer URLs for social network subtable {idSubtable} on site {idSite} for {date}.
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          date: query.date
      - text: Show the individual social links that sent visits to site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Referrers.getEntryPageUrlsForAIAssistant'].get
  update:
    x-apievangelist-phrasing:
      intent: Get entry page URLs for one AI assistant
      effect: read
      questions:
      - Which page URLs did visitors land on when an AI assistant referred them?
      - Can I see the landing URLs for traffic from one specific AI assistant?
      instructions:
      - text: List entry page URLs for AI assistant subtable {idSubtable} on site {idSite} for {date}.
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          date: query.date
      - text: Show the landing URLs reached from AI assistants on site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Referrers.getEntryPageTitlesForAIAssistant'].get
  update:
    x-apievangelist-phrasing:
      intent: Get entry page titles for one AI assistant
      effect: read
      questions:
      - What are the titles of the pages AI assistant visitors entered on?
      - Can I see landing page names, rather than URLs, for one AI assistant?
      instructions:
      - text: List entry page titles for AI assistant subtable {idSubtable} on site {idSite} for {date}.
        slots:
          idSubtable: query.idSubtable
          idSite: query.idSite
          date: query.date
      - text: Show the page names AI-referred visitors landed on for site {idSite} in {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Referrers.getNumberOfDistinctSearchEngines'].get
  update:
    x-apievangelist-phrasing:
      intent: Count distinct search engines in a period
      effect: read
      questions:
      - How many different search engines sent me traffic this month?
      - Can I get just the count of search engines, not the full report?
      instructions:
      - text: Count the distinct search engines for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Tell me the number of unique search engines referring site {idSite} on {date}.
        slots:
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Referrers.getNumberOfDistinctSocialNetworks'].get
  update:
    x-apievangelist-phrasing:
      intent: Count distinct social networks in a period
      effect: read
      questions:
      - How many different social networks referred visitors last week?
      - Is there a quick number for unique social referrers in a period?
      instructions:
      - text: Count the distinct social networks for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Tell me how many unique social platforms sent traffic to site {idSite} on {date}.
        slots:
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Referrers.getNumberOfDistinctKeywords'].get
  update:
    x-apievangelist-phrasing:
      intent: Count distinct search keywords in a period
      effect: read
      questions:
      - How many unique search keywords brought visitors this month?
      - What's the total count of distinct search terms for a date range?
      instructions:
      - text: Count the distinct search keywords for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Give me the number of unique search terms 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=Referrers.getNumberOfDistinctCampaigns'].get
  update:
    x-apievangelist-phrasing:
      intent: Count distinct campaigns in a period
      effect: read
      questions:
      - How many different campaigns drove traffic during a period?
      - Can I get only the number of active campaigns that sent visits?
      instructions:
      - text: Count the distinct campaigns for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Tell me how many unique campaigns referred site {idSite} on {date}.
        slots:
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Referrers.getNumberOfDistinctWebsites'].get
  update:
    x-apievangelist-phrasing:
      intent: Count distinct referring websites in a period
      effect: read
      questions:
      - How many different websites linked to me and sent visits?
      - What's the count of unique referring domains for last month?
      instructions:
      - text: Count the distinct referring websites for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Tell me the number of unique referring domains 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=Referrers.getNumberOfDistinctAIAssistants'].get
  update:
    x-apievangelist-phrasing:
      intent: Count distinct AI assistants in a period
      effect: read
      questions:
      - How many different AI assistants referred visitors this week?
      - Can I get a single count of unique AI chatbot referrers?
      instructions:
      - text: Count the distinct AI assistants for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Tell me how many unique AI assistants sent traffic to site {idSite} on {date}.
        slots:
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Referrers.getNumberOfDistinctWebsitesUrls'].get
  update:
    x-apievangelist-phrasing:
      intent: Count distinct referrer URLs in a period
      effect: read
      questions:
      - How many individual referring page URLs sent traffic, not just domains?
      - What's the count of unique referrer URLs for a period?
      instructions:
      - text: Count the distinct referrer URLs for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Tell me the number of unique linking page URLs for site {idSite} on {date}.
        slots:
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'