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 head="username:branch".

Get PR details

gh api repos/:owner/:repo/pulls/<number> --jq '{draft, state, title}'

Convert draft to ready for review

gh api --method PATCH repos/:owner/:repo/pulls/<number> -F draft=false \
  --jq '{number, title, html_url, draft}'

Note: Cannot convert back to draft via API once marked ready.

List open draft PRs

gh api repos/:owner/:repo/pulls --jq '.[] | select(.draft) | {number, title}'

List my open PRs in a repo

gh api repos/:owner/:repo/pulls -f state=open --jq '.[] | select(.user.login=="USERNAME") | {number, title, draft}'

Discussions (GraphQL)

List discussions:

gh api graphql -f query='query($owner:String!,$repo:String!) { repository(owner:$owner,name:$repo) { discussions(first:10) { nodes { number title url } } } }' -F owner=OWNER -F repo=REPO

View discussion:

gh api graphql -f query='query($owner:String!,$repo:String!,$number:Int!) { repository(owner:$owner,name:$repo) { discussion(number:$number) { title body comments(first:10) { nodes { body author { login } } } } } }' -F owner=OWNER -F repo=REPO -F number=NUM

Search discussions:

gh api graphql -f query='query($q:String!) { search(query:$q,type:DISCUSSION,first:10) { nodes { ...on Discussion { number title url } } } }' -f q="repo:OWNER/REPO QUERY"