# API Versioning

- Use an explicit major API version.
- Prefer additive fields and events.
- Clients must tolerate unknown fields and events.
- Breaking changes require a new major version, fixtures, migration notes, and coordinated releases.
- Each release records minimum compatible client and server versions.
- `GET /api/v1/server/info` publishes `minimum_client_version` and
  `maximum_client_version`; clients must use these fields to detect an
  incompatible pairing before enabling authenticated controls.
- Permission values are shared through `contracts/v1/permissions.json`.
  They are ordered from least to most privileged: `everyone`, `subscriber`,
  `moderator`, and `broadcaster`.
- The normalized result of a compatibility check is described by
  `contracts/v1/version-negotiation.json`; an incompatible result includes a
  human-readable `reason` while a compatible result may omit it.