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

# API versioning and deprecation

> How Squasher versions public REST paths and signals a future deprecation or shutdown.

Squasher versions the public REST contract in the URL. Current public operations use the `/v1` prefix. The OpenAPI document at `https://api.squasher.ai/openapi.json` is the machine-readable source for current paths, parameters, authentication, response schemas, and operation risk.

## Compatibility policy

Squasher makes additive changes within a public API version when possible. Additive changes can include new endpoints, optional request fields, response fields, enum values, and documented error details. Clients must ignore response fields they do not use and must validate enum values before branching on them.

A change that removes a documented field, changes its meaning, makes an optional input required, or changes an existing operation in an incompatible way requires a new versioned path or a published migration period.

## Deprecation signals

When Squasher deprecates a public REST operation, its response will include a `Deprecation` header. When a shutdown date is known, the response will also include a `Sunset` header with the planned date. The operation description in OpenAPI and the related documentation page will identify the replacement path and migration steps.

Squasher will keep the deprecated operation available through the published migration period unless an immediate security or legal issue requires a faster change. A client should log `Deprecation` and `Sunset`, move to the documented replacement, and stop creating new integrations on the deprecated path.

## Error contract

Most JSON errors contain a stable `type`, `code`, and safe human-readable `message`. An error can also include the related `param`, a `doc_url`, and a numeric `retry_after` delay. Some specialized endpoints still return a legacy `error` field with optional `message` and `hint` fields. The shared OpenAPI error schema documents both forms during this migration, so clients must handle either documented envelope.

The API publishes `RateLimit-Limit` and `RateLimit-Policy` on responses. Rate-limited operations return HTTP `429` with `RateLimit` and `Retry-After`. Wait for the supplied interval before retrying. Use bounded exponential backoff when a request can be retried safely.