gh-api

Display the releases for the current repository in JSON format

$ gh api repos/:owner/:repo/releases

$ gh api [[-H|--header]] [Accept:application/vnd.github.squirrel-girl-preview+json] [[-f|--raw-field]] '[content=+1]' [repos/:owner/:repo/issues/123/reactions]

$ gh api graphql [[-f|--field]] [name=':repo'] [[-f|--raw-field]] '[query]'

$ gh api [[-X|--method]] [POST] [endpoint]

$ gh api [[-i|--include]] [endpoint]

$ gh api --silent [endpoint]

$ gh api --hostname [github.example.com] [endpoint]

$ gh api --help

gh api [flags] [--] <endpoint>

-H, --header strings
    Add custom HTTP header(s), repeatable (e.g., Accept:application/vnd.github.v3+json)

-i, --input string
    Read request body from file; use - for stdin

-f, --field key=value
    Set template fields (repeatable); interpolates context like owner, repo

-q, --jq string
    Pipe JSON output through jq filter

-X, --method string
    HTTP method: GET (default), POST, PUT, PATCH, DELETE, HEAD

--paginate
    Automatically fetch all pages for paginated responses

-t, --template string
    Format JSON output with Go template

gh api is a subcommand of the GitHub CLI (gh) that enables direct interaction with the GitHub REST API from the command line. It handles authentication automatically if you've run gh auth login, supporting GitHub.com, GitHub Enterprise Server, and methods like web browser, device code, or personal access tokens (PATs).

Specify an API endpoint such as /user, /repos/OWNER/REPO, or /orgs/OWNER/repos. By default, it sends a GET request and outputs raw JSON. Customize with flags for HTTP methods (POST, PATCH, etc.), custom headers, request bodies from files or stdin, pagination for list endpoints, and output processing via jq filters or Go templates.

Perfect for automation, scripting in CI/CD (e.g., GitHub Actions), data extraction, or testing API changes without a full HTTP client like curl. It respects GitHub rate limits and includes retry logic for transient errors. For GraphQL, use gh api graphql instead.

Responses include full HTTP status and headers for debugging. Paginated results are concatenated seamlessly with --paginate. Fields can be interpolated from context (e.g., repo owner/name) using --field.

Requires prior gh auth login; subject to GitHub API rate limits (5000 req/hour for auth users); no built-in GraphQL (use gh api graphql); large paginated outputs may consume memory.

gh api user # Current user info
gh api repos/OWNER/REPO/issues --jq '.[].title' # Issue titles
gh api /repos/OWNER/REPO/issues -X POST -i issue.json # Create issue

Uses GH_TOKEN env, git credential helper, or ~/.config/gh/hosts.yml; supports SSO and fine-grained tokens.

Introduced in GitHub CLI v0.5.0 (Jan 2020); evolved with CLI releases for better pagination, templates, and Enterprise support; actively maintained by GitHub.

gh(1), gh-graphql(1), curl(1), jq(1)