Add redirects for legacy ReadMe /reference/* API links

[sbezludny]

Why

Every deep link into the old ReadMe.io API reference is a dead end today: developers.checklyhq.com/reference/<slug> 308s to docs.checklyhq.com/reference/<slug>, which 404s, and www.checklyhq.com/docs/reference/<slug> 404s in Mintlify because docs.json had no /reference/* redirects. These URLs are still emitted by search results, sent newsletters, OSS issue templates, and LLM answers.

What

• 182 explicit redirects /reference/<oldSlug> → /api-reference/<group>/<page>, generated from .github/reference-slug-map.json — a frozen snapshot of the ReadMe-era slug set (slug = lowercased OpenAPI operationId, joined to pages via their openapi: frontmatter). Do not regenerate from a newer spec; endpoints added after the ReadMe era never had /reference/ URLs. Generation: one-liner mapping each entry to {"source": "/reference/<oldSlug>", "destination": "/<newPath>"}.
• Manual entry /reference/authentication → /api-reference/overview#authentication.
• Catch-all /reference/:slug* → /api-reference/overview (last), covering slugs whose endpoints were removed since the ReadMe era. Mintlify resolves exact sources before wildcards, so it never shadows the explicit entries.
• New CI check .github/scripts/check_redirect_destinations.py wired into static-docs-checks.yml: mint broken-links never validates inbound-only redirect destinations, so a page rename/delete would silently dead-end them. The check runs on any docs change (.mdx or docs.json) — a rename PR is exactly the event it must catch.
• Content fixes: guides/developer-fixtures.mdx had four dead docs.checklyhq.com links with mangled slugs, now relative links guarded by the linter; guides/create-multiple-monitors.mdx sample output now matches its own code sample.
• Documented the legacy redirect scheme in API-DOCUMENTATION.md (including the warning for anyone adding a real /reference/* page).

Verification

• python3 -m json.tool docs.json — valid; 24 existing + 184 new = 208 redirects, zero duplicate sources (Mintlify's redirect map is last-write-wins, so dupes would be silently dropped)
• .github/scripts/check_redirect_destinations.py — all 184 destinations resolve to on-disk pages
• npx mint broken-links — no broken links found
• 14 sample destinations previously verified live (HTTP 200) on www.checklyhq.com

⚠️ Hard dependency — this alone does not fix developers.* links

developers.checklyhq.com/reference/* traffic dies at the docs.checklyhq.com Vercel shim (repo checkly/docs.checklyhq.com, archived 2026-01-05) before ever reaching Mintlify. These redirects immediately fix direct www.checklyhq.com/docs/reference/* hits, but the shim needs a /reference/:path* → https://www.checklyhq.com/docs/reference/:path* rule (unarchive the repo or change it in the Vercel dashboard) for the old links to fully resolve. Merged ≠ live for old bookmarks.

Post-deploy gate (blocking, manual)

• curl -L www.checklyhq.com/docs/reference/getv1checks → lands on the checks endpoint page (not overview)
• same with trailing slash /docs/reference/getv1checks/
• /docs/reference/authentication → overview#authentication
• /docs/reference/nonexistentslug123 → overview via catch-all (HTTP 200)

Follow-ups (separate tickets, out of this repo)

• Vercel shim /reference/:path* forwarding rule + stop serving stale Hugo HTML for /docs/<old-slug> (hard dependency above)
• Backend ReadmeController still mints developers.checklyhq.com?auth_token=<ReadMe SSO JWT> for the webapp navbar; API-keys page, mobile footer, and the multi-step "Authentication CRUD" template also link to dead URLs; scheduler-daemon has a dead readme.url config
• Marketing site: www.checklyhq.com/reference/* (no /docs prefix) 404s before Mintlify; homepage still links developers.checklyhq.com
• OSS repos' issue-template "API Reference" links
• Cross-check old-redirects.csv (checkly-marketing-website) against the 182 mapped slugs for removed-endpoint slugs worth explicit entries (incl. the old rate-limit page slug)

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
checkly-422f444a	🟢 Ready	View Preview	Jul 2, 2026, 4:35 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.