Learn more about API Checks in the API Checks overview.
Use API Checks to monitor HTTP endpoints, REST APIs, GraphQL APIs, and other HTTP-based services. The examples below show how to configure monitoring for different types of API endpoints.
Before creating API Checks, ensure you have:
  • An initialized Checkly CLI project
  • URLs or HTTP endpoints you want to monitor
  • Understanding of HTTP status codes and response behavior
  • Network access to the URLs you want to monitor
For additional setup information, see CLI overview.
import { ApiCheck } from "checkly/constructs"

new ApiCheck("hello-api-1", {
  name: "Hello API Check",
  request: {
    method: "GET",
    url: "https://api.checklyhq.com/hello",
  },
})

​
Configuration

The API Check configuration consists of specific API Check options and inherited general check options.
ParameterTypeRequiredDefaultDescription
requestobject✅-HTTP request configuration object
degradedResponseTimenumber❌10000Response time threshold in milliseconds for degraded status
maxResponseTimenumber❌20000Maximum response time in milliseconds before marking as failed
shouldFailboolean❌falseWhether a failure should count as a pass (status 400+ reported as passed)
setupScriptobject❌-Script to run before the API Check execution
tearDownScriptobject❌-Script to run after the API Check execution

​
API Check Options

​
request
object
required
The HTTP request configuration that defines the API endpoint to monitor. This is the core component of any API Check.Usage:
request: {
  method: 'GET',
  url: 'https://api.example.com/users'
}
Parameters:
ParameterTypeRequiredDefaultDescription
methodstring✅-HTTP method: GET | POST | PUT | PATCH | HEAD | DELETE | OPTIONS
urlstring✅-The target URL for the HTTP request
assertionsarray❌[]Response assertions using AssertionBuilder
basicAuthobject❌-Basic auth credentials: { username, password }
bodystring❌-HTTP request body content
bodyTypestring❌NONEBody type: JSON | FORM | RAW | GRAPHQL | NONE
followRedirectsboolean❌trueWhether to automatically follow 30x redirects
headersarray❌[]Array of { key, value } objects for HTTP headers
skipSSLboolean❌falseWhether to skip SSL certificate validation
queryParametersarray❌[]Array of { key, value } objects for query parameters
Examples:
request: {
  method: "GET",
  url: "https://api.example.com/users",
  headers: [
    { key: "Authorization", value: "Bearer {{API_TOKEN}}" },
    { key: "Content-Type", value: "application/json" },
  ],
  assertions: [
    AssertionBuilder.statusCode().equals(200),
    AssertionBuilder.jsonBody("$.length").greaterThan(0),
    AssertionBuilder.responseTime().lessThan(1000),
  ],
},
Use cases: HTTP endpoint monitoring, REST API testing, GraphQL API validation, authentication testing.
​
degradedResponseTime
number
default:"10000"
Response time threshold in milliseconds for marking the check as degraded. This provides an early warning before the check fails completely.Usage:
new ApiCheck("performance-check", {
  name: "Performance Monitoring",
  degradedResponseTime: 2000, // Warning at 2 seconds
  maxResponseTime: 5000, // Failure at 5 seconds
  request: {
    method: "GET",
    url: "https://api.example.com/users",
  },
})
Use cases: Performance alerting, SLA monitoring, gradual degradation detection.
​
maxResponseTime
number
default:"20000"
Maximum response time in milliseconds before marking the check as failed. This sets the absolute threshold for check failure based on response time.Usage:
new ApiCheck("timeout-check", {
  name: "API Timeout Check",
  maxResponseTime: 5000, // Fail if response takes longer than 5 seconds
  request: {
    method: "GET",
    url: "https://api.example.com/slow-endpoint",
  },
})
Use cases: Performance monitoring, SLA compliance, timeout management.
​
shouldFail
boolean
Whether a failure should count as a pass. When set to true, HTTP status codes 400 and above are reported as passed instead of failed.Usage:
new ApiCheck("negative-test", {
  name: "Test Error Handling",
  shouldFail: true, // Expect this to fail
  request: {
    method: "GET",
    url: "https://httpbin.org/status/403",
  },
})
Examples:
new ApiCheck("error-handling-test", {
  name: "Error Handling Test",
  shouldFail: true, // We expect 4xx/5xx responses
  request: {
    method: "POST",
    url: "https://api.example.com/protected",
    // No auth headers - should return 401
    assertions: [AssertionBuilder.statusCode().equals(401)],
  },
})
Use cases: Negative testing, error handling validation, security testing.
​
setupScript
object
Script to run before the API Check execution. Useful for setting up test data or authentication tokens.Usage:
new ApiCheck("api-with-setup", {
  name: "API with Setup Script",
  setupScript: {
    entrypoint: path.join(__dirname, "scripts/api-setup.ts"),
  },
  request: {
    method: "GET",
    url: "https://api.example.com/users",
  },
})
Parameters:
ParameterTypeRequiredDescription
entrypointstring❌Path to a .js or .ts file containing the setup script
contentstring❌Inline JavaScript/TypeScript code as a string
You must provide either entrypoint or content, but not both.
Learn more about writing setup and teardown scripts in the setup and teardown scripts documentation.
Use cases: Test data setup, authentication preparation, environment configuration.
​
tearDownScript
object
Script to run after the API Check execution. Useful for cleaning up test data or resources.Usage:
new ApiCheck("api-with-teardown", {
  name: "API with Teardown Script",
  tearDownScript: {
    entrypoint: path.join(__dirname, "scripts/api-teardown.ts"),
  },
  request: {
    method: "GET",
    url: "https://api.example.com/users",
  },
})
Parameters:
ParameterTypeRequiredDescription
entrypointstring❌Path to a .js or .ts file containing the teardown script
contentstring❌Inline JavaScript/TypeScript code as a string
You must provide either entrypoint or content, but not both.
Learn more about writing setup and teardown scripts in the setup and teardown scripts documentation.
Use cases: Test data cleanup, resource cleanup, logging and reporting.

​
Examples

new ApiCheck("users-api-check", {
  name: "Users API Check",
  maxResponseTime: 5000,
  degradedResponseTime: 2000,
  request: {
    method: "GET",
    url: "https://api.example.com/users",
    headers: [
      { key: "Authorization", value: "Bearer {{API_TOKEN}}" },
      { key: "Content-Type", value: "application/json" },
    ],
    assertions: [
      AssertionBuilder.statusCode().equals(200),
      AssertionBuilder.jsonBody("$.users.length").greaterThan(0),
      AssertionBuilder.responseTime().lessThan(1000),
    ],
  },
})
When using environment variables in your requests (like {{API_TOKEN}}), make sure they are properly configured in your project or check group settings.