# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Better Stack Uptime Incidents API
  version: 1.0.0
extends: openapi/betterstack-incidents-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: 9
- target: $.paths['/incidents'].get
  update:
    x-apievangelist-phrasing:
      intent: List incidents
      effect: read
      questions:
      - Which incidents have been opened in my Better Stack account?
      - Can I page through my incident history in smaller batches?
      instructions:
      - text: List all of my incidents.
      - text: Show page {page} of incidents with {per_page} per page.
        slots:
          page: query.page
          per_page: query.per_page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/incidents'].post
  update:
    x-apievangelist-phrasing:
      intent: Open a new incident and alert the team
      effect: write
      questions:
      - How do I manually raise an incident and page my on-call team?
      - Can I choose whether a new incident alerts people by call, SMS, email or push?
      instructions:
      - text: Open an incident titled {summary} reported by {requester_email}.
        slots:
          summary: requestBody.summary
          requester_email: requestBody.requester_email
      - text: 'Create an incident {summary} from {requester_email} with details: {description}.'
        slots:
          summary: requestBody.summary
          requester_email: requestBody.requester_email
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/incidents/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an incident's details
      effect: read
      questions:
      - What is the current status of a specific incident?
      - Who reported a given incident and what was its summary?
      instructions:
      - text: Show me incident {id}.
        slots:
          id: path.id
      - text: Fetch the details of incident {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/incidents/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an incident
      effect: destructive
      questions:
      - Can I permanently remove an incident that was opened by mistake?
      - Is deleting an incident different from resolving it?
      instructions:
      - text: Delete incident {id}.
        slots:
          id: path.id
      - text: Permanently remove incident {id} from the record.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/incidents/{id}/timeline'].get
  update:
    x-apievangelist-phrasing:
      intent: View an incident's timeline of events
      effect: read
      questions:
      - What happened during an incident, step by step?
      - When was an incident acknowledged and escalated?
      instructions:
      - text: Show the timeline of incident {id}.
        slots:
          id: path.id
      - text: List every event recorded on incident {id} in order.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/incidents/{id}/acknowledge'].post
  update:
    x-apievangelist-phrasing:
      intent: Acknowledge an incident
      effect: write
      questions:
      - How do I tell the team I'm working on an incident so alerts stop escalating?
      - Can I acknowledge an incident without resolving it?
      instructions:
      - text: Acknowledge incident {id}.
        slots:
          id: path.id
      - text: Mark incident {id} as acknowledged, I'm on it.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/incidents/{id}/resolve'].post
  update:
    x-apievangelist-phrasing:
      intent: Resolve an incident
      effect: write
      questions:
      - Can I close out an incident once the problem is fixed?
      - What do I call to mark an outage as resolved?
      instructions:
      - text: Resolve incident {id}.
        slots:
          id: path.id
      - text: Mark incident {id} as fixed and resolved.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/incidents/{id}/reopen'].post
  update:
    x-apievangelist-phrasing:
      intent: Reopen a resolved incident
      effect: write
      questions:
      - The problem came back. Can I reopen an incident I already resolved?
      - Is it possible to undo resolving an incident?
      instructions:
      - text: Reopen incident {id}.
        slots:
          id: path.id
      - text: Reopen resolved incident {id} because the issue has returned.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/incidents/{id}/escalate'].post
  update:
    x-apievangelist-phrasing:
      intent: Escalate an incident to more responders
      effect: write
      questions:
      - How do I escalate an incident when nobody has responded?
      - Can I push an incident up the escalation chain right away?
      instructions:
      - text: Escalate incident {id}.
        slots:
          id: path.id
      - text: Escalate incident {id} to the next people on call now.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'