GraphQL API Overview

The Buildkite GraphQL API provides an alternative to the REST API. It allows for more efficient retrieval of data by enabling you to fetch multiple, nested resources in a single request. The Buildkite GraphQL API is currently in beta.

Getting started

The quickest way to get started with the GraphQL API is to generate a Personal API Access Token with GraphQL scope, and then use the GraphQL Explorer with its built-in documentation:

Screenshot of the Buildkite GraphQL Explorer

See our Getting Started Tutorial for a step-by-step guide to using GraphQL queries and mutations.

Endpoint

The GraphQL API endpoint is https://graphql.buildkite.com/v1. All requests must be HTTP POST requests with application/json encoded bodies.

Authentication

GraphQL requests must be authenticated using an API Access Token with the GraphQL scope enabled. Pass the token in your GraphQL request using the Authorization HTTP header with a value Bearer <token>.

For example:

curl -H "Authorization: Bearer $TOKEN" https://graphql.buildkite.com/v1

Performing requests with curl

A GraphQL request is a standard HTTPS POST request, with a JSON-encoded body containing a "query" key, and optionally a "variables" key.

For example, the following curl command returns the name property of the current viewer:

curl https://graphql.buildkite.com/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "query": "{ viewer { user { name } } }",
    "variables": "{ }"
  }'
{
  "data": {
    "viewer": {
      "user": {
        "name": "Jane Doe"
      }
    }
  }
}

For documentation on the full list of fields and types, see the interactive documentation in the GraphQL Explorer.

Relay compatibility

The Buildkite GraphQL API adheres to the Relay Specification, which defines standards for querying paginated collections ("Connections" and "Edges"), identifying objects directly from the root of a query (avoiding long nested queries), and for providing mutation input data.

Learning more about GraphQL

Further resources for learning more about GraphQL:

Beta caveats

Whilst the GraphQL API is in beta, you should note the following cavaets:

  • GraphQL API tokens do not currently respect their organization scope settings, so we recommend creating a separate API token or user account for performing API requests in production.