openapi: 3.1.0
info:
  title: Status Dashboard API
  description: >
    Read-only public API for the Status Dashboard (SSD). Returns the current
    operational status of all monitored services. No authentication is required.
  version: 1.0.0

servers:
  - url: https://status.cloud.coop
    description: Production

paths:
  /api/v1/services:
    get:
      operationId: getServices
      summary: Get current service statuses
      description: >
        Returns the current status of every monitored service. Operational
        services include only `name` and `status`. Services with an active
        incident or maintenance event also include `impact_level`,
        `impact_color`, and `event_id`.

        Only services that are enabled in the admin are returned. Disabled
        services are hidden from this endpoint and from the dashboard, but
        their historical events are preserved.

        Responses are cached by the dashboard and served from the same
        in-memory cache used by the main UI, so there is no additional
        database load for consumers of this endpoint.
      tags:
        - Services
      responses:
        "200":
          description: Successful response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
                example: "*"
              description: CORS header — always set to `*`
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServicesResponse"
              examples:
                allOperational:
                  summary: All services operational
                  value:
                    generated: "2026-03-23T14:00:00+00:00"
                    overall_status: operational
                    services:
                      - name: Email Service
                        status: operational
                      - name: Web Portal
                        status: operational
                activeIncident:
                  summary: Active incident on one service
                  value:
                    generated: "2026-03-23T14:05:00+00:00"
                    overall_status: incident
                    services:
                      - name: Email Service
                        status: operational
                      - name: Web Portal
                        status: incident
                        impact_level: Service Disruption
                        impact_color: yellow
                        event_id: 42
                activeMaintenance:
                  summary: Maintenance in progress
                  value:
                    generated: "2026-03-23T02:00:00+00:00"
                    overall_status: maintenance
                    services:
                      - name: Email Service
                        status: operational
                      - name: File Storage
                        status: maintenance
                        impact_level: Maintenance
                        impact_color: blue
                        event_id: 17
        "405":
          description: Method not allowed — only GET is supported

components:
  schemas:
    ServicesResponse:
      type: object
      required:
        - generated
        - overall_status
        - services
      properties:
        generated:
          type: string
          format: date-time
          description: ISO-8601 UTC timestamp of when this response was generated
          example: "2026-03-23T14:00:00+00:00"
        overall_status:
          $ref: "#/components/schemas/StatusValue"
          description: >
            Worst status across all services. `incident` takes precedence
            over `maintenance`, which takes precedence over `operational`.
        services:
          type: array
          items:
            $ref: "#/components/schemas/ServiceStatus"

    ServiceStatus:
      type: object
      required:
        - name
        - status
      properties:
        name:
          type: string
          description: Service display name
          example: Email Service
        status:
          $ref: "#/components/schemas/StatusValue"
        impact_level:
          type: string
          description: >
            Name of the active impact level. Present only when `status` is
            not `operational`.
          example: Service Disruption
        impact_color:
          $ref: "#/components/schemas/ImpactColor"
        event_id:
          type: integer
          description: >
            ID of the active event driving this status. Present only when
            `status` is not `operational`. Use to link to the detail page:
            incidents at `/i_detail?id={event_id}`,
            maintenance at `/m_detail?id={event_id}`.
          example: 42

    StatusValue:
      type: string
      enum:
        - operational
        - incident
        - maintenance
      description: Current operational status

    ImpactColor:
      type: string
      enum:
        - red
        - yellow
        - blue
        - green
      description: >
        Color associated with the impact level. Present only when `status`
        is not `operational`. Priority order (highest to lowest):
        red > yellow > blue > green. When a service has both an active
        incident and maintenance event, the highest-priority color wins.
      example: yellow