gh api

Authenticated API calls, no token juggling

gh api sends authenticated requests to GitHub's REST and GraphQL APIs using your existing gh login — no manual token headers. Filter responses with built-in jq, follow pagination automatically, and reach any endpoint the CLI doesn't wrap yet.

Quick answer

gh api repos/cli/cli

↧ Download snippet Full cheat sheet

Syntax

gh api <endpoint> [flags]

Examples

GET a REST endpoint

gh api repos/cli/cli

Filter the response with jq

gh api repos/cli/cli --jq ".stargazers_count"

Follow pagination for every result

gh api --paginate users/octocat/repos

POST with fields

gh api repos/{owner}/{repo}/issues -f title="Bug" -f body="details"

Run a GraphQL query

gh api graphql -f query='{ viewer { login } }'

Options & flags

Flag	What it does
-X, --method	HTTP method (default GET, or POST when fields are set).
-f, --raw-field	Add a string parameter (key=value).
-F, --field	Add a typed parameter (numbers, booleans, @file, placeholders).
--paginate	Fetch every page of results automatically.
-q, --jq	Filter the JSON response with a jq expression.
-H, --header	Add an HTTP request header.
--hostname	Target a GitHub Enterprise host.

How to use gh api, step by step

Sign in with gh auth login so requests are authenticated.
Call an endpoint: gh api repos/OWNER/REPO.
Shape the output with --jq, or send data with -f key=value.
Add --paginate when a list spans multiple pages.

Common errors and fixes

HTTP 404: Not Found

Wrong endpoint path or no access. Drop the leading slash and leading https://api.github.com/; gh adds them. Check scopes with gh auth status.

HTTP 422: Validation Failed

Your fields are missing or malformed. Use -F for numbers/booleans and -f for strings, and check the endpoint's required parameters.

gh: To use GraphQL, the query must be provided via -f query=...

For GraphQL, target the graphql endpoint and pass the query as a field: gh api graphql -f query='...'.

Related commands

Frequently asked questions

How do I call the GitHub API from the command line?

Run gh api <endpoint>, for example gh api repos/cli/cli. gh uses your existing authentication, so you don't need to set an Authorization header, and you can filter the result with --jq.

How do I make a POST request with gh api?

Add fields with -f (strings) or -F (typed): gh api repos/{owner}/{repo}/issues -f title="Bug". Setting any field switches the method to POST automatically.

Can gh api handle pagination?

Yes. Add --paginate and gh follows the Link headers to fetch every page, concatenating the results.

Does gh api support GraphQL?

Yes. Target the graphql endpoint and pass your query as a field: gh api graphql -f query='{ viewer { login } }'.