Raw API access (gh api)

Active contributors: Mislav, Kynan, Corey Johnson

Purpose

gh api lets users (and scripts) call any GitHub REST or GraphQL endpoint. It handles auth, host selection, pagination, JSON decoding, request body construction, and field-level filtering with --jq or --template. It is essentially curl plus everything gh already knows about your account.

Directory layout

pkg/cmd/api/
  api.go               # NewCmdApi: ~14 KB, the whole command lives here
  fields.go            # parses --field/-F (typed values) and --raw-field/-f
  http.go              # request construction, hostname resolution
  pagination.go        # follows Link headers and GraphQL pageInfo
  pretty_print.go      # color JSON output for TTY

Unlike most commands, gh api is intentionally a single Cobra command without subcommands; verbs are encoded in flags (-X, --method).

Key abstractions

Symbol	File	Role
NewCmdApi	pkg/cmd/api/api.go	Sets up flags, wires the apiRun function.
processFields	pkg/cmd/api/fields.go	Parses -f key=value (string), -F key=value (typed), and reads stdin.
httpRequest	pkg/cmd/api/http.go	Builds the final http.Request, including hostname swap for graphql.
paginate	pkg/cmd/api/pagination.go	Implements --paginate for both REST (Link: rel="next") and GraphQL (pageInfo.endCursor).
prettyPrintJSON	pkg/cmd/api/pretty_print.go	Colour-printing through pkg/jsoncolor.

How it works

gh api graphql -f query='...' -f variables='...' resolves to:

1. The smart base repo resolver picks a host (so --hostname is rarely needed inside a clone).
2. The query field is plain JSON, the variables field is parsed via fields.go.
3. httpRequest sets Authorization, User-Agent, and the GraphQL features header. Hostname becomes api.<host> for REST, api.<host>/graphql for GraphQL.
4. The response body is streamed through the pretty-printer (TTY) or the --jq/--template filter.
5. With --paginate, the loop continues until there is no next cursor; multiple JSON arrays are concatenated when feasible.

gh api -X DELETE repos/{owner}/{repo}/issues/comments/123 works the same way; placeholder substitution uses the resolved repo for {owner} and {repo}.

Integration points

• Uses the same cmdutil.Factory.HttpClient as every other command, so debug logging via GH_DEBUG=api works identically.
• Output filtering uses pkg/jsoncolor and the embedded jq via itchyny/gojq.
• Errors with scope hints come back through api.HTTPError.ScopesSuggestion to surface "try gh auth refresh -s ..." messages.

Entry points for modification

• New flag: extend NewCmdApi and add a row to the table-driven test in api_test.go.
• New paginator behaviour: edit pagination.go (be careful: --paginate --jq interaction is exercised by tests in api_test.go).
• New placeholder: extend the substitution logic in api.go ({owner}, {repo}, {branch} are the existing ones).

Key source files

File	Purpose
pkg/cmd/api/api.go	Command definition.
pkg/cmd/api/fields.go	Field parsing.
pkg/cmd/api/http.go	Request construction.
pkg/cmd/api/pagination.go	Paginate REST + GraphQL.
pkg/cmd/api/pretty_print.go	Coloured JSON output.

Related pages

• API client.
• Patterns and conventions.