new API structure by Dgiordano33 · Pull Request #159 · checkly/docs

Dgiordano33 · 2026-01-23T00:18:18Z

Affected Components

Notes for the Reviewer

New Dependency Submission

Screenshots

sujaya-sys

@guolau I don't really have context on this change so mainly looked for wording inconsistencies. Hope that helps - feel free to disregard anything that doesn't make sense :)

api-reference/accounts/fetch-a-given-account-details.mdx

api-reference/accounts/fetch-current-account-details.mdx

api-reference/accounts/fetch-user-accounts.mdx

api-reference/client-certificates/creates-a-new-client-certificate.mdx

sujaya-sys · 2026-02-02T08:21:50Z

api-reference/analytics/api-checks.mdx

@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/analytics/api-checks/{id}
+title: Get API Check analytics


Suggested change

title: Get API Check analytics

title: Get API check analytics

api-reference/heartbeats/get-a-specific-heartbeat-event.mdx

api-reference/heartbeats/get-heartbeat-availability.mdx

api-reference/heartbeats/update-a-heartbeat-check.mdx

api-reference/client-certificates/deletes-a-client-certificate.mdx

sujaya-sys · 2026-02-02T08:30:14Z

API-DOCUMENTATION.md

+
+#### Broken Navigation Links (in docs.json but no MDX file)
+
+| Missing File |


I'm missing context on the purpose of this doc, but why are we documenting issues, missing files, open questions, inconsistencies etc here?

guolau

Thanks for this PR, Dan. IMO will look much better than our current API reference once we've polished it up.

guolau · 2026-02-03T21:33:38Z

docs.json

+              {
+                "group": "Triggers",
+                "pages": [
+                  "api-reference/triggers/get-the-check-group-trigger",
+                  "api-reference/triggers/create-the-check-group-trigger",
+                  "api-reference/triggers/delete-the-check-group-trigger",
+                  "api-reference/triggers/get-the-check-trigger",
+                  "api-reference/triggers/create-the-check-trigger",
+                  "api-reference/triggers/delete-the-check-trigger"
+                ]
+              }    


This should probably go in the Detect section, since it's about triggering check runs

guolau · 2026-02-03T21:51:20Z

docs.json

+                  "api-reference/checks/update-a-check"
+                ]
+              },
+              {


I wouldn't separate these endpoints into Uptime and Synthetic since some of these endpoints apply to both (like list all checks).

I think something like this would be bette:

api-reference/checks/list-all-checks

api-reference/checks/retrieve-a-check

api-reference/checks/delete-a-check

API check

api-reference/checks/create-an-api-check

api-reference/checks/update-an-api-check

Browser check

api-reference/checks/create-a-browser-check

api-reference/checks/update-a-browser-check

Multistep check

api-reference/checks/create-a-multi-step-check

api-reference/checks/update-a-multi-step-check

DNS monitor

api-reference/monitors/create-a-dns-monitor

api-reference/monitors/update-a-dns-monitor

Heartbeat monitor

api-reference/heartbeats/create-a-heartbeat-check

api-reference/heartbeats/update-a-heartbeat-check

api-reference/heartbeats/get-heartbeat-availability

api-reference/heartbeats/get-a-list-of-events-for-a-heartbeat

api-reference/heartbeats/get-a-specific-heartbeat-event

TCP monitor

api-reference/checks/create-a-tcp-check

api-reference/checks/update-an-tcp-check

URL monitor

api-reference/monitors/create-a-url-monitor

api-reference/monitors/update-an-url-monitor

api-reference/checks/create-a-check

api-reference/checks/update-a-check

guolau · 2026-02-03T21:53:22Z

docs.json

+                "group": "Locations",
+                "pages": [
+                  "api-reference/location/lists-all-supported-locations",
+                  "api-reference/private-locations/list-all-private-locations",
+                  "api-reference/private-locations/create-a-private-location",
+                  "api-reference/private-locations/retrieve-a-private-location",
+                  "api-reference/private-locations/update-a-private-location",
+                  "api-reference/private-locations/remove-a-private-location",
+                  "api-reference/private-locations/generate-a-new-api-key-for-a-private-location",
+                  "api-reference/private-locations/remove-an-existing-api-key-for-a-private-location",
+                  "api-reference/private-locations/get-private-location-health-metrics-from-a-window-of-time"
+                ]
+              },


Seems like this should go under Platform? Additionally, I'd separate api-reference/location/lists-all-supported-locations (just lists public locations) from the private location endpoints

guolau · 2026-02-03T21:57:03Z

docs.json

+                "group": "Check Groups",
+                "pages": [
+                  "api-reference/check-groups/list-all-check-groups",
+                  "api-reference/check-groups/create-a-check-group",
+                  "api-reference/check-groups/retrieve-one-check-in-a-specific-group-with-group-settings-applied",
+                  "api-reference/check-groups/retrieve-a-check-group",
+                  "api-reference/check-groups/update-a-check-group",
+                  "api-reference/check-groups/delete-a-check-group",
+                  "api-reference/check-groups/retrieve-all-checks-in-a-specific-group-with-group-settings-applied",
+                  "api-reference/check-groups/create-a-check-group-v2",
+                  "api-reference/check-groups/update-a-check-group-v2"
+                ]
+              },


Probably should change the order so that the V2 endpoints are higher up:

Suggested change

"group": "Check Groups",

"pages": [

"api-reference/check-groups/list-all-check-groups",

"api-reference/check-groups/create-a-check-group",

"api-reference/check-groups/retrieve-one-check-in-a-specific-group-with-group-settings-applied",

"api-reference/check-groups/retrieve-a-check-group",

"api-reference/check-groups/update-a-check-group",

"api-reference/check-groups/delete-a-check-group",

"api-reference/check-groups/retrieve-all-checks-in-a-specific-group-with-group-settings-applied",

"api-reference/check-groups/create-a-check-group-v2",

"api-reference/check-groups/update-a-check-group-v2"

]

},

"group": "Check Groups",

"pages": [

"api-reference/check-groups/list-all-check-groups",

"api-reference/check-groups/retrieve-a-check-group",

"api-reference/check-groups/retrieve-one-check-in-a-specific-group-with-group-settings-applied",

"api-reference/check-groups/create-a-check-group-v2",

"api-reference/check-groups/update-a-check-group-v2",

"api-reference/check-groups/delete-a-check-group",

"api-reference/check-groups/retrieve-all-checks-in-a-specific-group-with-group-settings-applied",

"api-reference/check-groups/create-a-check-group",

"api-reference/check-groups/update-a-check-group"

]

},

guolau · 2026-02-03T22:00:23Z

docs.json

+                  "api-reference/status-pages/get-all-subscriptions-for-a-specific-status-page",
+                  "api-reference/status-pages/delete-a-subscription-belonging-to-a-specific-status-page"


I'd put these in their own "Status Page Subscriptions" category

guolau · 2026-02-03T22:38:11Z

API-DOCUMENTATION.md

@@ -0,0 +1,279 @@
+# API Reference Documentation Architecture


Nice, good call to document how the API reference comes together. We can probably clean this up and make it more concise, but this is good for now.

guolau · 2026-02-03T22:43:10Z

api-reference/analytics/api-checks.mdx

@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/analytics/api-checks/{id}
+title: Get API Check analytics


The title was only changed for API checks. This should be consistent -- either we use this title format for all analytic pages, or we remove this one.

api-reference/client-certificates/shows-one-client-certificate.mdx

guolau · 2026-02-03T22:53:14Z

api-reference/opentelemetry/post-accounts-metrics.mdx

Does this endpoint exist publicly? I'm not seeing it in our OpenAPI spec https://api.checklyhq.com/openapi.json

api-reference/snippets/list-specific-snippet.mdx

Co-authored-by: Susa Tünker <74345218+sujaya-sys@users.noreply.github.com>

…cate.mdx Co-authored-by: Susa Tünker <74345218+sujaya-sys@users.noreply.github.com>

…s.mdx Co-authored-by: Susa Tünker <74345218+sujaya-sys@users.noreply.github.com>

….mdx

Co-authored-by: Susa Tünker <74345218+sujaya-sys@users.noreply.github.com>

new API structure

c6e205e

mintlify bot deployed to staging January 23, 2026 00:20 View deployment

API Update: OTEL

2b32c77

mintlify bot deployed to staging January 23, 2026 00:26 View deployment

guolau self-requested a review January 26, 2026 21:49

sujaya-sys reviewed Feb 2, 2026

View reviewed changes

guolau requested changes Feb 3, 2026

View reviewed changes

guolau and others added 4 commits February 4, 2026 16:25

Update api-reference/accounts/fetch-a-given-account-details.mdx

2e21c6a

Co-authored-by: Susa Tünker <74345218+sujaya-sys@users.noreply.github.com>

Update api-reference/accounts/fetch-current-account-details.mdx

af2f5c5

Co-authored-by: Susa Tünker <74345218+sujaya-sys@users.noreply.github.com>

Update api-reference/accounts/fetch-user-accounts.mdx

3e95ab3

Co-authored-by: Susa Tünker <74345218+sujaya-sys@users.noreply.github.com>

Update api-reference/client-certificates/creates-a-new-client-certifi…

f867739

…cate.mdx Co-authored-by: Susa Tünker <74345218+sujaya-sys@users.noreply.github.com>

mintlify bot deployed to staging February 4, 2026 21:26 View deployment

Update api-reference/client-certificates/lists-all-client-certificate…

f52d1ff

…s.mdx Co-authored-by: Susa Tünker <74345218+sujaya-sys@users.noreply.github.com>

mintlify bot deployed to staging February 4, 2026 21:26 View deployment

guolau and others added 2 commits February 4, 2026 16:26

Update api-reference/client-certificates/shows-one-client-certificate…

de9c863

….mdx

Update api-reference/heartbeats/create-a-heartbeat-check.mdx

23d1d13

Co-authored-by: Susa Tünker <74345218+sujaya-sys@users.noreply.github.com>

mintlify bot deployed to staging February 4, 2026 21:27 View deployment

Apply suggestions from code review for page titles

5fa8b38

Co-authored-by: Susa Tünker <74345218+sujaya-sys@users.noreply.github.com>

mintlify bot deployed to staging February 4, 2026 21:30 View deployment

mintlify bot deployed to staging February 4, 2026 21:38 View deployment

	title: Get API Check analytics
	title: Get API check analytics


		#### Broken Navigation Links (in docs.json but no MDX file)

		\| Missing File \|

		"api-reference/status-pages/get-all-subscriptions-for-a-specific-status-page",
		"api-reference/status-pages/delete-a-subscription-belonging-to-a-specific-status-page"

Conversation

Dgiordano33 commented Jan 23, 2026

Affected Components

Notes for the Reviewer

New Dependency Submission

Screenshots

Uh oh!

sujaya-sys left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

guolau left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants