REST API docs get a new layout and schema-driven examples
GitHub has overhauled its REST API documentation, moving from manually maintained pages to output generated directly from the OpenAPI schema. The update targets long-standing pain points: scattered parameters, generic example values, missing response schemas, and documentation pages that ballooned as the API grew.
Three-column layout for easier reference
Operations with large request bodies or responses previously forced heavy scrolling. The new three-column format groups parameters with example requests and responses side by side; smaller screens fall back to two columns. Example content sits in a sticky right-hand column so you can cross-check values against request parameters without losing your place. A dropdown and sub-navigation let you switch examples and languages, and your selected language becomes the default for future visits.
Examples now come from the schema
Example values for request body parameters previously used generic placeholders or parameter names as values, which made the docs confusing. All examples are now driven from the OpenAPI schema, with more meaningful data and a consistent format for future additions. The docs also include GitHub CLI examples directly, so you can see how to work with the REST API from the command line using the GitHub CLI.
Cleaner parameter tables and response schemas
The narrower column width forced a redesign of the parameter tables, and the move let GitHub generate more of the table from the OpenAPI definition. Enumerated values now appear with a "Can be one of" label below any default values. Response schemas, one of the most requested features, are now available for each operation: a toggle lets you switch between a sample response and the full schema, which shows required properties, nullable fields, and enumerated values.
Status code information is no longer buried inside examples. Each operation now shows its possible status codes in a dedicated, easy-to-scan table.
Reorganized navigation
The old documentation grouped operations into very long pages that didn't scale well. The REST API is now split into categories and subcategories in the sidebar, which removes the need for an on-page table of contents. Direct links to any operation still work, and the sidebar highlights the active operation's anchor as you scroll.
If you spot inaccuracies or unclear sections in the docs, GitHub asks you to open an issue in the public OpenAPI description repository. Feedback on the changes can be left in this discussion.
