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
maintainers The maintainers of 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
hosted_git_mirror_enabled Whether the hosted-agent git mirror cache is enabled for the cluster. Only included in responses for callers with manage cluster permission. Only applicable to clusters running Buildkite hosted agents.
hosted_container_cache_enabled Whether the hosted-agent container cache is enabled for the cluster. Only included in responses for callers with manage cluster permission. Only applicable to clusters running Buildkite hosted agents.
default_cache_registry_uuid UUID of the cluster's default cache registry. Only included in responses for callers with manage cluster permission.
default_cache_registry_url API URL of the cluster's default cache registry. Only included in responses for callers with manage cluster permission.

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",
    "maintainers": {
      "users": [],
      "teams": []
    },
    "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",
  "maintainers": {
    "users": [
      {
        "id": "56c210cb-474c-47a7-b4ef-5761a1cb91c1",
        "actor": {
          "id": "da206b36-e5ae-4f4a-aca6-07dd478f3a48",
          "graphql_id": "VXNlci0tLWU1N2ZiYTBmLWFiMTQtNGNjMC1iYjViLTY5NTc3NGZmYmZiZQ==",
          "name": "John Smith",
          "email": "john.smith@example.com",
          "type": "user"
        }
      }
    ],
    "teams": [
      {
        "id": "77ec8d4c-edb3-430e-baba-488757a418e2",
        "actor": {
          "id": "c5e09619-8648-4896-a936-9d0b8b7b3fe9",
          "graphql_id": "VGVhbS0tLWM1ZTA5NjE5LTg2NDgtNDg5Ni1hOTM2LTlkMGI4YjdiM2ZlOQ==",
          "name": "Fearless Frontenders",
          "slug": "fearless-frontenders",
        }
      }
    ]
  },
  "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"
  },
  "hosted_git_mirror_enabled": false,
  "hosted_container_cache_enabled": false,
  "default_cache_registry_uuid": "b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
  "default_cache_registry_url": "https://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/cache-registries/b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d"
}

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",
  "maintainers": {
    "users": [],
    "teams": []
  },
  "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",
  "maintainers": {
    "users": [],
    "teams": []
  },
  "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"
  },
  "hosted_git_mirror_enabled": false,
  "hosted_container_cache_enabled": false,
  "default_cache_registry_uuid": "b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
  "default_cache_registry_url": "https://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/cache-registries/b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d"
}

Request body properties:

The hosted_git_mirror_enabled, hosted_container_cache_enabled, and default_cache_registry_uuid fields can only be set when updating a cluster. Cluster creation requests do not apply these fields.

For example, to change the cluster's default cache registry:

curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{id}" \
  -H "Content-Type: application/json" \
  -d '{ "default_cache_registry_uuid": "b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d" }'
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"
default_cache_registry_uuid UUID of the cache registry to set as the cluster's default. Must be the UUID of a cache registry in this cluster. A registry slug isn't accepted. The value can't be null, because a cluster must always have a default cache registry. Requires permission to manage the cluster.
Example: "b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d"
hosted_git_mirror_enabled Enable or disable the hosted-agent git mirror cache for the cluster. Must be true or false. Only applicable to clusters running Buildkite hosted agents.
Example: true
hosted_container_cache_enabled Enable or disable the hosted-agent container cache for the cluster. Must be true or false. Only applicable to clusters running Buildkite hosted agents.
Example: true

Required scope: write_clusters

Success response: 200 OK

Error responses:

422 Unprocessable Entity A hosted-agent cache field is not true or false, a changed cache field targets a non-hosted cluster, default_cache_registry_uuid isn't the UUID of a cache registry in this cluster (for example, it's a slug, null, or the UUID of a deleted registry or a registry in another cluster), or another cluster validation fails.
503 Service Unavailable A change to hosted_git_mirror_enabled could not be applied by the hosted-agent service. The update is rolled back and is safe to retry.

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" }