Versioning

The contract is versioned by its path; models are versioned separately; and a field the gateway does not know is an error, never a no-op, so a client that works today keeps working when a field becomes accepted.

• The path carries the version. /v1 is this contract. A change that adds a field, a header, a code, a route or a model is not a version change; a change that removes or renames one, or changes a meaning, is a new path version with a notice period Not decided yet.
• Models are versioned separately. A catalog id resolves to the current pinned version and moves with releases; a pinned id names one version and does not move. Retirement of a pinned id and its notice period are open Not decided yet.
• Unknown is an error, not a no-op. A field the gateway does not know is a 400 unknown_parameter; a known OpenAI field the gateway does not accept is a 400 unsupported_parameter. Acceptance only turns a 400 into a served request.
• Every response carries x-hips-request-id, on every version and every error.

The Docs section is versioned by date, not by number: every page carries an updated date and the changelog lists dated entries, newest first, each naming the pages changed.