# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Soda Cloud API v4 Incidents API
  version: 1.0.0
extends: openapi/soda-data-incidents-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['/api/v1/incidents'].get
  update:
    x-apievangelist-phrasing:
      intent: List data quality incidents
      effect: read
      questions:
      - Which data quality incidents are open right now?
      - Can I filter incidents by severity or by the lead assigned?
      - What incidents were raised on a dataset during a date range?
      instructions:
      - text: List incidents with status {status}.
        slots:
          status: query.status
      - text: Show {severity} severity incidents on dataset {datasetId}.
        slots:
          severity: query.severity
          datasetId: query.datasetId
      - text: List incidents led by {leadId} between {from} and {to}.
        slots:
          leadId: query.leadId
          from: query.from
          to: query.to
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/incidents'].post
  update:
    x-apievangelist-phrasing:
      intent: Open an incident
      effect: write
      questions:
      - How do I raise an incident from failing monitor results?
      - Can I assign a lead when opening a new incident?
      instructions:
      - text: 'Open a {severity} incident titled {title} for monitor results {monitorResultIds}: {description}.'
        slots:
          severity: requestBody.severity
          title: requestBody.title
          monitorResultIds: requestBody.monitorResultIds
          description: requestBody.description
      - text: Create incident {title} ({severity}) on results {monitorResultIds}, lead {leadId}, described as {description}.
        slots:
          title: requestBody.title
          severity: requestBody.severity
          monitorResultIds: requestBody.monitorResultIds
          leadId: requestBody.leadId
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/incidents/{incidentId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update an incident
      effect: write
      questions:
      - How do I mark an existing incident as resolved with notes?
      - Can I change the severity of an incident already open?
      instructions:
      - text: Set incident {incidentId} to status {status}.
        slots:
          incidentId: path.incidentId
          status: requestBody.status
      - text: Resolve incident {incidentId} with notes {resolutionNotes}.
        slots:
          incidentId: path.incidentId
          resolutionNotes: requestBody.resolutionNotes
      - text: Change the severity of incident {incidentId} to {severity}.
        slots:
          incidentId: path.incidentId
          severity: requestBody.severity
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/incidents/{incidentId}/rcaReport'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an incident's root cause analysis
      effect: read
      questions:
      - What was the root cause of this data incident?
      - Is there a published impact assessment for an incident?
      instructions:
      - text: Show the root cause analysis report for incident {incidentId}.
        slots:
          incidentId: path.incidentId
      - text: Get the impact assessment published on incident {incidentId}.
        slots:
          incidentId: path.incidentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/incidents/{incidentId}/rcaReport'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish a root cause analysis report
      effect: write
      questions:
      - Can an agent attach a root cause analysis to an incident?
      - Does publishing an RCA report change the incident's title or status?
      instructions:
      - text: Publish root cause analysis {rootCauseAnalysis} on incident {incidentId}, authored by agent {agent}.
        slots:
          rootCauseAnalysis: requestBody.rootCauseAnalysis
          incidentId: path.incidentId
          agent: requestBody.agent
      - text: Attach RCA {rootCauseAnalysis} and impact assessment {impactAssessment} to incident {incidentId} as {agent}.
        slots:
          rootCauseAnalysis: requestBody.rootCauseAnalysis
          impactAssessment: requestBody.impactAssessment
          incidentId: path.incidentId
          agent: requestBody.agent
      method: generated
      generated: '2026-09-26'