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 an 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.

GraphQL IDs

All node types have an id property, which is a global identifier for the node. You can find the GraphQL ID for any node by querying for the id property, for example:

query {
  organization(slug: "my-org") {
    id
  }
}
{
  "data": {
    "organization": {
      "id": "T3JnYW5pemF0aW9uLS0tYTk4OTYxYjctYWRjMS00MWFhLTg3MjYtY2ZiMmM0NmU0MmUw"
    }
  }
}

A GraphQL ID can be used with the global node query to quickly return properties of a node, without having to query through nested layers of data. To return specific properties of the object, you’ll need to specify the object’s type using an Inline Fragment.

For example, the following query uses an organization’s id to find the total number of pipelines in the organization:

query {
  node(id: "T3JnYW5pemF0aW9uLS0tYTk4OTYxYjctYWRjMS00MWFhLTg3MjYtY2ZiMmM0NmU0MmUw") {
    ... on Organization {
      pipelines {
        count
      }
    }
  }
}
{
  "data": {
    "node": {
      "pipelines": {
        "count": 42
      }
    }
  }
}

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: