GitHub GraphQL API

What is GraphQL?

GraphQL is a new way to think about building and querying APIs. Rather than construct several REST requests to fetch data that you're interested in, you can often make a single call to fetch the information you need.

GraphQL is, above all, a querying language, and the format of the query you send matches the data you receive. For example, given the following query:

{
  viewer {
    login
    bio
    organizations(first: 3) {
      edges {
        org:node {
          name
        }
      }
    }
  }
}

your response will retrieve the login and bio of the requesting user (viewer), as well as the names of the first three organizations:

{
  "data": {
    "viewer": {
      "login": "gjtorikian",
      "bio": "I inhale and exhale.",
      "organizations": {
        "edges": [
          {
            "org": {
              "name": "GitHub"
            }
          },
          {
            "org": {
              "name": "Atom"
            }
          },
          {
            "org": {
              "name": "octokit"
            }
          }
        ]
      }
    }
  }
}

Why is GitHub using GraphQL?

We're supporting GraphQL because it offers much more flexibility for our integrators. The example above would require at least two REST calls—one to fetch information about the user, and one to fetch information about the user's organizations.

The ability to define and specify precisely the data you want for your integration is a powerful advantage over the existing REST endpoints. As we move out of Early Access, we'll be providing more resources and fields that you can access via GraphQL.

What can I build with the GitHub GraphQL API?

The GitHub GraphQL API is currently released as Early Access. The sidebar to the right provides information on which objects you can query for.

GraphQL natively supports performing an introspection query. As our GraphQL schema matures, you will automatically receive new data types as we release updates to the platform. The documentation on this site will also be updated.

What are some known issues?

  • We do not currently support "sub-scopes" like user:email. Please use the parent scope.
  • We do not currently support public_repo scope. Please use repo scope to access any repository.