gh api Command Reference

Call any GitHub REST or GraphQL endpoint with auth handled for you.

gh api is the escape hatch for anything the typed gh commands do not cover. It signs requests with your gh credentials and can paginate and filter results.

What it does

gh api sends authenticated requests to GitHub REST or GraphQL endpoints, inferring the method, attaching the token, and handling base URL and headers. It supports fields, pagination, and a built-in jq expression for shaping output.

Common flags and usage

ENDPOINT: REST path (repos/{owner}/{repo}) or graphql
--method GET|POST|PATCH|DELETE / -X: HTTP method
--field KEY=VALUE / -f and -F (raw): request fields
--paginate: follow pagination across pages
--jq EXPR: filter the JSON response with jq

Example

shell

- name: List job names for a run
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    gh api "repos/${{ github.repository }}/actions/runs/${{ github.run_id }}/jobs" \
      --jq '.jobs[].name'

In CI

Set GH_TOKEN (or GITHUB_TOKEN) in env and gh api authenticates automatically, so no curl plus token plumbing is needed. Use --paginate for list endpoints and --jq to extract just the fields you need.

Key takeaways

gh api handles authentication, base URL, and headers for REST and GraphQL.
Set GH_TOKEN in env and the request is authenticated automatically.
--paginate and --jq cover multi-page list endpoints and response parsing.