# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Mux Annotations API
  version: 1.0.0
extends: openapi/mux-com-annotations-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/data/v1/annotations'].get
  update:
    x-apievangelist-phrasing:
      intent: List annotations on my video analytics
      effect: read
      questions:
      - Which annotations have been added to my Mux Data charts?
      - Can I list annotations only within a certain timeframe?
      - How do I page through all my analytics annotations newest first?
      instructions:
      - text: List my annotations.
      - text: List annotations in timeframe {timeframe}, {limit} per page.
        slots:
          timeframe: query.timeframe[]
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/data/v1/annotations'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an annotation to analytics charts
      effect: write
      questions:
      - How do I mark a deploy date on my Mux Data charts with a note?
      - Can I scope a new annotation to a specific sub-property?
      instructions:
      - text: Add an annotation saying {note} on {date}.
        slots:
          note: requestBody.note
          date: requestBody.date
      - text: Create a new annotation {note} dated {date} for sub-property {sub_property_id}.
        slots:
          note: requestBody.note
          date: requestBody.date
          sub_property_id: requestBody.sub_property_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/data/v1/annotations/{ANNOTATION_ID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one annotation's details
      effect: read
      questions:
      - What does annotation I created earlier say, and what date is it on?
      - Can I look up a single annotation by its ID?
      instructions:
      - text: Show me annotation {annotation_id}.
        slots:
          annotation_id: path.ANNOTATION_ID
      - text: Fetch the note and date of annotation {annotation_id}.
        slots:
          annotation_id: path.ANNOTATION_ID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/data/v1/annotations/{ANNOTATION_ID}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an annotation
      effect: destructive
      questions:
      - How do I remove an annotation I no longer want on my charts?
      - Is deleting an annotation permanent?
      instructions:
      - text: Delete annotation {annotation_id}.
        slots:
          annotation_id: path.ANNOTATION_ID
      - text: Remove annotation {annotation_id} from my analytics charts.
        slots:
          annotation_id: path.ANNOTATION_ID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/data/v1/annotations/{ANNOTATION_ID}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit an existing annotation
      effect: write
      questions:
      - Can I change the note or date on an annotation that already exists?
      - How do I fix a typo in an existing Mux Data annotation?
      instructions:
      - text: Change annotation {annotation_id} to say {note} on {date}.
        slots:
          annotation_id: path.ANNOTATION_ID
          note: requestBody.note
          date: requestBody.date
      - text: Move existing annotation {annotation_id} to {date} keeping note {note}.
        slots:
          annotation_id: path.ANNOTATION_ID
          date: requestBody.date
          note: requestBody.note
      method: generated
      generated: '2026-09-26'