checkly api

Make authenticated HTTP requests to the Checkly API from the command line.

Available since CLI v8.3.0.

This command is primarily designed for agentic workflows — when you need to interact with the Checkly API but a dedicated CLI command doesn’t exist yet for that operation. Make sure your Checkly skills are up to date so your AI agent has the context it needs to use this command effectively.

The checkly api command makes authenticated HTTP requests to the Checkly API. It handles authentication automatically using your current login credentials, so you can query or update your account without manually managing API keys in request headers. For available endpoints, refer to the API reference or the OpenAPI spec.

Prerequisites

Before using checkly api, ensure you have:

• Checkly CLI installed
• Valid Checkly account authentication (run npx checkly login if needed)

See the Authentication section for other authentication options.

Usage

The basic command takes an API endpoint path and optional flags.

Terminal

npx checkly api <endpoint> [options]

Arguments

The command takes a single required argument.

Argument	Description
ENDPOINT	API endpoint path, e.g. /v1/checks.

Options

All flags are optional.

Option	Description
-X, --method	HTTP method: GET, POST, PUT, PATCH, or DELETE. Defaults to GET, or POST when fields are present.
-F, --field	Add a field as key=value (string) or key:=value (JSON-parsed). Sent as a query parameter for GET requests and in the request body otherwise. Can be used multiple times.
-H, --header	Add a custom HTTP header as "Key: Value". Can be used multiple times.
--input	Read the request body from a file path, or - to read from stdin.
--jq	Filter JSON output using a jq expression. Requires jq to be installed.
-i, --include	Include HTTP status line and response headers in the output.
--verbose	Print request and response headers to stderr.

Examples

List all checks

Returns all checks in your account as JSON.

Terminal

npx checkly api /v1/checks

Extract specific fields with jq

Use --jq to filter or reshape the JSON response inline.

--jq requires jq to be installed on your system.

Terminal

npx checkly api /v1/checks --jq '.[].name'

"My first check"
"Homepage availability"
"Login flow"

Paginate results

Use -F to pass query parameters. The API returns 10 results per page by default. Set -X GET explicitly, since the command otherwise switches to POST when fields are present.

Terminal

# Get the first 5 checks
npx checkly api /v1/checks -X GET -F limit=5

# Get the second page
npx checkly api /v1/checks -X GET -F limit=5 -F page=2

Get a single resource

Append the resource ID to the endpoint path to fetch a specific item.

Terminal

npx checkly api /v1/checks/<check-id>

List alert channels

Use --jq to extract only the fields you need from the response.

Terminal

npx checkly api /v1/alert-channels --jq '[.[] | {id, type}]'

[
  { "id": 263584, "type": "SMS" },
  { "id": 263585, "type": "EMAIL" },
  { "id": 263586, "type": "SLACK" }
]

Update a resource via stdin

Pipe JSON directly into the command using --input -:

Terminal

echo '{"activated": false}' | npx checkly api /v1/checks/<check-id> -X PUT --input -

Or read from a file:

Terminal

npx checkly api /v1/checks/<check-id> -X PUT --input ./payload.json

Add custom request headers

Use -H to pass additional HTTP headers with the request. You can repeat the flag for multiple headers.

Terminal

npx checkly api /v1/checks -H "Accept: application/json" -H "X-Custom-Header: value"

Inspect response headers

Use -i to include the HTTP status and headers in the output:

Terminal

npx checkly api /v1/checks -i

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
content-range: 0-9/11
...

The content-range header tells you the total number of results (0-9/11 means items 0–9 of 11 total).

Debug a request

Use --verbose to print request and response headers to stderr:

Terminal

npx checkly api /v1/checks --verbose

> GET /v1/checks

< 200 OK
< content-type: application/json; charset=utf-8
< content-range: 0-9/11
...

Related Commands

These commands are commonly used alongside checkly api.

• checkly login - Sign in to your Checkly account
• checkly whoami - Display current account and user information

API Reference

For available endpoints, see the Checkly API reference.