# Team suites API

The team suites API endpoint allows users to review, create, update, and delete test suites associated with a team in your organization.

## Team suite data model



| `suite_id` | UUID of the suite |
| --- | --- |
| `suite_url` | URL of the suite |
| `created_at` | When the team and suite association was created |
| `access_level` | The access levels that user has to the associated suite - `edit`, `read` |



## List team suites

Returns a list of a team's associated suites.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/teams/{team.uuid}/suites"
```

```json
[
  {
    "access_level": [ "read" ],
    "created_at": "2024-01-11T04:24:21.352Z",
    "suite_id": "19f3973d-1e0b-43f1-b490-22be52abd99a",
    "suite_url": "https://api.buildkite.com/v2/analytics/organizations/acme-corp/suites/suite-dreams"
  },
  {
    "access_level": [ "read", "edit" ],
    "created_at": "2024-01-11T04:24:21.352Z",
    "suite_id": "19f3973d-1e0b-43f1-b490-22besa5299a",
    "suite_url": "https://api.buildkite.com/v2/analytics/organizations/acme-corp/suites/suite-and-sour"
  }
]
```

Required scope: `view_teams`

Success response: `200 OK`

## Get a team suite

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/teams/{team.uuid}/suites/{suite.uuid}"
```

```json
{
  "access_level": [ "read" ],
  "created_at": "2024-01-11T04:24:21.352Z",
  "suite_id": "19f3973d-1e0b-43f1-b490-22besa5299a",
  "suite_url": "https://api.buildkite.com/v2/analytics/organizations/acme-corp/suites/suite-and-sour"
}
```

Required scope: `view_teams`

Success response: `200 OK`

## Create a team suite

Creates an association between a team and a suite.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/teams/{team.uuid}/suites/" \
  -H "Content-Type: application/json" \
  -d '{
    "suite_id": suite.uuid,
    "access_level": ["read", "edit"]
  }'
```

```json
{
  "access_level": [ "read", "edit" ],
  "created_at": "2024-01-11T04:39:18.638Z",
  "suite_id": "192k973d-1e0b-43f1-b490-22be52abd99a",
  "suite_url": "https://api.buildkite.com/v2/analytics/organizations/acme-inc/suites/suiteheart"
}
```

Required [request body properties](/docs/api#request-body-properties):



| `suite_id` | The UUID of the suite. |
| --- | --- |
| `access_level` | The access levels for team members to the associated suite - `read`, `edit` |



Required scope: `write_teams`

Success response: `201 Created`

Error responses:



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



## Update a team suite

Updates an association between a team and a suite.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/teams/{team.uuid}/suites/{suite.uuid}" \
  -H "Content-Type: application/json" \
  -d '{
    "access_level": ["edit", "read"]"
  }'
```

```json
{
  "access_level": [ "edit", "read" ],
  "created_at": "2024-01-11T04:56:53.516Z",
  "suite_id": "19f3973d-1e0b-43f1-b490-22be52abd99a",
  "suite_url": "https://api.buildkite.com/v2/analytics/organizations/acme-inc/suites/suiteness"
}
```

Required [request body properties](/docs/api#request-body-properties):



| `access_level` | The access level for the suite - `read` or `edit` |
| --- | --- |



Required scope: `write_teams`

Success response: `200 OK`

Error responses:



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



## Delete a team suite

Remove the association between a team and a suite.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/teams/{team.uuid}/suites/{suite.uuid}/"
```

Required scope: `write_teams`

Success response: `204 No Content`

Error responses:



| `422 Unprocessable Entity` | `{ "message": "Reason the team suite couldn't be deleted" }` |
| --- | --- |