Clusters API

The clusters API endpoint lets you create and manage clusters in your organization.

Clusters

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

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

Queues

Queues are discrete groups of agents within a cluster. Pipelines in that cluster can target queues to run jobs on agents assigned to those queues.

Queue data model

id ID of the queue
graphql_id GraphQL ID of the queue
key The queue key
description Description of the queue
url Canonical API URL of the queue
web_url URL of the queue on Buildkite
cluster_url API URL of the cluster the queue belongs to
dispatch_paused Indicates whether the queue has paused dispatching jobs to associated agents
dispatch_paused_by User who paused the queue
dispatch_paused_at When the queue was paused
dispatch_paused_note The note left when the queue was paused
created_at When the queue was created
created_by User who created the queue

List queues

Returns a paginated list of a cluster's queues.

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

[
  {
    "id": "01885682-55a7-44f5-84f3-0402fb452e66",
    "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
    "key": "default",
    "description": "The default queue for this cluster",
    "url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
    "web_url": "http://buildkite.com/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
    "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
    "dispatch_paused": false,
    "dispatch_paused_by": null,
    "dispatch_paused_at": null,
    "dispatch_paused_note": null,
    "created_at": "2023-05-03T04:17:55.867Z",
    "created_by": {
      "id": "0187dfd4-92cf-4b01-907b-1146c8525dde",
      "graphql_id": "VXNlci0tLTAxODdkZmQ0LTkyY2YtNGIwMS05MDdiLTExNDZjODUyNWRkZQ==",
      "name": "Sam Kim",
      "email": "sam@example.com",
      "avatar_url": "https://www.gravatar.com/avatar/example",
      "created_at": "2023-05-03T04:17:43.118Z"
    }
  }
]

Required scope: read_clusters

Success response: 200 OK

Get a queue

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

{
  "id": "01885682-55a7-44f5-84f3-0402fb452e66",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "key": "default",
  "description": "The default queue for this cluster",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "web_url": "http://buildkite.com/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "dispatch_paused": false,
  "dispatch_paused_by": null,
  "dispatch_paused_at": null,
  "dispatch_paused_note": null,
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "0187dfd4-92cf-4b01-907b-1146c8525dde",
    "graphql_id": "VXNlci0tLTAxODdkZmQ0LTkyY2YtNGIwMS05MDdiLTExNDZjODUyNWRkZQ==",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2023-05-03T04:17:43.118Z"
  }
}

Required scope: read_clusters

Success response: 200 OK

Create a queue

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/queues" \
  -H "Content-Type: application/json" \
  -d '{ "key": "default", "description": "The default queue for this cluster" }'

{
  "id": "01885682-55a7-44f5-84f3-0402fb452e66",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "key": "default",
  "description": "The default queue for this cluster",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "web_url": "http://buildkite.com/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "dispatch_paused": false,
  "dispatch_paused_by": null,
  "dispatch_paused_at": null,
  "dispatch_paused_note": null,
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "0187dfd4-92cf-4b01-907b-1146c8525dde",
    "graphql_id": "VXNlci0tLTAxODdkZmQ0LTkyY2YtNGIwMS05MDdiLTExNDZjODUyNWRkZQ==",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2023-05-03T04:17:43.118Z"
  }
}

Required request body properties:

key Key for the queue.
Example: "default"

Optional request body properties:

description Description for the queue.
Example: "The default queue for this cluster"

Required scope: write_clusters

Success response: 201 Created

Error responses:

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

Update a queue

curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/queues/{id}" \
  -H "Content-Type: application/json" \
  -d '{ "description": "The default queue for this cluster" }'

{
  "id": "01885682-55a7-44f5-84f3-0402fb452e66",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "key": "default",
  "description": "The default queue for this cluster",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "web_url": "http://buildkite.com/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "dispatch_paused": false,
  "dispatch_paused_by": null,
  "dispatch_paused_at": null,
  "dispatch_paused_note": null,
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "0187dfd4-92cf-4b01-907b-1146c8525dde",
    "graphql_id": "VXNlci0tLTAxODdkZmQ0LTkyY2YtNGIwMS05MDdiLTExNDZjODUyNWRkZQ==",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2023-05-03T04:17:43.118Z"
  }
}

Request body properties:

description Description for the queue.
Example: "The default queue for this cluster"

Required scope: write_clusters

Success response: 200 OK

Error responses:

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

Delete a queue

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

Required scope: write_clusters

Success response: 204 No Content

Error responses:

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

Pause a queue

Pause a queue to prevent jobs from being dispatched to agents associated with the queue.

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/queues/{id}/pause_dispatch" \
  -H "Content-Type: application/json" \
  -d '{ "dispatch_paused_note": "Paused while we investigate a security issue" }'

{
  "id": "01885682-55a7-44f5-84f3-0402fb452e66",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "key": "default",
  "description": "The default queue for this cluster",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "web_url": "http://buildkite.com/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/01885682-55a7-44f5-84f3-0402fb452e66",
  "dispatch_paused": true,
  "dispatch_paused_by": {
    "id": "0187dfd4-92cf-4b01-907b-1146c8525dde",
    "graphql_id": "VXNlci0tLTAxODdkZmQ0LTkyY2YtNGIwMS05MDdiLTExNDZjODUyNWRkZQ==",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2023-05-03T04:17:43.118Z"
  },
  "dispatch_paused_at": "2023-05-03T04:19:43.118Z",
  "dispatch_paused_note": "Paused while we investigate a security issue",
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "0187dfd4-92cf-4b01-907b-1146c8525dde",
    "graphql_id": "VXNlci0tLTAxODdkZmQ0LTkyY2YtNGIwMS05MDdiLTExNDZjODUyNWRkZQ==",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2023-05-03T04:17:43.118Z"
  }
}

Optional request body properties:

note Note explaining why the queue is paused. The note will display on the queue page and any affected builds.
Example: "Paused while we investigate a security issue"

Required scope: write_clusters

Success response: 200 OK

Error responses:

422 Unprocessable Entity { "message": "Cluster queue is already paused" }

Resume a paused queue

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/queues/{id}/resume_dispatch" \
  -H "Content-Type: application/json"

{
  "id": "01885682-55a7-44f5-84f3-0402fb452e66",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "key": "default",
  "description": "The default queue for this cluster",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "web_url": "http://buildkite.com/organizations/test/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/queues/01885682-55a7-44f5-84f3-0402fb452e66",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/01885682-55a7-44f5-84f3-0402fb452e66",
  "dispatch_paused": false,
  "dispatch_paused_by": null,
  "dispatch_paused_at": null,
  "dispatch_paused_note": null,
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "0187dfd4-92cf-4b01-907b-1146c8525dde",
    "graphql_id": "VXNlci0tLTAxODdkZmQ0LTkyY2YtNGIwMS05MDdiLTExNDZjODUyNWRkZQ==",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2023-05-03T04:17:43.118Z"
  }
}

Required scope: write_clusters

Success response: 200 OK

Error responses:

422 Unprocessable Entity { "message": "Cluster queue is not paused" }

Agent tokens

An agent token is used to connect agents to a cluster.

Token data model

id ID of the token
graphql_id GraphQL ID of the token
description Description of the token
allowed_ip_addresses A list of CIDR-notation IPv4 addresses from which agents can use this token
url Canonical API URL of the token
cluster_url API URL of the cluster the token belongs to
created_at When the token was created
created_by User who created the token

List tokens

Returns a paginated list of a cluster's agent tokens.

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

[
  {
    "id": "b6001416-0e1e-41c6-9dbe-3d96766f451a",
    "graphql_id": "Q2x1c3RlclRva2VuLS0tYjYwMDE0MTYtMGUxZS00MWM2LTlkYmUtM2Q5Njc2NmY0NTFh",
    "description": "Windows agents",
    "allowed_ip_addresses": "202.144.0.0/24",
    "url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a/tokens/b6001416-0e1e-41c6-9dbe-3d96766f451a",
    "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a",
    "created_at": "2023-05-26T04:21:41.350Z",
    "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 token

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

{
  "id": "b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "graphql_id": "Q2x1c3RlclRva2VuLS0tYjYwMDE0MTYtMGUxZS00MWM2LTlkYmUtM2Q5Njc2NmY0NTFh",
  "description": "Windows agents",
  "allowed_ip_addresses": "202.144.0.0/24",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a/tokens/b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a",
  "created_at": "2023-05-26T04:21:41.350Z",
  "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 token

Token visibility

To ensure the security of tokens, the value is only included in the response for the request to create the token. Subsequent responses do not contain the token value.

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/tokens" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Windows agents", "allowed_ip_addresses": "202.144.0.0/24" }'

{
  "id": "b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "graphql_id": "Q2x1c3RlclRva2VuLS0tYjYwMDE0MTYtMGUxZS00MWM2LTlkYmUtM2Q5Njc2NmY0NTFh",
  "description": "Windows agents",
  "allowed_ip_addresses": "202.144.0.0/24",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a/tokens/b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a",
  "created_at": "2023-05-26T04:21:41.350Z",
  "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"
  },
  "token": "igo6HEj5fxQbgBTDoDzNaZzT"
}

Required request body properties:

description Description for the token.
Example: "Windows agents"

Required scope: write_clusters

Success response: 201 Created

Error responses:

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

Update a token

curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/tokens/{id}" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Windows agents", "allowed_ip_addresses": "202.144.0.0/24" }'

{
  "id": "b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "graphql_id": "Q2x1c3RlclRva2VuLS0tYjYwMDE0MTYtMGUxZS00MWM2LTlkYmUtM2Q5Njc2NmY0NTFh",
  "description": "Windows agents",
  "allowed_ip_addresses": "202.144.0.0/24",
  "url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a/tokens/b6001416-0e1e-41c6-9dbe-3d96766f451a",
  "cluster_url": "http://api.buildkite.com/v2/organizations/test/clusters/e4f44564-d3ea-45eb-87c2-6506643b852a",
  "created_at": "2023-05-26T04:21:41.350Z",
  "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:

description Description for the token.
Example: "Windows agents"

Required scope: write_clusters

Success response: 200 OK

Error responses:

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

Revoke a token

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

Required scope: write_clusters

Success response: 204 No Content

Error responses:

422 Unprocessable Entity { "message": "Reason the token couldn't be revoked" }