A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The GitHub API is how an app or AI agent works with a GitHub account: reading and creating repositories, opening and merging pull requests, filing and updating issues, and triggering workflow runs. Access is granted through a token in an Authorization header and a set of permissions that decide what each call can read or write, and an agent is limited to the repositories and accounts that token reaches. The REST API is versioned by date, and GitHub can also push events to a webhook URL when something happens in a repository.
How an app or AI agent connects to GitHub determines what it can reach. There are several routes, each governed by the token or key behind it and the permissions that token carries.
The REST API answers at https://api.github.com. It defaults to version 2022-11-28 when no version header is sent, and its newest version is 2026-03-10.
The GraphQL API answers at https://api.github.com/graphql with a typed schema. It complements REST and does not fully overlap it.
Webhooks deliver the events that have been chosen to a receiver URL, and the X-Hub-Signature-256 header on each delivery confirms it came from GitHub.
GitHub's MCP server lets an agent call GitHub through the Model Context Protocol. The remote server at https://api.githubcopilot.com/mcp/ uses OAuth, while the local Docker image ghcr.io/github/github-mcp-server uses a personal access token. The source is at github.com/github/github-mcp-server.
A fine-grained personal access token grants granular per-resource permissions on chosen repositories, each set to read or write, and expires by default. It is the least-privilege choice for connecting to GitHub.
A classic personal access token uses coarse scopes, where the repo scope grants full read and write access to every repository the user can reach at once.
An OAuth app acts on behalf of a user with coarse scopes, which suits a quick user-login integration but gives less control than a GitHub App.
A GitHub App has its own identity, granular permissions, and per-repository installation, with higher rate limits and the ability to post check runs. GitHub recommends it for automation.
The GitHub API is split into areas an agent can act on, such as repositories, issues, pull requests, and workflows. Each area has its own methods and its own permissions, and some grant access to far more than others.
Read repository details, list an organization's repositories, create and update repositories, and list repository activity.
List, read, create, and update issues, and list and create their comments.
List, read, create, update, and merge pull requests, and list and create reviews on them.
List and read workflows and their runs, trigger a workflow, and re-run a workflow run.
List commits in a repository and read a single commit by SHA, branch, or tag.
List branches in a repository and read a single branch.
List releases, read the latest published release, and create a release.
Read the authenticated user's profile and read a user's public profile by username.
List the authenticated user's organizations, read an organization's details, and update its settings.
Work with the teams inside an organization.
List a repository's webhooks and create a new one.
Search repositories, issues and pull requests, file contents, and users.
List the authenticated user's gists, read a single gist, and create one.
Create a check run on a commit and read a single check run.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
RepositoriesRead repository details, list an organization's repositories, create and update repositories, and list repository activity.5 | ||||||
| GET | /repos/{owner}/{repo} | Get a repository's details. | read | Metadata: read | Current | |
Metadata read is the baseline permission for nearly all repository endpoints. Classic OAuth scope: repo (public_repo for public repos). Acts onrepository Permission (capability) Metadata: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /orgs/{org}/repos | List repositories owned by an organization. | read | Metadata: read | Current | |
Public repositories return without a token; private ones need access. Classic OAuth scope: repo. Acts onrepository Permission (capability) Metadata: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /orgs/{org}/repos | Create a repository in an organization. | write | Administration: write | Current | |
Creating a repository needs Administration write, not just Contents. Classic OAuth scope: repo. Acts onrepository Permission (capability) Administration: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /repos/{owner}/{repo} | Update a repository's settings. | write | Administration: write | Current | |
Classic OAuth scope: repo. Acts onrepository Permission (capability) Administration: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/activity | List repository activities (pushes, force-pushes, merges, branch changes). | read | Contents: read | Current | |
Classic OAuth scope: repo. Acts onrepository Permission (capability) Contents: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
IssuesList, read, create, and update issues, and list and create their comments.6 | ||||||
| GET | /repos/{owner}/{repo}/issues | List issues in a repository (excludes pull requests by default behavior of the issues UI, but PRs appear in this endpoint). | read | Issues: read | Current | |
Pull requests are returned here too, and can be filtered on the pull_request key. Classic OAuth scope: repo. Acts onissue Permission (capability) Issues: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/issues/{issue_number} | Get a single issue. | read | Issues: read | Current | |
Classic OAuth scope: repo. Acts onissue Permission (capability) Issues: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/issues | Create an issue. | write | Issues: write | Current | |
Subject to the secondary rate limits on content creation. Classic OAuth scope: repo (or public_repo). Acts onissue Permission (capability) Issues: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /repos/{owner}/{repo}/issues/{issue_number} | Update an issue (title, body, state, labels, assignees). | write | Issues: write | Current | |
Closing and reopening use the state field here. Classic OAuth scope: repo. Acts onissue Permission (capability) Issues: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/issues/{issue_number}/comments | List comments on an issue or pull request. | read | Issues: read | Current | |
The same endpoint serves pull request conversation comments. Classic OAuth scope: repo. Acts onissue Permission (capability) Issues: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/issues/{issue_number}/comments | Create a comment on an issue or pull request. | write | Issues: write | Current | |
Subject to the secondary rate limits on content creation. Classic OAuth scope: repo (or public_repo). Acts onissue Permission (capability) Issues: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Pull requestsList, read, create, update, and merge pull requests, and list and create reviews on them.7 | ||||||
| GET | /repos/{owner}/{repo}/pulls | List pull requests. | read | Pull requests: read | Current | |
Classic OAuth scope: repo. Acts onpull request Permission (capability) Pull requests: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/pulls/{pull_number} | Get a single pull request. | read | Pull requests: read | Current | |
Classic OAuth scope: repo. Acts onpull request Permission (capability) Pull requests: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/pulls | Create a pull request. | write | Pull requests: write | Current | |
Classic OAuth scope: repo (or public_repo). Acts onpull request Permission (capability) Pull requests: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /repos/{owner}/{repo}/pulls/{pull_number} | Update a pull request (title, body, state, base branch). | write | Pull requests: write | Current | |
Classic OAuth scope: repo. Acts onpull request Permission (capability) Pull requests: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /repos/{owner}/{repo}/pulls/{pull_number}/merge | Merge a pull request. | write | Contents: write | Current | |
Merging needs Contents write, because it commits to the base branch. Classic OAuth scope: repo. Acts onpull request Permission (capability) Contents: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/pulls/{pull_number}/reviews | List reviews for a pull request. | read | Pull requests: read | Current | |
Classic OAuth scope: repo. Acts onpull request Permission (capability) Pull requests: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/pulls/{pull_number}/reviews | Create a review (approve, request changes, or comment) on a pull request. | write | Pull requests: write | Current | |
Classic OAuth scope: repo. Acts onpull request Permission (capability) Pull requests: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Actions & workflowsList and read workflows and their runs, trigger a workflow, and re-run a workflow run.6 | ||||||
| GET | /repos/{owner}/{repo}/actions/workflows | List the workflows defined in a repository. | read | Actions: read | Current | |
Classic OAuth scope: repo. Acts onworkflow Permission (capability) Actions: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/actions/workflows/{workflow_id} | Get a single workflow. | read | Actions: read | Current | |
Classic OAuth scope: repo. Acts onworkflow Permission (capability) Actions: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches | Trigger a workflow run via a workflow_dispatch event. | write | Actions: write | Current | |
The workflow must declare on: workflow_dispatch. Under 2026-03-10 this returns 200 with run details, where it once returned 204. Classic OAuth scope: repo (workflow scope to change workflow files). Acts onworkflow Permission (capability) Actions: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/actions/runs | List workflow runs for a repository. | read | Actions: read | Current | |
Classic OAuth scope: repo. Acts onworkflow Permission (capability) Actions: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/actions/runs/{run_id} | Get a single workflow run. | read | Actions: read | Current | |
Classic OAuth scope: repo. Acts onworkflow Permission (capability) Actions: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/actions/runs/{run_id}/rerun | Re-run a workflow run. | write | Actions: write | Current | |
Classic OAuth scope: repo. Acts onworkflow Permission (capability) Actions: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Commits & git dataList commits in a repository and read a single commit by SHA, branch, or tag.2 | ||||||
| GET | /repos/{owner}/{repo}/commits | List commits on a repository. | read | Contents: read | Current | |
Classic OAuth scope: repo. Acts oncommit Permission (capability) Contents: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/commits/{ref} | Get a single commit by SHA, branch, or tag. | read | Contents: read | Current | |
Classic OAuth scope: repo. Acts oncommit Permission (capability) Contents: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BranchesList branches in a repository and read a single branch.2 | ||||||
| GET | /repos/{owner}/{repo}/branches | List branches in a repository. | read | Contents: read | Current | |
Classic OAuth scope: repo. Acts onbranch Permission (capability) Contents: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/branches/{branch} | Get a single branch. | read | Contents: read | Current | |
Classic OAuth scope: repo. Acts onbranch Permission (capability) Contents: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ReleasesList releases, read the latest published release, and create a release.3 | ||||||
| GET | /repos/{owner}/{repo}/releases | List releases. | read | Contents: read | Current | |
Classic OAuth scope: repo. Acts onrelease Permission (capability) Contents: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/releases/latest | Get the latest published full release. | read | Contents: read | Current | |
Excludes drafts and prereleases. Classic OAuth scope: repo. Acts onrelease Permission (capability) Contents: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/releases | Create a release. | write | Contents: write | Current | |
Classic OAuth scope: repo. Acts onrelease Permission (capability) Contents: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersRead the authenticated user's profile and read a user's public profile by username.2 | ||||||
| GET | /user | Get the profile of the authenticated user. | read | — | Current | |
Email is returned only with the user:email or user scope. Classic OAuth scope: none for public fields, user for private email or profile fields. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /users/{username} | Get a user's public profile by username. | read | — | Current | |
Works without a token, subject to the 60-per-hour IP limit. A classic OAuth token needs no special scope. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrganizationsList the authenticated user's organizations, read an organization's details, and update its settings.3 | ||||||
| GET | /user/orgs | List organizations the authenticated user belongs to. | read | Members: read | Current | |
Classic OAuth scope: read:org (or user) for full membership. Acts onorganization Permission (capability) Members: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /orgs/{org} | Get an organization's details. | read | Org metadata: read | Current | |
Classic OAuth scope: none for public fields, read:org for full. Acts onorganization Permission (capability) Org metadata: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /orgs/{org} | Update an organization's settings. | write | Org administration: write | Current | |
Classic OAuth scope: admin:org. Acts onorganization Permission (capability) Org administration: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList a repository's webhooks and create a new one.2 | ||||||
| GET | /repos/{owner}/{repo}/hooks | List a repository's webhooks. | read | Webhooks: read | Current | |
Classic OAuth scope: read:repo_hook or repo. Acts onwebhook Permission (capability) Webhooks: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /repos/{owner}/{repo}/hooks | Create a repository webhook. | write | Webhooks: write | Current | |
Classic OAuth scope: write:repo_hook or repo. Acts onwebhook Permission (capability) Webhooks: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SearchSearch repositories, issues and pull requests, file contents, and users.4 | ||||||
| GET | /search/repositories | Search for repositories. | read | — | Current | |
Search has its own limit: 30 requests per minute authenticated, 10 per minute without a token. A classic OAuth token needs no special scope. Acts onsearch result Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /search/issues | Search issues and pull requests. | read | — | Current | |
Subject to the authenticated search limit of 30 requests per minute. A classic OAuth token needs no special scope. Acts onsearch result Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /search/code | Search file contents across repositories. | read | Contents: read | Current | |
Stricter limit of about 10 requests per minute, and a token is required. Classic OAuth scope: repo for private code. Acts onsearch result Permission (capability) Contents: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /search/users | Search for users. | read | — | Current | |
Subject to the authenticated search limit of 30 requests per minute. A classic OAuth token needs no special scope. Acts onsearch result Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GistsList the authenticated user's gists, read a single gist, and create one.3 | ||||||
| GET | /gists | List the authenticated user's gists. | read | Gists: read | Current | |
Classic OAuth scope: gist (for private gists). Acts ongist Permission (capability) Gists: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /gists/{gist_id} | Get a single gist. | read | Gists: read | Current | |
Classic OAuth scope: none for public, gist for private. Acts ongist Permission (capability) Gists: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /gists | Create a gist. | write | Gists: write | Current | |
Classic OAuth scope: gist. Acts ongist Permission (capability) Gists: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ChecksCreate a check run on a commit and read a single check run.2 | ||||||
| POST | /repos/{owner}/{repo}/check-runs | Create a check run on a commit. | write | Checks: write | Current | |
Writing checks is restricted to GitHub Apps; OAuth and personal access tokens can only read. Acts oncheck run Permission (capability) Checks: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /repos/{owner}/{repo}/check-runs/{check_run_id} | Get a single check run. | read | Checks: read | Current | |
Classic OAuth scope: repo. Acts oncheck run Permission (capability) Checks: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GitHub can notify an app or AI agent when something happens in a repository, instead of the app repeatedly asking. GitHub posts the event payload to a webhook URL that has been registered for the chosen events.
| Event | What it signals | Triggered by |
|---|---|---|
push | Fires when one or more commits are pushed, or a tag or branch is created or deleted, on a repository branch. | In-app only |
pull_request | Fires on activity on a pull request, such as opened, closed, reopened, synchronize for new commits, ready_for_review, labeled, or assigned. | In-app only |
issues | Fires on activity on an issue, such as opened, edited, closed, reopened, assigned, labeled, or milestoned. | In-app only |
issue_comment | Fires when a comment is created, edited, or deleted on an issue or a pull request. | In-app only |
release | Fires when a release is published, unpublished, created, edited, deleted, or prereleased. | In-app only |
workflow_run | Fires when a GitHub Actions workflow run is requested, in_progress, or completed, whatever its conclusion. | In-app only |
workflow_job | Fires when a job in a workflow run is queued, in_progress, or completed. | In-app only |
check_run | Fires when a check run is created, rerequested, completed, or marked requested_action. | In-app only |
check_suite | Fires when a check suite is completed, requested, or rerequested, grouping all the check runs for a commit. | In-app only |
create | Fires when a Git branch or tag is created. | In-app only |
delete | Fires when a Git branch or tag is deleted. | In-app only |
pull_request_review | Fires when a pull request review is submitted, edited, or dismissed. | In-app only |
GitHub limits how fast and how much an app or AI agent can call, through an hourly request quota that depends on how the call is authenticated and a separate set of anti-abuse limits on top.
GitHub sets a primary limit on requests per hour, decided by how the call is authenticated. Requests without a token get 60 per hour per IP address; an authenticated user, a personal access token, or a standard OAuth app gets 5,000 per hour; an OAuth app owned or approved by a GitHub Enterprise Cloud organization gets 15,000 per hour for a member calling it; and a GitHub App installation token starts at 5,000 per hour, scaling with repositories and users up to 12,500, and reaching 15,000 on Enterprise Cloud. Separate secondary, anti-abuse limits apply on top of the primary quota: at most 100 concurrent requests, around 900 points per minute per endpoint, caps on CPU time, and content creation held to roughly 80 per minute and 500 per hour. Search has its own limit of 30 requests per minute when authenticated and 10 per minute when not, with code search around 10 per minute. The response headers x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-used, x-ratelimit-reset, and x-ratelimit-resource report the current state, and exceeding a limit returns 403 or 429 with x-ratelimit-remaining at 0.
List endpoints use offset pagination through the page parameter, which is 1-based, and the per_page parameter, which tops out at 100 and defaults to about 30. Each response carries a Link header with the relations next, prev, first, and last where they apply, and the next link should be followed rather than building the URL by hand. Some endpoints, including parts of search and a few list endpoints, use cursor-based pagination instead.
Requests and responses are standard JSON. Search returns at most 1,000 results per query, and list endpoints cap per_page at 100. There is no single documented payload size limit across the whole API, though individual endpoints such as file contents set their own size ceilings.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 304 | Not Modified | Returned for a conditional request, made with If-None-Match or If-Modified-Since, when the resource has not changed. A 304 does not count against the primary rate limit. | Treat the cached copy as current and skip refetching it. |
| 401 | Unauthorized | Authentication is missing, or the credentials are invalid or expired. | Check the token and the Authorization header, then send valid credentials. |
| 403 | Forbidden | The request is authenticated but not permitted. Most often this is a primary or secondary rate-limit hit, shown by x-ratelimit-remaining at 0 or a retry-after header, or the token lacks the required permission or scope. | Wait for the reset when it is a rate limit, or grant the missing permission or scope when it is not. |
| 404 | Not Found | The resource does not exist, or the token cannot see a private resource. GitHub returns 404 rather than 403 on purpose, so that it does not confirm a private repository exists. | Confirm the path is correct and the token has access to the resource. |
| 409 | Conflict | The request conflicts with the current state, such as merging when the pull request is not mergeable or its SHA is stale, or acting on an empty repository. | Refetch the current state, then retry once the conflict is resolved. |
| 422 | Unprocessable Entity | Validation failed: the request was well-formed but a field is missing, invalid, or already exists. The body holds an errors array with codes such as missing_field, invalid, and already_exists. | Read the errors array, correct the named field, and resend. |
| 429 | Too Many Requests | A rate limit was exceeded. GitHub may return 403 or 429 for a primary-limit hit and for secondary limits. | Honor the retry-after header in seconds, or the x-ratelimit-reset time, before retrying. |
GitHub versions its REST API by date through the X-GitHub-Api-Version header. The newest version is 2026-03-10, and 2022-11-28 stays the default that GitHub uses when no version header is sent.
The 2026-03-10 version is the first dated version to carry breaking changes. It is opted into through the X-GitHub-Api-Version header, and omitting that header still defaults to 2022-11-28. Breaking changes ship only in a new dated version, each supported for at least 24 months after its successor launches, with Deprecation and Sunset warning headers and a 410 Gone after end of support. It was released on Tuesday 10 March 2026.
The 2022-11-28 version was the first dated version, and it froze the then-current API exactly as it was, so no existing integration had to change. It remains the default when no X-GitHub-Api-Version header is sent, and is supported through at least 10 March 2028, which is 24 months after the 2026-03-10 release. It was released on Monday 28 November 2022.
An integration can pin a version and move up on a schedule that suits it.
GitHub API changelog ↗Bollard AI sits between a team's AI agents and GitHub. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.