Versioning comes to GitHub’s REST API

GitHub’s REST API has been stable for more than a decade under its “V3” banner, but that stability came with a constraint: the platform couldn’t make breaking changes without forcing every integrator to scramble. Add a new endpoint or response field? Fine. Delete a field, make a parameter required, or remove an endpoint? There was no clean path that let existing users migrate on their own schedule.

To fix that, GitHub is introducing calendar-based versioning for the REST API. The scheme applies only to REST—the GraphQL API and webhooks are not affected. Under the new model, breaking changes ship as part of a dated version, while non-breaking changes continue to roll out across all versions.

How the versioning model works

Each new version is named after its release date. A version released on December 25, 2025, for example, would be called 2025-12-25.

Old versions are not retired when a new one ships. Integrators choose which version to use per request by setting the X-GitHub-Api-Version header. The documentation includes a version picker so developers can view docs for the specific API version they’re targeting.

Breaking changes are the only trigger for a new version release. GitHub’s documentation defines what counts as breaking versus non-breaking. Non-breaking additions remain available to all versions. New integrations are encouraged to use the latest version, and existing integrators are nudged to keep up to date—but there’s no forced upgrade.

Retirement timeline

Once a new REST API version is released, GitHub commits to supporting the previous version for at least 24 months. After that window, GitHub reserves the right to retire a version, though it expects to support historic versions well beyond the minimum. Any decision to end support for an old version will be announced on the GitHub blog and communicated by email.

What existing integrators need to know

The current state of the REST API—exactly what developers are already using—has been designated as version 2022-11-28. That version is identical to the pre-versioning API, so no integration changes are required to keep working.

That said, GitHub recommends that integrators start sending the X-GitHub-Api-Version: 2022-11-28 header now. This is purely preparatory: since 2022-11-28 matches the current API, sending the header won’t alter behavior.

A future dated version, containing breaking changes, is expected within the next few months. Moving to it will require updating the header to the new version and validating that the integration handles the changes in that release. GitHub says a full changelog and upgrade instructions will accompany that release.

What happens at each release

Whenever a new API version ships, GitHub will:

  • Post an update to the GitHub Changelog.
  • Publish documentation, change details, and an upgrade guide in the GitHub REST API docs.
  • Email active GitHub.com developers about the new release.
  • Detail the API changes in the release notes for GitHub Enterprise Server and GitHub AE.

Additionally, GitHub plans to roll out tools that let organization and enterprise administrators track which integrations are using which API versions, simplifying upgrade management across an organization.

For now, the immediate action item for anyone with a REST API integration is to start sending the X-GitHub-Api-Version header with the 2022-11-28 value. That header will become the mechanism for opting into future versions as they appear.