# Team pipelines API

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

## Team pipeline data model



| `pipeline_id` | UUID of the pipeline |
| --- | --- |
| `access_level` | The access levels that users have to the associated pipeline - `read_only`, `build_and_read`, `manage_build_and_read` |
| `pipeline_url` | URL of the pipeline |
| `created_at` | When the team and pipeline association was created |



## List team pipelines

Returns a [paginated list](/docs/rest-api#pagination) of a team's associated pipelines.

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

```json
[
  {
    "access_level": "manage_build_and_read",
    "created_at": "2023-12-12T21:57:40.306Z",
    "pipeline_id": "018c5ad7-28f1-45d4-867e-b59fa04511b2",
    "pipeline_url": "http://api.buildkite.com/v2/organizations/acme-inc/pipelines/test-pipeline"
  },
]
```

Required scope: `view_teams`

Success response: `200 OK`

## Get a team pipeline

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

```json
{
  "access_level": "read_only",
  "created_at": "2023-12-12T21:57:40.306Z",
  "pipeline_id": "018c5ad7-28f1-45d4-867e-b59fa04511b2",
  "pipeline_url": "http://api.buildkite.com/v2/organizations/acme-inc/pipelines/test-pipeline"
}
```

Required scope: `view_teams`

Success response: `200 OK`

## Create a team pipeline

Creates an association between a team and a pipeline.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/teams/{team.uuid}/pipelines/" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": "pipeline.uuid",
    "access_level": "read_only"
  }'
```

```json
{
  "access_level": "read",
  "created_at": "2023-12-12T21:57:40.306Z",
  "pipeline_id": "018c5ad7-28f1-45d4-867e-b59fa04511b2",
  "pipeline_url": "http://api.buildkite.com/v2/organizations/acme-inc/pipelines/test-pipeline"
}
```

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



| `pipeline_id` | The UUID of the pipeline. |
| --- | --- |
| `access_level` | The access level for the pipeline - `read_only`, `build_and_read` or `manage_build_and_read`. |



Required scope: `write_teams`

Success response: `201 Created`

Error responses:



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



## Update a team pipeline

Updates an association between a team and a pipeline.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/teams/{team.uuid}/pipelines/{pipeline.uuid}" \
  -H "Content-Type: application/json" \
  -d '{
    "access_level": "read_only"
  }'
```

```json
{
  "access_level": "read_only",
  "created_at": "2023-12-12T21:57:40.306Z",
  "pipeline_id": "018c5ad7-28f1-45d4-867e-b59fa04511b2",
  "pipeline_url": "http://api.buildkite.com/v2/organizations/acme-inc/pipelines/test-pipeline"
}
```

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



| `access_level` | The access level for the pipeline - `read_only`, `build_and_read` or `manage_build_and_read`. |
| --- | --- |



Required scope: `write_teams`

Success response: `200 OK`

Error responses:



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



## Delete a team pipeline

Remove the association between a team and a pipeline.

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

Required scope: `write_teams`

Success response: `204 No Content`

Error responses:



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