# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Perigon Monitors API
  version: 1.0.0
extends: openapi/perigon-monitors-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: 10
- target: $.paths['/v1/api/monitors'].get
  update:
    x-apievangelist-phrasing:
      intent: List AI news monitors
      effect: read
      questions:
      - Which AI monitors does my organization have running?
      - Can I include archived monitors when listing them?
      - How do I find monitors that are still in draft?
      instructions:
      - text: List my monitors sorted by {sortBy} {sortOrder}.
        slots:
          sortBy: query.sortBy
          sortOrder: query.sortOrder
      - text: Show monitors with status {status}, newest first by {sortBy} in {sortOrder} order.
        slots:
          status: query.status
          sortBy: query.sortBy
          sortOrder: query.sortOrder
      - text: Find monitors named {name}, sorted by {sortBy} {sortOrder}.
        slots:
          name: query.name
          sortBy: query.sortBy
          sortOrder: query.sortOrder
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/monitors'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an AI news monitor
      effect: write
      questions:
      - How do I set up an AI monitor that watches the news for a specific signal?
      - Can a new monitor start as a draft rather than going live immediately?
      - What do I need to define, like an objective and data schema, to create a monitor?
      instructions:
      - text: Create a monitor called {name} with objective {monitoringObjective}, classification {classificationType}, query {query} and schema {dataSchema}.
        slots:
          name: requestBody.name
          monitoringObjective: requestBody.monitoringObjective
          classificationType: requestBody.classificationType
          query: requestBody.query
          dataSchema: requestBody.dataSchema
      - text: Set up a draft monitor {name} tracking {monitoringObjective} using watchlist {watchlistId}, schema {dataSchema}, query {query}, type {classificationType}.
        slots:
          name: requestBody.name
          monitoringObjective: requestBody.monitoringObjective
          watchlistId: requestBody.watchlistId
          dataSchema: requestBody.dataSchema
          query: requestBody.query
          classificationType: requestBody.classificationType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/monitors/{uuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a monitor's configuration
      effect: read
      questions:
      - What objective and query is a given monitor configured with?
      - Can I check whether one specific monitor is active or paused?
      instructions:
      - text: Show me the configuration of monitor {uuid}.
        slots:
          uuid: path.uuid
      - text: Fetch monitor {uuid} and report its current status.
        slots:
          uuid: path.uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/monitors/{uuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive a monitor
      effect: destructive
      questions:
      - How do I retire a monitor so it stops showing up in my list?
      - Does archiving a monitor hide it from list results?
      instructions:
      - text: Archive monitor {uuid}.
        slots:
          uuid: path.uuid
      - text: Retire the monitor {uuid} by archiving it.
        slots:
          uuid: path.uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/monitors/{uuid}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit a monitor's settings
      effect: write
      questions:
      - Can I change the query or objective of a monitor I already created?
      - How do I switch which contact points an existing monitor notifies?
      instructions:
      - text: Change monitor {uuid} to track {monitoringObjective} with query {query}.
        slots:
          uuid: path.uuid
          monitoringObjective: requestBody.monitoringObjective
          query: requestBody.query
      - text: Edit monitor {uuid} so it notifies contact points {contactPointIds}.
        slots:
          uuid: path.uuid
          contactPointIds: requestBody.contactPointIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/monitors/{uuid}/activate'].post
  update:
    x-apievangelist-phrasing:
      intent: Activate a monitor
      effect: write
      questions:
      - How do I turn on a draft or paused monitor so it starts processing news?
      - Can I restart a monitor I paused earlier?
      instructions:
      - text: Activate monitor {uuid}.
        slots:
          uuid: path.uuid
      - text: Start processing for monitor {uuid} again.
        slots:
          uuid: path.uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/monitors/{uuid}/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List events a monitor detected
      effect: read
      questions:
      - What matching articles or events has my monitor detected?
      - Can I filter a monitor's detected events by event type or date range?
      instructions:
      - text: List events from monitor {uuid} sorted by {sortBy} {sortOrder}.
        slots:
          uuid: path.uuid
          sortBy: query.sortBy
          sortOrder: query.sortOrder
      - text: Show {eventType} events detected by monitor {uuid} since {from}, sorted by {sortBy} {sortOrder}.
        slots:
          eventType: query.eventType
          uuid: path.uuid
          from: query.from
          sortBy: query.sortBy
          sortOrder: query.sortOrder
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/monitors/{uuid}/newsletters'].get
  update:
    x-apievangelist-phrasing:
      intent: List a monitor's newsletter digests
      effect: read
      questions:
      - Where can I read the newsletter digests my monitor has produced?
      - Can I search a monitor's newsletters by title?
      instructions:
      - text: List newsletters generated by monitor {uuid}, sorted by {sortBy} {sortOrder}.
        slots:
          uuid: path.uuid
          sortBy: query.sortBy
          sortOrder: query.sortOrder
      - text: Find newsletters titled {title} for monitor {uuid}, ordered by {sortBy} {sortOrder}.
        slots:
          title: query.title
          uuid: path.uuid
          sortBy: query.sortBy
          sortOrder: query.sortOrder
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/monitors/{uuid}/pause'].post
  update:
    x-apievangelist-phrasing:
      intent: Pause a monitor
      effect: write
      questions:
      - How do I temporarily stop a monitor without archiving it?
      - Is there a way to halt a monitor's processing pipeline for now?
      instructions:
      - text: Pause monitor {uuid}.
        slots:
          uuid: path.uuid
      - text: Stop monitor {uuid} from processing for the time being.
        slots:
          uuid: path.uuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/monitors/{uuid}/summary'].get
  update:
    x-apievangelist-phrasing:
      intent: List a monitor's AI summaries
      effect: read
      questions:
      - What AI-generated summaries has my monitor written about the content it matched?
      - Can I get only the monitor summaries produced in a certain date window?
      instructions:
      - text: List AI summaries for monitor {uuid} sorted by {sortBy} {sortOrder}.
        slots:
          uuid: path.uuid
          sortBy: query.sortBy
          sortOrder: query.sortOrder
      - text: Show summaries from monitor {uuid} between {from} and {to}, sorted by {sortBy} {sortOrder}.
        slots:
          uuid: path.uuid
          from: query.from
          to: query.to
          sortBy: query.sortBy
          sortOrder: query.sortOrder
      method: generated
      generated: '2026-10-01'