# XispeScore public API versioning and deprecation

Canonical policy: https://xispescore.vercel.app/developers/versioning

## Versioning

The public REST API uses major-version URL paths such as `/api/public/v1/...`. Backward-compatible additions may be made within the current major version. Breaking contract changes require a new major version path rather than silently changing an existing version.

The current `v1` API is not deprecated.

## Deprecation signals

Public REST responses include a `Link` header pointing to the canonical policy with `rel="deprecation"` so clients can discover this document. The policy link alone does not mean an endpoint is deprecated.

When a version or endpoint is actually deprecated, its response will include the RFC 9745 `Deprecation` response header with the effective date. If a retirement date is scheduled, the response will also include the RFC 8594 `Sunset` header. A Sunset date will not precede the deprecation date.

Migration guidance and replacement endpoints will be documented here, on the developer page, and in OpenAPI before retirement.

## Rate limits

Public API responses expose `RateLimit-Policy` and `RateLimit` fields. Compatibility fields `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` are also returned. The current default quota is 120 requests per 60-second window per observed client address.

When the quota is exceeded, the API responds with HTTP `429 Too Many Requests`, a typed JSON error, remaining quota of zero, and `Retry-After`. Clients should follow the live response headers rather than hard-coding the default quota.