API versioning policy¶

Applies to the public REST API (#46, ADR 0015). The version is in the path: /v1/...; every /v1 response has the X-API-Version: v1 header.

Stable within `/v1`¶

Paths, methods, input/output field names and types, the error format and codes from errors.md.

New endpoint, new optional input field, new response field, new error code, new rule in the catalog, new profile. Clients must ignore unknown response fields.
Changes to error message text and OpenAPI descriptions.

Removing/renaming a field or endpoint, type change, new required field, changing the meaning of a code, changing result semantics (e.g. the score scale).
Beta exception (#142): during the closed beta, resource ids changed from integers to opaque public ids (rep_…, prj_…, see Identifiers) in place, without /v2.
Rule versioning (ver) and prompt versioning (PROMPT_VER) are separate: they change results, not the contract. Reports include these versions, so clients can see what produced them.

A deprecated endpoint/version sends Deprecation (RFC 9745) and Sunset (RFC 8594) headers with the shutdown date, and Link: <…>; rel="deprecation" to the migration notes.
Support period: at least 6 months from the deprecation announcement to Sunset; /vN and /vN+1 run in parallel during that time.
Announcement: CHANGELOG (API section; separate docs/api/ changelog — ADR 0015, planned).