Checkly Checks API

openapi: 3.2.0
info:
  title: Checkly Public Checks 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: Checks
paths:
  /v1/checks:
    get:
      summary: List all checks
      operationId: getV1Checks
      description: Lists all current checks in your account.
      tags:
      - Checks
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChecksV1CheckList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          description: Limit the number of results
        required: false
        description: Limit the number of results
        name: limit
        in: query
      - schema:
          type: number
          default: 1
          description: Page number
          exclusiveMinimum: 0
        required: false
        description: Page number
        name: page
        in: query
      - schema:
          type: string
          minLength: 1
          description: Filters the results by a string contained in the URL of an API check, for instance a domain like "www.myapp.com". Only returns API checks.
        required: false
        description: Filters the results by a string contained in the URL of an API check, for instance a domain like "www.myapp.com". Only returns API checks.
        name: apiCheckUrlFilterPattern
        in: query
      - schema:
          type: array
          items:
            type: string
          description: Filters checks by tags. Returns checks that have at least one of the specified tags.
        required: false
        description: Filters checks by tags. Returns checks that have at least one of the specified tags.
        name: tag
        in: query
      - schema:
          type: string
          enum:
          - AGENTIC
          - API
          - BROWSER
          - HEARTBEAT
          - ICMP
          - MULTI_STEP
          - TCP
          - PLAYWRIGHT
          - TRACEROUTE
          - URL
          - DNS
          - SSL
          - GRPC
          description: Filters checks by type. Returns checks that match the specified type.
        required: false
        description: Filters checks by type. Returns checks that match the specified type.
        name: checkType
        in: query
      - schema:
          type: string
          description: Filters checks by name using a case-insensitive partial match.
        required: false
        description: Filters checks by name using a case-insensitive partial match.
        name: search
        in: query
      - schema:
          type: string
          enum:
          - passing
          - failing
          - degraded
          description: Filters checks by current status.
        required: false
        description: Filters checks by current status.
        name: status
        in: query
      - schema:
          type: boolean
          default: false
          description: Checks that belong to a group are returned with group settings applied.
        required: false
        description: Checks that belong to a group are returned with group settings applied.
        name: applyGroupSettings
        in: query
      - schema:
          type: string
          format: uuid
          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
    post:
      summary: Create a check
      operationId: postV1Checks
      description: "<b>[DEPRECATED] This endpoint will be removed soon. Instead use <code>POST /checks/api</code> or  <code>POST /checks/browser</code>.</b> Creates a new API or browser check. Will return a `402` when you are over the limit of your plan.\n    When using the `globalAlertSettings`, the `alertSettings` can be `null`"
      tags:
      - Checks
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChecksV1Check'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      deprecated: true
      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
          format: uuid
          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/ChecksV1CheckCreate'
  /v1/checks/api:
    post:
      summary: Create an API check
      operationId: postV1ChecksApi
      description: "Creates a new API 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:
      - Checks
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChecksV1ApiCheckMutationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      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
          format: uuid
          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/ChecksV1ApiCheckCreate'
  /v1/checks/api/{id}:
    put:
      summary: Update an API check
      operationId: putV1ChecksApiId
      description: Updates an API check.
      tags:
      - Checks
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChecksV1ApiCheckMutationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      parameters:
      - schema:
          type: string
          minLength: 1
          format: uuid
        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
          format: uuid
          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/ChecksV1ApiCheckUpdate'
  /v1/checks/browser:
    post:
      summary: Create a browser check
      operationId: postV1ChecksBrowser
      description: "Creates a new browser 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:
      - Checks
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChecksV1BrowserCheck'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      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
          format: uuid
          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/ChecksV1BrowserCheckCreate'
  /v1/checks/browser/{id}:
    put:
      summary: Update a browser check
      operationId: putV1ChecksBrowserId
      description: Updates a browser check.
      tags:
      - Checks
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChecksV1BrowserCheck'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      parameters:
      - schema:
          type: string
          minLength: 1
          format: uuid
        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
          format: uuid
          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/ChecksV1BrowserCheckUpdate'
  /v1/checks/dns:
    post:
      summary: Create an DNS monitor
      operationId: postV1ChecksDns
      description: "Creates a new DNS monitor. Will return a `402` when you are over the limit of your plan.\n    When using the `globalAlertSetting`, the `alertSetting` can be `null`"
      tags:
      - Checks
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChecksV1DnsMonitorMutationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      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
          format: uuid
          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/ChecksV1DnsMonitorCreate'
  /v1/checks/multistep:
    post:
      summary: Create a multi-step check
      operationId: postV1ChecksMultistep
      description: "Creates a new Multi-Step 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:
      - Checks
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChecksV1MultiStepCheck'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      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
          format: uuid
          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/ChecksV1MultiStepCheckCreate'
  /v1/checks/multistep/{id}:
    put:
      summary: Update a multi-step check
      operationId: putV1ChecksMultistepId
      description: Updates a Multi-Step check.
      tags:
      - Checks
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChecksV1MultiStepCheck'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      parameters:
      - schema:
          type: string
          minLength: 1
          format: uuid
        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
          format: uuid
          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/ChecksV1MultiStepCheckUpdate'
  /v1/checks/tcp:
    post:
      summary: Create a TCP check
      operationId: postV1ChecksTcp
      description: "Creates a new TCP 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:
      - Checks
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChecksV1TcpCheckMutationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      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
          format: uuid
          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/ChecksV1TcpCheckCreate'
  /v1/checks/tcp/{id}:
    put:
      summary: Update an TCP check
      operationId: putV1ChecksTcpId
      description: Updates an TCP check.
      tags:
      - Checks
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChecksV1TcpCheckMutationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      parameters:
      - schema:
          type: string
          minLength: 1
          format: uuid
        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
          format: uuid
          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/ChecksV1TcpCheckUpdate'
  /v1/checks/{id}:
    delete:
      summary: Delete a check
      operationId: deleteV1ChecksId
      description: Permanently removes a API or browser check and all its related status and results data.
      tags:
      - Checks
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      parameters:
      - schema:
          type: string
          minLength: 1
          format: uuid
        required: true
        name: id
        in: path
      - schema:
          type: string
          format: uuid
          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
    get:
      summary: Retrieve a check
      operationId: getV1ChecksId
      description: Show details of a specific API or browser check
      tags:
      - Checks
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChecksV1Check'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      parameters:
      - schema:
          type: string
          minLength: 1
          format: uuid
        required: true
        name: id
        in: path
      - schema:
          type: boolean
          description: Include check dependencies in the response
        required: false
        description: Include check dependencies in the response
        name: includeDependencies
        in: query
      - schema:
          type: boolean
          default: false
          description: Checks that belong to a group are returned with group settings applied.
        required: false
        description: Checks that belong to a group are returned with group settings applied.
        name: applyGroupSettings
        in: query
      - schema:
          type: string
          format: uuid
          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
    put:
      summary: Update a check
      operationId: putV1ChecksId
      description: <b>[DEPRECATED] This endpoint will be removed soon. Instead use <code>PUT /checks/api/{id}</code> or  <code>PUT /checks/browser/{id}</code>.</b> Updates a new API or browser check.
      tags:
      - Checks
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChecksV1Check'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#

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