API versioning strategy inconsistency

How to fix

1. Move the route under the expected versioned path.
2. Update OpenAPI paths to match implementation.
3. Document any intentionally unversioned internal endpoint.

What the rule validates

An endpoint appears outside the expected versioned API surface or mixes versioning conventions.

Why it matters

Versioning consistency keeps compatibility and deprecation behavior understandable.

Common causes

• A route was mounted without the /v1 prefix.
• Contract generation includes mixed version paths.
• A new API surface skipped the style decision.

Typical violation example

Most routes use /api/v1, but a new public endpoint is exposed under /api/reports.

Typical compliant example

Public endpoints follow /api/v1 unless an ADR documents a different strategy.

Related rules

Adjacent categories

Related files/config

• contracts/openapi.yaml
• apps/api/src

Related CLI commands

• archpilot validate
• archpilot validate --ci