Versioning
Path versioning and the deprecation policy
Path versioning
The stateful applicant lifecycle and integration endpoints are namespaced under /v1/. Breaking
changes to request/response shapes ship under a new path prefix (/v2/, ...); the previous
version keeps running during a published migration window.
What is a breaking change
Breaking (new version): removing or renaming a field, removing an endpoint, tightening a type, adding a newly-required request field, or changing an enum's meaning.
Non-breaking (shipped in place): adding a new optional request field, adding a new response
field, adding a new endpoint, adding a new enum value to an open set (for example a new
top_findings[].code or override_rules_fired id; clients must tolerate unknown codes, the
current set is in check-catalog.json), or relaxing a constraint.
Client guidance: parse defensively. Ignore unknown JSON fields rather than rejecting them, and treat unknown finding/rule codes and verdict values as forward-compatible additions.
Response version header
/v1/* responses carry an API-Version header identifying the served build. Use it for support
correlation; do not branch behaviour on it. GET /version returns the build version as JSON.
Deprecation
When an endpoint or version is deprecated, IDCanopy publishes the sunset date and notifies
integration contacts in advance. Deprecated surfaces remain operational until the sunset date.
The OpenAPI document marks deprecated operations with deprecated: true.