openapi: 3.0.1
info:
  title: ilert REST Alert Actions Heartbeat Monitors API
  description: "# Introduction\nThe ilert API is a [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) API and provides programmatic access to entities in ilert and lets you easily integrate ilert with 3rd party tools. If you are looking to develop an inbound integration (e.g. for a monitoring tool), please use our [Events API](#tag/events). \n\nThe API supports the JSON content type for requests and responses. The response content type is requested via the HTTP Accept header (`application/json`). All resources are accessible via https and are located at `api.ilert.com/api`. \n\n You may download ilert's latest [OpenAPI.json {...} here](https://api.ilert.com/api-docs/openapi.json).\n\n If you are looking for a classic Swagger-UI view you may also open [this link](https://api.ilert.com/api-docs/swagger-ui). \n\n ## Authentication\nThe REST API accepts bearer API tokens. Each user may create API keys using the ilert web application. Note: Make sure to send the `Bearer ` prefix e.g. `Bearer APIKEY` when sending api key requests. By default, access to all resources (using any method) requires the client to be authenticated.\n\n ## Team Context\n When using API tokens, the currently selected team context of the user will not be taken into account, i.e. list results will always return all entities to which the user has a view permission. When using basic auth credentials the currently selected team context of the user will be used to filter resource results. The context may be overwritten for API key calls using the `team-context` HTTP header. Specifying `0` for ALL teams, `-1` for MY teams or a specific team id e.g. `team-context=901` to fetch results for a certain team.  \n\n ## Errors\nilert uses HTTP response codes to indicate success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate a client error (e.g. a missing required parameter) and codes in the 5xx range indicate an error with ilert's servers. In case of an error, the response body contains the following information:\n\n Attribute     | Description \n ------------- | ------------- \n status  | the corresponsing HTTP status code  \n message  | a human readable description of the error \n code  | error code, used to identify error type  \n\n ## API Versioning\nChanges to our API are always backwards-compatible. To get more information about our API versioning and historical changes, please <a href='https://docs.ilert.com/rest-api/api-version-history' target='_blank'>take a look here</a>."
  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'
    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'
  /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'
    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'
    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: {}
components:
  schemas:
    ServiceStatus:
      type: string
      description: the service status
      enum:
      - OPERATIONAL
      - UNDER_MAINTENANCE
      - DEGRADED
      - PARTIAL_OUTAGE
      - MAJOR_OUTAGE
    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
    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
    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'
    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
    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'
    AlertSourceSeverityTemplateMapping:
      required:
      - severity
      - value
      type: object
      properties:
        value:
          type: string
        severity:
          type: integer
          format: int32
    UserRel:
      required:
      - id
      type: object
      properties:
        id:
          type: integer
          format: int64
        firstName:
          type: string
        lastName:
          type: string
    AlertSourcePriorityTemplate:
      required:
      - mappings
      - valueTemplate
      type: object
      properties:
        valueTemplate:
          $ref: '#/components/schemas/AlertSourceTemplate'
        mappings:
          type: array
          items:
            $ref: '#/components/schemas/AlertSourcePriorityTemplateMapping'
    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
    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
    ServiceOutage:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ServiceStatus'
        from:
          type: string
          format: date-time
        until:
          type: string
          format: date-time
    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'
    ScheduleRel:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        type:
          type: string
          enum:
          - STATIC
          - RECURRING
    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'
    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'
    IncidentStatus:
      type: string
      description: the incident status
      enum:
      - INVESTIGATING
      - IDENTIFIED
      - MONITORING
      - RESOLVED
    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'
    AlertSourcePriorityTemplateMapping:
      required:
      - priority
      - value
      type: object
      properties:
        value:
          type: string
        priority:
          type: string
          enum:
          - LOW
          - HIGH
    AlertSourceTemplateElementArg:
      type: object
      properties:
        S:
          type: string
        N:
          type: integer
    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'
    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
    TeamRel:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    AlertSourceSeverityTemplate:
      required:
      - mappings
      - valueTemplate
      type: object
      properties:
        valueTemplate:
          $ref: '#/components/schemas/AlertSourceTemplate'
        mappings:
          type: array
          items:
            $ref: '#/components/schemas/AlertSourceSeverityTemplateMapping'
    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
    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'
    AlertPriorityRule:
      type: string
      enum:
      - HIGH
      - LOW
      - HIGH_DURING_SUPPORT_HOURS
      - LOW_DURING_SUPPORT_HOURS
    AlertSourceLinkTemplate:
      required:
      - hrefTemplate
      - text
      type: object
      properties:
        text:
          type: string
        hrefTemplate:
          $ref: '#/components/schemas/AlertSourceTemplate'
  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'