# Cluster maintainers

Cluster maintainers permissions can be assigned to a list of [Users or teams](/docs/platform/team-management/permissions), or both. This grants assignees the ability to manage the [Buildkite clusters they maintain](/docs/pipelines/security/clusters/manage#manage-maintainers-on-a-cluster).

## Cluster maintainer data model



| `id` | The ID of the cluster maintainer assignment. |
| --- | --- |
| `actor` | Metadata on the assigned User or Team |



## List cluster maintainers

Returns a list of [maintainers](/docs/pipelines/security/clusters/manage#manage-maintainers-on-a-cluster) on a [cluster](/docs/pipelines/security/clusters).

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

```json
[
	{
		"id": "f6cf1097-c9c5-4492-885f-a2d3281a07dd",
		"actor": {
			"id": "01973824-0c57-45ae-a440-638fceb3ec06",
			"graphql_id": "VXNlci0tLTAxOTczODI0LTBjNTctNDVhZS1hNDQwLTYzOGZjZWIzZWMwNg==",
			"name": "Staff",
			"email": "staff@example.com",
			"type": "user"
		}
	},
	{
		"id": "282a043f-4d4f-4db5-ac9a-58673ae02caf",
		"actor": {
			"id": "0da645b7-9840-428f-bd80-0b92ee274480",
			"graphql_id": "VGVhbS0tLTBkYTY0NWI3LTk4NDAtNDI4Zi1iZDgwLTBiOTJlZTI3NDQ4MA==",
			"slug": "Developers",
			"type": "team"
		}
	}
]
```

Required scope: `read_clusters`

Success response: `200 OK`

## Get a cluster maintainer

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

```json
{
	"id": "282a043f-4d4f-4db5-ac9a-58673ae02caf",
	"actor": {
		"id": "0da645b7-9840-428f-bd80-0b92ee274480",
		"graphql_id": "VGVhbS0tLTBkYTY0NWI3LTk4NDAtNDI4Zi1iZDgwLTBiOTJlZTI3NDQ4MA==",
		"slug": "Developers",
		"type": "team"
	}
}
```

Required scope: `read_clusters`

Success response: `200 OK`

## Create a cluster maintainer

Assigns [cluster maintainer](/docs/pipelines/security/clusters/manage#manage-maintainers-on-a-cluster) permissions to a [user or team](/docs/platform/team-management/permissions).

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/maintainers" \
  -H "Content-Type: application/json" \
  -d '{ "team": "0da645b7-9840-428f-bd80-0b92ee274480" }'
```

```json
{
	"id": "282a043f-4d4f-4db5-ac9a-58673ae02caf",
	"actor": {
		"id": "0da645b7-9840-428f-bd80-0b92ee274480",
		"graphql_id": "VGVhbS0tLTBkYTY0NWI3LTk4NDAtNDI4Zi1iZDgwLTBiOTJlZTI3NDQ4MA==",
		"slug": "Developers",
		"type": "team"
	}
}
```

### Cluster maintainer permission target

Cluster maintainer permissions can be targeted to either a [user or team](/docs/platform/team-management/permissions) by specifying either a `user` or `team` field as the target in the request body, along with the target's UUID for its value.



| `user` | UUID of the user | `{ "user: "282a043f-4d4f-4db5-ac9a-58673ae02caf" }` |
| --- | --- | --- |
| `team` | UUID of the team | `{ "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" }` |
| --- | --- |



## Remove a cluster maintainer

Remove cluster maintainer permissions from a [user or team](/docs/platform/team-management/permissions).

```bash
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": "Validation failed: Reason cluster maintainer permission could not be deleted" }` |
| --- | --- |