# gh-got

> Convenience wrapper for Got to interact with the GitHub API

Latest version **12.0.0** (published 2026-04-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install gh-got
pnpm add gh-got
yarn add gh-got
bun add gh-got
```

## Health

**Score 55/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 12.0.0 |
| Published | 2026-04-02 |
| First published | 2015-04-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=22 |
| Dependencies | 1 |
| Unpacked size | 8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 177 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | got, gh, github, api, request, http, https, get, url, utility |

## Links

- npm: https://www.npmjs.com/package/gh-got
- Repository: https://github.com/sindresorhus/gh-got
- Homepage: https://github.com/sindresorhus/gh-got#readme
- Issues: https://github.com/sindresorhus/gh-got/issues
- Funding: https://github.com/sindresorhus/got?sponsor=1
- npm.io page: https://npm.io/package/gh-got

## Dependencies (1)

- [got](https://npm.io/package/got.md) ^15.0.0

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 12.0.0 (latest) — 2026-04-02
- 11.0.0 — 2025-11-02
- 10.0.0 — 2022-10-18
- 9.0.0 — 2020-02-17
- 8.1.0 — 2019-01-01
- 8.0.1 — 2018-08-27
- 8.0.0 — 2018-08-23
- 7.1.0 — 2018-08-23
- 7.0.0 — 2017-11-22
- 6.0.0 — 2017-06-06
- 5.0.0 — 2016-08-14
- 4.0.1 — 2016-07-30
- 4.0.0 — 2016-04-11
- 3.0.0 — 2016-04-06
- 2.4.0 — 2015-12-11
- … 10 more at https://npm.io/package/gh-got/versions

## README

# gh-got

> Convenience wrapper for [Got](https://github.com/sindresorhus/got) to interact with the [GitHub API](https://developer.github.com/v3/)

Unless you're already using Got, you should probably use GitHub's own [@octokit/rest.js](https://github.com/octokit/rest.js) or [@octokit/graphql.js](https://github.com/octokit/graphql.js) packages instead.

## Install

```sh
npm install gh-got
```

## Usage

Instead of:

```js
import got from 'got';

const token = 'foo';

const {body} = await got('https://api.github.com/users/sindresorhus', {
	json: true,
	headers: {
		'accept': 'application/vnd.github.v3+json',
		'authorization': `token ${token}`
	}
});

console.log(body.login);
//=> 'sindresorhus'
```

You can do:

```js
import ghGot from 'gh-got';

const {body} = await ghGot('users/sindresorhus', {
	context: {
		token: 'foo'
	}
});

console.log(body.login);
//=> 'sindresorhus'
```

Or:

```js
import ghGot from 'gh-got';

const {body} = await ghGot('https://api.github.com/users/sindresorhus', {
	context: {
		token: 'foo'
	}
});

console.log(body.login);
//=> 'sindresorhus'
```

## API

Same API as [`got`](https://github.com/sindresorhus/got), including options, the stream API, aliases, pagination, etc, but with some additional options below.

Errors are improved by using the custom GitHub error messages. Doesn't apply to the stream API.

### `gh-got` specific options

#### token

Type: `string`

GitHub [access token](https://github.com/settings/tokens/new).

Can be set globally with the `GITHUB_TOKEN` environment variable.

#### prefixUrl

Type: `string`\
Default: `https://api.github.com/`

To support [GitHub Enterprise](https://enterprise.github.com).

Can be set globally with the `GITHUB_ENDPOINT` environment variable.

#### body

Type: `object`

Can be specified as a plain object and will be serialized as JSON with the appropriate headers set.

## Rate limit

Responses and errors have a `.rateLimit` property with info about the current [rate limit](https://developer.github.com/v3/#rate-limiting). *(This is not yet implemented for the stream API)*

```js
import ghGot from 'gh-got';

const {rateLimit} = await ghGot('users/sindresorhus');

console.log(rateLimit);
//=> {limit: 5000, remaining: 4899, reset: [Date 2018-12-31T20:45:20.000Z]}
```

## Authorization

Authorization for GitHub uses the following logic:

1. If `options.headers.authorization` is passed to `gh-got`, then this will be used as first preference.
2. If `options.token` is provided, then the `authorization` header will be set to `token <options.token>`.
3. If `options.headers.authorization` and `options.token` are not provided, then the `authorization` header will be set to `token <process.env.GITHUB_TOKEN>`

In most cases, this means you can simply set `GITHUB_TOKEN`, but it also allows it to be overridden by setting `options.token` or `options.headers.authorization` explicitly. For example, if [authenticating as a GitHub App](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app), you could do the following:

```js
import ghGot from 'gh-got';

const options = {
	headers: {
		authorization: `Bearer ${jwt}`
	}
};
const {body} = await ghGot('app', options);

console.log(body.name);
//=> 'MyApp'
```

## Pagination

See the [Got docs](https://github.com/sindresorhus/got/blob/main/documentation/4-pagination.md).

---
_Source: https://npm.io/package/gh-got · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._