> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning and compatibility

> Understand REST versions, additive changes, deprecations, and OpenAPI pinning.

The REST major version is part of the path: `/v1`. A new
major version is required for changes that would make a correct v1 client
interpret a response incorrectly or construct an invalid request.

## Compatible v1 changes

Qoory may add operations, optional request fields, response fields, enum values,
or new entity variants within v1. Clients should ignore unknown object fields
and include a fallback for unknown enum values.

Qoory does not silently change a field's meaning, unit, or identity semantics
within v1. Required-field removal, incompatible type changes, and renamed paths
require a versioned migration.

## Deprecation process

When an operation or field is deprecated, the reference and changelog identify
the replacement and target removal window. Security or data-rights issues can
require a faster restriction; Qoory favors returning an unavailable field over
substituting data with different semantics.

## Contract pinning

Generate client types from the OpenAPI snapshot used by your release, and check
a newer snapshot in CI before adopting it. Do not scrape rendered HTML or infer
schemas from one example response.