GitHub's REST API has an official, actively maintained OpenAPI spec at github/rest-api-description — the same description GitHub uses internally to validate API requests. You can point a generator at it and get a typed client in minutes. Before you do: GitHub already publishes Octokit, an official, well-maintained SDK family for JavaScript, Ruby, .NET, and more. This post is for the cases Octokit doesn't cover — a language Octokit doesn't ship, an internal wrapper with your own auth and retry logic, or feeding the spec to an agent framework.
Where the spec lives
| Fact | Value |
|---|---|
| Repo | github/rest-api-description |
| File | descriptions/api.github.com/api.github.com.yaml (or .json) |
| Spec version | OpenAPI 3.0.3, description version 1.1.4 |
| Size | ~9.9 MB (YAML) / ~13 MB (JSON) |
| License | MIT |
| Status | GitHub-maintained, "stable and generally available" per repo README |
The repo also ships dated snapshots (api.github.com.2026-03-10.yaml) and a fully dereferenced variant under descriptions/api.github.com/dereferenced/ for tools that handle $ref poorly. The bundled version (the one above) is what GitHub recommends by default.
How to fetch it
curl -sL -o github-openapi.yaml \
https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.yaml
Or clone the repo directly if you want the changelog and dated versions alongside it:
gh repo clone github/rest-api-description
The honest complication: it's genuinely huge
At roughly 9.9 MB of YAML (13 MB as JSON) covering the entire GitHub REST surface — repos, issues, Actions, Packages, billing, and more — this is one of the largest single-file OpenAPI specs in general circulation. A few practical effects:
- Editors and diff tools slow down opening it. Don't expect instant syntax highlighting in VS Code on the full bundled file.
- Local codegen runs take real time — expect minutes, not seconds, and give Node a bigger heap if a generator runs out of memory (
NODE_OPTIONS=--max-old-space-size=4096). - Most teams don't need the whole surface. GitHub doesn't ship a way to slice the spec by tag out of the box, so if you only need
reposandissues, you'll want to pre-filter with a tool likeopenapi-filterbefore generating, or generate everything and only import what you use.
The dereferenced variant avoids $ref-resolution bugs in weaker tooling but roughly doubles the file size again — worth testing both if your generator chokes on one.
Generate a TypeScript client locally
OpenAPI Generator's typescript-fetch template produces a full typed client:
npx @openapitools/openapi-generator-cli generate \
-i github-openapi.yaml \
-g typescript-fetch \
-o ./generated/github-client
For types only (paired with your own fetch wrapper), openapi-typescript is lighter and faster against a spec this size:
npx openapi-typescript github-openapi.yaml -o ./src/github-api.d.ts
Either way, run the spec through a validator first — see OpenAPI best practices for SDK-friendly specs for what "clean" looks like before you generate. The free OpenAPI validator catches structural issues before you spend the codegen time.
The hosted path
If you'd rather skip maintaining a codegen pipeline against a 13 MB spec, Sourced takes the same GitHub OpenAPI file and produces hosted docs, a TypeScript SDK preview, a Python SDK preview, and an llms.txt file in one pass — create hosted docs from your repo or paste the raw spec URL directly. Previews are free and unlimited, with up to two hosted noindex docs sites and one hosted MCP server, no credit card. It won't replace Octokit for a JS or Ruby app talking to GitHub — but it's a fast way to get a working client and browsable docs in a language Octokit doesn't cover, or to preview what a GitHub-shaped internal SDK would look like before you commit to maintaining one.
When to actually do this
- Learning the codegen pattern. GitHub's spec is real, public, and well-formed — a good target for practicing OpenAPI-to-SDK generation before you point a generator at your own company's spec.
- A language Octokit doesn't cover well. Octokit's official list is JS/TS, Ruby, .NET, Kotlin (community), and a few others — if you're in Rust or a niche language, a generated client fills the gap.
- Agent tooling. Feeding the GitHub OpenAPI spec into an MCP server generator gives an LLM agent typed tool calls against GitHub's API without hand-writing each function.
- Internal wrappers. Teams building an internal platform layer over GitHub's API sometimes want generated types without Octokit's opinions on retries, pagination helpers, or auth flow.
For anything else — a JS, TS, or Ruby app that just needs to talk to GitHub — use Octokit. It's official, it's maintained by GitHub, and it already handles pagination, rate limiting, and auth correctly.
FAQ
Does GitHub have an official OpenAPI spec?
Yes. github/rest-api-description is maintained by GitHub itself and used internally to validate API requests, not a community reverse-engineering effort. As of the 1.1.4 release the repo's README describes it as "stable and generally available."
Is the GitHub OpenAPI spec OpenAPI 3.0 or 3.1?
The descriptions/ folder (the one most tools want) is OpenAPI 3.0.3. GitHub also publishes a descriptions-next/ folder with a 3.1 version, but the README flags it as subject to breaking changes — use the 3.0 folder unless you specifically need 3.1 features.
Should I generate a client instead of using Octokit?
Not for typical JS, TS, Ruby, or .NET use — Octokit is official, actively maintained, and already handles GitHub-specific concerns like conditional requests and pagination. Generate a client when you need a language Octokit doesn't cover, an internal wrapper, or typed tool definitions for an agent.
Why is the GitHub OpenAPI file so large?
It describes the entire GitHub REST API — Actions, Packages, repos, issues, billing, and dozens of other resource groups — in one bundled file. GitHub also ships a dereferenced version with all $refs inlined, which is larger still but more compatible with simpler tooling.
Can Sourced generate docs and an SDK from the GitHub spec directly?
Yes — see "The hosted path" above for what it generates from the same spec. Previews are free and unlimited; paid plans start when you're ready to publish under your own package name and domain.
What's the fastest way to try this without installing anything?
Paste the spec URL into the OpenAPI validator first to confirm it parses cleanly, then start a free preview at sourced.sh/signup — no local generator install required.