AlertCamp Health API

openapi: 3.2.0
info:
  title: AlertCamp Health API
  description: Service d'alertes de disponibilité SEPAQ pour le camping au Québec
  version: 0.1.0
tags:
- name: Health
paths:
  /health:
    get:
      tags:
      - Health
      summary: Health Check
      description: 'Health check endpoint.


        Performs real checks against database, polling loop, and circuit

        breaker. Returns overall status: healthy, degraded, or unhealthy.

        Uptime Robot keyword monitoring should check for "healthy".'
      operationId: health_check_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
  /ping:
    get:
      tags:
      - Health
      summary: Ping
      description: 'Minimal liveness probe. Always returns 200 with {"status": "ok"}.'
      operationId: ping_ping_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'
components:
  schemas:
    NotificationHealth:
      properties:
        total:
          type: integer
          title: Total
          default: 0
        push_sent:
          type: integer
          title: Push Sent
          default: 0
        push_failed:
          type: integer
          title: Push Failed
          default: 0
        email_sent:
          type: integer
          title: Email Sent
          default: 0
        email_failed:
          type: integer
          title: Email Failed
          default: 0
        sms_sent:
          type: integer
          title: Sms Sent
          default: 0
        sms_failed:
          type: integer
          title: Sms Failed
          default: 0
      type: object
      title: NotificationHealth
      description: Notification service stats.
    PingResponse:
      properties:
        status:
          type: string
          title: Status
          default: ok
      type: object
      title: PingResponse
      description: Minimal liveness probe response.
    PollingBacklog:
      properties:
        sites_tracked:
          type: integer
          title: Sites Tracked
          default: 0
        sites_overdue:
          type: integer
          title: Sites Overdue
          default: 0
        max_overdue_seconds:
          type: number
          title: Max Overdue Seconds
          default: 0.0
        max_overdue_ratio:
          type: number
          title: Max Overdue Ratio
          default: 0.0
        max_overdue_tier:
          anyOf:
          - type: string
          - type: 'null'
          title: Max Overdue Tier
      type: object
      title: PollingBacklog
      description: Polling backlog metrics — shows whether the backend can keep up.
    CircuitBreakerHealth:
      properties:
        status:
          $ref: '#/components/schemas/ComponentStatus'
        state:
          type: string
          title: State
        failure_count:
          type: integer
          title: Failure Count
          default: 0
        opened_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Opened At
      type: object
      required:
      - status
      - state
      title: CircuitBreakerHealth
      description: Circuit breaker component health.
    ComponentStatus:
      type: string
      enum:
      - ok
      - warn
      - fail
      title: ComponentStatus
      description: Health status of an individual component.
    WorkerStatus:
      properties:
        node_name:
          type: string
          title: Node Name
        instance_role:
          type: string
          title: Instance Role
        polling_tiers:
          type: string
          title: Polling Tiers
        status:
          type: string
          title: Status
        uptime_seconds:
          type: number
          title: Uptime Seconds
        last_heartbeat_seconds_ago:
          type: number
          title: Last Heartbeat Seconds Ago
        polling_task_running:
          type: boolean
          title: Polling Task Running
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        sites_polled_total:
          type: integer
          title: Sites Polled Total
          default: 0
        sites_successful:
          type: integer
          title: Sites Successful
          default: 0
        sites_failed:
          type: integer
          title: Sites Failed
          default: 0
        success_rate:
          type: number
          title: Success Rate
          default: 0.0
        sites_polled_by_tier:
          additionalProperties:
            type: integer
          type: object
          title: Sites Polled By Tier
          default: {}
        sites_tracked:
          type: integer
          title: Sites Tracked
          default: 0
        sites_overdue:
          type: integer
          title: Sites Overdue
          default: 0
        stats_sites_tracked:
          type: integer
          title: Stats Sites Tracked
          default: 0
        stats_sites_overdue:
          type: integer
          title: Stats Sites Overdue
          default: 0
      type: object
      required:
      - node_name
      - instance_role
      - polling_tiers
      - status
      - uptime_seconds
      - last_heartbeat_seconds_ago
      - polling_task_running
      title: WorkerStatus
      description: Health status of a single cluster node.
    StuckTarget:
      properties:
        provider:
          type: string
          title: Provider
        tier:
          type: string
          title: Tier
        worst_overdue_seconds:
          type: number
          title: Worst Overdue Seconds
        max_window_seconds:
          type: number
          title: Max Window Seconds
        windows_overdue:
          type: number
          title: Windows Overdue
        stuck_since:
          type: string
          title: Stuck Since
      type: object
      required:
      - provider
      - tier
      - worst_overdue_seconds
      - max_window_seconds
      - windows_overdue
      - stuck_since
      title: StuckTarget
      description: 'One (provider, tier) whose WORST single poll target is badly overdue.


        Ops-only: this is deliberately NOT folded into ``provider_tier_status``.

        A single stuck target means one user''s alert is dark, not that the provider

        is down for everyone, so it degrades the aggregate ``/health`` status (what

        the uptime monitor keys on) without showing a degraded banner to every user

        of that provider and tier.'
    DatabaseHealth:
      properties:
        status:
          $ref: '#/components/schemas/ComponentStatus'
        latency_ms:
          anyOf:
          - type: number
          - type: 'null'
          title: Latency Ms
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      type: object
      required:
      - status
      title: DatabaseHealth
      description: Database component health.
    HealthResponse:
      properties:
        status:
          $ref: '#/components/schemas/HealthStatus'
        app:
          type: string
          title: App
        version:
          type: string
          title: Version
        environment:
          type: string
          title: Environment
        uptime_seconds:
          type: number
          title: Uptime Seconds
        started_at:
          type: string
          title: Started At
        checked_at:
          type: string
          title: Checked At
        min_app_version:
          type: string
          title: Min App Version
        database:
          $ref: '#/components/schemas/DatabaseHealth'
        polling:
          $ref: '#/components/schemas/PollingHealth'
        circuit_breaker:
          anyOf:
          - $ref: '#/components/schemas/CircuitBreakerHealth'
          - type: 'null'
        notifications:
          $ref: '#/components/schemas/NotificationHealth'
        cluster:
          anyOf:
          - $ref: '#/components/schemas/ClusterHealth'
          - type: 'null'
        status_reasons:
          items:
            type: string
          type: array
          title: Status Reasons
          default: []
      type: object
      required:
      - status
      - app
      - version
      - environment
      - uptime_seconds
      - started_at
      - checked_at
      - min_app_version
      - database
      - polling
      - notifications
      title: HealthResponse
      description: Full health check response.
    PollingHealth:
      properties:
        status:
          $ref: '#/components/schemas/ComponentStatus'
        task_running:
          type: boolean
          title: Task Running
        last_poll_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Poll At
        seconds_since_last_poll:
          anyOf:
          - type: number
          - type: 'null'
          title: Seconds Since Last Poll
        sites_polled_total:
          type: integer
          title: Sites Polled Total
          default: 0
        sites_successful:
          type: integer
          title: Sites Successful
          default: 0
        sites_failed:
          type: integer
          title: Sites Failed
          default: 0
        sites_skipped:
          type: integer
          title: Sites Skipped
          default: 0
        cancellations_detected:
          type: integer
          title: Cancellations Detected
          default: 0
        alerts_matched:
          type: integer
          title: Alerts Matched
          default: 0
        api_calls_total:
          type: integer
          title: Api Calls Total
          default: 0
        success_rate:
          type: number
          title: Success Rate
          default: 0.0
        sites_polled_by_tier:
          additionalProperties:
            type: integer
          type: object
          title: Sites Polled By Tier
          default: {}
        backlog:
          anyOf:
          - $ref: '#/components/schemas/PollingBacklog'
          - type: 'null'
        stats_backlog:
          anyOf:
          - $ref: '#/components/schemas/PollingBacklog'
          - type: 'null'
        stress_mode:
          additionalProperties:
            additionalProperties:
              type: boolean
            type: object
          type: object
          title: Stress Mode
          default: {}
        maintenance_mode:
          type: boolean
          title: Maintenance Mode
          default: false
        maintenance_since:
          anyOf:
          - type: string
          - type: 'null'
          title: Maintenance Since
        maintenance_providers:
          items:
            type: string
          type: array
          title: Maintenance Providers
          default: []
        maintenance_since_by_provider:
          additionalProperties:
            type: string
          type: object
          title: Maintenance Since By Provider
          default: {}
        provider_status:
          additionalProperties:
            type: string
          type: object
          title: Provider Status
          default: {}
        provider_tier_status:
          additionalProperties:
            additionalProperties:
              type: string
            type: object
          type: object
          title: Provider Tier Status
          default: {}
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        status_reasons:
          items:
            type: string
          type: array
          title: Status Reasons
          default: []
      type: object
      required:
      - status
      - task_running
      title: PollingHealth
      description: Polling loop component health.
    HealthStatus:
      type: string
      enum:
      - healthy
      - degraded
      - unhealthy
      title: HealthStatus
      description: Overall health status of the application.
    ClusterHealth:
      properties:
        status:
          $ref: '#/components/schemas/ComponentStatus'
        total_nodes:
          type: integer
          title: Total Nodes
        healthy_nodes:
          type: integer
          title: Healthy Nodes
        workers:
          items:
            $ref: '#/components/schemas/WorkerStatus'
          type: array
          title: Workers
        cluster_sites_polled:
          type: integer
          title: Cluster Sites Polled
          default: 0
        cluster_sites_successful:
          type: integer
          title: Cluster Sites Successful
          default: 0
        cluster_sites_failed:
          type: integer
          title: Cluster Sites Failed
          default: 0
        cluster_success_rate:
          type: number
          title: Cluster Success Rate
          default: 0.0
        cluster_alerts_matched:
          type: integer
          title: Cluster Alerts Matched
          default: 0
        cluster_requests_per_second:
          type: number
          title: Cluster Requests Per Second
          default: 0.0
        cluster_backlog:
          anyOf:
          - $ref: '#/components/schemas/PollingBacklog'
          - type: 'null'
        cluster_stats_backlog:
          anyOf:
          - $ref: '#/components/schemas/PollingBacklog'
          - type: 'null'
        cluster_provider_status:
          additionalProperties:
            type: string
          type: object
          title: Cluster Provider Status
          default: {}
        cluster_maintenance_providers:
          items:
            type: string
          type: array
          title: Cluster Maintenance Providers
          default: []
        cluster_maintenance_since:
          additionalProperties:
            type: string
          type: object
          title: Cluster Maintenance Since
          default: {}
        provider_tier_status:
          additionalProperties:
            additionalProperties:
              type: string
            type: object
          type: object
          title: Provider Tier Status
          default: {}
        stuck_targets:
          items:
            $ref: '#/components/schemas/StuckTarget'
          type: array
          title: Stuck Targets
          default: []
      type: object
      required:
      - status
      - total_nodes
      - healthy_nodes
      - workers
      title: ClusterHealth
      description: Aggregate health of all nodes in the cluster.