Versioning

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, 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.

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.