# Paz.ai Public API versioning and deprecation policy

The Paz.ai Public API uses major versions in the URL path. The current supported version is `/v1`.

## Compatible changes within v1

Paz may add optional request fields, response fields, endpoints, and clarifying validation detail within `/v1` when existing requests keep their meaning. Clients should ignore response fields they do not use.

## Breaking changes

A change that removes or renames an operation, changes required input, or changes the meaning of an existing response uses a new major version path rather than silently changing `/v1`.

## Deprecation and sunset process

When Paz schedules an operation for retirement, its OpenAPI operation is marked `deprecated: true`. The developer documentation then names the replacement, the affected version, and the sunset date. The operation remains available until that published date. The current contract has no deprecated operations.

## Client guidance

Read the current OpenAPI contract at https://www.paz.ai/openapi.json and monitor this policy before adopting a new major version. Questions can be sent to hello@paz.ai.