ilert Heartbeat Monitors API

openapi: 3.2.0
info:
  title: ilert REST Heartbeat Monitors API
  description: '# Introduction

    The ilert API is a RESTful API and provides programmatic access to entities in ilert and lets you easily integrate ilert with 3rd party tools.'
  version: v2.2026.5-r.3
  x-logo:
    url: ./ilert-logo-spaced.png
    backgroundColor: '#fafafa'
    altText: ilert documentation logo
servers:
- url: /api
security:
- apiKey: []
tags:
- name: Heartbeat Monitors
paths:
  /heartbeat-monitors:
    get:
      tags:
      - Heartbeat Monitors
      summary: List heartbeat monitors
      description: This resource uses a 'cursor' to paginate. 'start-index' has no effect here.
      parameters:
      - name: cursor
        in: query
        description: A cursor identifying the current position in the pagination, leave empty to start at the first item, each call returns a 'next-cursor' header for the next page, do not alter the cursor yourself.
        schema:
          type: string
          default: null
      - name: max-results
        in: query
        description: The maximum number of results when paging through a list of heartbeat monitors.
        schema:
          maximum: 200
          type: integer
          format: int32
          default: 100
      - name: include
        in: query
        description: Describes optional properties that should be included in the response. You may declare multiple. (integrationKey, integrationUrl)
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - integrationKey
            - integrationUrl
      responses:
        '200':
          description: The heartbeat monitor objects
          headers:
            next-cursor:
              schema:
                description: The cursor value for the next page, do not alter this yourself. Provide it as is to the ?cursor=${cursor} query param.
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HeartbeatMonitorNoIncludes'
      operationId: getHeartbeatMonitors
      x-operation-id-source: derived
    post:
      tags:
      - Heartbeat Monitors
      summary: Create a new heartbeat monitor
      description: 'The ''integrationKey'' field cannot be set as it is generated automatically. Note: if you are building installation scripts for your hosts, you may send deterministic names and ?include=integrationUrl to still return the ''response.body.integrationUrl'' field on 409 (already existing resource) conflict responses. This allows you to run installations with a simple single POST request.'
      parameters:
      - name: include
        in: query
        description: Describes optional properties that should be included in the response. You may declare multiple. (alertSource (default), integrationKey (default), integrationUrl)
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - integrationKey
            - integrationUrl
            - alertSource
      requestBody:
        description: the heartbeat monitor
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeartbeatMonitorRel'
        required: true
      responses:
        '201':
          description: Your newly created heartbeat monitor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatMonitor'
        '409':
          description: A heartbeat monitor with this name already exists, this resource will return the details of the already existing heartbeat monitor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatMonitor'
      operationId: postHeartbeatMonitors
      x-operation-id-source: derived
  /heartbeat-monitors/{id}:
    get:
      tags:
      - Heartbeat Monitors
      summary: Get the heartbeat monitor with specified id
      parameters:
      - name: id
        in: path
        description: numeric entity id
        required: true
        schema:
          type: string
      - name: include
        in: query
        description: Describes optional properties that should be included in the response. You may declare multiple. (integrationKey (default), integrationUrl, alertSource (default)); alertSource does not work in lists; may be used for POST and PUT as well.
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - integrationKey
            - integrationUrl
            - alertSource
      responses:
        '200':
          description: the heartbeat monitor object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatMonitor'
      operationId: getHeartbeatMonitorsById
      x-operation-id-source: derived
    put:
      tags:
      - Heartbeat Monitors
      summary: Update an existing heartbeat monitor
      description: 'ATTENTION: changing ''intervalSec'' will regenerate the ''integrationKey'', you will have to update your monitoring integrations.'
      parameters:
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      requestBody:
        description: the heartbeat monitor
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeartbeatMonitorRel'
        required: true
      responses:
        '200':
          description: the updated heartbeat monitor object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatMonitor'
      operationId: putHeartbeatMonitorsById
      x-operation-id-source: derived
    delete:
      tags:
      - Heartbeat Monitors
      summary: Delete the specified heartbeat monitor
      parameters:
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      responses:
        '204':
          description: if deletion was successful
          content: {}
      operationId: deleteHeartbeatMonitorsById
      x-operation-id-source: derived
components:
  schemas:
    AlertSourceSeverityTemplate:
      required:
      - mappings
      - valueTemplate
      type: object
      properties:
        valueTemplate:
          $ref: '#/components/schemas/AlertSourceTemplate'
        mappings:
          type: array
          items:
            $ref: '#/components/schemas/AlertSourceSeverityTemplateMapping'
    AlertSourceTemplateElement:
      type: object
      properties:
        type:
          type: string
          enum:
          - TEXT
          - VAR
          - RAW
        val:
          type: string
        func:
          type: string
        args:
          type: array
          items:
            $ref: '#/components/schemas/AlertSourceTemplateElementArg'
    IncidentNoIncludes:
      type: object
      properties:
        id:
          type: number
        summary:
          type: string
        status:
          $ref: '#/components/schemas/IncidentStatus'
        message:
          type: string
        sendNotification:
          type: boolean
        createdAt:
          type: string
          description: May be overwritten during the creation of the incident, otherwise read-only
          format: date-time
        updatedAt:
          type: string
          description: May be overwritten during the creation of the incident, otherwise read-only
          format: date-time
        affectedServices:
          type: array
          items:
            type: object
            properties:
              impact:
                $ref: '#/components/schemas/ServiceStatus'
              service:
                $ref: '#/components/schemas/ServiceNoIncludes'
        resolvedOn:
          type: string
          format: date-time
          readOnly: true
    AlertSourceSeverityTemplateMapping:
      required:
      - severity
      - value
      type: object
      properties:
        value:
          type: string
        severity:
          type: integer
          format: int32
    AlertSourceRel:
      required:
      - escalationPolicy
      - integrationType
      - name
      type: object
      properties:
        id:
          type: integer
          format: int64
        teams:
          type: array
          items:
            $ref: '#/components/schemas/TeamRel'
        name:
          type: string
        iconUrl:
          type: string
        lightIconUrl:
          type: string
        darkIconUrl:
          type: string
        escalationPolicy:
          $ref: '#/components/schemas/EscalationPolicy'
        integrationType:
          $ref: '#/components/schemas/IntegrationType'
        integrationKey:
          type: string
        integrationUrl:
          type: string
          readOnly: true
        autoResolutionTimeout:
          type: string
          format: ISO-8601
        alertGroupingWindow:
          type: string
          format: ISO-8601
        alertCreation:
          type: string
          default: ONE_ALERT_PER_EMAIL
          enum:
          - ONE_ALERT_PER_EMAIL
          - ONE_ALERT_PER_EMAIL_SUBJECT
          - ONE_PENDING_ALERT_ALLOWED
          - ONE_OPEN_ALERT_ALLOWED
          - OPEN_RESOLVE_ON_EXTRACTION
          - ONE_ALERT_GROUPED_PER_WINDOW
          - INTELLIGENT_GROUPING
        status:
          type: string
          readOnly: true
          enum:
          - PENDING
          - ALL_ACCEPTED
          - ALL_RESOLVED
          - IN_MAINTENANCE
          - DISABLED
        active:
          type: boolean
          default: true
        alertPriorityRule:
          $ref: '#/components/schemas/AlertPriorityRule'
        supportHours:
          $ref: '#/components/schemas/SimpleIdField64'
        bidirectional:
          type: boolean
          readOnly: true
        summaryTemplate:
          $ref: '#/components/schemas/AlertSourceTemplate'
        detailsTemplate:
          $ref: '#/components/schemas/AlertSourceTemplate'
        routingTemplate:
          $ref: '#/components/schemas/AlertSourceTemplate'
        linkTemplates:
          type: array
          items:
            $ref: '#/components/schemas/AlertSourceLinkTemplate'
        priorityTemplate:
          $ref: '#/components/schemas/AlertSourcePriorityTemplate'
        severityTemplate:
          $ref: '#/components/schemas/AlertSourceSeverityTemplate'
        eventFilter:
          type: string
          description: 'Defines an optional event filter condition in ICL language. This is a code based implementation, more info on syntax: https://docs.ilert.com/rest-api/icl-ilert-condition-language. For block based configuration please use the web UI. It has no effect on manually created alerts. Note: this field is an ?include, it will not appear in lists.'
        alertKeyTemplate:
          $ref: '#/components/schemas/AlertSourceTemplate'
        servicesTemplate:
          type: array
          description: 'Optional list of templates that extract service identifiers from the inbound event payload. Each rendered value is comma-split, and each resulting token is resolved against the tenant''s services by alias or name (case-insensitive). Unmatched tokens are silently dropped. Capped at 10 templates and at the alert''s per-event services limit. Note: this field is an ?include, it will not appear in lists.'
          items:
            $ref: '#/components/schemas/AlertSourceTemplate'
        eventTypeFilterCreate:
          type: string
          description: 'Defines an optional create alert rule in ICL language. This is a code based implementation, more info on syntax: https://docs.ilert.com/rest-api/icl-ilert-condition-language. For block based configuration please use the web UI. It has no effect on manually created alerts. Note: this field is an ?include, it will not appear in lists.'
        eventTypeFilterAccept:
          type: string
          description: 'Defines an optional accept alert rule in ICL language This is a code based implementation, more info on syntax: https://docs.ilert.com/rest-api/icl-ilert-condition-language. For block based configuration please use the web UI. It has no effect on manually created alerts. Note: this field is an ?include, it will not appear in lists.'
        eventTypeFilterResolve:
          type: string
          description: 'Defines an optional resolve alert rule in ICL language This is a code based implementation, more info on syntax: https://docs.ilert.com/rest-api/icl-ilert-condition-language. For block based configuration please use the web UI. It has no effect on manually created alerts. Note: this field is an ?include, it will not appear in lists.'
        autoRaiseAlerts:
          type: boolean
          description: Only effective when a support hour is linked to this alert source.
        scoreThreshold:
          type: number
          format: double
          description: Only used when alertCreation is set to INTELLIGENT_GROUPING.
        severity:
          type: integer
        services:
          type: array
          items:
            $ref: '#/components/schemas/Service'
        setupStatus:
          type: string
          enum:
          - CREATED
          - CREATED_ADVANCED
          - CREATED_BIDIRECTIONAL
          - FINISHED
        autoCreateServices:
          type: boolean
          default: false
        createdAt:
          type: string
          readOnly: true
        updatedAt:
          type: string
          readOnly: true
    ScheduleRel:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        type:
          type: string
          enum:
          - STATIC
          - RECURRING
    SimpleIdField64:
      required:
      - id
      type: object
      properties:
        id:
          type: integer
          format: int64
      description: For POST and PUT requests only the id field is required for sub entities, e.g. status page -> service, alert source -> support hour
    AlertSourcePriorityTemplate:
      required:
      - mappings
      - valueTemplate
      type: object
      properties:
        valueTemplate:
          $ref: '#/components/schemas/AlertSourceTemplate'
        mappings:
          type: array
          items:
            $ref: '#/components/schemas/AlertSourcePriorityTemplateMapping'
    ServiceNoIncludes:
      type: object
      properties:
        id:
          type: number
        name:
          type: string
        alias:
          type: string
        status:
          $ref: '#/components/schemas/ServiceStatus'
        description:
          type: string
        oneOpenIncidentOnly:
          type: boolean
        showUptimeHistory:
          type: boolean
        teams:
          type: array
          items:
            $ref: '#/components/schemas/TeamRel'
    AlertSourceTemplate:
      type: object
      properties:
        textTemplate:
          type: string
          description: "For more information on alert source templating, please visit: https://docs.ilert.com/alerting/alert-sources#alert-template.\n\n Example: <br />`Hi {{ users[0].name }} there!` \n\nYou can use the text template instead of elements by adding the include `textTemplate` to your request. Any version can be used for POST or PUT requests."
        elements:
          type: array
          items:
            $ref: '#/components/schemas/AlertSourceTemplateElement'
    EscalationRule:
      required:
      - escalationTimeout
      type: object
      properties:
        escalationTimeout:
          type: integer
        user:
          type: object
          properties:
            id:
              type: number
          description: 'This field (type: User) is deprecated, please use ''users'' instead'
        schedule:
          type: object
          properties:
            id:
              type: number
          description: 'This field (type: Schedule) is deprecated, please use ''schedules'' instead'
        team:
          type: object
          properties:
            id:
              type: number
          description: 'This field (type: Team) is deprecated, please use ''teams'' instead'
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserRel'
        schedules:
          type: array
          items:
            $ref: '#/components/schemas/ScheduleRel'
        teams:
          type: array
          items:
            $ref: '#/components/schemas/TeamRel'
    Service:
      type: object
      properties:
        id:
          type: number
        name:
          type: string
        alias:
          type: string
        status:
          $ref: '#/components/schemas/ServiceStatus'
        description:
          type: string
        oneOpenIncidentOnly:
          type: boolean
        showUptimeHistory:
          type: boolean
        teams:
          type: array
          items:
            $ref: '#/components/schemas/TeamRel'
        subscribed:
          type: boolean
          readOnly: true
        uptime:
          $ref: '#/components/schemas/ServiceUptime'
        incidents:
          type: array
          description: Note that this only contains the latest 10 unresolved incidents, use /api/incidents?service=x if more or specific results are needed
          readOnly: true
          items:
            $ref: '#/components/schemas/IncidentNoIncludes'
    AlertSourceTemplateElementArg:
      type: object
      properties:
        S:
          type: string
        N:
          type: integer
    IntegrationType:
      type: string
      enum:
      - NAGIOS
      - ICINGA
      - EMAIL2
      - SMS
      - API
      - HEARTBEAT2
      - PRTG
      - PINGDOM
      - CLOUDWATCH
      - AWSPHD
      - STACKDRIVER
      - INSTANA
      - ZABBIX
      - SOLARWINDS
      - PROMETHEUS
      - NEWRELIC
      - GRAFANA
      - GITHUB
      - DATADOG
      - UPTIMEROBOT
      - APPDYNAMICS
      - DYNATRACE
      - TOPDESK
      - STATUSCAKE
      - MONITOR
      - TOOL
      - CHECKMK
      - AUTOTASK
      - AWSBUDGET
      - SYSDIG
      - SERVERDENSITY
      - ZAPIER
      - KENTIXAM
      - JIRA
      - CONSUL
      - ZAMMAD
      - SPLUNK
      - SERVICENOW
      - SEARCHGUARD
      - KUBERNETES
      - SIGNALFX
      - AZUREALERTS
      - TERRAFORMCLOUD
      - SENTRY
      - SEMATEXT
      - SUMOLOGIC
      - RAYGUN
      - MXTOOLBOX
      - ESWATCHER
      - AMAZONSNS
      - KAPACITOR
      - CORTEXXSOAR
      - ZENDESK
      - AUVIK
      - SENSU
      - NCENTRAL
      - JUMPCLOUD
      - SALESFORCE
      - GUARDDUTY
      - STATUSHUB
      - IXON
      - APIFORTRESS
      - FRESHSERVICE
      - APPSIGNAL
      - LIGHTSTEP
      - IBMCLOUDFUNCTIONS
      - CROWDSTRIKE
      - HUMIO
      - OHDEAR
      - MONGODBATLAS
      - GITLAB
      - HYPERPING
      - PAPRISMACLOUD
      - SAMSARA
      - PANDORAFMS
      - MSSCOM
      - TWILIO
      - CISCOMERAKI
      - CHECKLY
      - POSTHOG
      - GOOGLESCC
      - SLACK
      - MSTEAMS
      - UPTIMEKUMA
      - TWILIOERRORS
      - PARTICLE
      - CLOUDFLARE
      - TULIP
      - GRAYLOG
      - CATCHPOINT
      - LOKI
      - CORTEX
      - MIMIR
      - HALOPSA
      - INFLUXDB
      - CALLFLOW
      - HALOITSM
      - KIBANA
      - VICTORIAMETRICS
      - HONEYCOMB
      - FOURME
      - KEEP
      - UBIDOTS
      - HETRIXTOOLS
      - POSTMAN
      - CLUSTERCONTROL
      - NETDATA
      - AWX
      - KAFKA
      - MQTT
      - RAPIDSPIKE
      - HONEYBADGER
      - HEALTHCHECKSIO
      - MEZMO
      - SERVERGUARD24
      - CISCOTHOUSANDEYES
      - SITE24X7
      - ITCONDUCTOR
      - SAPFRUN
      - APICA
      - DASH0
      - ROLLBAR
      - GATUS
      - LIBRENMS
      - PANTHER
      - TEAMCITY
      - ALIBABACLOUD
      - FLEETDM
      - CONNECTWISEPSA
      - DEADMANSSNITCH
      - FORTISOAR
      - OPMANAGER
      - CRONITOR
      - DOMOTZ
      - LIVEWATCH
      - AZUREDEVOPS
      - LEVELIO
      - EKARA
      - SYSAID
      - PHAREIO
      - OPSGENIE
      - WHATAP
      - SIGNOZ
      - GOOGLECHAT
      - DOTCOMMONITOR
      - UPTIME
      - HELPSCOUT
      - SCIENCELOGIC
      - PULSETIC
      - WAZUH
      - SEKOIA
    ServiceUptime:
      type: object
      properties:
        rangeStart:
          type: string
          format: date-time
        rangeEnd:
          type: string
          format: date-time
        outages:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOutage'
        uptimePercentage:
          $ref: '#/components/schemas/ServiceUptimePercentage'
    AlertSourceLinkTemplate:
      required:
      - hrefTemplate
      - text
      type: object
      properties:
        text:
          type: string
        hrefTemplate:
          $ref: '#/components/schemas/AlertSourceTemplate'
    AlertSourcePriorityTemplateMapping:
      required:
      - priority
      - value
      type: object
      properties:
        value:
          type: string
        priority:
          type: string
          enum:
          - LOW
          - HIGH
    HeartbeatMonitor:
      type: object
      required:
      - name
      - intervalSec
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        state:
          type: string
          default: UNKNOWN
          enum:
          - UNKNOWN
          - HEALTHY
          - OVERDUE
        intervalSec:
          type: integer
          format: int32
          minimum: 25
          maximum: 2678400
        alertSummary:
          type: string
        createdAt:
          type: string
          format: ISO-8601
        updatedAt:
          type: string
          format: ISO-8601
        alertSource:
          $ref: '#/components/schemas/AlertSourceRel'
        teams:
          type: array
          items:
            $ref: '#/components/schemas/TeamRel'
        integrationKey:
          type: string
        integrationUrl:
          type: string
    HeartbeatMonitorNoIncludes:
      type: object
      required:
      - name
      - intervalSec
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        state:
          type: string
          default: UNKNOWN
          enum:
          - UNKNOWN
          - HEALTHY
          - OVERDUE
        intervalSec:
          type: integer
          format: int32
          minimum: 25
          maximum: 2678400
        alertSummary:
          type: string
        createdAt:
          type: string
          format: ISO-8601
        updatedAt:
          type: string
          format: ISO-8601
        teams:
          type: array
          items:
            $ref: '#/components/schemas/TeamRel'
    ServiceStatus:
      type: string
      description: the service status
      enum:
      - OPERATIONAL
      - UNDER_MAINTENANCE
      - DEGRADED
      - PARTIAL_OUTAGE
      - MAJOR_OUTAGE
    AlertPriorityRule:
      type: string
      enum:
      - HIGH
      - LOW
      - HIGH_DURING_SUPPORT_HOURS
      - LOW_DURING_SUPPORT_HOURS
    UserRel:
      required:
      - id
      type: object
      properties:
        id:
          type: integer
          format: int64
        firstName:
          type: string
        lastName:
          type: string
    ServiceOutage:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ServiceStatus'
        from:
          type: string
          format: date-time
        until:
          type: string
          format: date-time
    HeartbeatMonitorRel:
      type: object
      required:
      - name
      - intervalSec
      properties:
        name:
          type: string
        intervalSec:
          type: integer
          format: int32
          minimum: 25
          maximum: 2678400
          description: We recommend using an interval between 3 and 5 minutes, while pinging every 60 seconds. Of course if you are tracking use-cases like backup jobs that run once a week, a larger timeout and less pings suffice.
        alertSummary:
          type: string
        alertSource:
          $ref: '#/components/schemas/SimpleIdField64'
    ServiceUptimePercentage:
      type: object
      properties:
        uptimePercentage:
          type: object
          properties:
            p90:
              maximum: 100
              minimum: 0
              type: number
              format: float
              readOnly: true
            p60:
              maximum: 100
              minimum: 0
              type: number
              format: float
              readOnly: true
            p30:
              maximum: 100
              minimum: 0
              type: number
              format: float
              readOnly: true
    TeamRel:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    IncidentStatus:
      type: string
      description: the incident status
      enum:
      - INVESTIGATING
      - IDENTIFIED
      - MONITORING
      - RESOLVED
    EscalationPolicy:
      required:
      - escalationRules
      - name
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        escalationRules:
          type: array
          items:
            $ref: '#/components/schemas/EscalationRule'
        teams:
          type: array
          items:
            $ref: '#/components/schemas/TeamRel'
        repeating:
          type: boolean
          default: false
        frequency:
          maximum: 9
          minimum: 1
          type: integer
          format: int32
          default: 1
        delayMin:
          maximum: 15
          minimum: 0
          type: integer
          format: int32
          default: 0
        routingKey:
          type: string
          description: optional
  securitySchemes:
    apiKey:
      type: apiKey
      description: The Bearer API key of your user <a href='/api-docs/#section/Authentication'>more info</a>.
      name: Authorization
      in: header
x-original-swagger-version: '2.0'