This article describes how to use the GitHub REST API with GitHub CLI,
curl
, or JavaScript. For a quickstart guide, see "
Quickstart for GitHub REST API
."
This section describes the elements that make up an API request:
Every request to the REST API includes an HTTP method and a path. Depending on the REST API endpoint, you might also need to specify request headers, authentication information, query parameters, or body parameters.
The REST API reference documentation describes the HTTP method, path, and parameters for every endpoint. It also displays example requests and responses for each endpoint. For more information, see the
REST reference documentation
.
The HTTP method of an endpoint defines the type of action it performs on a given resource. Some common HTTP methods are
GET
,
POST
,
DELETE
, and
PATCH
. The REST API reference documentation provides the HTTP method for every endpoint.
For example, the HTTP method for the
"List repository issues" endpoint
is
GET
."
Where possible, the GitHub REST API strives to use an appropriate HTTP method for each action.
GET
: Used for retrieving resources.
POST
: Used for creating resources.
PATCH
: Used for updating properties of resources.
PUT
: Used for replacing resources or collections of resources.
DELETE
: Used for deleting resources.
Each endpoint has a path. The REST API reference documentation gives the path for every endpoint. For example, the path for the
"List repository issues" endpoint
is
/repos/{owner}/{repo}/issues
.
The curly brackets
{}
in a path denote path parameters that you need to specify. Path parameters modify the endpoint path and are required in your request. For example, the path parameters for the
"List repository issues" endpoint
are
{owner}
and
{repo}
. To use this path in your API request, replace
{repo}
with the name of the repository where you would like to request a list of issues, and replace
{owner}
with the name of the account that owns the repository.
Headers provide extra information about the request and the desired response. Following are some examples of headers that you can use in your requests to the GitHub REST API. For an example of a request that uses headers, see "
Making a request
."
Most GitHub REST API endpoints specify that you should pass an
Accept
header with a value of
application/vnd.github+json
. The value of the
Accept
header is a media type. For more information about media types, see "
Media types
."
You should use this header to specify a version of the REST API to use for your request. For more information, see "
API Versions
."
All API requests must include a valid
User-Agent
header. The
User-Agent
header identifies the user or application that is making the request.
The following is an example
User-Agent
for an app named
Awesome-Octocat-App
:
User-Agent: Awesome-Octocat-App
Requests with no
User-Agent
header will be rejected. If you provide an invalid
User-Agent
header, you will receive a
403 Forbidden
response.
You can specify one or more media types by adding them to the
Accept
header of your request. For more information about the
Accept
header, see "
Accept
."
Media types specify the format of the data you want to consume from the API. Media types are specific to resources, allowing them to change independently and support formats that other resources don't. The documentation for each GitHub REST API endpoint will describe the media types that it supports. For more information, see the "
GitHub REST API documentation
."
The most common media types supported by the GitHub REST API are
application/vnd.github+json
and
application/json
.
There are custom media types that you can use with some endpoints. For example, the REST API to manage
commits
and
pull requests
support the media types
diff
,
patch
, and
sha
. The media types
full
,
raw
,
text
, or
html
are used by some other endpoints.
All custom media types for GitHub look like this:
application/vnd.github.PARAM+json
, where
PARAM
is the name of the media type. For example, to specify the
raw
media type, you would use
application/vnd.github.raw+json
.
For an example of a request that uses media types, see "
Making a request
."
Many endpoints require authentication or return additional information if you are authenticated. Additionally, you can make more requests per hour when you are authenticated.
Many API methods require or allow you to send additional information in parameters in your request. There are a few different types of parameters: Path parameters, body parameters, and query parameters.
Path parameters modify the endpoint path. These parameters are required in your request. For more information, see "
Path
."
Body parameters allow you to pass additional data to the API. These parameters can be optional or required, depending on the endpoint. For example, a body parameter may allow you to specify an issue title when creating a new issue, or specify certain settings when enabling or disabling a feature. The documentation for each GitHub REST API endpoint will describe the body parameters that it supports. For more information, see the "
GitHub REST API documentation
."
For example, the
"Create an issue" endpoint
requires that you specify a title for the new issue in your request. It also allows you to optionally specify other information, such as text to put in the issue body, users to assign to the new issue, or labels to apply to the new issue. For an example of a request that uses body parameters, see "
Making a request
."
You must authenticate your request to pass body parameters. For more information, see "
Authenticating
."
Query parameters allow you to control what data is returned for a request. These parameters are usually optional. The documentation for each GitHub REST API endpoint will describe any query parameters that it supports. For more information, see the "
GitHub REST API documentation
."
For example, the
"List public events" endpoint
returns thirty issues by default. You can use the
per_page
query parameter to return two issues instead of 30. You can use the
page
query parameter to fetch only the first page of results. For an example of a request that uses query parameters, see "
Making a request
."
After you make a request, the API will return the response status code, response headers, and potentially a response body.
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
option when you send your request.
For example, this request gets a list of issues in the octocat/Spoon-Knife repository:
gh api \
--header 'Accept: application/vnd.github+json' \
--method GET /repos/octocat/Spoon-Knife/issues \
-F per_page=2 --include
And it returns a response code and headers that look something like this:
HTTP/2.0 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, Location, Retry-After, 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, 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.
To view the status code and headers, use the
--include
or
--i
option when you send your request.
For example, this request gets a list of issues in the octocat/Spoon-Knife repository:
curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--include
And it returns a response code and headers that look something like this:
HTTP/2 200
server: GitHub.com
date: Thu, 04 Aug 2022 20:07:51 GMT
content-type: application/json; charset=utf-8
cache-control: public, max-age=60, s-maxage=60
vary: Accept, Accept-Encoding, Accept, X-Requested-With
etag: W/"7fceb7e8c958d3ec4d02524b042578dcc7b282192e6c939070f4a70390962e18"
x-github-media-type: github.v3; format=json
link: <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=7409>; rel="last"
access-control-expose-headers: ETag, Link, Location, Retry-After, 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
access-control-allow-origin: *
strict-transport-security: max-age=31536000; includeSubdomains; preload
x-frame-options: deny
x-content-type-options: nosniff
x-xss-protection: 0
referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin
content-security-policy: default-src 'none'
x-ratelimit-limit: 15000
x-ratelimit-remaining: 14996
x-ratelimit-reset: 1659645535
x-ratelimit-resource: core
x-ratelimit-used: 4
accept-ranges: bytes
content-length: 4936
x-github-request-id: 14E0:4BC6:F1B8BA:208E317:62EC2715
In this example, the response code is
200
, which indicates a successful request.
Many endpoints will return a response body. Unless otherwise specified, the response body is in JSON format. Blank fields are included as
null
instead of being omitted. All timestamps return in UTC time, ISO 8601 format:
YYYY-MM-DDTHH:MM:SSZ
.
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.
A response can include all attributes for a resource or only a subset of attributes, depending on whether you fetch an individual resource or a list of resources.
- When you fetch an
individual resource
, like a specific repository, the response will typically include all attributes for that resource. This is the "detailed" representation of the resource.
- When you fetch a
list of resources
, like a list of multiple repositories, the response will only include a subset of the attributes for each resource. This is the "summary" representation of the resource.
Note that authorization sometimes influences the amount of detail included in a representation.
The reason for this is because some attributes are computationally expensive for the API to provide, so GitHub excludes those attributes from the summary representation. To obtain those attributes, you can fetch the detailed representation.
The documentation provides an example response for each API method. The example response illustrates all attributes that are returned by that method.
All resources may have one or more
*_url
properties linking to other resources. These are meant to provide explicit URLs so that proper API clients don't need to construct URLs on their own. It is highly recommended that API clients use these. Doing so will make future upgrades of the API easier for developers. All URLs are expected to be proper
RFC 6570
URI templates.
You can then expand these templates using something like the
uri_template
gem:
>>
tmpl =
URITemplate
.new(
'/notifications{?since,all,participating}'
)
>>
tmpl.expand
=>
"/notifications"
>>
tmpl.expand
all:
1
=>
"/notifications?all=1"
>>
tmpl.expand
all:
1
,
participating:
1
=>
"/notifications?all=1&participating=1"
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, see the
"Create an issue comment" endpoint
and the
"Update an issue" endpoint
.
For more information about other endpoints that you can use, see the
REST reference documentation
.