POST
/
v1
/
checks
/
api
Create an API check
curl --request POST \
  --url https://api.checklyhq.com/v1/checks/api \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Check",
  "activated": true,
  "muted": false,
  "doubleCheck": true,
  "shouldFail": false,
  "locations": [
    "us-east-1",
    "eu-central-1"
  ],
  "tags": [
    "production"
  ],
  "alertSettings": {
    "escalationType": "RUN_BASED",
    "runBasedEscalation": {
      "failedRunThreshold": 1
    },
    "reminders": {
      "amount": 0,
      "interval": 5
    },
    "parallelRunFailureThreshold": {
      "enabled": false,
      "percentage": 10
    }
  },
  "useGlobalAlertSettings": true,
  "groupId": "null",
  "groupOrder": "null",
  "runtimeId": null,
  "alertChannelSubscriptions": [],
  "retryStrategy": {
    "type": "FIXED",
    "baseBackoffSeconds": 60,
    "maxRetries": 2,
    "maxDurationSeconds": 600,
    "sameRegion": true,
    "onlyOn": [
      "NETWORK_ERROR"
    ]
  },
  "runParallel": false,
  "request": {
    "method": "GET",
    "url": "https://api.checklyhq.com",
    "followRedirects": true,
    "skipSSL": false,
    "ipFamily": "IPv4",
    "body": "",
    "bodyType": "NONE",
    "headers": [
      {
        "key": "<string>",
        "value": "<string>",
        "locked": true
      }
    ],
    "queryParameters": [
      {
        "key": "<string>",
        "value": "<string>",
        "locked": true
      }
    ],
    "assertions": [
      {
        "source": "STATUS_CODE",
        "comparison": "NOT_EMPTY",
        "target": "200"
      }
    ],
    "basicAuth": {
      "username": "admin",
      "password": "abc12345"
    }
  },
  "frequency": 10,
  "frequencyOffset": 2,
  "degradedResponseTime": 5000,
  "maxResponseTime": 20000,
  "privateLocations": [
    "data-center-eu"
  ],
  "tearDownSnippetId": "null",
  "setupSnippetId": "null",
  "localSetupScript": "",
  "localTearDownScript": ""
}'
{
  "id": "2739d22d-086f-481d-a484-8b93ac84de61",
  "name": "Check",
  "activated": true,
  "muted": false,
  "doubleCheck": true,
  "shouldFail": false,
  "locations": [
    "us-east-1",
    "eu-central-1"
  ],
  "tags": [
    "production"
  ],
  "alertSettings": {
    "escalationType": "RUN_BASED",
    "runBasedEscalation": {
      "failedRunThreshold": 1
    },
    "reminders": {
      "amount": 0,
      "interval": 5
    },
    "parallelRunFailureThreshold": {
      "enabled": false,
      "percentage": 10
    }
  },
  "useGlobalAlertSettings": true,
  "groupId": "null",
  "groupOrder": "null",
  "runtimeId": null,
  "alertChannelSubscriptions": [
    {
      "alertChannelId": 123,
      "activated": true
    }
  ],
  "retryStrategy": {
    "type": "FIXED",
    "baseBackoffSeconds": 60,
    "maxRetries": 2,
    "maxDurationSeconds": 600,
    "sameRegion": true,
    "onlyOn": [
      "NETWORK_ERROR"
    ]
  },
  "runParallel": false,
  "frequency": 10,
  "frequencyOffset": 2,
  "degradedResponseTime": 123,
  "maxResponseTime": 123,
  "created_at": "2023-12-25",
  "updated_at": "2023-11-07T05:31:56Z",
  "alertChannels": {
    "email": [
      {
        "address": ""
      }
    ],
    "webhook": [
      {
        "name": "",
        "url": "",
        "method": "POST",
        "headers": [
          {
            "key": "<string>",
            "value": "<string>",
            "locked": true
          }
        ],
        "queryParameters": [
          {
            "key": "<string>",
            "value": "<string>",
            "locked": true
          }
        ]
      }
    ],
    "slack": [
      {
        "url": ""
      }
    ],
    "sms": [
      {
        "number": "+549110000000",
        "name": "SMS Alert"
      }
    ]
  },
  "privateLocations": [
    "data-center-eu"
  ],
  "request": {
    "method": "GET",
    "url": "https://api.checklyhq.com",
    "followRedirects": true,
    "skipSSL": false,
    "ipFamily": "IPv4",
    "body": "",
    "bodyType": "NONE",
    "headers": [
      {
        "key": "<string>",
        "value": "<string>",
        "locked": true
      }
    ],
    "queryParameters": [
      {
        "key": "<string>",
        "value": "<string>",
        "locked": true
      }
    ],
    "assertions": [
      {
        "source": "STATUS_CODE",
        "comparison": "NOT_EMPTY",
        "target": "200"
      }
    ],
    "basicAuth": {
      "username": "admin",
      "password": "abc12345"
    }
  },
  "checkType": "API",
  "tearDownSnippetId": null,
  "setupSnippetId": null,
  "localSetupScript": "",
  "localTearDownScript": ""
}

​
Overview

The Create API Check endpoint allows you to create new API monitoring checks to monitor REST APIs, GraphQL endpoints, and other HTTP-based services. Configure request parameters, assertions, and monitoring settings. Common Use Cases:
  • API Endpoint Monitoring
  • REST API Health Checks
  • GraphQL Query Monitoring
  • API Performance Tracking
API checks support various HTTP methods, custom headers, request bodies, and response assertions. Configure appropriate timeouts and retry settings for reliable monitoring.

Authorizations

​
Authorization
string
header
required

The Checkly Public API uses API keys to authenticate requests. You can get the API Key here.

Your API key is like a password: keep it secure!

Authentication to the API is performed using the Bearer auth method in the Authorization header and using the account ID.

For example, set Authorization header while using cURL:

curl -H "Authorization: Bearer [apiKey]" "X-Checkly-Account: [accountId]"

Headers

​
x-checkly-account
string

Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general

Query Parameters

​
autoAssignAlerts
boolean
default:true

Determines whether a new check will automatically be added as a subscriber to all existing alert channels when it gets created.

Body

application/json
​
name
string
required

The name of the check.

Example:

"Check"

​
request
object
required

Determines the request that the check is going to run.

​
activated
boolean
default:true

Determines if the check is running or not.

​
muted
boolean
default:false

Determines if any notifications will be send out when a check fails and/or recovers.

​
doubleCheck
boolean
default:true

[Deprecated] Retry failed check runs. This property is deprecated, and retryStrategy can be used instead.

​
shouldFail
boolean
default:false

Allows to invert the behaviour of when a check is considered to fail. Allows for validating error status like 404.

​
locations
enum<string>[]

An array of one or more data center locations where to run this check.

Example:
["us-east-1", "eu-central-1"]
​
tags
string[]

Tags for organizing and filtering checks.

Example:
["production"]
​
alertSettings
object

Alert settings.

​
useGlobalAlertSettings
boolean
default:true

When true, the account level alert setting will be used, not the alert setting defined on this check.

​
groupId
number

The id of the check group this check is part of.

Example:

null

​
groupOrder
number

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.

Required range: x >= 0
Example:

null

​
runtimeId
enum<string>

The runtime version, i.e. fixed set of runtime dependencies, used to execute this check.

Available options:
2025.04,
2024.09,
2024.02,
2023.09,
2023.02,
2022.10
​
alertChannelSubscriptions
object[]

List of alert channel subscriptions.

Example:
[]
​
retryStrategy
object

The strategy to determine how failed checks are retried.

​
runParallel
boolean
default:false

When true, the check will run in parallel in all selected locations.

​
frequency
enum<integer>
default:10

How often the check should run in minutes.

Available options:
0,
1,
2,
5,
10,
15,
30,
60,
120,
180,
360,
720,
1440
​
frequencyOffset
integer

Used for setting seconds for check frequencies under 1 minutes (only for API & TCP checks) and spreading checks over a time range for frequencies over 1 minute. This works as follows: Checks with a frequency of 0 can have a frequencyOffset of 10, 20 or 30 meaning they will run every 10, 20 or 30 seconds. Checks with a frequency lower than and equal to 60 can have a frequencyOffset between 1 and a max value based on the formula "Math.floor(frequency * 10)", i.e. for a check that runs every 5 minutes the max frequencyOffset is 50. Checks with a frequency higher than 60 can have a frequencyOffset between 1 and a max value based on the formula "Math.ceil(frequency / 60)", i.e. for a check that runs every 720 minutes, the max frequencyOffset is 12.

Required range: x >= 1
​
degradedResponseTime
number
default:5000

The response time in milliseconds where a check should be considered degraded.

Required range: 0 <= x <= 30000
​
maxResponseTime
number
default:20000

The response time in milliseconds where a check should be considered failing.

Required range: 0 <= x <= 30000
​
privateLocations
string[]

An array of one or more private locations where to run the check.

Example:
["data-center-eu"]
​
tearDownSnippetId
number

An ID reference to a snippet to use in the teardown phase of an API check.

Example:

null

​
setupSnippetId
number

An ID reference to a snippet to use in the setup phase of an API check.

Example:

null

​
localSetupScript
string

A valid piece of Node.js code to run in the setup phase.

Example:

""

​
localTearDownScript
string

A valid piece of Node.js code to run in the teardown phase.

Example:

""

Response

Created

​
name
string
required

The name of the check.

Example:

"Check"

​
id
string
Example:

"2739d22d-086f-481d-a484-8b93ac84de61"

​
activated
boolean
default:true

Determines if the check is running or not.

​
muted
boolean
default:false

Determines if any notifications will be send out when a check fails and/or recovers.

​
doubleCheck
boolean
default:true

[Deprecated] Retry failed check runs. This property is deprecated, and retryStrategy can be used instead.

​
shouldFail
boolean
default:false

Allows to invert the behaviour of when a check is considered to fail. Allows for validating error status like 404.

​
locations
enum<string>[]

An array of one or more data center locations where to run this check.

Example:
["us-east-1", "eu-central-1"]
​
tags
string[]

Tags for organizing and filtering checks.

Example:
["production"]
​
alertSettings
object

Alert settings.

​
useGlobalAlertSettings
boolean
default:true

When true, the account level alert setting will be used, not the alert setting defined on this check.

​
groupId
number

The id of the check group this check is part of.

Example:

null

​
groupOrder
number

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.

Required range: x >= 0
Example:

null

​
runtimeId
enum<string>

The runtime version, i.e. fixed set of runtime dependencies, used to execute this check.

Available options:
2025.04,
2024.09,
2024.02,
2023.09,
2023.02,
2022.10
​
alertChannelSubscriptions
object[]
​
retryStrategy
object

The strategy to determine how failed checks are retried.

​
runParallel
boolean
default:false

When true, the check will run in parallel in all selected locations.

​
frequency
enum<integer>
default:10

How often the check should run in minutes.

Available options:
0,
1,
2,
5,
10,
15,
30,
60,
120,
180,
360,
720,
1440
​
frequencyOffset
integer

Used for setting seconds for check frequencies under 1 minutes (only for API & TCP checks) and spreading checks over a time range for frequencies over 1 minute. This works as follows: Checks with a frequency of 0 can have a frequencyOffset of 10, 20 or 30 meaning they will run every 10, 20 or 30 seconds. Checks with a frequency lower than and equal to 60 can have a frequencyOffset between 1 and a max value based on the formula "Math.floor(frequency * 10)", i.e. for a check that runs every 5 minutes the max frequencyOffset is 50. Checks with a frequency higher than 60 can have a frequencyOffset between 1 and a max value based on the formula "Math.ceil(frequency / 60)", i.e. for a check that runs every 720 minutes, the max frequencyOffset is 12.

Required range: x >= 1
​
degradedResponseTime
number
​
maxResponseTime
number
​
created_at
string<date>
​
updated_at
string<date-time>
​
alertChannels
object
​
privateLocations
string[]

An array of one or more private locations where to run the check.

Example:
["data-center-eu"]
​
request
object

Determines the request that the check is going to run.

​
checkType
enum<string>
Available options:
API
​
tearDownSnippetId
number

An ID reference to a snippet to use in the teardown phase of an API check.

​
setupSnippetId
number

An ID reference to a snippet to use in the setup phase of an API check.

​
localSetupScript
string

A valid piece of Node.js code to run in the setup phase.

Example:

""

​
localTearDownScript
string

A valid piece of Node.js code to run in the teardown phase.

Example:

""