From cc2e1448bb28e75bf454b3b9031b6eace4c1ea2b Mon Sep 17 00:00:00 2001 From: stefan judis Date: Mon, 15 Jun 2026 12:32:36 +0200 Subject: [PATCH 01/13] docs: add checkly api command reference Documents the checkly api pass-through command with verified examples covering GET/PUT, jq filtering, pagination, stdin input, and response header inspection. --- cli/checkly-api.mdx | 149 ++++++++++++++++++++++++++++++++++++++++++++ docs.json | 1 + 2 files changed, 150 insertions(+) create mode 100644 cli/checkly-api.mdx diff --git a/cli/checkly-api.mdx b/cli/checkly-api.mdx new file mode 100644 index 00000000..a6e7b02d --- /dev/null +++ b/cli/checkly-api.mdx @@ -0,0 +1,149 @@ +--- +title: checkly api +description: 'Make authenticated HTTP requests to the Checkly API from the command line.' +sidebarTitle: 'checkly api' +--- + +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. + + +Before using `checkly api`, ensure you have: + +- Checkly CLI installed +- A valid Checkly account authentication (run `npx checkly login` if needed) + +See the [Authentication section](/cli/authentication) for other authentication options. + + +## Usage + +```bash Terminal +npx checkly api [options] +``` + +## Arguments + +| Argument | Description | +|----------|-------------| +| `ENDPOINT` | API endpoint path, e.g. `/v1/checks`. | + +## Options + +| Option | Description | +|--------|-------------| +| `-X, --method` | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. Defaults to `GET`. | +| `-F, --field` | Add a request field as `key=value` (string) or `key:=value` (JSON-parsed). 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](https://jqlang.org/) 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 + +```bash Terminal +npx checkly api /v1/checks +``` + +### Extract specific fields with jq + +```bash Terminal +npx checkly api /v1/checks --jq '.[].name' +``` + +``` +"Heartbeat Check #1" +"Product catalog" +"Login flow" +``` + +### Paginate results + +Use `-F` to pass query parameters. The API returns 10 results per page by default. + +```bash Terminal +# Get the first 5 checks +npx checkly api /v1/checks -F limit=5 + +# Get the second page +npx checkly api /v1/checks -F limit=5 -F page=2 +``` + +### Get a single resource + +```bash Terminal +npx checkly api /v1/checks/ +``` + +### List alert channels + +```bash Terminal +npx checkly api /v1/alert-channels --jq '[.[] | {id, type}]' +``` + +```json +[ + { "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 -`: + +```bash Terminal +echo '{"activated": false}' | npx checkly api /v1/checks/ -X PUT --input - +``` + +Or read from a file: + +```bash Terminal +npx checkly api /v1/checks/ -X PUT --input ./payload.json +``` + +### Inspect response headers + +Use `-i` to include the HTTP status and headers in the output: + +```bash 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 page 1 of 11 items). + +### Debug a request + +Use `--verbose` to print request and response headers to stderr: + +```bash 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 + +- [`checkly login`](/cli/checkly-login) - Sign in to your Checkly account +- [`checkly whoami`](/cli/checkly-whoami) - Display current account and user information + +## API Reference + +For available endpoints, see the [Checkly API reference](/api-reference/overview). diff --git a/docs.json b/docs.json index 90871d95..3307152e 100644 --- a/docs.json +++ b/docs.json @@ -548,6 +548,7 @@ "group": "CLI Commands", "pages": [ "cli/checkly-account", + "cli/checkly-api", "cli/checkly-checks", "cli/checkly-deploy", "cli/checkly-destroy", From 479d06a49df4613fc781516a0d3ac92bf0528c98 Mon Sep 17 00:00:00 2001 From: stefan judis Date: Mon, 15 Jun 2026 13:01:32 +0200 Subject: [PATCH 02/13] docs: add version availability note to checkly api --- cli/checkly-api.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/cli/checkly-api.mdx b/cli/checkly-api.mdx index a6e7b02d..6043d643 100644 --- a/cli/checkly-api.mdx +++ b/cli/checkly-api.mdx @@ -4,6 +4,8 @@ description: 'Make authenticated HTTP requests to the Checkly API from the comma sidebarTitle: 'checkly api' --- +Available since CLI v8.3.0. + 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. From 8cee1eea2130215645a0ae60b6de04a2975fc9b6 Mon Sep 17 00:00:00 2001 From: stefan judis Date: Mon, 15 Jun 2026 13:02:53 +0200 Subject: [PATCH 03/13] docs: add tip about agentic workflow use case --- cli/checkly-api.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/cli/checkly-api.mdx b/cli/checkly-api.mdx index 6043d643..2bdd1b9c 100644 --- a/cli/checkly-api.mdx +++ b/cli/checkly-api.mdx @@ -8,6 +8,8 @@ sidebarTitle: 'checkly api' 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. +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. + Before using `checkly api`, ensure you have: From 3a374ced30cde4fe5ed8f32c57554c80b1a70e87 Mon Sep 17 00:00:00 2001 From: stefan judis Date: Mon, 15 Jun 2026 13:03:37 +0200 Subject: [PATCH 04/13] docs: link to checkly skills from api command tip --- cli/checkly-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cli/checkly-api.mdx b/cli/checkly-api.mdx index 2bdd1b9c..9ad2f4a5 100644 --- a/cli/checkly-api.mdx +++ b/cli/checkly-api.mdx @@ -8,7 +8,7 @@ sidebarTitle: 'checkly api' 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. -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. +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](/cli/checkly-skills) are up to date so your AI agent has the context it needs to use this command effectively. Before using `checkly api`, ensure you have: From 2feff3b567535934c297160eccff38dc565c0bdb Mon Sep 17 00:00:00 2001 From: stefan judis Date: Mon, 15 Jun 2026 13:04:35 +0200 Subject: [PATCH 05/13] docs: clarify jq installation requirement --- cli/checkly-api.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/cli/checkly-api.mdx b/cli/checkly-api.mdx index 9ad2f4a5..0a6213d2 100644 --- a/cli/checkly-api.mdx +++ b/cli/checkly-api.mdx @@ -53,6 +53,8 @@ npx checkly api /v1/checks ### Extract specific fields with jq +`--jq` requires [jq](https://jqlang.org/) to be installed on your system. + ```bash Terminal npx checkly api /v1/checks --jq '.[].name' ``` From b84cfc38278b8a548fab28c5805331e9b12da50c Mon Sep 17 00:00:00 2001 From: stefan judis Date: Mon, 15 Jun 2026 13:05:37 +0200 Subject: [PATCH 06/13] docs: replace real check names with generic example output --- cli/checkly-api.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cli/checkly-api.mdx b/cli/checkly-api.mdx index 0a6213d2..d58d5b3f 100644 --- a/cli/checkly-api.mdx +++ b/cli/checkly-api.mdx @@ -60,8 +60,8 @@ npx checkly api /v1/checks --jq '.[].name' ``` ``` -"Heartbeat Check #1" -"Product catalog" +"My first check" +"Homepage availability" "Login flow" ``` From 305de1393ecb6de21121d7d70d7eb47983192802 Mon Sep 17 00:00:00 2001 From: stefan judis Date: Mon, 15 Jun 2026 13:06:56 +0200 Subject: [PATCH 07/13] docs: add intro paragraphs under all headings --- cli/checkly-api.mdx | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/cli/checkly-api.mdx b/cli/checkly-api.mdx index d58d5b3f..b33d1c86 100644 --- a/cli/checkly-api.mdx +++ b/cli/checkly-api.mdx @@ -21,18 +21,24 @@ See the [Authentication section](/cli/authentication) for other authentication o ## Usage +The basic command takes an API endpoint path and optional flags. + ```bash Terminal npx checkly api [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`. | @@ -45,14 +51,20 @@ npx checkly api [options] ## Examples +The following examples cover common use cases for the `checkly api` command. + ### List all checks +Returns all checks in your account as JSON. + ```bash Terminal npx checkly api /v1/checks ``` ### Extract specific fields with jq +Use `--jq` to filter or reshape the JSON response inline. + `--jq` requires [jq](https://jqlang.org/) to be installed on your system. ```bash Terminal @@ -79,12 +91,16 @@ npx checkly api /v1/checks -F limit=5 -F page=2 ### Get a single resource +Append the resource ID to the endpoint path to fetch a specific item. + ```bash Terminal npx checkly api /v1/checks/ ``` ### List alert channels +Use `--jq` to extract only the fields you need from the response. + ```bash Terminal npx checkly api /v1/alert-channels --jq '[.[] | {id, type}]' ``` @@ -147,6 +163,8 @@ npx checkly api /v1/checks --verbose ## Related Commands +These commands are commonly used alongside `checkly api`. + - [`checkly login`](/cli/checkly-login) - Sign in to your Checkly account - [`checkly whoami`](/cli/checkly-whoami) - Display current account and user information From 9873edf6fc41772d4d5c16405901874e7f1bea46 Mon Sep 17 00:00:00 2001 From: stefan judis Date: Mon, 15 Jun 2026 13:08:39 +0200 Subject: [PATCH 08/13] docs: add missing -H header example --- cli/checkly-api.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/cli/checkly-api.mdx b/cli/checkly-api.mdx index b33d1c86..97cb0c3a 100644 --- a/cli/checkly-api.mdx +++ b/cli/checkly-api.mdx @@ -127,6 +127,14 @@ Or read from a file: npx checkly api /v1/checks/ -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. + +```bash 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: From 267465b95edb22c68bacba1aa5a2f63317f2b4d2 Mon Sep 17 00:00:00 2001 From: stefan judis Date: Mon, 15 Jun 2026 13:09:17 +0200 Subject: [PATCH 09/13] docs: mention OpenAPI spec in opening paragraph --- cli/checkly-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cli/checkly-api.mdx b/cli/checkly-api.mdx index 97cb0c3a..77a084fe 100644 --- a/cli/checkly-api.mdx +++ b/cli/checkly-api.mdx @@ -6,7 +6,7 @@ sidebarTitle: 'checkly api' Available since CLI v8.3.0. -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. +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](/api-reference/overview) or the [OpenAPI spec](https://api.checklyhq.com/openapi.json). 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](/cli/checkly-skills) are up to date so your AI agent has the context it needs to use this command effectively. From 8e65becdb48f940ece7b4d4429e709cf12716be5 Mon Sep 17 00:00:00 2001 From: stefan judis Date: Mon, 15 Jun 2026 13:10:36 +0200 Subject: [PATCH 10/13] docs: move agentic tip below version note --- cli/checkly-api.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cli/checkly-api.mdx b/cli/checkly-api.mdx index 77a084fe..fd306437 100644 --- a/cli/checkly-api.mdx +++ b/cli/checkly-api.mdx @@ -6,10 +6,10 @@ sidebarTitle: 'checkly api' Available since CLI v8.3.0. -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](/api-reference/overview) or the [OpenAPI spec](https://api.checklyhq.com/openapi.json). - 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](/cli/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](/api-reference/overview) or the [OpenAPI spec](https://api.checklyhq.com/openapi.json). + Before using `checkly api`, ensure you have: From d88e767237e0580a9d1635b31b3188c34332c9c3 Mon Sep 17 00:00:00 2001 From: stefan judis Date: Mon, 15 Jun 2026 13:12:19 +0200 Subject: [PATCH 11/13] docs: drop filler intro under Examples heading --- cli/checkly-api.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/cli/checkly-api.mdx b/cli/checkly-api.mdx index fd306437..ba4bc1cc 100644 --- a/cli/checkly-api.mdx +++ b/cli/checkly-api.mdx @@ -51,8 +51,6 @@ All flags are optional. ## Examples -The following examples cover common use cases for the `checkly api` command. - ### List all checks Returns all checks in your account as JSON. From 4a4b87c8885726fb59615024400520820b08798c Mon Sep 17 00:00:00 2001 From: stefan judis Date: Mon, 15 Jun 2026 13:15:01 +0200 Subject: [PATCH 12/13] =?UTF-8?q?docs:=20fix=20pagination=20examples=20?= =?UTF-8?q?=E2=80=94=20-F=20adds=20body=20fields=20and=20flips=20method=20?= =?UTF-8?q?to=20POST?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cli/checkly-api.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/cli/checkly-api.mdx b/cli/checkly-api.mdx index ba4bc1cc..807d4988 100644 --- a/cli/checkly-api.mdx +++ b/cli/checkly-api.mdx @@ -41,8 +41,8 @@ All flags are optional. | Option | Description | |--------|-------------| -| `-X, --method` | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. Defaults to `GET`. | -| `-F, --field` | Add a request field as `key=value` (string) or `key:=value` (JSON-parsed). Can be used multiple times. | +| `-X, --method` | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. Defaults to `GET`, or `POST` when fields are present. | +| `-F, --field` | Add a request body field as `key=value` (string) or `key:=value` (JSON-parsed). 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](https://jqlang.org/) expression. Requires `jq` to be installed. | @@ -77,14 +77,14 @@ npx checkly api /v1/checks --jq '.[].name' ### Paginate results -Use `-F` to pass query parameters. The API returns 10 results per page by default. +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. ```bash Terminal # Get the first 5 checks -npx checkly api /v1/checks -F limit=5 +npx checkly api /v1/checks -X GET -F limit=5 # Get the second page -npx checkly api /v1/checks -F limit=5 -F page=2 +npx checkly api /v1/checks -X GET -F limit=5 -F page=2 ``` ### Get a single resource From 7a9ad6dfa4325d982b3fa6f913c9ffa1c66de74c Mon Sep 17 00:00:00 2001 From: stefan judis Date: Mon, 15 Jun 2026 13:20:53 +0200 Subject: [PATCH 13/13] docs: address review comments on -F behavior, content-range, grammar --- cli/checkly-api.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/cli/checkly-api.mdx b/cli/checkly-api.mdx index 807d4988..b06ba258 100644 --- a/cli/checkly-api.mdx +++ b/cli/checkly-api.mdx @@ -14,7 +14,7 @@ The `checkly api` command makes authenticated HTTP requests to the Checkly API. Before using `checkly api`, ensure you have: - Checkly CLI installed -- A valid Checkly account authentication (run `npx checkly login` if needed) +- Valid Checkly account authentication (run `npx checkly login` if needed) See the [Authentication section](/cli/authentication) for other authentication options. @@ -42,7 +42,7 @@ 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 request body field as `key=value` (string) or `key:=value` (JSON-parsed). Can be used multiple times. | +| `-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](https://jqlang.org/) expression. Requires `jq` to be installed. | @@ -148,7 +148,7 @@ content-range: 0-9/11 ... ``` -The `content-range` header tells you the total number of results (`0-9/11` means page 1 of 11 items). +The `content-range` header tells you the total number of results (`0-9/11` means items 0–9 of 11 total). ### Debug a request