Healthchecks.io Checks API

openapi: 3.2.0
info:
  title: Healthchecks.io Checks API
  version: '2026-10-13'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-13: 25 operation(s) read from 3 public documentation page(s) (each operation names its page in x-source). This is not the provider''s published contract; Healthchecks.io has published no machine-readable contract that the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 13
    documentation: 12
    pages-with-code: 2
    pages-read: 3
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-13'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://healthchecks.io/docs/api
  - https://healthchecks.io/docs/http_api
  - https://healthchecks.io/docs/monitoring_cron_jobs
servers:
- url: https://hc-ping.com
security:
- apiKey: []
tags:
- name: Checks
paths:
  /api/v3/checks:
    post:
      operationId: post_api_v3_checks
      tags:
      - Checks
      summary: POST /api/v3/checks
      x-source: https://healthchecks.io/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV3ChecksRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV3ChecksResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://healthchecks.io/api/v3/checks/  --header \"X-Api-Key: your-api-key\"  --data '{\"name\": \"Backups\", \"tags\": \"prod www\", \"timeout\": 3600, \"grace\": 60}' \n Or, alternatively: "
  /api/v3/checks/:
    get:
      operationId: get_api_v3_checks
      tags:
      - Checks
      summary: List existing checks
      description: Returns a list of checks belonging to the user, optionally filtered by one or more tags.
      x-source: https://healthchecks.io/docs/api
      parameters:
      - name: slug
        in: query
        required: false
        schema:
          type: string
        description: Filters the checks and returns only the checks with the specified slug.
      - name: tag
        in: query
        required: false
        schema:
          type: string
        description: Filters the checks and returns only the checks that are tagged with the specified value. This parameter can be repeated multiple times.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV3ChecksResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: postApiV3Checks
      tags:
      - Checks
      summary: Create a new check
      description: Creates a new check and returns its ping URL.
      x-source: https://healthchecks.io/docs/api
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV3ChecksRequest2'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV3ChecksResponse2'
      x-evidence:
        kind: documentation
      x-operation-id-source: normalized
      x-operation-id-original: post_api_v3_checks
  /api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79:
    delete:
      operationId: delete_api_v3_checks_7918b17b_a745_4db1_8575_9d2e07c97f79
      tags:
      - Checks
      summary: DELETE /api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79
      x-source: https://healthchecks.io/docs/api
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteApiV3Checks7918B17BA7454Db185759D2E07C97F79Response'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://healthchecks.io/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79  --request DELETE --header \"X-Api-Key: your-api-key\" \n Example Response \n { \n \"name\" : \"Backups\" , \n \"slug\" : \"\" , \n \"tags\" : \"prod www\" , \n \"desc\" : \"\" , \n \"grace\" : 60 , \n \"n_pings\" : 0 , \n \"status\" : \"new\" , \n \"started\" : false , \n \"last_ping\" : null , \n \"next_ping\" : null , \n \"manual_resume\" : false , \n \"methods\" :"
    post:
      operationId: post_api_v3_checks_7918b17b_a745_4db1_8575_9d2e07c97f79
      tags:
      - Checks
      summary: POST /api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79
      x-source: https://healthchecks.io/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV3Checks7918B17BA7454Db185759D2E07C97F79Request'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV3Checks7918B17BA7454Db185759D2E07C97F79Response'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://healthchecks.io/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79  --header \"X-Api-Key: your-api-key\"  --data '{\"name\": \"Backups\", \"tags\": \"prod www\", \"timeout\": 3600, \"grace\": 60}' \n Or, alternatively: "
  /api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/{7918b17ba7454db185759d2e07c97f79Id}:
    post:
      operationId: post_api_v3_checks_7918b17b_a745_4db1_8575_9d2e07c97f79_7918b17ba7454db185759d2e
      tags:
      - Checks
      summary: POST /api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause
      x-source: https://healthchecks.io/docs/api
      parameters:
      - name: 7918b17ba7454db185759d2e07c97f79Id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV3Checks7918B17BA7454Db185759D2E07C97F797918B17Ba7454'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://healthchecks.io/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause  --request POST --header \"X-Api-Key: your-api-key\" --data \"\" \n Note: the --data \"\" argument forces curl to send a Content-Length request header\neven though the request body is empty. For HTTP POST requests, the Content-Length \nheader is sometimes required by some network proxies and web servers. \n Example Respons"
        collapsed_from: 2 example path(s) differing only at 7918b17ba7454db185759d2e07c97f79Id
  /api/v3/checks/{uuid}:
    delete:
      operationId: delete_api_v3_checks_uuid
      tags:
      - Checks
      summary: Delete check
      description: Permanently deletes the check from the user's account.
      x-source: https://healthchecks.io/docs/api
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteApiV3ChecksUuidResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_v3_checks_uuid
      tags:
      - Checks
      summary: Update an existing check
      description: Updates an existing check.
      x-source: https://healthchecks.io/docs/api
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV3ChecksUuidRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV3ChecksUuidResponse'
      x-evidence:
        kind: documentation
    get:
      operationId: get_api_v3_checks_uuid
      tags:
      - Checks
      summary: GET /api/v3/checks/{uuid}
      x-source: https://healthchecks.io/docs/api
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV3ChecksUuidResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl --header \"X-Api-Key: your-api-key\" https://healthchecks.io/api/v3/checks/<uuid>\n Example Response \n { \n \"name\" : \"Database Backup\" , \n \"slug\" : \"database-backup\" , \n \"tags\" : \"production db\" , \n \"desc\" : \"Runs ~/db-backup.sh\" , \n \"grace\" : 1200 , \n \"n_pings\" : 7 , \n \"status\" : \"down\" , \n \"started\" : false , \n \"last_ping\" : \"2020-03-23T10:19:32+00:00\" , \n \"next_ping\" : null , \n \"manual_resume\""
  /api/v3/checks/{uuid}/{uuidid}:
    post:
      operationId: post_api_v3_checks_uuid_uuidid
      tags:
      - Checks
      summary: Pause monitoring of a check
      description: Disables monitoring for a check without removing it.
      x-source: https://healthchecks.io/docs/api
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
      - name: uuidid
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV3ChecksUuidUuididResponse'
      x-evidence:
        kind: documentation
        collapsed_from: 2 example path(s) differing only at uuidId
  /api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips/:
    get:
      operationId: get_api_v3_checks_f618072a_7bde_4eee_af63_71a77c5723bc_flips
      tags:
      - Checks
      summary: List check's status changes
      description: Returns a list of "flips" this check has experienced. A flip is a change of status (from "down" to "up," or from "up" to "down").
      x-source: https://healthchecks.io/docs/api
      parameters:
      - name: seconds
        in: query
        required: false
        schema:
          type: integer
        description: Returns the flips from the last value seconds
      - name: start
        in: query
        required: false
        schema:
          type: integer
        description: Returns flips that are newer than the specified UNIX timestamp
      - name: end
        in: query
        required: false
        schema:
          type: integer
        description: Returns flips that are older than the specified UNIX timestamp
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV3ChecksF618072A7Bde4EeeAf6371A77C5723BcFlipsResponse'
      x-evidence:
        kind: documentation
  /api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/:
    get:
      operationId: get_api_v3_checks_f618072a_7bde_4eee_af63_71a77c5723bc_pings
      tags:
      - Checks
      summary: List check's logged pings
      description: Returns a list of pings this check has received.
      x-source: https://healthchecks.io/docs/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV3ChecksF618072A7Bde4EeeAf6371A77C5723BcPingsResponse'
      x-evidence:
        kind: documentation
  /api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/{pingid}/body:
    get:
      operationId: get_api_v3_checks_f618072a_7bde_4eee_af63_71a77c5723bc_pings_pingid_body
      tags:
      - Checks
      summary: GET /api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/{pingId}/body
      x-source: https://healthchecks.io/docs/api
      parameters:
      - name: pingid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV3ChecksF618072A7Bde4EeeAf6371A77C5723BcPingsPingidBod'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://healthchecks.io/api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/397/body  --header \"X-Api-Key: your-api-key\" \n List check's status changes \n GET https://healthchecks.io/api/v3/checks/<uuid>/flips/ \n GET https://healthchecks.io/api/v3/checks/<unique_key>/flips/ \n Returns a list of \"flips\" this check has experienced. A flip is a change of status\n(from \"down\" to \"up,\" or from \"u"
  /api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/{f618072a7bde4eeeaf6371a77c5723bcid}:
    get:
      operationId: get_api_v3_checks_f618072a_7bde_4eee_af63_71a77c5723bc_f618072a7bde4eeeaf6371a77
      tags:
      - Checks
      summary: GET /api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips
      x-source: https://healthchecks.io/docs/api
      parameters:
      - name: f618072a7bde4eeeaf6371a77c5723bcid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV3ChecksF618072A7Bde4EeeAf6371A77C5723BcF618072A7Bde4E'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://healthchecks.io/api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips/  --header \"X-Api-Key: your-api-key\" \n Example Response \n [ \n { \n \"timestamp\" : \"2020-03-23T10:18:23+00:00\" , \n \"up\" : 1 \n }, \n { \n \"timestamp\" : \"2020-03-23T10:17:15+00:00\" , \n \"up\" : 0 \n }, \n { \n \"timestamp\" : \"2020-03-23T10:16:18+00:00\" , \n \"up\" : 1 \n } \n ] \n List Existing Integrations \n GET https://healthchec"
        collapsed_from: 2 example path(s) differing only at f618072a7bde4eeeaf6371a77c5723bcId
components:
  schemas:
    GetApiV3ChecksF618072A7Bde4EeeAf6371A77C5723BcPingsResponse:
      type: object
      properties:
        pings:
          type: array
          description: List of ping objects.
    PostApiV3ChecksResponse:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
        tags:
          type: string
        desc:
          type: string
        grace:
          type: integer
        n_pings:
          type: integer
        status:
          type: string
        started:
          type: boolean
        last_ping:
          type:
          - string
          - 'null'
        next_ping:
          type:
          - string
          - 'null'
        manual_resume:
          type: boolean
        methods:
          type: string
        subject:
          type: string
        subject_fail:
          type: string
        start_kw:
          type: string
        success_kw:
          type: string
        failure_kw:
          type: string
        filter_subject:
          type: boolean
        filter_body:
          type: boolean
        filter_http_body:
          type: boolean
        filter_default_fail:
          type: boolean
        badge_url:
          type: string
        uuid:
          type: string
        ping_url:
          type: string
        update_url:
          type: string
        pause_url:
          type: string
        resume_url:
          type: string
        channels:
          type: string
        timeout:
          type: integer
    GetApiV3ChecksF618072A7Bde4EeeAf6371A77C5723BcFlipsResponse:
      type: object
      properties:
        timestamp:
          type: string
          description: ISO8601 timestamp of the flip
        up:
          type: integer
          description: 1 if the check became up, 0 if it became down
    PostApiV3ChecksResponse2:
      type: object
      properties:
        uuid:
          type: string
        ping_url:
          type: string
        update_url:
          type: string
        pause_url:
          type: string
        resume_url:
          type: string
        channels:
          type: string
        timeout:
          type: number
    DeleteApiV3Checks7918B17BA7454Db185759D2E07C97F79Response:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
        tags:
          type: string
        desc:
          type: string
        grace:
          type: integer
        n_pings:
          type: integer
        status:
          type: string
        started:
          type: boolean
        last_ping:
          type:
          - string
          - 'null'
        next_ping:
          type:
          - string
          - 'null'
        manual_resume:
          type: boolean
        methods:
          type: string
        subject:
          type: string
        subject_fail:
          type: string
        start_kw:
          type: string
        success_kw:
          type: string
        failure_kw:
          type: string
        filter_subject:
          type: boolean
        filter_body:
          type: boolean
        filter_http_body:
          type: boolean
        filter_default_fail:
          type: boolean
        badge_url:
          type: string
        uuid:
          type: string
        ping_url:
          type: string
        update_url:
          type: string
        pause_url:
          type: string
        resume_url:
          type: string
        channels:
          type: string
        timeout:
          type: integer
    GetApiV3ChecksResponse:
      type: object
      properties:
        checks:
          type: array
          description: List of check objects.
    PostApiV3ChecksRequest:
      type: object
      properties:
        name:
          type: string
        tags:
          type: string
        timeout:
          type: integer
        grace:
          type: integer
    PostApiV3ChecksRequest2:
      type: object
      properties:
        name:
          type: string
          description: Name for the new check.
        slug:
          type: string
          description: Slug for the new check.
        tags:
          type: string
          description: Space‑delimited list of tags for the new check.
        desc:
          type: string
          description: Description of the check.
        timeout:
          type: number
          description: Expected period of this check in seconds.
        grace:
          type: number
          description: Grace period for this check in seconds.
        schedule:
          type: string
          description: Cron or systemd OnCalendar expression defining this check's schedule.
        tz:
          type: string
          description: Server's timezone.
        manual_resume:
          type: boolean
          description: Controls whether a paused check automatically resumes when pinged.
        methods:
          type: string
          description: Allowed HTTP methods for ping requests.
        channels:
          type: string
          description: Integration assignment for the new check.
        unique:
          type: array
          description: Enables upsert functionality.
    PostApiV3Checks7918B17BA7454Db185759D2E07C97F79Request:
      type: object
      properties:
        name:
          type: string
        tags:
          type: string
        timeout:
          type: integer
        grace:
          type: integer
    GetApiV3ChecksF618072A7Bde4EeeAf6371A77C5723BcPingsPingidBod:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        up:
          type: integer
    PostApiV3ChecksUuidUuididResponse:
      type: object
      properties:
        status:
          type: string
          description: Will be "paused".
    GetApiV3ChecksUuidResponse:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
        tags:
          type: string
        desc:
          type: string
        grace:
          type: integer
        n_pings:
          type: integer
        status:
          type: string
        started:
          type: boolean
        last_ping:
          type: string
          format: date-time
        next_ping:
          type:
          - string
          - 'null'
        manual_resume:
          type: boolean
        methods:
          type: string
        start_kw:
          type: string
        success_kw:
          type: string
        failure_kw:
          type: string
        filter_subject:
          type: boolean
        filter_body:
          type: boolean
        filter_http_body:
          type: boolean
        filter_default_fail:
          type: boolean
        badge_url:
          type: string
        uuid:
          type: string
        ping_url:
          type: string
        update_url:
          type: string
        pause_url:
          type: string
        resume_url:
          type: string
        channels:
          type: string
        schedule:
          type: string
        tz:
          type: string
    PostApiV3Checks7918B17BA7454Db185759D2E07C97F797918B17Ba7454:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
        tags:
          type: string
        desc:
          type: string
        grace:
          type: integer
        n_pings:
          type: integer
        status:
          type: string
        started:
          type: boolean
        last_ping:
          type:
          - string
          - 'null'
        next_ping:
          type:
          - string
          - 'null'
        manual_resume:
          type: boolean
        methods:
          type: string
        subject:
          type: string
        subject_fail:
          type: string
        start_kw:
          type: string
        success_kw:
          type: string
        failure_kw:
          type: string
        filter_subject:
          type: boolean
        filter_body:
          type: boolean
        filter_http_body:
          type: boolean
        filter_default_fail:
          type: boolean
        badge_url:
          type: string
        uuid:
          type: string
        ping_url:
          type: string
        update_url:
          type: string
        pause_url:
          type: string
        resume_url:
          type: string
        channels:
          type: string
        timeout:
          type: integer
    DeleteApiV3ChecksUuidResponse:
      type: object
      properties:
        uuid:
          type: string
        ping_url:
          type: string
        update_url:
          type: string
        pause_url:
          type: string
        resume_url:
          type: string
        channels:
          type: string
        timeout:
          type: number
    PostApiV3Checks7918B17BA7454Db185759D2E07C97F79Response:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
        tags:
          type: string
        desc:
          type: string
        grace:
          type: integer
        n_pings:
          type: integer
        status:
          type: string
        started:
          type: boolean
        last_ping:
          type:
          - string
          - 'null'
        next_ping:
          type:
          - string
          - 'null'
        manual_resume:
          type: boolean
        methods:
          type: string
        subject:
          type: string
        subject_fail:
          type: string
        start_kw:
          type: string
        success_kw:
          type: string
        failure_kw:
          type: string
        filter_subject:
          type: boolean
        filter_body:
          type: boolean
        filter_http_body:
          type: boolean
        filter_default_fail:
          type: boolean
        badge_url:
          type: string
        uuid:
          type: string
        ping_url:
          type: string
        update_url:
          type: string
        pause_url:
          type: string
        resume_url:
          type: string
        channels:
          type: string
        timeout:
          type: integer
    PostApiV3ChecksUuidResponse:
      type: object
      properties:
        uuid:
          type: string
        ping_url:
          type: string
        update_url:
          type: string
        pause_url:
          type: string
        resume_url:
          type: string
        channels:
          type: string
        timeout:
          type: number
    PostApiV3ChecksUuidRequest:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
        tags:
          type: string
        desc:
          type: string
        timeout:
          type: number
        grace:
          type: number
        schedule:
          type: string
        tz:
          type: string
        manual_resume:
          type: boolean
        methods:
          type: string
        channels:
          type: string
    GetApiV3ChecksF618072A7Bde4EeeAf6371A77C5723BcF618072A7Bde4E:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        up:
          type: integer
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key