Merge pull request #159 from checkly/giordanodaniel-api-nav

guolau · web-flow · commit 24ca6b353797 · 2026-02-24T15:07:59.000-05:00
new API structure
diff --git a/API-DOCUMENTATION.md b/API-DOCUMENTATION.md
@@ -0,0 +1,67 @@
+# API Reference Documentation Architecture
+
+This document outlines how the API reference section works.
+
+```mermaid
+---
+config:
+  flowchart:
+    defaultRenderer: "elk"
+---
+flowchart TD
+    docs_json["docs.json"]
+    mdx_pages["api-reference/{category}/*.mdx"]
+    openapi["api-reference/openapi.json"]
+    workflow[".github/workflows/update-api-spec.yml"]
+    script["update-api-spec.sh"]
+
+    subgraph ci["Github Actions"]
+        workflow -->|"runs every 48h"| script
+    end
+
+    subgraph docs["Documentation Content"]
+        docs_json -->|"defines sidebar navigation that points to"| mdx_pages
+    mdx_pages -->|"points to endpoint and auto-generates documentation based on"| openapi
+    end
+    
+    ci -->|"pulls updated OpenAPI spec and formats it for Mintlify"| openapi
+```
+
+## Rendering the documentation content
+
+### `docs.json`
+
+Defines the navigational structure of the docs. The "API" section determines the sidebar navigation structure of the API reference. Each path points to an MDX page in `/api-reference`.
+
+### `api-reference/{category}/\*.mdx`
+
+Each page has an `openapi` attribute that points to an endpoint listed in `api-reference/openapi.json`. Mintlify auto-generates the documentation based on this information.
+
+### `api-reference/openapi.json`
+
+Contains a copy of the OpenAPI spec that all our API reference pages pull from. It's automatically updated every 48 hours by our [Github Actions](https://github.com/checkly/docs/actions/workflows/update-api-spec.yml) workflow.
+
+## Updating `api-reference/openapi.json` via Github Actions
+
+Checkly's public OpenAPI spec can be found here: https://api.checklyhq.com/openapi.json. We have a copy saved to `api-reference/openapi.json` that we update every 48 hours. This copy is formatted to play nicely with how Mintlify renders pages, and all our API reference pages use this file to auto-generate the API reference documentation.
+
+* `.github/workflows/update-api-spec.yml` runs the update script (`update-api-spec.sh`) every 48 hours and commits the changes to `main`. [View all recent runs.](https://github.com/checkly/docs/actions/workflows/update-api-spec.yml)
+
+* The update script (`update-api-spec.sh`) pulls the most recent OpenAPI spec, cleans it up for use with Mintlify, and applies those edits to `api-reference/openapi.json`.
+
+## Adding new endpoints
+
+If you need to add an endpoint to an API reference:
+
+1. Create the sidebar navigation item in `docs.json`
+2. Create a new file in `api-reference/{category}/\*.mdx`. That file should have an `openapi` attribute that references the corresponding endpoint. You can also define a custom title, if the OpenAPI spec doesn't have a nice one. For example:
+```md
+---
+openapi: get /v1/analytics/api-checks/{id}
+title: API checks
+---
+```
+
+If you need to update your local copy of the OpenAPI spec, run `./update-api-spec.sh`
+
+That's it! Your new endpoint should be showing properly now.
diff --git a/api-reference/accounts/fetch-a-given-account-details.mdx b/api-reference/accounts/fetch-a-given-account-details.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/accounts/{accountId}
+title: Get details for a specific account
 ---
diff --git a/api-reference/accounts/fetch-current-account-details.mdx b/api-reference/accounts/fetch-current-account-details.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/accounts/me
+title: Get details for the current account
 ---
diff --git a/api-reference/accounts/fetch-user-accounts.mdx b/api-reference/accounts/fetch-user-accounts.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/accounts
+title: Get details for all accounts
 ---
diff --git a/api-reference/analytics/api-checks.mdx b/api-reference/analytics/api-checks.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/analytics/api-checks/{id}
+title: API checks
 ---
diff --git a/api-reference/analytics/dns-monitors.mdx b/api-reference/analytics/dns-monitors.mdx
@@ -0,0 +1,4 @@
+---
+openapi: get /v1/analytics/dns/{id}
+title: DNS monitors
+---
diff --git a/api-reference/analytics/heartbeat-checks.mdx b/api-reference/analytics/heartbeat-checks.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/analytics/heartbeat-checks/{id}
+title: Heartbeat monitors
 ---
diff --git a/api-reference/analytics/tcp-checks.mdx b/api-reference/analytics/tcp-checks.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/analytics/tcp-checks/{id}
+title: TCP monitors
 ---
diff --git a/api-reference/analytics/url-monitors.mdx b/api-reference/analytics/url-monitors.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/analytics/url-monitors/{id}
+title: URL monitors
 ---
diff --git a/api-reference/badges/get-v1badgeschecks.mdx b/api-reference/badges/get-v1badgeschecks.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/badges/checks/{checkId}
+title: Get badge for a check
 ---
diff --git a/api-reference/badges/get-v1badgesgroups.mdx b/api-reference/badges/get-v1badgesgroups.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/badges/groups/{groupId}
+title: Get badge for a group
 ---
diff --git a/api-reference/checks/create-a-tcp-check.mdx b/api-reference/checks/create-a-tcp-check.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: post /v1/checks/tcp
+title: Create a TCP monitor
 ---
diff --git a/api-reference/checks/update-an-tcp-check.mdx b/api-reference/checks/update-an-tcp-check.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: put /v1/checks/tcp/{id}
+title: Update a TCP monitor
 ---
diff --git a/api-reference/client-certificates/creates-a-new-client-certificate.mdx b/api-reference/client-certificates/creates-a-new-client-certificate.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: post /v1/client-certificates
+title: Create a client certificate
 ---
diff --git a/api-reference/client-certificates/deletes-a-client-certificate.mdx b/api-reference/client-certificates/deletes-a-client-certificate.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: delete /v1/client-certificates/{id}
+title: Delete a client certificate
 ---
diff --git a/api-reference/client-certificates/lists-all-client-certificates.mdx b/api-reference/client-certificates/lists-all-client-certificates.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/client-certificates
+title: List all client certificates
 ---
diff --git a/api-reference/client-certificates/shows-one-client-certificate.mdx b/api-reference/client-certificates/shows-one-client-certificate.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/client-certificates/{id}
+title: Retrieve a client certificate
 ---
diff --git a/api-reference/environment-variables/create-an-environment-variable.mdx b/api-reference/environment-variables/create-an-environment-variable.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: post /v1/variables
+title: Create an environment variable
 ---
diff --git a/api-reference/error-groups/list-all-error-groups-for-a-specific-check.mdx b/api-reference/error-groups/list-all-error-groups-for-a-specific-check.mdx
@@ -0,0 +1,3 @@
+---
+openapi: get /v1/error-groups/checks/{checkId}
+---
diff --git a/api-reference/error-groups/retrieve-an-error-group.mdx b/api-reference/error-groups/retrieve-an-error-group.mdx
@@ -0,0 +1,3 @@
+---
+openapi: get /v1/error-groups/{id}
+---
diff --git a/api-reference/error-groups/update-an-error-group.mdx b/api-reference/error-groups/update-an-error-group.mdx
@@ -0,0 +1,4 @@
+---
+openapi: patch /v1/error-groups/{id}
+title: Update an error group
+---
diff --git a/api-reference/heartbeats/create-a-heartbeat-check.mdx b/api-reference/heartbeats/create-a-heartbeat-check.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: post /v1/checks/heartbeat
+title: Create a heartbeat monitor
 ---
diff --git a/api-reference/heartbeats/get-a-list-of-events-for-a-heartbeat.mdx b/api-reference/heartbeats/get-a-list-of-events-for-a-heartbeat.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/checks/heartbeats/{checkId}/events
+title: List all events for a heartbeat monitor
 ---
diff --git a/api-reference/heartbeats/get-a-specific-heartbeat-event.mdx b/api-reference/heartbeats/get-a-specific-heartbeat-event.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/checks/heartbeats/{checkId}/events/{id}
+title: List a specific event for a heartbeat monitor
 ---
diff --git a/api-reference/heartbeats/get-heartbeat-availability.mdx b/api-reference/heartbeats/get-heartbeat-availability.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/checks/heartbeats/{checkId}/availability
+title: Get heartbeat monitor availability
 ---
diff --git a/api-reference/heartbeats/update-a-heartbeat-check.mdx b/api-reference/heartbeats/update-a-heartbeat-check.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: put /v1/checks/heartbeat/{id}
+title: Update a heartbeat monitor
 ---
diff --git a/api-reference/monitors/create-a-dns-monitor.mdx b/api-reference/monitors/create-a-dns-monitor.mdx
@@ -0,0 +1,3 @@
+---
+openapi: post /v1/checks/dns
+---
diff --git a/api-reference/monitors/create-a-url-monitor.mdx b/api-reference/monitors/create-a-url-monitor.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: post /v1/checks/url
+title: Create a URL monitor
 ---
diff --git a/api-reference/monitors/update-a-dns-monitor.mdx b/api-reference/monitors/update-a-dns-monitor.mdx
@@ -0,0 +1,3 @@
+---
+openapi: put /v1/checks/dns/{id}
+---
diff --git a/api-reference/monitors/update-an-url-monitor.mdx b/api-reference/monitors/update-an-url-monitor.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: put /v1/checks/url/{id}
+title: Update a URL monitor
 ---
diff --git a/api-reference/openapi.json b/api-reference/openapi.json
diff --git a/api-reference/opentelemetry/post-accounts-metrics.mdx b/api-reference/opentelemetry/post-accounts-metrics.mdx
diff --git a/api-reference/overview.mdx b/api-reference/overview.mdx
@@ -0,0 +1,34 @@
+---
+title: 'Using the Checkly API'
+sidebarTitle: 'Overview'
+---
+
+The Checkly API enables you to manage your monitoring infrastructure, retrieve account information, and export analytics using HTTP requests.
+
+<Note>
+  For creating and updating resources, we recommend using the [Checkly CLI](/cli/overview) or another [Monitoring as Code](/learn/monitoring/monitoring-as-code/) option. Managing resources using the Checkly API is possible, but Monitoring as Code generally provides a better experience for this.
+</Note>
+
+## Authentication
+
+The Checkly Public API uses API keys to authenticate requests. You can get a API Key in your [user settings](https://app.checklyhq.com/settings/user/api-keys).
+
+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 the `Authorization` and `X-Checkly-Account` headers when using cURL:
+
+```bash Bash icon="square-terminal"
+curl -H "Authorization: Bearer [apiKey]" -H "X-Checkly-Account: [accountId]"
+```
+
+[More information about managing API keys](/admin/creating-api-key), including service API keys.
+
+## Rate Limits
+
+The Checkly Public API uses rate limits to help manage the sheer volume of requests we receive. The rate limit is characterized by allowing a maximum number of requests within a time interval.
+
+For most of our routes, that limit is **600 requests every 60 seconds**.
+
+However, we also have **routes with custom rate limits**. If the endpoint you are using has a custom rate limit, you will find that information in the documentation of that route.
diff --git a/api-reference/runtimes/lists-all-supported-runtimes.mdx b/api-reference/runtimes/lists-all-supported-runtimes.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/runtimes
+title: List all supported runtimes
 ---
diff --git a/api-reference/runtimes/shows-details-for-one-specific-runtime.mdx b/api-reference/runtimes/shows-details-for-one-specific-runtime.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/runtimes/{id}
+title: List details for a runtime
 ---
diff --git a/api-reference/snippets/create-a-snippet.mdx b/api-reference/snippets/create-a-snippet.mdx
@@ -0,0 +1,4 @@
+---
+openapi: post /v1/snippets
+title: Create a snippet
+---
diff --git a/api-reference/snippets/delete-a-snippet.mdx b/api-reference/snippets/delete-a-snippet.mdx
@@ -0,0 +1,4 @@
+---
+openapi: delete /v1/snippets/{id}
+title: Delete a snippet
+---
diff --git a/api-reference/snippets/list-all-snippets.mdx b/api-reference/snippets/list-all-snippets.mdx
@@ -0,0 +1,4 @@
+---
+openapi: get /v1/snippets
+title: List all snippets
+---
diff --git a/api-reference/snippets/retrieve-a-snippet.mdx b/api-reference/snippets/retrieve-a-snippet.mdx
@@ -0,0 +1,4 @@
+---
+openapi: get /v1/snippets/{id}
+title: Retrieve a snippet
+---
diff --git a/api-reference/snippets/update-a-snippet.mdx b/api-reference/snippets/update-a-snippet.mdx
@@ -0,0 +1,4 @@
+---
+openapi: put /v1/snippets/{id}
+title: Update a snippet
+---
diff --git a/api-reference/static-ips/lists-all-source-ips-for-check-runs-1.mdx b/api-reference/static-ips/lists-all-source-ips-for-check-runs-1.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/static-ips-by-region
+title: List IPs for check runs by region
 ---
diff --git a/api-reference/static-ips/lists-all-source-ips-for-check-runs-as-txt-file.mdx b/api-reference/static-ips/lists-all-source-ips-for-check-runs-as-txt-file.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/static-ips.txt
+title: List IPs for check runs as a TXT file
 ---
diff --git a/api-reference/static-ips/lists-all-source-ips-for-check-runs.mdx b/api-reference/static-ips/lists-all-source-ips-for-check-runs.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/static-ips
+title: List IPs for check runs
 ---
diff --git a/api-reference/static-ips/lists-all-source-ipv6s-for-check-runs-1.mdx b/api-reference/static-ips/lists-all-source-ipv6s-for-check-runs-1.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/static-ipv6s-by-region
+title: List IPv6s for check runs by region
 ---
diff --git a/api-reference/static-ips/lists-all-source-ipv6s-for-check-runs-as-a-txt-file.mdx b/api-reference/static-ips/lists-all-source-ipv6s-for-check-runs-as-a-txt-file.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/static-ipv6s.txt
+title: List IPv6s for check runs as a TXT file
 ---
diff --git a/api-reference/static-ips/lists-all-source-ipv6s-for-check-runs.mdx b/api-reference/static-ips/lists-all-source-ipv6s-for-check-runs.mdx
@@ -1,3 +1,4 @@
 ---
 openapi: get /v1/static-ipv6s
+title: List IPv6s for check runs
 ---
diff --git a/concepts/metrics.mdx b/concepts/metrics.mdx
@@ -428,5 +428,5 @@ These metrics are specific to heartbeat checks, which monitor the availability a
 ---
 
 <Note>
-For complete metric definitions and API response formats, see the [Analytics API Reference](/api-reference/analytics/metrics).
+For all available metrics see the [Analytics API Reference](/api-reference/analytics/list-all-available-reporting-metrics).
 </Note>
diff --git a/docs.json b/docs.json
diff --git a/index.mdx b/index.mdx
diff --git a/platform/reporting/analytics-api.mdx b/platform/reporting/analytics-api.mdx
diff --git a/update-api-spec.sh b/update-api-spec.sh
