# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Cumulocity Alarm Alarms API
  version: 1.0.0
extends: openapi/cumulocity-alarms-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: 6
- target: $.paths['/alarm/alarms'].get
  update:
    x-apievangelist-phrasing:
      intent: List alarms raised on devices
      effect: read
      questions:
      - Which alarms are currently active on my Cumulocity devices?
      - Can I filter the alarm list by severity, such as only critical ones?
      - What alarms were raised for one device between two dates?
      instructions:
      - text: List active alarms for device {source}.
        slots:
          source: query.source
      - text: Show all {severity} alarms raised since {dateFrom}.
        slots:
          severity: query.severity
          dateFrom: query.dateFrom
      - text: List alarms of type {type} that are already resolved.
        slots:
          type: query.type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/alarm/alarms'].put
  update:
    x-apievangelist-phrasing:
      intent: Update many alarms at once by filter
      effect: write
      questions:
      - How do I acknowledge every active alarm on a device in one call?
      - Can I change the status of all alarms matching a filter at once?
      instructions:
      - text: Set every {status} alarm on device {source} to ACKNOWLEDGED in bulk.
        slots:
          status: query.status
          source: query.source
      - text: Bulk-clear all alarms raised by device {source}.
        slots:
          source: query.source
      method: generated
      generated: '2026-10-01'
- target: $.paths['/alarm/alarms'].post
  update:
    x-apievangelist-phrasing:
      intent: Raise a new alarm for a device
      effect: write
      questions:
      - How can I raise an alarm against a device from my own code?
      - What fields are required when creating a new alarm, like severity and text?
      instructions:
      - text: Raise a {severity} alarm of type {type} on device {source} saying "{text}" at {time}.
        slots:
          severity: requestBody.severity
          type: requestBody.type
          source: requestBody.source
          text: requestBody.text
          time: requestBody.time
      - text: Create a new {status} alarm for device {source} with message {text}.
        slots:
          status: requestBody.status
          source: requestBody.source
          text: requestBody.text
      method: generated
      generated: '2026-10-01'
- target: $.paths['/alarm/alarms'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete alarms matching a filter
      effect: destructive
      questions:
      - Is there a way to purge a whole batch of old alarms by filter?
      - Can I wipe out many alarms in one request instead of one at a time?
      instructions:
      - text: Delete all alarms matching the current filter.
      - text: Purge the alarm collection by filter in a single request.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/alarm/alarms/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a single alarm by ID
      effect: read
      questions:
      - How do I fetch the full details of one alarm by its ID?
      - What severity and status does a specific alarm have right now?
      instructions:
      - text: Show me alarm {id}.
        slots:
          id: path.id
      - text: Get the severity, count and first occurrence time of alarm {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/alarm/alarms/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Change the status or text of one alarm
      effect: write
      questions:
      - How do I acknowledge or clear one specific alarm?
      - Can I change the severity of an alarm I already raised?
      instructions:
      - text: Set the status of alarm {id} to {status}.
        slots:
          id: path.id
          status: requestBody.status
      - text: Change alarm {id} to severity {severity} with text {text}.
        slots:
          id: path.id
          severity: requestBody.severity
          text: requestBody.text
      method: generated
      generated: '2026-10-01'