openapi: 3.0.1
info:
  title: Hyperping API
  description: >-
    REST API for the Hyperping uptime monitoring and status page platform.
    Programmatically manage monitors, cron-style healthchecks, status page
    incidents and maintenance windows, on-call outages, and uptime / SLA
    reporting. All requests are authenticated with a project API key passed as
    a Bearer token in the Authorization header. Note that Hyperping versions
    resources independently in the request path (monitors and maintenance use
    v1, healthchecks / outages / reporting use v2, incidents use v3); the base
    server is https://api.hyperping.io and the version segment is included in
    each path below.
  termsOfService: https://hyperping.com/terms
  contact:
    name: Hyperping Support
    email: hello@hyperping.io
  version: '1.0'
servers:
  - url: https://api.hyperping.io/v1
    description: Hyperping API base (monitors, maintenance, status JSON). Other
      resources use sibling version segments (../v2, ../v3) on the same host.
security:
  - bearerAuth: []
tags:
  - name: Monitors
    description: Create, retrieve, update, and delete uptime monitors.
  - name: Healthchecks
    description: Cron-style monitors that expect periodic pings from scheduled tasks.
  - name: Status Pages
    description: Public machine-readable status feed for a status page.
  - name: Incidents
    description: Status page incident lifecycle and updates.
  - name: Maintenance
    description: Scheduled maintenance windows.
  - name: Outages
    description: On-call outage acknowledgement, resolution, and escalation.
  - name: Reports
    description: Uptime, SLA, and MTTR reporting for monitors.
paths:
  /monitors:
    get:
      operationId: listMonitors
      tags:
        - Monitors
      summary: List all monitors
      responses:
        '200':
          description: A list of monitors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Monitor'
    post:
      operationId: createMonitor
      tags:
        - Monitors
      summary: Create a new monitor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorInput'
      responses:
        '201':
          description: The created monitor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
  /monitors/{monitor_uuid}:
    parameters:
      - $ref: '#/components/parameters/MonitorUuid'
    get:
      operationId: getMonitor
      tags:
        - Monitors
      summary: Retrieve a monitor
      responses:
        '200':
          description: The requested monitor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
    put:
      operationId: updateMonitor
      tags:
        - Monitors
      summary: Update a monitor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorInput'
      responses:
        '200':
          description: The updated monitor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
    delete:
      operationId: deleteMonitor
      tags:
        - Monitors
      summary: Delete a monitor
      responses:
        '204':
          description: The monitor was deleted.
  /{subdomain}/status.json:
    parameters:
      - name: subdomain
        in: path
        required: true
        description: The status page host (e.g. yourdomain.hyperping.io).
        schema:
          type: string
    get:
      operationId: getStatusPageJson
      tags:
        - Status Pages
      summary: Get the public status feed for a status page
      description: >-
        Returns the current overall status and per-service uptime for an active
        status page in a machine-readable form. Available only on active status
        pages.
      security: []
      responses:
        '200':
          description: The status page status feed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusPage'
  /healthchecks:
    servers:
      - url: https://api.hyperping.io/v2
    get:
      operationId: listHealthchecks
      tags:
        - Healthchecks
      summary: List all healthchecks
      responses:
        '200':
          description: A list of healthchecks.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Healthcheck'
    post:
      operationId: createHealthcheck
      tags:
        - Healthchecks
      summary: Create a new healthcheck
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HealthcheckInput'
      responses:
        '201':
          description: The created healthcheck.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Healthcheck'
  /healthchecks/{healthcheck_uuid}:
    servers:
      - url: https://api.hyperping.io/v2
    parameters:
      - $ref: '#/components/parameters/HealthcheckUuid'
    get:
      operationId: getHealthcheck
      tags:
        - Healthchecks
      summary: Retrieve a healthcheck
      responses:
        '200':
          description: The requested healthcheck.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Healthcheck'
    put:
      operationId: updateHealthcheck
      tags:
        - Healthchecks
      summary: Update a healthcheck
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HealthcheckInput'
      responses:
        '200':
          description: The updated healthcheck.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Healthcheck'
    delete:
      operationId: deleteHealthcheck
      tags:
        - Healthchecks
      summary: Delete a healthcheck
      responses:
        '204':
          description: The healthcheck was deleted.
  /healthchecks/{healthcheck_uuid}/pause:
    servers:
      - url: https://api.hyperping.io/v2
    parameters:
      - $ref: '#/components/parameters/HealthcheckUuid'
    post:
      operationId: pauseHealthcheck
      tags:
        - Healthchecks
      summary: Pause a healthcheck
      responses:
        '200':
          description: The paused healthcheck.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Healthcheck'
  /healthchecks/{healthcheck_uuid}/resume:
    servers:
      - url: https://api.hyperping.io/v2
    parameters:
      - $ref: '#/components/parameters/HealthcheckUuid'
    post:
      operationId: resumeHealthcheck
      tags:
        - Healthchecks
      summary: Resume a healthcheck
      responses:
        '200':
          description: The resumed healthcheck.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Healthcheck'
  /incidents:
    servers:
      - url: https://api.hyperping.io/v3
    get:
      operationId: listIncidents
      tags:
        - Incidents
      summary: Get all incidents
      responses:
        '200':
          description: A list of incidents.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Incident'
    post:
      operationId: createIncident
      tags:
        - Incidents
      summary: Create an incident
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncidentInput'
      responses:
        '201':
          description: The created incident.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Incident'
  /incidents/{incident_uuid}:
    servers:
      - url: https://api.hyperping.io/v3
    parameters:
      - $ref: '#/components/parameters/IncidentUuid'
    get:
      operationId: getIncident
      tags:
        - Incidents
      summary: Get an incident
      responses:
        '200':
          description: The requested incident.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Incident'
    put:
      operationId: updateIncident
      tags:
        - Incidents
      summary: Update an incident
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncidentInput'
      responses:
        '200':
          description: The updated incident.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Incident'
    delete:
      operationId: deleteIncident
      tags:
        - Incidents
      summary: Delete an incident
      responses:
        '204':
          description: The incident was deleted.
  /incidents/{incident_uuid}/updates:
    servers:
      - url: https://api.hyperping.io/v3
    parameters:
      - $ref: '#/components/parameters/IncidentUuid'
    post:
      operationId: addIncidentUpdate
      tags:
        - Incidents
      summary: Add an update to an incident
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncidentUpdate'
      responses:
        '201':
          description: The created incident update.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentUpdate'
  /maintenance-windows:
    get:
      operationId: listMaintenanceWindows
      tags:
        - Maintenance
      summary: List all maintenance windows
      responses:
        '200':
          description: A list of maintenance windows.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MaintenanceWindow'
    post:
      operationId: createMaintenanceWindow
      tags:
        - Maintenance
      summary: Create a maintenance window
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MaintenanceWindowInput'
      responses:
        '201':
          description: The created maintenance window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaintenanceWindow'
  /maintenance-windows/{maintenance_uuid}:
    parameters:
      - $ref: '#/components/parameters/MaintenanceUuid'
    get:
      operationId: getMaintenanceWindow
      tags:
        - Maintenance
      summary: Retrieve a maintenance window
      responses:
        '200':
          description: The requested maintenance window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaintenanceWindow'
    put:
      operationId: updateMaintenanceWindow
      tags:
        - Maintenance
      summary: Update a maintenance window
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MaintenanceWindowInput'
      responses:
        '200':
          description: The updated maintenance window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaintenanceWindow'
    delete:
      operationId: deleteMaintenanceWindow
      tags:
        - Maintenance
      summary: Delete a maintenance window
      responses:
        '204':
          description: The maintenance window was deleted.
  /maintenance-windows/{maintenance_uuid}/complete:
    parameters:
      - $ref: '#/components/parameters/MaintenanceUuid'
    post:
      operationId: completeMaintenanceWindow
      tags:
        - Maintenance
      summary: Mark a maintenance window as completed
      responses:
        '200':
          description: The completed maintenance window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaintenanceWindow'
  /outages:
    servers:
      - url: https://api.hyperping.io/v2
    get:
      operationId: listOutages
      tags:
        - Outages
      summary: List all outages
      responses:
        '200':
          description: A list of outages.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Outage'
    post:
      operationId: createOutage
      tags:
        - Outages
      summary: Create a manual outage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutageInput'
      responses:
        '201':
          description: The created outage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Outage'
  /outages/{outage_uuid}:
    servers:
      - url: https://api.hyperping.io/v2
    parameters:
      - $ref: '#/components/parameters/OutageUuid'
    get:
      operationId: getOutage
      tags:
        - Outages
      summary: Retrieve an outage
      responses:
        '200':
          description: The requested outage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Outage'
    delete:
      operationId: deleteOutage
      tags:
        - Outages
      summary: Delete a manual outage
      responses:
        '204':
          description: The outage was deleted.
  /outages/{outage_uuid}/acknowledge:
    servers:
      - url: https://api.hyperping.io/v2
    parameters:
      - $ref: '#/components/parameters/OutageUuid'
    post:
      operationId: acknowledgeOutage
      tags:
        - Outages
      summary: Acknowledge an outage
      responses:
        '200':
          description: The acknowledged outage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Outage'
  /outages/{outage_uuid}/unacknowledge:
    servers:
      - url: https://api.hyperping.io/v2
    parameters:
      - $ref: '#/components/parameters/OutageUuid'
    post:
      operationId: unacknowledgeOutage
      tags:
        - Outages
      summary: Remove acknowledgement from an outage
      responses:
        '200':
          description: The unacknowledged outage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Outage'
  /outages/{outage_uuid}/resolve:
    servers:
      - url: https://api.hyperping.io/v2
    parameters:
      - $ref: '#/components/parameters/OutageUuid'
    post:
      operationId: resolveOutage
      tags:
        - Outages
      summary: Resolve an outage
      responses:
        '200':
          description: The resolved outage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Outage'
  /outages/{outage_uuid}/escalate:
    servers:
      - url: https://api.hyperping.io/v2
    parameters:
      - $ref: '#/components/parameters/OutageUuid'
    post:
      operationId: escalateOutage
      tags:
        - Outages
      summary: Escalate an outage to team members
      responses:
        '200':
          description: The escalated outage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Outage'
  /reporting/monitor-reports:
    servers:
      - url: https://api.hyperping.io/v2
    get:
      operationId: listMonitorReports
      tags:
        - Reports
      summary: Get reports for all monitors
      responses:
        '200':
          description: Monitor reports including SLA, MTTR, and outages.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MonitorReport'
  /reporting/monitor-reports/{monitor_uuid}:
    servers:
      - url: https://api.hyperping.io/v2
    parameters:
      - $ref: '#/components/parameters/MonitorUuid'
    get:
      operationId: getMonitorReport
      tags:
        - Reports
      summary: Get a report for a specific monitor
      responses:
        '200':
          description: The monitor report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorReport'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Project API key issued from the Developers tab in project settings,
        sent as `Authorization: Bearer $USER_API_KEY`. Keys can be Read & Write
        or Read-only. A missing or invalid key returns 401; insufficient
        permissions return 403.
  parameters:
    MonitorUuid:
      name: monitor_uuid
      in: path
      required: true
      description: The unique identifier of the monitor.
      schema:
        type: string
    HealthcheckUuid:
      name: healthcheck_uuid
      in: path
      required: true
      description: The unique identifier of the healthcheck.
      schema:
        type: string
    IncidentUuid:
      name: incident_uuid
      in: path
      required: true
      description: The unique identifier of the incident.
      schema:
        type: string
    MaintenanceUuid:
      name: maintenance_uuid
      in: path
      required: true
      description: The unique identifier of the maintenance window.
      schema:
        type: string
    OutageUuid:
      name: outage_uuid
      in: path
      required: true
      description: The unique identifier of the outage.
      schema:
        type: string
  schemas:
    Monitor:
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier of the monitor.
        name:
          type: string
        url:
          type: string
          description: The target URL or host being monitored.
        type:
          type: string
          description: Monitor type.
          enum:
            - http
            - ping
            - port
            - keyword
            - dns
            - browser
        protocol:
          type: string
        port:
          type: integer
        interval:
          type: integer
          description: Check interval in seconds.
        regions:
          type: array
          description: Monitoring regions the check runs from.
          items:
            type: string
        paused:
          type: boolean
        status:
          type: string
          description: Current monitor status.
          enum:
            - up
            - down
            - paused
        created_at:
          type: string
          format: date-time
    MonitorInput:
      type: object
      required:
        - url
        - type
      properties:
        name:
          type: string
        url:
          type: string
        type:
          type: string
          enum:
            - http
            - ping
            - port
            - keyword
            - dns
            - browser
        protocol:
          type: string
        port:
          type: integer
        interval:
          type: integer
          description: Check interval in seconds.
        regions:
          type: array
          items:
            type: string
        keyword:
          type: string
          description: Keyword to match in the response body (keyword monitors).
    Healthcheck:
      type: object
      properties:
        uuid:
          type: string
        name:
          type: string
        period:
          type: integer
          description: Expected ping period in seconds.
        grace:
          type: integer
          description: Grace period in seconds before alerting.
        status:
          type: string
          enum:
            - up
            - down
            - paused
        last_ping_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    HealthcheckInput:
      type: object
      required:
        - name
        - period
      properties:
        name:
          type: string
        period:
          type: integer
          description: Expected ping period in seconds.
        grace:
          type: integer
          description: Grace period in seconds before alerting.
    StatusPage:
      type: object
      properties:
        name:
          type: string
        url:
          type: string
        status:
          type: string
          description: Overall status indicator for the page.
        services:
          type: array
          items:
            $ref: '#/components/schemas/StatusPageService'
    StatusPageService:
      type: object
      properties:
        name:
          type: string
        status:
          type: string
        operational:
          type: boolean
        uptime:
          type: number
          format: float
          description: Uptime percentage.
    Incident:
      type: object
      properties:
        uuid:
          type: string
        title:
          type: string
        status:
          type: string
          enum:
            - investigating
            - identified
            - update
            - monitoring
            - resolved
        impact:
          type: string
        monitors:
          type: array
          items:
            type: string
        updates:
          type: array
          items:
            $ref: '#/components/schemas/IncidentUpdate'
        created_at:
          type: string
          format: date-time
        resolved_at:
          type: string
          format: date-time
    IncidentInput:
      type: object
      required:
        - title
        - status
      properties:
        title:
          type: string
        status:
          type: string
          enum:
            - investigating
            - identified
            - update
            - monitoring
            - resolved
        impact:
          type: string
        message:
          type: string
        monitors:
          type: array
          items:
            type: string
    IncidentUpdate:
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: string
          enum:
            - investigating
            - identified
            - update
            - monitoring
            - resolved
        message:
          type: string
        created_at:
          type: string
          format: date-time
    MaintenanceWindow:
      type: object
      properties:
        uuid:
          type: string
        title:
          type: string
        status:
          type: string
          enum:
            - scheduled
            - in_progress
            - completed
        starts_at:
          type: string
          format: date-time
        ends_at:
          type: string
          format: date-time
        monitors:
          type: array
          items:
            type: string
        notify_subscribers:
          type: boolean
    MaintenanceWindowInput:
      type: object
      required:
        - title
        - starts_at
        - ends_at
      properties:
        title:
          type: string
        starts_at:
          type: string
          format: date-time
        ends_at:
          type: string
          format: date-time
        monitors:
          type: array
          items:
            type: string
        notify_subscribers:
          type: boolean
    Outage:
      type: object
      properties:
        uuid:
          type: string
        monitor_uuid:
          type: string
        type:
          type: string
          description: Outage origin.
          enum:
            - monitor
            - manual
        acknowledged:
          type: boolean
        resolved:
          type: boolean
        started_at:
          type: string
          format: date-time
        resolved_at:
          type: string
          format: date-time
    OutageInput:
      type: object
      properties:
        monitor_uuid:
          type: string
        title:
          type: string
        message:
          type: string
    MonitorReport:
      type: object
      properties:
        monitor_uuid:
          type: string
        sla:
          type: number
          format: float
          description: SLA / uptime percentage over the report period.
        mttr:
          type: integer
          description: Mean time to recovery in seconds.
        outages:
          type: integer
          description: Number of outages in the report period.
        response_time_avg:
          type: number
          format: float
          description: Average response time in milliseconds.