# 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 Annotations API
  version: 1.0.0
extends: openapi/matomo-annotations-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: 7
- target: $.paths['/index.php?module=API&method=Annotations.add'].get
  update:
    x-apievangelist-phrasing:
      intent: Add an annotation to a site's timeline
      effect: write
      questions:
      - How do I note a campaign launch on my traffic graph in Matomo?
      - Can I star an annotation when I create it?
      instructions:
      - text: Add annotation {note} on {date} for site {idSite}.
        slots:
          note: query.note
          date: query.date
          idSite: query.idSite
      - text: Create a starred note {note} dated {date} on site {idSite}.
        slots:
          note: query.note
          date: query.date
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Annotations.save'].get
  update:
    x-apievangelist-phrasing:
      intent: Edit an existing annotation
      effect: write
      questions:
      - Can I fix the text or date of an annotation I already added?
      - What's the way to star or unstar an existing annotation?
      instructions:
      - text: Change the text of annotation {idNote} on site {idSite} to {note}.
        slots:
          idNote: query.idNote
          idSite: query.idSite
          note: query.note
      - text: Move existing annotation {idNote} on site {idSite} to date {date}.
        slots:
          idNote: query.idNote
          idSite: query.idSite
          date: query.date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Annotations.delete'].get
  update:
    x-apievangelist-phrasing:
      intent: Delete one annotation
      effect: destructive
      questions:
      - How do I remove a single annotation from a site?
      - Can I delete an annotation I added by mistake?
      instructions:
      - text: Delete annotation {idNote} from site {idSite}.
        slots:
          idNote: query.idNote
          idSite: query.idSite
      - text: Remove note {idNote} on site {idSite}.
        slots:
          idNote: query.idNote
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Annotations.deleteAll'].get
  update:
    x-apievangelist-phrasing:
      intent: Delete every annotation on a site
      effect: destructive
      questions:
      - Can I wipe all annotations for a website at once?
      - Who is allowed to clear every annotation on a site?
      instructions:
      - text: Delete all annotations for site {idSite}.
        slots:
          idSite: query.idSite
      - text: Clear every note from site {idSite}'s timeline.
        slots:
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Annotations.get'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single annotation
      effect: read
      questions:
      - What does a specific annotation say?
      - Can I fetch one annotation by its note ID?
      instructions:
      - text: Get annotation {idNote} for site {idSite}.
        slots:
          idNote: query.idNote
          idSite: query.idSite
      - text: Show the text and date of note {idNote} on site {idSite}.
        slots:
          idNote: query.idNote
          idSite: query.idSite
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=Annotations.getAll'].get
  update:
    x-apievangelist-phrasing:
      intent: List annotations for a date range
      effect: read
      questions:
      - What annotations were added for my site last month?
      - Can I list all notes on a site across the last few periods?
      instructions:
      - text: List all annotations for site {idSite}.
        slots:
          idSite: query.idSite
      - text: Show annotations 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=Annotations.getAnnotationCountForDates'].get
  update:
    x-apievangelist-phrasing:
      intent: Count annotations per period
      effect: read
      questions:
      - How many annotations, and how many starred ones, exist for each day this month?
      - Can I get annotation counts per period instead of the notes themselves?
      instructions:
      - text: Count annotations on site {idSite} per {period} for {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Give per-period annotation and starred counts for site {idSite}, {period} {date}, over the last {lastN} periods.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
          lastN: query.lastN
      method: generated
      generated: '2026-10-01'