ghapi

ghapi v2 (July 2026) is now async by default. Every API call is now awaited: res = await api.repos.get(). Top-level await works directly in Jupyter and modern REPLs; in scripts, use asyncio.run. For sync code (which should be largely compatible with v1), use GhApi(sync=True). See the Sync usage section of the docs for details. To stay on the old version, pin ghapi<2.

ghapi provides 100% always-updated coverage of the entire GitHub API. Because we automatically convert the OpenAPI spec to a Pythonic API, ghapi is always up to date with the latest changes to GitHub APIs. Furthermore, because this is all built dynamically from a compact pre-parsed copy of the spec, the package stays small and is always up to date.

Using ghapi, you can automate nearly anything that you can do through the GitHub web interface or through the git client, such as:

• Open, list, comment on, or modify issues or pull requests
• Create, list, or modify git tags or GitHub releases, including uploading release assets
• Configure and run GitHub Actions and webhooks
• Set up GitHub users and organizations
• Manage your deployments
• …and much, much more.

There are two ways to use ghapi: either through Python, or from the command line. An overview of each is provided below.

To install, run pip install ghapi.

Throughout this documentation, you will see code inputs and outputs shown in this format:

1+1

2

We recommend reading the documentation on the official site, rather than on GitHub, since not all the functionality described on this page is available through the GitHub viewer.

All of the documentation is available directly as Jupyter Notebooks, for instance the current page you’re reading is available as a notebook here. To open any page as an interactive notebook in Google Colab, click the Colab badge at the top of the page.

To access the GitHub API, first create a GhApi object. Note that as of v2, ghapi is async: every endpoint call is awaited. In Jupyter and modern Python REPLs top-level await just works, as shown below; in scripts, wrap your code in a function run with asyncio.run.

from ghapi.all import GhApi

api = GhApi()

Every part of the API includes documentation directly in the api object itself. For instance, here’s how to explore the groups of functionality provided by the API by displaying the object:

api

• actions
• activity
• agent_tasks
• agents
• api_insights
• apps
• billing
• campaigns
• checks
• classroom
• code_quality
• code_scanning
• code_security
• codes_of_conduct
• codespaces
• copilot
• copilot_spaces
• credentials
• dependabot
• dependency_graph
• emojis
• enterprise_team_memberships
• enterprise_team_organizations
• enterprise_teams
• gists
• git
• gitignore
• hosted_compute
• interactions
• issues
• licenses
• markdown
• meta
• migrations
• oidc
• orgs
• packages
• private_registries
• projects
• pull_request_stacks
• pulls
• rate_limit
• reactions
• repos
• search
• secret_scanning
• security_advisories
• teams
• users

Then we can explore the endpoints provided by the API in each group, e.g. for the git group:

api.git

• git.create_blob(owner, repo, content, encoding): Create a blob
• git.get_blob(owner, repo, file_sha): Get a blob
• git.create_commit(owner, repo, message, tree, parents, author, committer, signature): Create a commit
• git.get_commit(owner, repo, commit_sha): Get a commit object
• git.list_matching_refs(owner, repo, ref): List matching references
• git.get_ref(owner, repo, ref): Get a reference
• git.create_ref(owner, repo, ref, sha): Create a reference
• git.update_ref(owner, repo, ref, sha, force): Update a reference
• git.delete_ref(owner, repo, ref): Delete a reference
• git.create_tag(owner, repo, tag, message, object, type, tagger): Create a tag object
• git.get_tag(owner, repo, tag_sha): Get a tag
• git.create_tree(owner, repo, tree, base_tree): Create a tree
• git.get_tree(owner, repo, tree_sha, recursive): Get a tree

Read an endpoint’s full documentation on the generated object. Its display includes parameter descriptions, bound defaults, request controls, and async usage. With pyskills, use doc(api.git.get_ref) for the same documentation, or xdir(api.git, 'ref') to search names. Construction and discovery send no requests:

api.git.get_ref

Get a reference

Docs: https://docs.github.com/rest/git/refs#get-a-reference

Parameters:

• owner (str, required): The account owner of the repository. The name is not case sensitive.
• repo (str, required): The name of the repository without the .git extension. The name is not case sensitive.
• ref (str, required): The Git reference. For more information, see “Git References” in the Git documentation.

Jupyter provides full tab completion and parameter lists for every endpoint. Endpoints are called as standard Python methods:

await api.git.get_ref(owner='fastai', repo='fastcore', ref='heads/master')

{ 'node_id': 'MDM6UmVmMjI1NDYwNTk5OnJlZnMvaGVhZHMvbWFzdGVy',
  'object': { 'sha': 'c0608379fe60014534c8dffe2e381138e8160f53',
              'type': 'commit',
              'url': 'https://api.github.com/repos/AnswerDotAI/fastcore/git/commits/c0608379fe60014534c8dffe2e381138e8160f53'},
  'ref': 'refs/heads/master',
  'url': 'https://api.github.com/repos/AnswerDotAI/fastcore/git/refs/heads/master'}

To use authenticated operations (other than when running through GitHub Actions), you will need a GitHub personal access token. If you don’t have one, click here to create it, choosing the scopes you need (“repo”, “gist”, “notifications”, and “workflow” cover most uses). Save it as an environment variable named GITHUB_TOKEN, e.g. by adding this to your .bashrc or .zshrc:

export GITHUB_TOKEN=xxx

GhApi uses that variable automatically, or you can pass token= explicitly.

As well as token, you can pass any parameters you want auto-inserted into relevant methods, such as owner and repo:

api = GhApi(owner='fastai', repo='fastcore', token=github_token)

We can now repeat the previous method, but only need to pass ref:

await api.git.get_ref('heads/master')

{ 'node_id': 'MDM6UmVmMjI1NDYwNTk5OnJlZnMvaGVhZHMvbWFzdGVy',
  'object': { 'sha': 'c0608379fe60014534c8dffe2e381138e8160f53',
              'type': 'commit',
              'url': 'https://api.github.com/repos/AnswerDotAI/fastcore/git/commits/c0608379fe60014534c8dffe2e381138e8160f53'},
  'ref': 'refs/heads/master',
  'url': 'https://api.github.com/repos/AnswerDotAI/fastcore/git/refs/heads/master'}

Now that we’ve provided our token, we can use authenticated endpoints such as creating an issue:

issue = await api.issues.create("Remember to check out GhApi!")

Since we’ve now checked out GhApi, let’s close this issue. 😎

await api.issues.update(issue.number, state='closed')