docs(usage): update public API and MCP guides for v2

[sbezludny]

The public Usage API overview and MCP tool descriptions still teach V1 behavior. Make V2 the primary path and document the current filters, credits, measurements, projections, and pagination.

Add deprecation warnings and replacement links to all three V1 endpoint pages. Put V2 first in navigation and synchronize the usage OpenAPI definitions. Fix internal-link validation to recognize API pages generated from navigation while continuing to reject missing destinations.

Affected Components

• Docs
• Other: documentation validation tooling

Notes for the Reviewer

Companion backend PR: https://github.com/checkly/monorepo/pull/5000.

Publish the OpenAPI copy after the companion backend deprecation metadata is deployed. The scheduled schema refresh reads production and can otherwise propose removing the three V1 flags. The authored warnings remain visible independently of those flags.

Testing

• All six existing API navigation tests pass. This PR adds no tests.
• Full internal-link scan, OpenAPI validation, group-tag synchronization, frontmatter checks, legacy redirect checks, and sitemap consistency pass.
• The local Mintlify preview renders the V1 deprecation badge and warning, and its replacement link opens the generated V2 endpoint page.
• The usage query example validates against the exported backend contract. Unrelated API operations remain unchanged.

New Dependency Submission

Declare @mintlify/link-rot 3.0.803 directly for the link-check wrapper. This version already exists transitively through the pinned Mintlify CLI; the lockfile adds only the root dependency declaration. The wrapper uses the existing navigation resolver for generated destinations.

[mintlify]

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

Project	Status	Preview	Updated
checkly-422f444a	🟢 Ready	View Preview	Oct 16, 2026, 11:16 AM