gh api: Usage, Options & Common CI Errors

Call any GitHub REST or GraphQL endpoint with gh’s auth built in.

gh api makes authenticated requests to the GitHub API - REST or GraphQL - handling the token, base URL, and pagination so you can script anything gh’s commands do not cover directly.

What it does

gh api <endpoint> sends a request using your gh credentials. It defaults to GET (POST when fields are present), supports path placeholders like {owner}/{repo}, sets fields with -f (string) and -F (typed), paginates with --paginate, and filters responses with --jq. It also talks GraphQL via gh api graphql.

Common usage

# GET a REST endpoint (placeholders resolve from the current repo)
gh api repos/{owner}/{repo}/releases/latest --jq '.tag_name'

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

# Paginate a list endpoint
gh api --paginate user/repos --jq '.[].full_name'

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

Common error in CI: 404/403 from placeholders or scopes

gh api commonly returns 404 (wrong path, or {owner}/{repo} unresolved outside a repo) or 403 (token missing a scope, or secondary rate limiting). Fix: in CI pass -H headers and full paths or set GH_REPO so placeholders resolve; ensure GH_TOKEN has the scope the endpoint needs (e.g. workflow for Actions writes). For mutations use -f/-F to send a JSON body, and add --paginate for list endpoints so you do not silently miss pages past the first 30.

Key options

Related guides