Checkly Heartbeats API

openapi: 3.2.0
info:
  title: Checkly Public Heartbeats API
  version: v1
  description: These are the docs for the newly released Checkly Public API.<br />If you have any questions, please do not hesitate to get in touch with us.
servers:
- url: https://api.checklyhq.com
security:
- Bearer: []
tags:
- name: Heartbeats
paths:
  /v1/checks/heartbeat:
    post:
      summary: Create a heartbeat check
      operationId: postV1ChecksHeartbeat
      description: "Creates a new Heartbeat check. Will return a `402` when you are over the limit of your plan.\n    When using the `globalAlertSetting`, the `alertSetting` can be `null`"
      tags:
      - Heartbeats
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChecksV1HeartbeatCheckMutationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsError'
      parameters:
      - schema:
          type: boolean
          default: true
          description: Determines whether a new check will automatically be added as a subscriber to all existing alert channels when it gets created.
        required: false
        description: Determines whether a new check will automatically be added as a subscriber to all existing alert channels when it gets created.
        name: autoAssignAlerts
        in: query
      - schema:
          type: string
          x-format:
            guid: true
          description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
        required: false
        description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
        name: x-checkly-account
        in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChecksV1HeartbeatCheckCreate'
  /v1/checks/heartbeat/{id}:
    put:
      summary: Update a heartbeat check
      operationId: putV1ChecksHeartbeatId
      description: Updates a Heartbeat check.
      tags:
      - Heartbeats
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChecksV1HeartbeatCheckMutationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsError'
      parameters:
      - schema:
          type: string
          x-format:
            guid: true
        required: true
        name: id
        in: path
      - schema:
          type: boolean
          default: true
          description: Determines whether a new check will automatically be added as a subscriber to all existing alert channels when it gets created.
        required: false
        description: Determines whether a new check will automatically be added as a subscriber to all existing alert channels when it gets created.
        name: autoAssignAlerts
        in: query
      - schema:
          type: string
          x-format:
            guid: true
          description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
        required: false
        description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
        name: x-checkly-account
        in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChecksV1HeartbeatCheckUpdate'
  /v1/checks/heartbeats/{checkId}/availability:
    get:
      summary: Get heartbeat availability
      operationId: getV1ChecksHeartbeatsCheckidAvailability
      description: Get heartbeat availability.
      tags:
      - Heartbeats
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatsV1AvailabilityResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsError'
      parameters:
      - schema:
          type: string
          x-format:
            guid: true
        required: true
        name: checkId
        in: path
      - schema:
          type: string
          format: date
        required: false
        name: startTime
        in: query
      - schema:
          type: string
          format: date
        required: false
        name: endTime
        in: query
      - schema:
          type: string
          x-format:
            guid: true
          description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
        required: false
        description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
        name: x-checkly-account
        in: header
  /v1/checks/heartbeats/{checkId}/events:
    get:
      summary: Get a list of events for a heartbeat
      operationId: getV1ChecksHeartbeatsCheckidEvents
      description: Get all events from a heartbeat.
      tags:
      - Heartbeats
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatsV1EventsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsError'
      parameters:
      - schema:
          type: string
          x-format:
            guid: true
        required: true
        name: checkId
        in: path
      - schema:
          type: string
          format: date
        required: false
        name: startTime
        in: query
      - schema:
          type: string
          format: date
        required: false
        name: endTime
        in: query
      - schema:
          type: number
          maximum: 10
          default: 10
        required: false
        name: limit
        in: query
      - schema:
          type: string
          x-format:
            guid: true
          description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
        required: false
        description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
        name: x-checkly-account
        in: header
  /v1/checks/heartbeats/{checkId}/events/{id}:
    get:
      summary: Get a specific Heartbeat event
      operationId: getV1ChecksHeartbeatsCheckidEventsId
      description: Get a specific event by its id.
      tags:
      - Heartbeats
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatsV1EventResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsError'
      parameters:
      - schema:
          type: string
          x-format:
            guid: true
        required: true
        name: checkId
        in: path
      - schema:
          type: string
          x-format:
            guid: true
        required: true
        name: id
        in: path
      - schema:
          type: string
          x-format:
            guid: true
          description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
        required: false
        description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
        name: x-checkly-account
        in: header
components:
  schemas:
    attributes:
      type: object
    ChecksV1HeartbeatRequest:
      type: object
      properties:
        period:
          type: number
          description: Interval expected between pings.
        periodUnit:
          type: string
          enum:
          - seconds
          - minutes
          - hours
          - days
        grace:
          type: number
          description: Grace added to the period.
        graceUnit:
          type: string
          enum:
          - seconds
          - minutes
          - hours
          - days
        pingToken:
          type:
          - string
          - 'null'
          x-format:
            guid: true
          description: UUID token used to build a unique ping URL.
      required:
      - period
      - periodUnit
      - grace
      - graceUnit
    ChecksV1HeartbeatResponseAlertChannels:
      type:
      - object
      - 'null'
      properties:
        email:
          type: array
          items:
            $ref: '#/components/schemas/ChecksV1HeartbeatResponseAlertEmail'
        webhook:
          type: array
          items:
            $ref: '#/components/schemas/ChecksV1HeartbeatResponseAlertWebhook'
        slack:
          type: array
          items:
            $ref: '#/components/schemas/ChecksV1HeartbeatResponseAlertSlack'
        sms:
          type: array
          items:
            $ref: '#/components/schemas/ChecksV1HeartbeatResponseAlertSms'
    ChecksV1HeartbeatResponseAlertSlack:
      type: object
      properties:
        url:
          type: string
          default: ''
      required:
      - url
    HeartbeatsV1EventStats:
      type: object
      properties:
        last24Hours:
          $ref: '#/components/schemas/HeartbeatsV1AvailabilityResponse'
        last7Days:
          $ref: '#/components/schemas/HeartbeatsV1AvailabilityResponse'
    Model2:
      type: string
      enum:
      - Too Many Requests
    ChecksV1Heartbeat:
      type: object
      properties:
        period:
          type: number
          description: Interval expected between pings.
        periodUnit:
          type: string
          enum:
          - seconds
          - minutes
          - hours
          - days
        grace:
          type: number
          description: Grace added to the period.
        graceUnit:
          type: string
          enum:
          - seconds
          - minutes
          - hours
          - days
        pingToken:
          type:
          - string
          - 'null'
          x-format:
            guid: true
          description: UUID token used to build a unique ping URL.
        pingUrl:
          type: string
      required:
      - period
      - periodUnit
      - grace
      - graceUnit
    UnauthorizedError:
      type: object
      properties:
        statusCode:
          type: number
          enum:
          - 401
        error:
          $ref: '#/components/schemas/error'
        message:
          type: string
          example: Bad Token
        attributes:
          $ref: '#/components/schemas/attributes'
      required:
      - statusCode
      - error
    ChecksV1CheckIntent:
      type:
      - object
      - 'null'
      properties:
        goal:
          type: string
          minLength: 1
          maxLength: 2000
          description: The user or system outcome this check protects.
        requiredOutcomes:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 1000
          maxItems: 20
          default: []
          description: Observable outcomes the check must continue to prove.
        mustPreserve:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 1000
          maxItems: 20
          default: []
          description: Guardrails an AI repair must not weaken or bypass.
      required:
      - goal
      additionalProperties: false
    ChecksV1HeartbeatCheckUpdate:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: The name of the check.
          example: Check
        activated:
          type: boolean
          description: Determines if the check is running or not.
        muted:
          type: boolean
          description: Determines if any notifications will be send out when a check fails and/or recovers.
        doubleCheck:
          type: boolean
          description: '[Deprecated] Retry failed check runs. This property is deprecated, and `retryStrategy` can be used instead.'
        shouldFail:
          type: boolean
          description: Allows to invert the behaviour of when a check is considered to fail. Allows for validating error status like 404.
        locations:
          type:
          - array
          - 'null'
          items:
            type: string
            enum:
            - us-east-1
            - us-east-2
            - us-west-1
            - us-west-2
            - ca-central-1
            - sa-east-1
            - eu-west-1
            - eu-central-1
            - eu-west-2
            - eu-west-3
            - eu-north-1
            - eu-south-1
            - me-south-1
            - ap-southeast-1
            - ap-northeast-1
            - ap-east-1
            - ap-southeast-2
            - ap-southeast-3
            - ap-northeast-2
            - ap-northeast-3
            - ap-south-1
            - af-south-1
          description: An array of one or more data center locations where to run this check.
          example:
          - us-east-1
          - eu-central-1
        tags:
          type: array
          items:
            type: string
            minLength: 1
          description: Tags for organizing and filtering checks.
          example:
          - production
        alertSettings:
          type: object
          properties:
            escalationType:
              type: string
              enum:
              - RUN_BASED
              - TIME_BASED
              description: Determines what type of escalation to use.
            reminders:
              type: object
              properties:
                amount:
                  type: integer
                  enum:
                  - 0
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                  - 100000
                  description: How many reminders to send out after the initial alert notification.
                interval:
                  type: integer
                  enum:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                  - 10
                  - 15
                  - 30
                  description: At what interval the reminders should be send.
            sslCertificates:
              type: object
              properties:
                enabled:
                  type: boolean
                  description: Determines if alert notifications should be send for expiring SSL certificates.
                alertThreshold:
                  type: integer
                  description: At what moment in time to start alerting on SSL certificates.
              description: '[DEPRECATED] `sslCertificates` is deprecated and is not longer used. Please ignore it, will be removed in a future version.'
            runBasedEscalation:
              type: object
              properties:
                failedRunThreshold:
                  type: integer
                  enum:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                  description: After how many failed consecutive check runs an alert notification should be send.
            timeBasedEscalation:
              type: object
              properties:
                minutesFailingThreshold:
                  type: integer
                  enum:
                  - 5
                  - 10
                  - 15
                  - 30
                  description: After how many minutes after a check starts failing an alert should be send.
            parallelRunFailureThreshold:
              type: object
              properties:
                enabled:
                  type: boolean
                  description: Determines if parallel run threshold is enabled
                percentage:
                  type: integer
                  enum:
                  - 10
                  - 20
                  - 30
                  - 40
                  - 50
                  - 60
                  - 70
                  - 80
                  - 90
                  - 100
                  description: The percentage of parallel runs that should fail before an alert is triggered
          description: Alert settings.
        useGlobalAlertSettings:
          type: boolean
          description: When true, the account level alert setting will be used, not the alert setting defined on this check.
        groupId:
          type:
          - number
          - 'null'
          description: The id of the check group this check is part of.
          example: null
        groupOrder:
          type:
          - number
          - 'null'
          minimum: 0
          description: The position of this check in a check group. It determines in what order checks are run when a group is triggered from the API or from CI/CD.
          example: null
        runtimeId:
          type:
          - string
          - 'null'
          enum:
          - '2026.04'
          - '2025.04'
          - '2024.09'
          - '2024.02'
          - '2023.09'
          - '2023.02'
          - '2022.10'
          - null
          description: The runtime version, i.e. fixed set of runtime dependencies, used to execute this check.
        alertChannelSubscriptions:
          type: array
          items:
            type: object
            properties:
              alertChannelId:
                type: number
              activated:
                type: boolean
            required:
            - alertChannelId
            - activated
            description: Alert channel subscription.
          description: List of alert channel subscriptions.
          example: []
        triggerIncident:
          type:
          - object
          - 'null'
          properties:
            serviceId:
              type: string
              minLength: 1
              format: uuid
              description: The status page service that the incident will be associated with.
            severity:
              type: string
              enum:
              - CRITICAL
              - MAJOR
              - MEDIUM
              - MINOR
              description: The severity level of the incident.
            name:
              type: string
              description: The name of the incident.
            description:
              type: string
              description: A detailed description of the incident.
            notifySubscribers:
              type: boolean
              description: Whether to notify subscribers when the incident is triggered.
          required:
          - serviceId
          - severity
          - name
          - description
          - notifySubscribers
          description: Determines whether the check or monitor should create and resolve an incident based on its alert configuration. Useful for status page automation.
        runParallel:
          type: boolean
          description: When true, the check will run in parallel in all selected locations.
        description:
          type:
          - string
          - 'null'
          maxLength: 510
          description: A description of the check.
        intent:
          $ref: '#/components/schemas/ChecksV1CheckIntent'
        aiAutoRepairEnabled:
          type:
          - boolean
          - 'null'
        checkType:
          type: string
          enum:
          - HEARTBEAT
        frequency:
          type: integer
          enum:
          - 0
          - 1
          - 2
          - 5
          - 10
          - 15
          - 30
          - 60
          - 120
          - 180
          - 360
          - 720
          - 1440
          description: How often the check should run in minutes.
        frequencyOffset:
          type: integer
          minimum: 1
        request:
          type:
          - object
          - 'null'
          additionalProperties: true
        heartbeat:
          $ref: '#/components/schemas/ChecksV1HeartbeatRequest'
        script:
          type:
          - string
          - 'null'
        scriptPath:
          type:
          - string
          - 'null'
          minLength: 1
          description: Path of the script in the runtime.
        sslCheckDomain:
          type:
          - string
          - 'null'
        environmentVariables:
          type:
          - array
          - 'null'
          items:
            type: object
            properties:
              key:
                type: string
                minLength: 1
                description: The key of the environment variable (this value cannot be changed).
                example: API_KEY
              value:
                type:
                - string
                - 'null'
              locked:
                type: boolean
                description: Used only in the UI to hide the value like a password.
              secret:
                type: boolean
                description: Set an environment variable as secret. Once set, its value cannot be unlocked.
            required:
            - key
            - value
          maxItems: 200
          description: Key/value pairs for setting environment variables during check execution. These are only relevant for Browser checks. Use global environment variables whenever possible.
        setupSnippetId:
          type:
          - number
          - 'null'
          description: An ID reference to a snippet to use in the setup phase of an API check.
        tearDownSnippetId:
          type:
          - number
          - 'null'
          description: An ID reference to a snippet to use in the teardown phase of an API check.
        localSetupScript:
          type:
          - string
          - 'null'
          description: A valid piece of Node.js code to run in the setup phase.
        localTearDownScript:
          type:
          - string
          - 'null'
          description: A valid piece of Node.js code to run in the teardown phase.
        degradedResponseTime:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 300000
          description: The response time in milliseconds where a check should be considered degraded.
        maxResponseTime:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 300000
          description: The response time in milliseconds where a check should be considered failing.
    TooManyRequestsError:
      type: object
      properties:
        statusCode:
          type: number
          enum:
          - 429
        error:
          $ref: '#/components/schemas/Model2'
        message:
          type: string
          example: Too Many Requests
        attributes:
          $ref: '#/components/schemas/attributes'
      required:
      - statusCode
      - error
    ChecksV1HeartbeatCheckMutationResponse:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          description: The name of the check.
        activated:
          type: boolean
          default: true
          description: Determines if the check is running or not.
        muted:
          type: boolean
          default: false
          description: Determines if any notifications will be send out when a check fails and/or recovers.
        tags:
          type: array
          items:
            type: string
          description: Tags for organizing and filtering checks.
        alertSettings:
          $ref: '#/components/schemas/ChecksV1HeartbeatResponseAlertSettings'
        useGlobalAlertSettings:
          type: boolean
          default: true
          description: When true, the account level alert setting will be used, not the alert setting defined on this check.
        alertChannelSubscriptions:
          type: array
          items:
            $ref: '#/components/schemas/ChecksV1HeartbeatResponseAlertChannelSubscription'
        triggerIncident:
          $ref: '#/components/schemas/ChecksV1HeartbeatResponseTriggerIncident'
        runParallel:
          type: boolean
          default: false
          description: When true, the check will run in parallel in all selected locations.
        description:
          type:
          - string
          - 'null'
          maxLength: 500
          default: null
          description: A description of the check.
        intent:
          type:
          - object
          - 'null'
          properties:
            goal:
              type: string
              minLength: 1
              maxLength: 2000
              description: The user or system outcome this check protects.
            requiredOutcomes:
              type: array
              items:
                type: string
                minLength: 1
                maxLength: 1000
              maxItems: 20
              default: []
              description: Observable outcomes the check must continue to prove.
            mustPreserve:
              type: array
              items:
                type: string
                minLength: 1
                maxLength: 1000
              maxItems: 20
              default: []
              description: Guardrails an AI repair must not weaken or bypass.
          default: null
          required:
          - goal
          additionalProperties: false
        aiAutoRepairEnabled:
          type:
          - boolean
          - 'null'
          default: null
        checkType:
          type: string
          enum:
          - HEARTBEAT
        heartbeat:
          $ref: '#/components/schemas/ChecksV1Heartbeat'
        alertChannels:
          $ref: '#/components/schemas/ChecksV1HeartbeatResponseAlertChannels'
        created_at:
          type: string
          format: date-time
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
      required:
      - name
    HeartbeatsV1Event:
      type: object
      properties:
        id:
          type: string
          format: uuid
        state:
          type: string
          enum:
          - FAILING
          - EARLY
          - RECEIVED
          - GRACE
          - LATE
          description: Describe the event state, if the ping was received or not.
        timestamp:
          type: string
          format: date
          description: UTC timestamp on which we received the event.
        source:
          type:
          - string
          - 'null'
          description: Source which triggered the event.
        userAgent:
          type:
          - string
          - 'null'
          description: User agent from the ping.
      required:
      - id
    ChecksV1HeartbeatResponseTriggerIncident:
      type:
      - object
      - 'null'
      properties:
        serviceId:
          type: string
          minLength: 1
          format: uuid
          description: The status page service that the incident will be associated with.
        severity:
          type: string
          enum:
          - CRITICAL
          - MAJOR
          - MEDIUM
          - MINOR
          description: The severity level of the incident.
        name:
          type: string
          description: The name of the incident.
        description:
          type: string
          description: A detailed description of the incident.
        notifySubscribers:
          type: boolean
          description: Whether to notify subscribers when the incident is triggered.
      required:
      - serviceId
      - severity
      - name
      - description
      - notifySubscribers
      description: Determines whether the check or monitor should create and resolve an incident based on its alert configuration. Useful for status page automation.
    HeartbeatsV1AvailabilityResponse:
      type:
      - object
      - 'null'
      properties:
        successRatio:
          $ref: '#/components/schemas/HeartbeatsV1AvailabilitySuccessRatio'
        totalEntitiesCurrentPeriod:
          type: number
    ChecksV1HeartbeatResponseAle

# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/checkly/refs/heads/main/openapi/checkly-heartbeats-api-openapi.yml