Skip to main content

This version of GitHub Enterprise Server was discontinued on 2023-09-25. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise Server. For help with the upgrade, contact GitHub Enterprise support.

Getting started with the REST API

Learn how to use the GitHub REST API.

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.

Although some REST API operations are accessible without authentication, you must authenticate to GitHub CLI in order to use the 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.

Press alt+up to activate