# Alpha public API versioning and deprecation policy

Alpha Governance Group PBC publishes a dated public HTTP contract for the operations described at `/openapi.json`.

## Version selection

The current public contract version is `2026-08-25`. Clients may send `X-Alpha-API-Version: 2026-08-25` on any operation in the public OpenAPI description. A client that omits the header receives the current stable contract. Every public API response includes `Alpha-API-Version` so an agent can record which contract produced the representation.

Authenticated services on `api.alpha.ac` use their own published versioned contracts. This document does not expand access to an authenticated operation.

## Compatible changes

Alpha may add optional fields, new enum values where the schema permits them, new operations, and new machine representations without creating a new public contract version. Agents should ignore fields they do not recognize and preserve the evidence, rights, freshness, and verification fields they do recognize.

## Breaking changes and retirement

Alpha will publish a new dated contract before making a breaking change. Affected operations receive at least 180 days of notice. During that period, responses include a `Deprecation` header, a `Sunset` header using the HTTP date form defined by RFC 8594, and a `Link` header pointing to the successor contract or migration guide. The OpenAPI operation is also marked `deprecated: true`.

Alpha does not emit deprecation or sunset headers for an active operation that has no scheduled retirement.

## Errors and limits

Documented failures use the shared `PublicError` schema. Public API responses expose `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`. A `429 Too Many Requests` response also includes `Retry-After` and a machine-readable resolution.

Questions about a contract or migration may be sent to `hello@alpha.ac`.