GraphQL API

Diffinery answers GraphQL at https://diffinery.com/api/graphql with the part of GitHub's GraphQL schema that covers repositories, issues, pull requests, reviews, CI, commit history and releases. Type, field, argument and enum names are GitHub's, so tools written for GitHub's GraphQL API work unchanged for those queries. The main users are the GitHub CLI (gh pr create, gh pr view, gh pr checks, gh issue list, gh issue create and the rest, see GitHub CLI and Claude Code) and Claude Code, which shows a session's pull request and its CI from it. release-please reads commit history, merged pull requests and releases from it, and gh release list lists releases.

Everything else (creating releases, Actions, settings and so on) is in the REST API.

#Requests

Send a POST with a JSON body and a token, as on GitHub:

curl https://diffinery.com/api/graphql \
  -H "Authorization: Bearer $DIFFINERY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { viewer { login } }"}'

#What it answers

Queries

issues takes GitHub's filterBy: assignee (a login, * for anyone, null for no one), createdBy, mentioned, labels, milestoneNumber (a number, * or null), since and states. labels on issues matches issues with any of the labels, as on GitHub. An Issue has its number, title, body, state and stateReason, author, labels, assignees, milestone and comments.

A PullRequest has its number, title, body, state, draft flag, author, branches (baseRef and headRef, with the branch's protection rule) and head commit, additions, deletions and changed files, labels, assignees, milestone, review requests, reviews and latestReviews, reviewDecision, comments, files, commits, mergeable and mergeStateStatus, auto-merge (autoMergeRequest) and statusCheckRollup.

Commits and refs. ref(qualifiedName:) takes a full name (refs/heads/main, refs/tags/v1.0.0) or a short one, which is looked up as a branch, then as a tag, as on GitHub; a ref that doesn't exist is null. A ref's target is its commit (an annotated tag is peeled to the commit it tags). A Commit has history(first, after, last, before, path), the commit and its ancestors in git log order (with path, only the commits that changed that file or directory), and associatedPullRequests: for a commit on the default branch, the merged pull request that brought it there; for any other commit, also the open pull requests that contain it, as on GitHub.

Releases. releases lists published releases, and drafts for those who can push, oldest first unless orderBy: {field: CREATED_AT, direction: DESC} asks for newest first, as on GitHub. A Release has its name, tagName, tag and tagCommit (both null while a draft's tag doesn't exist yet), description (the notes), url, isDraft, isPrerelease, isLatest, author, createdAt, publishedAt and updatedAt.

CI. A commit's statusCheckRollup combines its check runs and commit statuses: state is SUCCESS, FAILURE, ERROR, PENDING or EXPECTED, and contexts lists each CheckRun and StatusContext, with checkRunCountsByState and statusContextCountsByState for the counts. A check run from Diffinery Actions has its workflow under checkSuite.workflowRun.workflow.name, and isRequired(pullRequestNumber:) says whether the base branch requires it.

Mutations

#Fields Diffinery doesn't have

GitHub's schema is much larger than this one. To keep tools that ask for a few extra fields working, a field, argument or type that Diffinery doesn't know is left out of the answer instead of failing the whole query, and the answer says which:

{
  "data": { "repository": { "pullRequest": { "number": 1 } } },
  "extensions": { "unsupported": ["Cannot query field \"notAThing\" on type \"PullRequest\"."] }
}

Lists Diffinery has no data for answer empty: projectItems and reactionGroups. Team review requests aren't supported. isCrossRepository is always false, since pull requests come from branches of the same repository.

#Errors

Errors use GitHub's shape: a message, the path of the field, and a type such as NOT_FOUND, FORBIDDEN, UNPROCESSABLE or RATE_LIMITED, both at the top of the error and under extensions. The GitHub CLI reads type. A field that fails is null while the rest of the answer still comes back.

{
  "data": { "repository": null },
  "errors": [{ "type": "NOT_FOUND", "path": ["repository"], "message": "Could not resolve to a Repository with the name 'octo/nope'." }]
}

#Limits

Each request counts against your account's request limit like a REST call, and createPullRequest, createIssue and addComment also count against the limit on creating things (60 a minute), as POST /pulls, POST /issues and comments do over REST. See Rate limits.