gh-api

name

gh-api

description

Use when operating on the GitHub REST or GraphQL API via `gh api` for cases not covered by higher-level `gh` subcommands: creating or managing draft pull requests, querying or mutating GitHub Discussions, or any GitHub API call requiring raw endpoints. Do NOT use for standard `gh pr`, `gh issue`, `gh release`, or `gh repo` workflows. Do NOT use for any PR review operations (reading comments, posting replies, managing reviews); use `gh-review` instead.

PR Review Exclusion

Do NOT use gh api for any PR review operations: reading comments, posting replies, managing reviews, or viewing review threads. Use gh-review for all review workflows. Load the gh-pr-review skill for details.

Output Filtering

Mutation responses (POST, PATCH, PUT, DELETE) return the full object by default, which wastes context tokens. Always pipe through --jq to extract only the fields you need.

General pattern

For any mutation, append --jq selecting the fields the caller actually needs. Typical minimal set: {id, body, html_url}. Add state, title, or number when relevant.

Draft Pull Requests

Create a draft PR

gh api --method POST repos/:owner/:repo/pulls \
  -f title="My new feature" -f body="Description of changes" \
  -f head="feature-branch" -f base="main" -F draft=true \
  --jq '{number, title, html_url, draft}'

For cross-repo PRs, use .