Clusters API

The clusters API endpoint lets you create and manage clusters in your organization, along with the following other aspects associated with clusters:

Clusters

A Buildkite cluster is an isolated set of agents and pipelines within an organization.

Cluster data model

id ID of the cluster
graphql_id GraphQL ID of the cluster
default_queue_id ID of the cluster's default queue. Agents that connect to the cluster without specifying a queue will accept jobs from this queue.
name Name of the cluster
description Description of the cluster
emoji Emoji for the cluster using the emoji syntax
color Color hex code for the cluster
url Canonical API URL of the cluster
web_url URL of the cluster on Buildkite
queues_url API URL of the cluster's queues
default_queue_url API URL of the cluster's default queue
created_at When the cluster was created
created_by User who created the cluster

List clusters

Returns a paginated list of an organization's clusters.

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters"

[
  {
    "id": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
    "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
    "default_queue_id": "01885682-55a7-44f5-84f3-0402fb452e66",
    "name": "Open Source",
    "description": "A place for safely running our open source builds",
    "emoji": ":technologist:",
    "color": "#FFE0F1",
    "url": "http://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
    "web_url": "http://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
    "default_queue_url": "http://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
    "queues_url": "http://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues",
    "created_at": "2023-05-03T04:17:55.867Z",
    "created_by": {
      "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
      "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
      "name": "Sam Kim",
      "email": "sam@example.com",
      "avatar_url": "https://www.gravatar.com/avatar/example",
      "created_at": "2013-08-29T10:10:03.000Z"
    }
  }
]

Required scope: read_clusters

Success response: 200 OK

Get a cluster

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{id}"

{
  "id": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "default_queue_id": "01885682-55a7-44f5-84f3-0402fb452e66",
  "name": "Open Source",
  "description": "A place for safely running our open source builds",
  "emoji": ":technologist:",
  "color": "#FFE0F1",
  "url": "http://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "web_url": "http://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "default_queue_url": "http://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "queues_url": "http://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues",
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-08-29T10:10:03.000Z"
  }
}

Required scope: read_clusters

Success response: 200 OK

Create a cluster

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Open Source",
    "description": "A place for safely running our open source builds",
    "emoji": ":technologist:",
    "color": "#FFE0F1",
  }'

{
  "id": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "default_queue_id": null,
  "name": "Open Source",
  "description": "A place for safely running our open source builds",
  "emoji": ":technologist:",
  "color": "#FFE0F1",
  "url": "http://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "web_url": "http://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "default_queue_url": null,
  "queues_url": "http://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues",
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-08-29T10:10:03.000Z"
  }
}

Required request body properties:

name Name for the cluster.
Example: "Open Source"

Optional request body properties:

description Description for the cluster.
Example: "A place for safely running our open source builds"
emoji Emoji for the cluster using the emoji syntax
Example: ":technologist:"
color Color hex code for the cluster.
Example: "#FFE0F1"
maintainers An array of one or more hashes of representing users or teams to grant maintainer permissions to for this cluster.
Example: [{ "user: "282a043f-4d4f-4db5-ac9a-58673ae02caf" }, { "team: "0da645b7-9840-428f-bd80-0b92ee274480" }]

Required scope: write_clusters

Success response: 201 Created

Error responses:

422 Unprocessable Entity { "message": "Validation failed: Reason for failure" }

Update a cluster

curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{id}" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Open Source" }'

{
  "id": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "default_queue_id": "01885682-55a7-44f5-84f3-0402fb452e66",
  "name": "Open Source",
  "description": "A place for safely running our open source builds",
  "emoji": ":technologist:",
  "color": "#FFE0F1",
  "url": "http://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "web_url": "http://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "default_queue_url": "http://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "queues_url": "http://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues",
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-08-29T10:10:03.000Z"
  }
}

Request body properties:

name Name for the cluster.
Example: "Open Source"
description Description for the cluster.
Example: "A place for safely running our open source builds"
emoji Emoji for the cluster using the emoji syntax.
Example: ":technologist:"
color Color hex code for the cluster.
Example: "#FFE0F1"
default_queue_id ID of the queue to set as the cluster's default queue. Agents that connect to the cluster without specifying a queue will accept jobs from this queue.
Example: "01885682-55a7-44f5-84f3-0402fb452e66"

Required scope: write_clusters

Success response: 200 OK

Error responses:

422 Unprocessable Entity { "message": "Validation failed: Reason for failure" }

Delete a cluster

Delete a cluster along with any queues and tokens that belong to it.

curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{id}"

Required scope: write_clusters

Success response: 204 No Content

Error responses:

422 Unprocessable Entity { "message": "Reason the cluster couldn't be deleted" }