APIBreak

GitHub

GitHub's REST API, read through its own OpenAPI description: what changed in six months

GitHub publishes its REST surface as an OpenAPI document in a public repository. What a diff between two commits of that document shows, what it does not, and how to run the same check on the endpoints you call.

Published 12 October 2026 · 6 min read

GitHub publishes the OpenAPI description of its REST API in a public repository, github/rest-api-description, with full commit history. That makes its contract diffable in a way a prose changelog is not. This article reports one six-month diff of that document, says plainly what the diff does and does not prove, and ends with a real check you can repeat. GitHub's documentation is quoted as read on 2026-10-08.

What GitHub promises about versions

GitHub's API versions page says the REST API is versioned and that each version is named for the date it was released. You choose one with the X-GitHub-Api-Version header. Requests without the header default to 2022-11-28, and two versions are supported today: 2026-03-10 and 2022-11-28. When a new version is released, the previous one is supported for at least 24 more months.

The same page lists what GitHub counts as a breaking change, and says it will give advance notice before releasing one:

  • Removing an entire operation
  • Removing or renaming a parameter or a response field
  • Adding a new required parameter, or making an optional one required
  • Changing the type of a parameter or response field
  • Removing enum values
  • Adding a new validation rule to an existing parameter
  • Changing authentication or authorization requirements

Additive changes are available in all supported versions: new operations, optional parameters, optional request headers, response fields, response headers and enum values. So a pinned header does not freeze what you receive.

Which document we measured

The repository holds several description files. One is api.github.com.json, and beside it sit one file per API version: api.github.com.2022-11-28.json and api.github.com.2026-03-10.json. Our measurement reads api.github.com.json at two commits:

  • Baseline: commit f31bdfd, 2026-03-26, 1,107 operations.
  • Current: commit 0029c0d, 2026-09-25, 1,224 operations.

Six months, counted

  • 142 operations added.
  • 25 operations removed. 1,107 plus 142 minus 25 is 1,224.
  • 7 operations newly marked deprecated.
  • 38 operations carry the deprecated flag in the current document. 31 of them already carried it at the baseline.
  • 1 request field became required, and 4 request fields were removed from one operation.

What was removed

The 25 removals are not scattered. They fall into four groups, each removed in a single commit:

  • 17 operations under /enterprises/{enterprise}/teams, removed 2026-09-23.
  • 3 operations on Dependabot repository access under /organizations/{org}, removed 2026-04-14.
  • 3 operations on issue field values under /repositories/{repository_id}, removed 2026-04-20.
  • 2 Copilot metrics operations, GET /orgs/{org}/copilot/metrics and its team variant, removed 2026-06-18.

We have not established why each group left the document: a rename, a move to another path, or a retirement. The diff answers a narrower question, and for a caller it is the useful one. If your code calls one of those 25 paths, the document that describes the API no longer describes your call.

What was newly deprecated

  • 6 GitHub Classroom read operations (under /classrooms and /assignments), flagged 2026-07-14.
  • GET /repos/{owner}/{repo}/dependency-graph/sbom, flagged 2026-08-26.

A deprecated flag is the cheapest moment to act. The operation still answers, and the flag is machine-readable, so a program can find it on the day it appears instead of a person finding it in a changelog later.

The smaller changes

Two changes are the kind GitHub's own list calls breaking, and neither removes an operation. DELETE /orgs/{org}/code-security/configurations/detach now requires selected_repository_ids. And PATCH /organizations/{org}/settings/billing/budgets/{budget_id} lost four request fields: budget_entity_name, budget_product_sku, budget_scope and budget_type. Changes this size are easy to miss by eye in a document with more than a thousand operations.

Run the check on your own endpoints

The full list is published free on the apibreak site at /changes/github, with a link to the commit behind every removal and deprecation. The page is built from snapshot data committed to our repository, not fetched when you load it. For your own integration, the totals matter less than the few operations you call. Declare them with a baseline date:

{
  "version": 1,
  "integrations": [
    {
      "vendor": "github",
      "baseline": "2026-03-26",
      "endpoints": [
        "GET /repos/{owner}/{repo}/issues",
        "POST /repos/{owner}/{repo}/pulls",
        "GET /repos/{owner}/{repo}/dependency-graph/sbom"
      ]
    }
  ]
}

We ran that manifest with apibreak check on 2026-10-08. The check reads the newest commit, which that day was 355db39 from 2026-10-07, so its window is twelve days longer than the snapshot above. The output, shortened:

1 deprecation, 1 advisory, 1 not compared. 3 endpoints checked,
40 additive changes not listed.

deprecation   GET /repos/{owner}/{repo}/dependency-graph/sbom
  marked deprecated since the baseline

advisory      GET /repos/{owner}/{repo}/issues
  response [].issue_field_values[].data_type may now return
           multi_select

not compared  GET /repos/{owner}/{repo}/issues
  response 4 fields (anyOf/oneOf unions), including
           [].labels[] and [].issue_field_values[].value

Three things are worth reading in that output:

  • No breaking finding on any of the three endpoints. POST /repos/{owner}/{repo}/pulls produced no listed finding.
  • The advisory is a new enum value on a response. That is additive drift, the kind GitHub says can arrive in any supported version.
  • Four response fields were not compared because they are anyOf or oneOf unions. The report lists them on every run instead of passing them silently.

The run exited 0, because by default only a breaking finding fails it. With --fail-on deprecation the same run exits 2, which is how a team turns a deprecation into a failed CI job while there is still time to act on it.

What the description does not carry

The document describes the REST surface. It does not describe the GraphQL API, and it cannot show a behavior change that leaves the schema untouched. GitHub also says to read the changelog of breaking changes for a new API version before you upgrade to it. A diff of the description is the contract channel, and the changelog is the narrative one. A team that calls GitHub from production wants both.

Check the endpoints you actually call

APIBreak reads the endpoints you declare, compares the vendor's own OpenAPI specification against the revision you pinned, and fails the build only when a change touches one of yours. It runs in your CI with no credentials and nothing uploaded, and the check is free.

Install the check · read a real report · what changed at each vendor

Keep reading