openapi.yaml

openapi: 3.0.3
info:
  title: Status Dashboard API
  version: 1.0.0
  description: |
    Status Dashboard API for managing incidents, maintenance events, and components.

    ## Authentication & Field Visibility

    The API is an OIDC resource server. Bearer tokens are validated against the
    configured OIDC provider (Zitadel) using its discovery document and JWKS:

    - **Issuer**: `SD_OIDC_ISSUER` — must expose `/.well-known/openid-configuration`
    - **Audience**: `SD_OIDC_CLIENT_ID` — every accepted token must be issued to this client
    - **Roles**: the Zitadel roles claims — the generic
      `urn:zitadel:iam:org:project:roles` claim, the legacy `groups` claim a service
      identity carries and any project scoped roles claim the token carries

    Machine clients such as the metrics processor authenticate with a Zitadel
    service user and a private JWT. Only `RS256` tokens are accepted. Clients
    obtain tokens directly from the identity provider; this API never mints,
    refreshes or stores them.

    Some fields are only visible to authenticated users:
    - `creator` - User ID of the event creator
    - `contact_email` - Contact email for maintenance events
    - `version` - Version number for optimistic locking (maintenance events only)

    Maintenance events with status `pending_review` or `reviewed` are only visible to authenticated users.

    ## Optimistic Locking

    The API uses optimistic locking for maintenance events to prevent concurrent update conflicts:
    - GET requests return a `version` field for maintenance events (only for authenticated users)
    - PATCH requests for maintenance events must include the current `version` number
    - If the version doesn't match (event was modified by another user), a 409 Conflict is returned
    - On successful update, the version is automatically incremented

    ## Role-Based Access Control (RBAC)

    The API implements RBAC with four roles (highest to lowest privilege).
    Role names are abstract application roles mapped from the role names carried
    by the roles claim of the token via the `SD_RBAC_ROLES_*` environment variables.

    | Role | Permissions |
    |------|-------------|
    | `admin` | Unrestricted access to all operations; will gain additional system-level privileges in future releases |
    | `operator` | Full CRUD access to all maintenance events (event admin) — unrestricted status transitions, create events (status: `planned`), cancel from any status |
    | `creator` | Create maintenance events (status: `pending_review`), modify/cancel own events in `pending_review` only |
    | `reporter` | Machine principal — create system incidents (`"system": true`) via `POST /v2/events` only; read-only elsewhere |

    Roles are resolved from the roles claim, matched against:
    - `SD_RBAC_ROLES_ADMINS` (mandatory) — role name that maps to the `admin` role
    - `SD_RBAC_ROLES_OPERATORS` (optional) — role name that maps to the `operator` role
    - `SD_RBAC_ROLES_CREATORS` (optional) — role name that maps to the `creator` role
    - `SD_RBAC_ROLES_REPORTERS` (optional) — role name that maps to the `reporter` role

    RBAC is always active — there is no disable toggle.

    ### Error Responses
    - `401 Unauthorized` - Missing or invalid JWT token
    - `403 Forbidden` - Insufficient role permissions or not event owner
    - `403 Forbidden` - `reporter` role outside `POST /v2/events` with a system incident
servers:
  - url: http://localhost:8000
tags:
  - name: incidents
    description: Incident management
  - name: events
    description: Event management
  - name: components
    description: Operations about components
security:
  - BearerAuth: []
paths:
  /v2/components:
    get:
      summary: Get all components.
      tags:
        - components
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Component"
    post:
      summary: In development.
      tags:
        - components
      responses:
        "200":
          description: API under development.
  /v2/components/{component_id}:
    get:
      summary: Get target component.
      tags:
        - components
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Component"
        "404":
          description: The component is not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errMsg:
                    type: string
                    example: component does not exist

        "500":
          description: internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InternalServerError"
  /v2/availability:
    get:
      summary: Get availability.
      tags:
        - availability
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ComponentAvailability"
  /v2/incidents:
    get:
      deprecated: true
      summary: Get all incidents.
      tags:
        - incidents
      parameters:
        - $ref: "#/components/parameters/IncidentFilterType"
        - $ref: "#/components/parameters/IncidentFilterActive"
        - $ref: "#/components/parameters/IncidentFilterStatus"
        - $ref: "#/components/parameters/IncidentFilterStartDate"
        - $ref: "#/components/parameters/IncidentFilterEndDate"
        - $ref: "#/components/parameters/IncidentFilterImpact"
        - $ref: "#/components/parameters/IncidentFilterSystem"
        - $ref: "#/components/parameters/IncidentFilterComponents"
      responses:
        "200":
          description: Successful operation. Returns a list of incidents matching the criteria. If none match, data is an empty array.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Incidents"
    post:
      deprecated: true
      summary: Create an incident.
      tags:
        - incidents
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentPost"
        required: true
      responses:
        "200":
          description: Create an incident.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentPostResponse"
  /v2/events:
    get:
      summary: Get all events with pagination.
      tags:
        - events
      parameters:
        - $ref: "#/components/parameters/IncidentFilterType"
        - $ref: "#/components/parameters/IncidentFilterActive"
        - $ref: "#/components/parameters/IncidentFilterStatus"
        - $ref: "#/components/parameters/IncidentFilterStartDate"
        - $ref: "#/components/parameters/IncidentFilterEndDate"
        - $ref: "#/components/parameters/IncidentFilterImpact"
        - $ref: "#/components/parameters/IncidentFilterSystem"
        - $ref: "#/components/parameters/IncidentFilterComponents"
        - $ref: "#/components/parameters/PaginationLimit"
        - $ref: "#/components/parameters/PaginationPage"
      responses:
        "200":
          description: Successful operation. Returns a list of events matching the criteria. If none match, data is an empty array.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedEvents"
    post:
      summary: Create an event.
      tags:
        - events
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentPost"
        required: true
      responses:
        "200":
          description: Create an event.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentPostResponse"
        "401":
          description: Unauthorized - missing or invalid JWT token
        "403":
          description: Forbidden - insufficient permissions for this operation

  /v2/events/{event_id}:
    get:
      summary: Find an event by id.
      description: Returns a single event.
      tags:
        - events
      parameters:
        - name: event_id
          in: path
          description: ID of event to return
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Incident"
        "400":
          description: Invalid ID supplied
        "404":
          description: Event not found.
    patch:
      summary: Update an event.
      tags:
        - events
      parameters:
        - name: event_id
          in: path
          description: ID of event to update
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentPatch"
        required: true
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Incident"
        "400":
          description: Invalid ID supplied
        "404":
          description: Event not found.
        "401":
          description: Unauthorized - missing or invalid JWT token
        "403":
          description: Forbidden - insufficient permissions or not event owner
        "409":
          description: Version conflict - event has been modified by another user. Fetch the latest version and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestGeneralError"
  /v2/events/{event_id}/extract:
    post:
      summary: Extract components to the new event
      tags:
        - events
      parameters:
        - name: event_id
          in: path
          description: ID of event
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentPostExtract"
        required: true
      responses:
        "200":
          description: successful operation, return the new event id
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Incident"
        "400":
          description: Invalid ID supplied
        "404":
          description: Event not found.
  /v2/events/{event_id}/updates/{update_id}:
    patch:
      summary: Update the text of an event update.
      tags:
        - events
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: update_id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  example: "Updated status text"
      responses:
        "200":
          description: Update successful.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/EventUpdateData"
        "400":
          description: Invalid input.
        "404":
          description: Not found.

  /v2/incidents/{incident_id}:
    get:
      deprecated: true
      summary: Find an incident by id.
      description: Returns a single incident.
      tags:
        - incidents
      parameters:
        - name: incident_id
          in: path
          description: ID of incident to return
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Incident"
        "400":
          description: Invalid ID supplied
        "404":
          description: Incident not found.
    patch:
      deprecated: true
      summary: Update an incident.
      tags:
        - incidents
      parameters:
        - name: incident_id
          in: path
          description: ID of incident to return
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentPatch"
        required: true
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Incident"
        "400":
          description: Invalid ID supplied
        "404":
          description: Incident not found.
        "401":
          description: Unauthorized - missing or invalid JWT token
        "403":
          description: Forbidden - insufficient permissions or not event owner
        "409":
          description: Version conflict - incident has been modified by another user. Fetch the latest version and retry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestGeneralError"
  /v2/incidents/{incident_id}/extract:
    post:
      deprecated: true
      summary: extract components to the new incident
      tags:
        - incidents
      parameters:
        - name: incident_id
          in: path
          description: ID of incident to return
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentPostExtract"
        required: true
      responses:
        "200":
          description: successful operation, return the new incident id
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Incident"
        "400":
          description: Invalid ID supplied
        "404":
          description: Incident not found.
  /v2/incidents/{incident_id}/updates/{update_id}:
    patch:
      deprecated: true
      summary: Update the text of an incident update.
      tags:
        - incidents
      parameters:
        - name: incident_id
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: update_id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  example: "Updated status text"
      responses:
        "200":
          description: Update successful.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/EventUpdateData"
        "400":
          description: Invalid input.
        "404":
          description: Not found.

components:
  schemas:
    Component:
      type: object
      required:
        - id
        - name
        - attributes
      properties:
        id:
          type: integer
          format: int64
          example: 218
        name:
          type: string
          example: "Object Storage Service"
        attributes:
          $ref: "#/components/schemas/ComponentAttr"
    ComponentAttr:
      type: object
      properties:
        name:
          type: string
          enum:
            - category
            - region
            - type
          example: "category"
        value:
          type: string
          example: "Storage"
    ComponentNotFound:
      type: object
      properties:
        errMsg:
          type: string
          example: internal server error
    ComponentAvailability:
      type: object
      required:
        - id
        - name
        - region
        - availability
      properties:
        id:
          type: integer
          format: int64
          example: 218
        name:
          type: string
          example: "Auto Scaling"
        region:
          type: string
          example: "EU-DE"
        availability:
          type: array
          items:
            type: object
            required:
              - year
              - month
              - percentage
            properties:
              year:
                type: integer
                example: 2024
              month:
                type: integer
                example: 5
              percentage:
                type: number
                format: float
                example: 99.999666
    Incidents:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Incident"
    PaginatedEvents:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Incident"
        pagination:
          $ref: "#/components/schemas/Pagination"
    Pagination:
      type: object
      description: Pagination object
      properties:
        pageIndex:
          type: integer
          example: 1
        recordsPerPage:
          type: integer
          enum: [10, 20, 50]
          example: 50
        totalRecords:
          type: integer
          example: 500
        totalPages:
          type: integer
          example: 10
      required:
        - pageIndex
        - recordsPerPage
        - totalRecords
        - totalPages
    Incident:
      type: object
      required:
        - title
        - description
        - impact
        - components
        - start_date
        - system
        - type
      properties:
        id:
          type: integer
          format: int64
          example: 200
        title:
          type: string
          example: "OpenStack Upgrade in regions EU-DE/EU-NL"
        description:
          type: string
          example: "The service is partially unavailable or its performance has decreased."
        impact:
          type: integer
          enum: [0, 1, 2, 3]
          example: 1
        components:
          type: array
          items:
            type: string
          example: [218, 254]
        start_date:
          type: string
          format: date-time
        end_date:
          type: string
          format: date-time
        system:
          type: boolean
          example: false
        type:
          type: string
          enum:
            - "incident"
            - "maintenance"
            - "info"
          example: "incident"
        updates:
          type: array
          items:
            $ref: "#/components/schemas/IncidentStatus"
        status:
          type: string
          enum:
            - "analysing"
            - "fixing"
            - "impact changed"
            - "observing"
            - "resolved"
            - "reopened"
            - "changed"
            - "in_progress"
            - "modified"
            - "completed"
            - "planned"
            - "active"
            - "cancelled"
            - "pending_review"
            - "reviewed"
          example: "in_progress"
        creator:
          type: string
          description: "User ID of the event creator. Only visible to authenticated users."
          example: "user-123-uuid"
        contact_email:
          type: string
          format: email
          description: "Contact email for maintenance events. Only visible to authenticated users."
          example: "maintainer@example.com"
        version:
          type: integer
          format: int32
          description: "Version number for optimistic locking. Visible only to authenticated users and only for maintenance events. Automatically incremented on each maintenance update."
          example: 1
    IncidentPost:
      type: object
      required:
        - title
        - impact
        - components
        - start_date
        - type
      properties:
        title:
          type: string
          example: "OpenStack Upgrade in regions EU-DE/EU-NL"
        description:
          type: string
          example: "Any description for maintenance incident."
        impact:
          type: integer
          enum: [0, 1, 2, 3]
          example: 1
        components:
          type: array
          items:
            type: string
          example: [218, 254]
        start_date:
          type: string
          format: date-time
        end_date:
          type: string
          format: date-time
        system:
          type: boolean
          example: false
        type:
          type: string
          enum:
            - "incident"
            - "maintenance"
          example: "incident"
        contact_email:
          type: string
          format: email
          description: "Required for maintenance events. Contact email for the maintenance."
          example: "maintainer@example.com"
    IncidentPostResponse:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: "#/components/schemas/IncidentPostResult"
    IncidentPostResult:
      type: object
      properties:
        component_id:
          type: integer
          format: int64
          nullable: false
          example: 254
        incident_id:
          type: integer
          format: int64
          nullable: false
          example: 123
    IncidentPatch:
      type: object
      required:
        - message
        - status
        - update_date
      properties:
        title:
          type: string
          example: "OpenStack Upgrade in regions EU-DE/EU-NL"
        impact:
          type: integer
          enum: [0, 1, 2, 3]
          example: 1
        message:
          type: string
          example: "Any message why the incident was updated."
        status:
          type: string
          enum:
            - "in_progress"
            - "modified"
            - "completed"
            - "analysing"
            - "fixing"
            - "impact changed"
            - "observing"
            - "resolved"
            - "reopened"
            - "changed"
            - "planned"
            - "cancelled"
            - "pending_review"
            - "reviewed"
            - "active"
        update_date:
          type: string
          format: date-time
        start_date:
          type: string
          format: date-time
        end_date:
          type: string
          format: date-time
        version:
          type: integer
          format: int32
          description: "Current version number for optimistic locking. Required for maintenance PATCH requests; ignored for incident and info events."
          example: 1
    IncidentPostExtract:
      type: object
      required:
        - components
      properties:
        components:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: integer
          example: [218, 254]
    IncidentStatus:
      type: object
      allOf:
        - type: object
          properties:
            id:
              type: integer
              format: int64
              nullable: true
              example: 0
        - $ref: "#/components/schemas/IncidentStatusPost"
    IncidentStatusPost:
      type: object
      properties:
        status:
          type: string
          example: "resolved"
        text:
          type: string
          example: "issue resolved"
        timestamp:
          type: string
          format: date-time
    InternalServerError:
      type: object
      properties:
        errMsg:
          type: string
          example: internal server error
    BadRequestGeneralError:
      type: object
      properties:
        errMsg:
          type: string
          example: "any error message"
    EventUpdateData:
      type: object
      properties:
        id:
          type: integer
        status:
          type: string
        text:
          type: string
        timestamp:
          type: string
          format: date-time
  parameters:
    IncidentFilterType:
      name: type
      in: query
      description: Filter by incident type ('incident', 'maintenance' or 'info'). Can be a comma-separated list of types.
      required: false
      schema:
        type: string
        example: "incident,maintenance"
    IncidentFilterActive:
      name: active
      in: query
      description: Filter by active status for events. For incidents, this means the incident is currently ongoing. For maintenance, it means the maintenance is currently in progress. And for info, it means the info event is currently active. Supporting only 'true' value.
      required: false
      schema:
        type: boolean
    IncidentFilterStatus:
      name: status
      in: query
      description: Filter by the latest incident status (e.g., 'resolved', 'fixing', 'completed'). See backend implementation for all valid statuses.
      required: false
      schema:
        type: string
    IncidentFilterStartDate:
      name: start_date
      in: query
      description: Filter incidents active on or after this date (RFC3339 format).
      required: false
      schema:
        type: string
        format: date-time
        example: "2026-04-01T00:00:00Z"
    IncidentFilterEndDate:
      name: end_date
      in: query
      description: Filter incidents active on or before this date (RFC3339 format). Must be after start_date if both are provided.
      required: false
      schema:
        type: string
        format: date-time
        example: "2026-04-30T23:59:59Z"
    IncidentFilterImpact:
      name: impact
      in: query
      description: Filter by specific impact level (0=Maintenance, 1=Minor, 2=Major, 3=Outage).
      required: false
      schema:
        type: integer
        enum: [0, 1, 2, 3]
        example: 2
    IncidentFilterSystem:
      name: system
      in: query
      description: Filter by whether the incident was system-generated ('true') or manually created ('false').
      required: false
      schema:
        type: boolean
    IncidentFilterComponents:
      name: components
      in: query
      description: Filter by associated component IDs (comma-separated list of positive integers).
      required: false
      schema:
        type: string
        example: "1,5,23"
    PaginationPage:
      name: page
      in: query
      description: The page number for pagination.
      required: false
      schema:
        type: integer
        example: 1
    PaginationLimit:
      name: limit
      in: query
      description: The numbers of items to return.
      required: false
      schema:
        type: integer
        enum: [10, 20, 50]
        default: 50
        example: 50
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT bearer token issued by the OIDC provider (Zitadel).
        Include in Authorization header as "Bearer <token>".