# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for BigPanda Changes & Root Cause API
  version: 1.0.0
extends: openapi/bigpanda-changes-root-cause-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: 6
- target: $.paths['/resources/v2.0/rcc'].get
  update:
    x-apievangelist-phrasing:
      intent: List root cause change relations
      effect: read
      questions:
      - Which changes have been linked as possible root causes of an incident?
      - Can I see the history of RCC relations for a given change?
      instructions:
      - text: List RCC relations for incident {incident_id}.
        slots:
          incident_id: query.incident_id
      - text: Show RCC relations for change {change_id}, including history set to {include_history}.
        slots:
          change_id: query.change_id
          include_history: query.include_history
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.0/rcc'].post
  update:
    x-apievangelist-phrasing:
      intent: Link a change to an incident as a root cause
      effect: write
      questions:
      - How do I mark a change as the likely cause of an incident?
      - Can I record how certain I am that a change caused an incident?
      instructions:
      - text: Link change {change_id} to incident {incident_id} with match certainty {match_certainty}.
        slots:
          change_id: requestBody.change_id
          incident_id: requestBody.incident_id
          match_certainty: requestBody.match_certainty
      - text: Flag change {change_id} as a {match_certainty} root cause of {incident_id}, commenting {comment}.
        slots:
          change_id: requestBody.change_id
          match_certainty: requestBody.match_certainty
          incident_id: requestBody.incident_id
          comment: requestBody.comment
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.0/changes'].get
  update:
    x-apievangelist-phrasing:
      intent: Search change records in a time frame
      effect: read
      questions:
      - What changes went out in the hour before an incident started?
      - Can I search change records by keyword within a date range?
      instructions:
      - text: List changes between {start_time_frame} and {end_time_frame}.
        slots:
          start_time_frame: query.start_time_frame
          end_time_frame: query.end_time_frame
      - text: Search changes for {search} from {start_time_frame} to {end_time_frame}, limited to {limit}.
        slots:
          search: query.search
          start_time_frame: query.start_time_frame
          end_time_frame: query.end_time_frame
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.0/changes/{change_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a change record
      effect: read
      questions:
      - What are the details of a specific change record?
      - Can I pull one change by its ID to check what it touched?
      instructions:
      - text: Get change {change_id}.
        slots:
          change_id: path.change_id
      - text: Show me the full record for change {change_id}.
        slots:
          change_id: path.change_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.0/rcc/{related_change_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a root cause change relation
      effect: read
      questions:
      - What certainty and comment are on a specific RCC relation?
      - Can I look up one root cause change relation by its ID?
      instructions:
      - text: Get RCC relation {related_change_id}.
        slots:
          related_change_id: path.related_change_id
      - text: Show the details of related change {related_change_id}.
        slots:
          related_change_id: path.related_change_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.0/rcc/{related_change_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a root cause change relation
      effect: write
      questions:
      - Can I raise or lower the match certainty on a linked root cause change?
      - Can I add a comment to an existing RCC relation?
      instructions:
      - text: Set match certainty on RCC relation {related_change_id} to {match_certainty}.
        slots:
          related_change_id: path.related_change_id
          match_certainty: requestBody.match_certainty
      - text: Update the comment on related change {related_change_id} to {comment}.
        slots:
          related_change_id: path.related_change_id
          comment: requestBody.comment
      method: generated
      generated: '2026-09-26'