Introduction
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.
About requests to the 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.
HTTP method
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.
Path
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
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.
Accept
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.
X-GitHub-Api-Version
You should use this header to specify a version of the REST API to use for your request. For more information, see API Versions.
Media types
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.