Merge branch 'main' into slack-app-updates

Author: tnolet

.github/reference-slug-map.json

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Verify every legacy /reference/* redirect in docs.json points at an on-disk page.
+
+These redirects (generated from .github/reference-slug-map.json, the frozen
+ReadMe-era slug set) are inbound-only: no docs page links to /reference/*, so
+`mint broken-links` never walks them and a page rename/delete would dead-end
+their destinations silently. This check closes that gap. It must run on any
+PR that touches .mdx files or docs.json — a rename PR is exactly the event
+it exists to catch.
+"""
+import json
+import pathlib
+import sys
+
+root = pathlib.Path(__file__).resolve().parents[2]
+docs = json.loads((root / "docs.json").read_text())
+
+pages = {
+    "/" + str(p.relative_to(root))[: -len(".mdx")]
+    for p in root.rglob("*.mdx")
+    if "node_modules" not in p.parts
+}
+
+broken = []
+for redirect in docs.get("redirects", []):
+    if not redirect["source"].startswith("/reference/"):
+        continue
+    destination = redirect["destination"].split("#")[0]
+    if destination not in pages:
+        broken.append(f"{redirect['source']} -> {redirect['destination']}")
+
+if broken:
+    print(f"{len(broken)} /reference/* redirect destination(s) have no matching .mdx page:")
+    print("\n".join(broken))
+    sys.exit(1)
+
+checked = sum(1 for r in docs.get("redirects", []) if r["source"].startswith("/reference/"))
+print(f"OK: {checked} /reference/* redirect destinations all resolve to on-disk pages")

.github/scripts/check_redirect_destinations.py

@@ -68,6 +68,13 @@ jobs:
         if: steps.detect.outputs.openapi_changed == 'true'
         run: npx mint openapi-check api-reference/openapi.json
 
+      # Legacy /reference/* redirects are inbound-only, so `mint broken-links`
+      # never validates their destinations. Runs on any docs change (.mdx or
+      # docs.json) because a page rename/delete is exactly what breaks them.
+      - name: Check legacy redirect destinations
+        if: steps.detect.outputs.docs_changed == 'true'
+        run: python3 .github/scripts/check_redirect_destinations.py
+
       - name: Broken-links scan
         if: steps.detect.outputs.docs_changed == 'true'
         run: |

.github/workflows/static-docs-checks.yml

@@ -54,10 +54,12 @@ jobs:
     - name: Generate pages for any new endpoints
       run: node .github/scripts/detect-new-endpoints.mjs
 
-    - name: Open auto-merging PR if anything changed
+    - name: Create or update API spec PR if anything changed
       env:
         GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       run: |
+        set -euo pipefail
+
         # Stage everything that might have changed
         git add api-reference docs.json
 
@@ -88,13 +90,13 @@ jobs:
           TITLE="chore(api): refresh API reference"
         fi
 
-        BRANCH="auto/update-api-spec-${{ github.run_id }}"
-        git checkout -b "$BRANCH"
+        BRANCH="auto/update-api-spec"
+        git checkout -B "$BRANCH"
 
         git commit -m "$TITLE" \
                    -m "Automatically fetched from https://api.checklyhq.com/openapi.json" \
                    -m "Updated on $(date -u '+%Y-%m-%d %H:%M:%S UTC')"
-        git push origin "$BRANCH"
+        git push --force-with-lease origin "$BRANCH"
 
         # Build PR body
         BODY_FILE=$(mktemp)
@@ -105,24 +107,42 @@ jobs:
           echo "- New endpoint pages: $NEW_PAGES"
           echo "- \`docs.json\` updated: $([ "$DOCS_JSON_CHANGED" = "1" ] && echo yes || echo no)"
           echo ""
-          echo "This PR will auto-merge once all required checks pass."
+          echo "This PR reuses the \`$BRANCH\` branch so future runs update this PR instead of opening duplicates."
           echo ""
           echo "---"
           echo "_Run: [${{ github.run_id }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})_"
         } > "$BODY_FILE"
 
-        PR_URL=$(gh pr create \
-          --title "$TITLE" \
-          --body-file "$BODY_FILE" \
+        PR_URL=$(gh pr list \
           --base main \
           --head "$BRANCH" \
-          --label auto-generated \
-          --label api-docs)
-        echo "Created $PR_URL"
+          --state open \
+          --json url \
+          --jq '.[0].url // ""')
+
+        if [ -n "$PR_URL" ]; then
+          gh pr edit "$PR_URL" \
+            --title "$TITLE" \
+            --body-file "$BODY_FILE" \
+            --add-label auto-generated \
+            --add-label api-docs
+          echo "Updated $PR_URL"
+        else
+          PR_URL=$(gh pr create \
+            --title "$TITLE" \
+            --body-file "$BODY_FILE" \
+            --base main \
+            --head "$BRANCH" \
+            --label auto-generated \
+            --label api-docs)
+          echo "Created $PR_URL"
+        fi
 
-        # Enable auto-merge; branch protection requires status checks to pass
-        # before the PR is actually merged.
-        gh pr merge "$PR_URL" --squash --auto --delete-branch
+        # Try to enable auto-merge, but do not create another PR if GitHub
+        # requires manual approval before pull_request workflows can run.
+        if ! gh pr merge "$PR_URL" --squash --auto --delete-branch; then
+          echo "::notice::Could not enable auto-merge for $PR_URL. The stable branch will be updated by the next run instead of opening another PR."
+        fi
 
     - name: Ping Checkly
       if: always()

.github/workflows/update-api-spec.yml

@@ -1 +1,2 @@
 api-reference-old/**/*.mdx
+skills/**

.mintignore

@@ -65,3 +65,11 @@ 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.
+
+## Legacy `/reference/*` redirects
+
+The pre-Mintlify API reference lived on ReadMe.io at `developers.checklyhq.com/reference/<slug>`, where `<slug>` was the lowercased OpenAPI `operationId` (e.g. `getv1checks`). To keep those old deep links alive, `docs.json` carries redirects generated from `.github/reference-slug-map.json` — a **frozen** snapshot of the ReadMe-era slug set. Don't regenerate it from a newer spec: endpoints added after the ReadMe era never had `/reference/` URLs.
+
+* One explicit redirect per historical slug maps to its endpoint page, so old bookmarks deep-link correctly.
+* A trailing catch-all `/reference/:slug*` → `/api-reference/overview` backstops slugs whose endpoints were removed after the ReadMe era. Mintlify resolves exact sources before wildcards, so the catch-all never shadows the explicit entries. **If you ever add a real docs page under `/reference/`, this catch-all will intercept it — narrow or remove it first.**
+* `mint broken-links` does **not** validate these destinations (nothing links to `/reference/*` in page content), so `.github/scripts/check_redirect_destinations.py` runs in the static-docs-checks workflow on every docs PR and fails if a page rename/delete breaks any of them.

API-DOCUMENTATION.md

@@ -16,11 +16,9 @@ The [llms.txt standard](https://llmstxt.org/) provides a machine-readable index
 - [Adding team members to your Checkly account](https://checklyhq.com/docs/admin/team-management/adding-team-members.md): Learn how to invite team members to join your Checkly account and manage team collaboration
 - [Using Microsoft Entra ID for Single Sign-on in Checkly](https://checklyhq.com/docs/admin/team-management/microsoft-azure-ad.md): This page illustrates the standard procedure to follow in order to get started with Microsoft Entra ID SSO (formerly Azure AD) on Checkly.
 - [Multi-Factor Authentication in Checkly](https://checklyhq.com/docs/admin/team-management/multi-factor-authentication.md): Learn how to set up and manage multi-factor authentication for enhanced account security
-- [Using Okta for Single Sign-on in Checkly](https://checklyhq.com/docs/admin/team-management/okta.md): This page illustrates the standard procedure to follow in order to get started with Okta SSO on Checkly.
-- [Role Based Access Control in Checkly](https://checklyhq.com/docs/admin/team-management/rbac.md): Checkly roles and permissions for team members
-- [Removing team members from your Checkly account](https://checklyhq.com/docs/admin/team-management/removing-team-members.md): Learn how to remove team members from your Checkly account and understand how it affects your billing
-- [Using SAML for Single Sign-On in Checkly](https://checklyhq.com/docs/admin/team-management/saml-sso.md): Learn how to set up SAML-based SSO for your Checkly account with supported identity providers
-- [Using SCIM provisioning in Checkly](https://checklyhq.com/docs/admin/team-management/scim-provisioning.md): Learn how to set up SCIM provisioning for Checkly using your identity provider
+- [Admin Overview](https://checklyhq.com/docs/admin/team-management/overview.md): Comprehensive guide to managing your Checkly account, team members, security, and integrations
+- [SAML for Single Sign-on in Checkly](https://checklyhq.com/docs/admin/team-management/saml.md): Learn how to configure SAML SSO integration with Checkly for your organization
+- [Single Sign-on in Checkly](https://checklyhq.com/docs/admin/team-management/single-sign-on.md): Overview of Single Sign-On (SSO) options available in Checkly for enterprise security
 - [Team management in Checkly](https://checklyhq.com/docs/admin/team-management.md): Manage your team and collaborate effectively in Checkly
 ```
 
@@ -38,4 +36,3 @@ curl https://checklyhq.com/docs/detect/synthetic-monitoring/browser-checks/overv
 
 - [Markdown Access](/ai/markdown-access)
 - [Checkly Skills](/ai/skills)
-- [Checkly Rules](/ai/rules)

ai/llms-txt.mdx

@@ -61,4 +61,3 @@ Based on this, how do I set up a browser check with a custom user agent?
 ## Additional resources
 
 - [Checkly Skills](/ai/skills)
-- [Checkly Rules](/ai/rules)

ai/markdown-access.mdx

@@ -0,0 +1,97 @@
+---
+title: 'Checkly MCP Server'
+description: 'Connect supported AI clients to Checkly to inspect checks, test sessions, RCA, result assets, status pages, incidents, and account context.'
+sidebarTitle: 'Overview'
+---
+
+The Checkly MCP Server lets supported AI clients connect to Checkly over Streamable HTTP and use Checkly tools from your conversation.
+
+Use the production MCP endpoint in your client:
+
+```text
+https://api.checklyhq.com/mcp
+```
+
+<Warning>
+The Checkly MCP Server only supports Checkly-approved OAuth clients listed in setup. Clients that use Dynamic Client Registration (DCR) are rejected. See [setup requirements](/ai/mcp-server/setup) for supported clients and details.
+</Warning>
+
+Use it when your agent needs live Checkly account context, check status, check results, test sessions, root cause analyses, result assets, status pages, incidents, account environment variables, or when it needs to trigger existing checks.
+
+<Note>
+Use [Checkly Skills](/ai/skills) and the [Checkly CLI](/cli/overview) when your agent needs to create, edit, test, bundle, or deploy check code. The MCP server runs remotely and cannot access your local filesystem.
+</Note>
+
+## What you can do
+
+- Inspect account membership, plan, and feature entitlements.
+- Check which checks are passing, failing, muted, or deactivated.
+- Read compact check results and test-session results.
+- Fetch normalized result asset manifests and bounded text assets.
+- Start or read Rocky AI root cause analyses.
+- Trigger existing deployed checks on demand.
+- Manage account-level environment variables and secrets.
+- Read status pages and manage status page incidents.
+
+## Quick start
+
+<Accordion title="Before you begin">
+Before connecting an MCP client, ensure you have:
+
+- A Checkly user account.
+- Access to the Checkly account you want the MCP client to use.
+- A [supported MCP client](/ai/mcp-server/setup#supported-clients).
+</Accordion>
+
+[Add the Checkly MCP endpoint to your client](/ai/mcp-server/setup), complete the OAuth flow, then ask your client to verify the connection:
+
+```text title="Prompt" wrap
+Use Checkly to show which accounts I can access.
+```
+
+If you belong to more than one Checkly account, tell your client which account to use in your prompt. To always use the same account, set the `X-Checkly-Account` header when your client supports custom MCP headers.
+
+See [Set up the MCP server](/ai/mcp-server/setup) for client configuration examples.
+
+## Example prompts
+
+Basic prompts:
+
+```text title="Prompt" wrap
+Show me the current status of my Checkly checks.
+```
+
+```text title="Prompt" wrap
+List open status page incidents.
+```
+
+```text title="Prompt" wrap
+What features are available on my current Checkly plan?
+```
+
+Advanced prompts:
+
+```text title="Prompt" wrap
+Investigate the latest failed result for the checkout API check. If there is an error group, check whether an RCA already exists before triggering a new one.
+```
+
+```text title="Prompt" wrap
+Trigger the checks tagged production-smoke, then follow the test session until results are available.
+```
+
+```text title="Prompt" wrap
+Create a major status page incident for the API outage, but do not notify subscribers until I confirm the message.
+```
+
+## MCP, Skills, and CLI
+
+MCP, Checkly Skills, and the Checkly CLI are complementary. Use the MCP Server for a quick, OAuth-based connection from a supported client. Use Checkly Skills with the CLI when your agent needs to create, edit, test, or deploy code from your local project.
+
+See [Skills, MCP, and the CLI](/ai/overview#skills-mcp-and-the-cli) for a full comparison of when to use each.
+
+## Learn more
+
+- [Set up the MCP server](/ai/mcp-server/setup)
+- [MCP tools reference](/ai/mcp-server/tools)
+- [Security and permissions](/ai/mcp-server/security-and-permissions)
+- [Troubleshooting](/ai/mcp-server/troubleshooting)

ai/mcp-server.mdx

@@ -0,0 +1,74 @@
+---
+title: 'MCP security and permissions'
+description: 'Understand how the Checkly MCP Server authenticates users, filters tools by permission, handles account context, and protects write actions.'
+sidebarTitle: 'Security & permissions'
+---
+
+The Checkly MCP Server uses OAuth and Checkly account authorization together. OAuth permissions decide which tools are visible to your MCP client. Checkly account membership, role, and feature entitlements decide whether a specific tool call can operate on an account.
+
+## Authentication
+
+The MCP Server accepts Auth0-issued bearer tokens for `https://api.checklyhq.com/mcp`. Your MCP client completes the OAuth flow and sends the token with requests to the MCP endpoint.
+
+The public MCP Server only supports OAuth clients that Checkly has approved in Auth0. Checkly rejects clients that attempt to use [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591). See [supported clients](/ai/mcp-server/setup#supported-clients) for setup details.
+
+Checkly maps the token subject to a Checkly user, then loads that user's account memberships and account context for tool calls.
+
+## OAuth permissions
+
+| Permission | Description |
+| --- | --- |
+| `checkly:account:read` | Read your Checkly account membership and status |
+| `checkly:account:invite` | Invite members to your Checkly account |
+| `checkly:checks:read` | List checks, their status and results |
+| `checkly:checks:run` | Trigger Checkly checks and on-demand test sessions |
+| `checkly:incidents:read` | Read your Checkly incidents |
+| `checkly:incidents:write` | Create and update your Checkly incidents |
+| `checkly:environment-variables:read` | Read your Checkly account environment variables (secret values excluded) |
+| `checkly:environment-variables:write` | Create, update and delete your Checkly account environment variables |
+| `checkly:status-pages:read` | Read your Checkly status pages |
+| `checkly:rca:read` | Read your Checkly root cause analyses |
+| `checkly:rca:run` | Run Checkly root cause analysis for your account |
+| `checkly:test-sessions:read` | Read your Checkly test sessions |
+| `checkly:assets:read` | Read your Checkly assets |
+
+Tools are filtered from `tools/list` when the MCP session does not include the required permission. Tool calls are also rejected if the session lacks the required permission.
+
+## Account context
+
+Most tools operate on one Checkly account. You can select a specific account in your prompt or pin an account in your MCP client configuration. See [Use a specific account](/ai/mcp-server/setup#use-a-specific-account) for setup examples.
+
+<Warning>
+Accounts that require mTLS are not available through the public MCP Server.
+</Warning>
+
+## Role checks
+
+Some tools require both an OAuth permission and a Checkly account role:
+
+| Tool or action | Additional account access required |
+| --- | --- |
+| `invite-account-member` | Owner or Admin |
+| `create-account-environment-variable` | Write access |
+| `update-account-environment-variable` | Write access |
+| `trigger-checks` | Run access |
+| `trigger-root-cause-analysis` | Run access |
+| Status page incident writes | Access required by the underlying incident action |
+
+## Write-action safety
+
+Some MCP tools create side effects:
+
+- `invite-account-member` sends an invite email and is not idempotent.
+- `trigger-checks` consumes check-run execution quota.
+- `trigger-root-cause-analysis` consumes RCA invocation quota.
+- `create-status-page-incident`, `update-status-page-incident`, and `resolve-status-page-incident` can notify subscribers and are not idempotent.
+- Environment variable write tools can create or replace account-level variables and secrets.
+
+Review write tool calls in your MCP client before approving them.
+
+## Secrets
+
+MCP read tools never reveal Checkly secret values. Secret values are returned as `null`.
+
+When you create or update a secret through MCP, Checkly encrypts the value and does not echo it back in the tool response.