openapi: 3.1.0
info:
  title: Enterprise Incident Framework API
  version: 2026-07-06
servers:
  - url: https://incident.example.com/api/v1
paths:
  /incidents:
    get:
      summary: List incidents
      parameters:
        - name: status
          in: query
          schema:
            type: string
        - name: categoryId
          in: query
          schema:
            type: string
        - name: severity
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Incident list
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Incident"
    post:
      summary: Create incident
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentCreate"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Incident"
  /incidents/{incidentId}:
    get:
      summary: Get incident
      parameters:
        - $ref: "#/components/parameters/IncidentId"
      responses:
        "200":
          description: Incident
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Incident"
    patch:
      summary: Update incident metadata
      parameters:
        - $ref: "#/components/parameters/IncidentId"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: Updated incident
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Incident"
  /incidents/{incidentId}/transitions:
    post:
      summary: Transition lifecycle state
      parameters:
        - $ref: "#/components/parameters/IncidentId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LifecycleTransition"
      responses:
        "201":
          description: Transition recorded
  /incidents/{incidentId}/timeline:
    post:
      summary: Add timeline event
      parameters:
        - $ref: "#/components/parameters/IncidentId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TimelineEvent"
      responses:
        "201":
          description: Timeline event created
  /incidents/{incidentId}/evidence:
    post:
      summary: Register evidence item
      parameters:
        - $ref: "#/components/parameters/IncidentId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EvidenceItem"
      responses:
        "201":
          description: Evidence registered
  /incidents/{incidentId}/communications/generate:
    post:
      summary: Generate communication draft
      parameters:
        - $ref: "#/components/parameters/IncidentId"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [audience, templateId]
              properties:
                audience:
                  type: string
                templateId:
                  type: string
                redactionProfile:
                  type: string
      responses:
        "200":
          description: Generated communication draft
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Communication"
  /incidents/{incidentId}/reports/generate:
    post:
      summary: Generate report
      parameters:
        - $ref: "#/components/parameters/IncidentId"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [reportType, format]
              properties:
                reportType:
                  type: string
                  enum: [technical, postmortem, rca, executive, security, soc, timeline, evidence, regulatory, audit, status_page, customer_postmortem]
                format:
                  type: string
                  enum: [markdown, html, pdf, json, csv, text]
                redactionProfile:
                  type: string
      responses:
        "200":
          description: Report export
          content:
            application/json:
              schema:
                type: object
                properties:
                  reportId:
                    type: string
                  uri:
                    type: string
components:
  parameters:
    IncidentId:
      name: incidentId
      in: path
      required: true
      schema:
        type: string
  schemas:
    Incident:
      type: object
      required: [id, title, category, severity, status, createdAt]
      properties:
        id:
          type: string
        title:
          type: string
        summary:
          type: string
        category:
          $ref: "#/components/schemas/Category"
        severity:
          type: object
        status:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    IncidentCreate:
      type: object
      required: [title, summary, category, severity, timezone, ownership, environment]
      properties:
        title:
          type: string
        summary:
          type: string
        category:
          $ref: "#/components/schemas/Category"
        severity:
          type: object
        timezone:
          type: string
        ownership:
          type: object
        environment:
          type: object
    Category:
      type: object
      required: [id, name, family]
      properties:
        id:
          type: string
        name:
          type: string
        family:
          type: string
        tags:
          type: array
          items:
            type: string
    LifecycleTransition:
      type: object
      required: [from, to, actor, reason]
      properties:
        from:
          type: string
        to:
          type: string
        actor:
          type: object
        reason:
          type: string
        evidenceRefs:
          type: array
          items:
            type: string
    TimelineEvent:
      type: object
      required: [timestamp, actor, source, category, description, confidence]
      properties:
        timestamp:
          type: string
          format: date-time
        actor:
          type: object
        source:
          type: string
        category:
          type: string
        description:
          type: string
        confidence:
          type: string
    EvidenceItem:
      type: object
      required: [id, category, description, source, collector, collectedAt, confidentiality, integrityStatus, retentionPolicy]
      properties:
        id:
          type: string
        category:
          type: string
        description:
          type: string
        source:
          type: string
        collector:
          type: object
        collectedAt:
          type: string
          format: date-time
        sha256:
          type: string
        confidentiality:
          type: string
        integrityStatus:
          type: string
    Communication:
      type: object
      required: [id, audience, channel, status, body]
      properties:
        id:
          type: string
        audience:
          type: string
        channel:
          type: string
        status:
          type: string
        subject:
          type: string
        body:
          type: string

