About the GitHub REST API
This article describes how to use the GitHub REST API using GitHub CLI, JavaScript, or curl
. For a quickstart guide, see "Quickstart for GitHub REST API."
When you make a request to the REST API, you will specify an HTTP method and a path. Additionally, you might also specify request headers and path, query, or body parameters. The API will return the response status code, response headers, and potentially a response body.
The REST API reference documentation describes the HTTP method, path, and parameters for every operation. It also displays example requests and responses for each operation. For more information, see the REST reference documentation.
For more information about GitHub's APIs, see "Comparing GitHub's REST API and GraphQL API."
Making a request
To make a request, first find the HTTP method and the path for the operation that you want to use. For example, the "Get Octocat" operation uses the GET
method and the /octocat
path. For the full reference documentation for this operation, see "Meta."
Note: You must install GitHub CLI in order to use the commands in the GitHub CLI examples. For installation instructions, see the GitHub CLI repository.
If you are not already authenticated to GitHub CLI, you must use the gh auth login
subcommand to authenticate before making any requests. For more information, see "Authenticating."
To make a request using GitHub CLI, use the api
subcommand along with the path. Use the --method
or -X
flag to specify the method.
gh api /octocat --method GET
Continue reading to learn how to authenticate, send parameters, and use the response.
Authenticating
Many operations require authentication or return additional information if you are authenticated. Additionally, you can make more requests per hour when you are authenticated.
api
subcommand.About tokens
You can authenticate your request by adding a token.
If you want to use the GitHub REST API for personal use, you can create a personal access token. The REST API operations used in this article require repo
scope for personal access tokens. Other operations may require different scopes. For more information about creating a personal access token, see "Managing your personal access tokens."
If you want to use the API on behalf of an organization or another user, GitHub recommends that you use a GitHub App. If an operation is available to GitHub Apps, the REST reference documentation for that operation will say "Works with GitHub Apps." The REST API operations used in this article require issues
read and write permissions for GitHub Apps. Other operations may require different permissions. For more information, see "Registering a GitHub App", "About authentication with a GitHub App, and "Authenticating with a GitHub App on behalf of a user."
If you want to use the API in a GitHub Actions workflow, GitHub recommends that you authenticate with the built-in GITHUB_TOKEN
instead of creating a token. You can grant permissions to the GITHUB_TOKEN
with the permissions
key. For more information, see "Automatic token authentication."
For more information about best practices you can use to keep your tokens secure, see "Keeping your API credentials secure."
Authentication example
With GitHub CLI, you don't need to create an access token in advance. Use the auth login
subcommand to authenticate to GitHub CLI:
gh auth login
You can use the --scopes
flag to specify what scopes you want. If you want to authenticate with a token that you created, you can use the --with-token
flag. For more information, see the GitHub CLI auth login
documentation.
Authentication example for GitHub Actions
You can also use the run
keyword to execute GitHub CLI commands in your GitHub Actions workflows. For more information, see "Workflow syntax for GitHub Actions."
Instead of using the gh auth login
command, pass your token as an environment variable called GH_TOKEN
. GitHub recommends that you authenticate with the built-in GITHUB_TOKEN
instead of creating a token. If this is not possible, store your token as a secret and replace GITHUB_TOKEN
in the example below with the name of your secret. For more information about GITHUB_TOKEN
, see "Automatic token authentication." For more information about secrets, see "Using secrets in GitHub Actions."
jobs:
use_api:
runs-on: ubuntu-latest
permissions: {}
steps:
- env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh api /octocat
Using headers
Most operations specify that you should pass an Accept
header with a value of application/vnd.github+json
. Other operations may specify that you should send a different Accept
header or additional headers.
To send a header with GitHub CLI, use the --header
or -H
flag followed by the header in key: value
format.
gh api --header 'Accept: application/vnd.github+json' --method GET /octocat
Using path parameters
Path parameters modify the operation path. For example, the "List repository issues" path is /repos/{owner}/{repo}/issues
. The curly brackets {}
denote path parameters that you need to specify. In this case, you must specify the repository owner and name. For the reference documentation for this operation, see "Issues."
Note: In order for this command to work for your GitHub Enterprise Server instance, replace octocat/Spoon-Knife
with a repository owned by your GitHub Enterprise Server instance. Otherwise, rerun the gh auth login
command to authenticate to GitHub.com instead of your GitHub Enterprise Server instance.
To get issues from the octocat/Spoon-Knife
repository, replace {owner}
with octocat
and {repo}
with Spoon-Knife
.
gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues
The operation returns a list of issues and data about each issue. For more information about using the response, see the "Using the response" section.
Using query parameters
Query parameters allow you to control what data is returned for a request. For example, a query parameter may let you specify how many items are returned when the response is paginated.
By default, the "List repository issues" operation returns thirty issues, sorted in descending order by the date they were created. You can use the per_page
parameter to return two issues instead of 30. You can use the sort
parameter to sort the issues by the date they were last updated instead of by the date they were created. You can use the direction
parameter to sort the results in ascending order instead of descending order.
For GitHub CLI, use the -F
flag to pass a parameter that is a number, Boolean, or null. Use -f
to pass string parameters.
gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2 -f sort=updated -f direction=asc
Some operations use query parameters that are arrays. To send an array in the query string, use the query parameter once per array item, and append []
after the query parameter name. For example, to provide an array of two repository IDs, use -f repository_ids[]=REPOSITORY_A_ID -f repository_ids[]=REPOSITORY_B_ID
.
In order to use GitHub CLI with query parameters that are arrays, you must use GitHub CLI version 2.31.0 or greater. For upgrade instructions, see the GitHub CLI repository.
The operation returns a list of issues and data about each issue. For more information about using the response, see the "Using the response" section.
Using body parameters
Body parameters allow you to pass additional data to the API. For example, the "Create an issue" operation requires you to specify a title for the new issue. It also lets you specify other information, such as text to put in the issue body. For the full reference documentation for this operation, see "Issues."
The "Create an issue" operation uses the same path as the "List repository issues" operation in the examples above, but it uses a POST
method instead of a GET
method.
For GitHub CLI, use the -F
flag to pass a parameter that is a number, Boolean, or null. Use -f
to pass string parameters. If the parameter is an array, you must append []
to the parameter name.
In order to use GitHub CLI with body parameters that are arrays, you must use GitHub CLI version 2.21.0 or greater. For upgrade instructions, see the GitHub CLI repository.
gh api --header 'Accept: application/vnd.github+json' --method POST /repos/octocat/Spoon-Knife/issues -f title="Created with the REST API" -f body="This is a test issue created by the REST API" -f "labels[]=bug"
The operation creates an issue and returns data about the new issue. In the response, find the html_url
of your issue and navigate to your issue in the browser. For more information about using the response, see the "Using the response" section.
Using the response
About the response code and headers
Every request will return an HTTP status code that indicates the success of the response. For more information about response codes, see the MDN HTTP response status code documentation.
Additionally, the response will include headers that give more details about the response. Headers that start with X-
or x-
are custom to GitHub. For example, the x-ratelimit-remaining
and x-ratelimit-reset
headers tell you how many requests you can make in a time period.
To view the status code and headers, use the --include
or --i
flag when you send your request.
For example, this request:
gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2 --include
returns the response code and headers like:
HTTP/2.0 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
Cache-Control: private, max-age=60, s-maxage=60
Content-Security-Policy: default-src 'none'
Content-Type: application/json; charset=utf-8
Date: Thu, 04 Aug 2022 19:56:41 GMT
Etag: W/"a63dfbcfdb73621e9d2e89551edcf9856731ced534bd7f1e114a5da1f5f73418"
Link: <https://api.github.com/repositories/1300192/issues?per_page=1&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=1&page=14817>; rel="last"
Referrer-Policy: origin-when-cross-origin, strict-origin-when-cross-origin
Server: GitHub.com
Strict-Transport-Security: max-age=31536000; includeSubdomains; preload
Vary: Accept, Authorization, Cookie, X-GitHub-OTP, Accept-Encoding, Accept, X-Requested-With
X-Accepted-Oauth-Scopes: repo
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-Github-Api-Version-Selected: 2022-08-09
X-Github-Media-Type: github.v3; format=json
X-Github-Request-Id: 1C73:26D4:E2E500:1EF78F4:62EC2479
X-Oauth-Client-Id: 178c6fc778ccc68e1d6a
X-Oauth-Scopes: gist, read:org, repo, workflow
X-Ratelimit-Limit: 15000
X-Ratelimit-Remaining: 14996
X-Ratelimit-Reset: 1659645499
X-Ratelimit-Resource: core
X-Ratelimit-Used: 4
X-Xss-Protection: 0
In this example, the response code is 200
, which indicates a successful request.
About the response body
Many operations will return a response body. Unless otherwise specified, the response body is in JSON format. For example, this request returns a list of issues with data about each issue:
gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2
Unlike the GraphQL API where you specify what information you want, the REST API typically returns more information than you need. If desired, you can parse the response to pull out specific pieces of information.
For example, you can use >
to redirect the response to a file:
gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2 > data.json
Then you can use jq to get the title and author ID of each issue:
jq '.[] | {title: .title, authorID: .user.id}' data.json
The previous two commands return something like:
{
"title": "Update index.html",
"authorID": 10701255
}
{
"title": "Edit index file",
"authorID": 53709285
}
For more information about jq, see the jq documentation.
Next steps
This article demonstrated how to list and create issues in a repository. For more practice, try to comment on an issue, edit the title of an issue, or close an issue. For more information about these operations, see "Issues" and "Issues."
For more information about the operations that you can use, see the REST reference documentation.