# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Checkly Public Maintenance windows API
  version: 1.0.0
extends: openapi/checkly-maintenance-windows-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: 12
- target: $.paths['/v1/maintenance-windows'].get
  update:
    x-apievangelist-phrasing:
      intent: List maintenance windows
      effect: read
      questions:
      - What maintenance windows are scheduled in my Checkly account?
      - Can I filter maintenance windows by when they start or end?
      instructions:
      - text: List all my maintenance windows.
      - text: Show maintenance windows starting {startsAt}.
        slots:
          startsAt: query.startsAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/maintenance-windows'].post
  update:
    x-apievangelist-phrasing:
      intent: Schedule a maintenance window
      effect: write
      questions:
      - How do I pause alerts during a planned deploy window?
      - Can a maintenance window repeat weekly and stop repeating on a set date?
      - Can I show a maintenance window on my status page when I create it?
      instructions:
      - text: Create a maintenance window {name} from {startsAt} to {endsAt} repeating {repeatUnit}.
        slots:
          name: requestBody.name
          startsAt: requestBody.startsAt
          endsAt: requestBody.endsAt
          repeatUnit: requestBody.repeatUnit
      - text: Schedule maintenance {name} from {startsAt} to {endsAt}, repeat {repeatUnit}, for checks tagged {tags}.
        slots:
          name: requestBody.name
          startsAt: requestBody.startsAt
          endsAt: requestBody.endsAt
          repeatUnit: requestBody.repeatUnit
          tags: requestBody.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/maintenance-windows/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a maintenance window's details
      effect: read
      questions:
      - Which checks does a specific maintenance window cover?
      - What schedule and timezone is a given maintenance window set to?
      instructions:
      - text: Show maintenance window {id}.
        slots:
          id: path.id
      - text: Get the settings of maintenance window {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/maintenance-windows/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a maintenance window
      effect: write
      questions:
      - Can I extend an existing maintenance window's end date?
      - How do I change which tags an existing maintenance window applies to?
      instructions:
      - text: Move maintenance window {id} to end at {endsAt}.
        slots:
          id: path.id
          endsAt: requestBody.endsAt
      - text: Rename maintenance window {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/maintenance-windows/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a maintenance window
      effect: destructive
      questions:
      - How do I remove a maintenance window I no longer need?
      - Is deleting a maintenance window permanent?
      instructions:
      - text: Delete maintenance window {id}.
        slots:
          id: path.id
      - text: Remove the whole maintenance window {id} from my account.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/maintenance-windows/{id}/maintenances'].get
  update:
    x-apievangelist-phrasing:
      intent: List occurrences of a maintenance window
      effect: read
      questions:
      - What individual maintenances has a recurring window produced?
      - Can I page through each scheduled occurrence of a maintenance window?
      instructions:
      - text: List the maintenance occurrences of window {id}.
        slots:
          id: path.id
      - text: Show page {page} of maintenances for window {id}.
        slots:
          page: query.page
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/maintenance-windows/{id}/maintenances/{maintenanceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one occurrence of a maintenance window
      effect: read
      questions:
      - When does one specific occurrence of my recurring maintenance start?
      - Can I look up a single maintenance within a maintenance window?
      instructions:
      - text: Show maintenance {maintenanceId} of window {id}.
        slots:
          maintenanceId: path.maintenanceId
          id: path.id
      - text: Get the dates of occurrence {maintenanceId} in maintenance window {id}.
        slots:
          maintenanceId: path.maintenanceId
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/maintenance-windows/{id}/maintenances/{maintenanceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Cancel one occurrence of a maintenance window
      effect: destructive
      questions:
      - Can I skip just one occurrence of a recurring maintenance window?
      - How do I delete a single maintenance without removing the whole window?
      instructions:
      - text: Delete occurrence {maintenanceId} from maintenance window {id}.
        slots:
          maintenanceId: path.maintenanceId
          id: path.id
      - text: Skip maintenance {maintenanceId} in window {id} but keep the rest.
        slots:
          maintenanceId: path.maintenanceId
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/maintenance-windows/{id}/maintenances/{maintenanceId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Reschedule one maintenance occurrence
      effect: write
      questions:
      - Can I shift the dates of a single maintenance occurrence?
      - How do I push back one scheduled maintenance by an hour?
      instructions:
      - text: Reschedule maintenance {maintenanceId} in window {id} to start {startsAt} and end {endsAt}.
        slots:
          maintenanceId: path.maintenanceId
          id: path.id
          startsAt: requestBody.startsAt
          endsAt: requestBody.endsAt
      - text: Change the end of maintenance {maintenanceId} in window {id} to {endsAt}.
        slots:
          maintenanceId: path.maintenanceId
          id: path.id
          endsAt: requestBody.endsAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/maintenance-windows/{id}/maintenances/{maintenanceId}/updates'].post
  update:
    x-apievangelist-phrasing:
      intent: Post a status update for a maintenance
      effect: write
      questions:
      - How do I tell status page subscribers that maintenance is in progress?
      - Can I post a maintenance progress update without emailing subscribers?
      instructions:
      - text: 'Post a {status} update on maintenance {maintenanceId} of window {id}: {description}.'
        slots:
          status: requestBody.status
          maintenanceId: path.maintenanceId
          id: path.id
          description: requestBody.description
      - text: Add update {description} with status {status} to maintenance {maintenanceId} in window {id} and notify subscribers {notifySubscribers}.
        slots:
          description: requestBody.description
          status: requestBody.status
          maintenanceId: path.maintenanceId
          id: path.id
          notifySubscribers: requestBody.notifySubscribers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/maintenance-windows/{id}/maintenances/{maintenanceId}/updates/{updateId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a maintenance status update
      effect: write
      questions:
      - Can I fix a typo in a maintenance update I already posted?
      - Does editing a maintenance update keep its status if I leave status out?
      instructions:
      - text: Change the text of update {updateId} on maintenance {maintenanceId} in window {id} to {description}.
        slots:
          updateId: path.updateId
          maintenanceId: path.maintenanceId
          id: path.id
          description: requestBody.description
      - text: Set update {updateId} on maintenance {maintenanceId} of window {id} to status {status} with text {description}.
        slots:
          updateId: path.updateId
          maintenanceId: path.maintenanceId
          id: path.id
          status: requestBody.status
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/maintenance-windows/{id}/maintenances/{maintenanceId}/updates/{updateId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a maintenance status update
      effect: destructive
      questions:
      - How do I take down a maintenance update posted by mistake?
      - Can I delete one status update from a maintenance?
      instructions:
      - text: Delete update {updateId} from maintenance {maintenanceId} in window {id}.
        slots:
          updateId: path.updateId
          maintenanceId: path.maintenanceId
          id: path.id
      - text: Remove status update {updateId} on maintenance {maintenanceId} of window {id}.
        slots:
          updateId: path.updateId
          maintenanceId: path.maintenanceId
          id: path.id
      method: generated
      generated: '2026-09-26'