# Pipeline settings API

The pipeline settings API endpoint lets organization administrators read and update organization-level pipeline settings. These settings correspond to the options available in the Buildkite **Pipeline Settings** page for your organization.

Both read and write operations require organization administrator privileges (the `change_organization` permission).

## Get pipeline settings

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

```json
{
  "url": "https://api.buildkite.com/v2/organizations/my-great-org/pipeline-settings",
  "default_branch": "main",
  "default_cluster_id": "3f4b6df0-1234-5678-abcd-9e0a1b2c3d4e",
  "default_timeout_in_minutes": 60,
  "maximum_timeout_in_minutes": 120,
  "scheduled_job_expiry_in_minutes": null,
  "hosted_agents_terminal_access": {
    "enabled": true,
    "enabled_at": "2024-06-01T12:00:00.000Z",
    "enabled_by": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Sam Kim"
    }
  },
  "public_pipeline_creation": {
    "enabled": false,
    "enabled_at": null,
    "enabled_by": null
  },
  "advanced_queue_metrics": {
    "enabled": false,
    "enabled_at": null,
    "enabled_by": null,
    "disable_supported": false
  },
  "build_exports": {
    "available": true,
    "enabled": true,
    "location": "my-export-bucket",
    "strategy_id": "s3",
    "supported_strategies": ["s3", "gcs"]
  }
}
```

Required scope: `read_organization_settings`

Success response: `200 OK`

Error responses:



| `403 Forbidden` | The token does not have the `read_organization_settings` scope, or the authenticated user does not have organization administrator privileges. |
| --- | --- |



## Update pipeline settings

Updates one or more simple pipeline settings for the organization. Only the fields you include in the request body are changed.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/pipeline-settings" \
  -d '{
    "default_branch": "main",
    "default_timeout_in_minutes": 60
  }'
```

```json
{
  "url": "https://api.buildkite.com/v2/organizations/my-great-org/pipeline-settings",
  "default_branch": "main",
  "default_cluster_id": null,
  "default_timeout_in_minutes": 60,
  "maximum_timeout_in_minutes": 120,
  "scheduled_job_expiry_in_minutes": null,
  "hosted_agents_terminal_access": {
    "enabled": false,
    "enabled_at": null,
    "enabled_by": null
  },
  "public_pipeline_creation": {
    "enabled": false,
    "enabled_at": null,
    "enabled_by": null
  },
  "advanced_queue_metrics": {
    "enabled": false,
    "enabled_at": null,
    "enabled_by": null,
    "disable_supported": false
  },
  "build_exports": {
    "available": true,
    "enabled": false,
    "location": null,
    "strategy_id": null,
    "supported_strategies": ["s3", "gcs"]
  }
}
```

Required scope: `write_organization_settings`

Success response: `200 OK`

Error responses:



| `403 Forbidden` | The token does not have the `write_organization_settings` scope, or the authenticated user is not an organization administrator. |
| --- | --- |
| `422 Unprocessable Entity` | A field value failed validation—for example, a `default_cluster_id` that is not a syntactically valid UUID, a cluster that belongs to another organization, or a value that fails the organization's own validations. |



### Request body fields



| `default_branch` | The default branch name for new pipelines in the organization. |
| --- | --- |
| `default_cluster_id` | The UUID of the cluster to use as the default for new pipelines. Pass `null` to clear the default cluster. |
| `default_timeout_in_minutes` | The default job timeout in minutes for new pipelines. |
| `maximum_timeout_in_minutes` | The maximum job timeout in minutes that can be set on any pipeline in the organization. |
| `scheduled_job_expiry_in_minutes` | The number of minutes after which scheduled jobs expire if they have not started. |



## Enable hosted agents terminal access

Enables SSH terminal access for hosted agents in the organization. Records who enabled it and when.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/pipeline-settings/hosted-agents-ssh"
```

Returns the full pipeline settings resource.

Required scope: `write_organization_settings`

Success response: `200 OK`

Error responses:



| `403 Forbidden` | The token does not have the `write_organization_settings` scope, or the authenticated user is not an organization administrator. |
| --- | --- |



## Disable hosted agents terminal access

Disables SSH terminal access for hosted agents in the organization.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/pipeline-settings/hosted-agents-ssh"
```

Returns the full pipeline settings resource.

Required scope: `write_organization_settings`

Success response: `200 OK`

Error responses:



| `403 Forbidden` | The token does not have the `write_organization_settings` scope, or the authenticated user is not an organization administrator. |
| --- | --- |



## Enable public pipeline creation

Allows organization members to create public pipelines.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/pipeline-settings/public-pipelines"
```

Returns the full pipeline settings resource.

Required scope: `write_organization_settings`

Success response: `200 OK`

Error responses:



| `403 Forbidden` | The token does not have the `write_organization_settings` scope, or the authenticated user is not an organization administrator. |
| --- | --- |



## Disable public pipeline creation

Prevents organization members from creating public pipelines.

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

Returns the full pipeline settings resource.

Required scope: `write_organization_settings`

Success response: `200 OK`

Error responses:



| `403 Forbidden` | The token does not have the `write_organization_settings` scope, or the authenticated user is not an organization administrator. |
| --- | --- |



## Enable advanced queue metrics

Enables advanced queue metrics for clusters in the organization. This is a one-way operation. Once enabled, it cannot be disabled via the API (the `disable_supported` field in the response will be `false`). To disable advanced queue metrics, contact Buildkite support.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/pipeline-settings/advanced-queue-metrics"
```

Returns the full pipeline settings resource.

Required scope: `write_organization_settings`

Success response: `200 OK`

Error responses:



| `403 Forbidden` | The token does not have the `write_organization_settings` scope, or the authenticated user is not an organization administrator. |
| --- | --- |



## Configure build export

Sets the location and strategy for exporting build data. Build export is a plan-gated feature. The `build_exports.available` field in the response indicates whether it is available on your plan.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/pipeline-settings/build-export" \
  -d '{
    "location": "my-export-bucket",
    "strategy_id": "s3"
  }'
```

Returns the full pipeline settings resource.

Required scope: `write_organization_settings`

Success response: `200 OK`

Error responses:



| `403 Forbidden` | The token does not have the `write_organization_settings` scope, the authenticated user is not an organization administrator, or your billing plan does not include build data export. |
| --- | --- |
| `422 Unprocessable Entity` | `location` is missing or blank, `strategy_id` is missing or not a recognized value, a parameter is the wrong type, or Buildkite cannot validate access to the destination bucket. To clear the export location, use [disable build export](#disable-build-export) instead. |



### Request body fields



| `location` | Required. The destination bucket name, or a fully qualified URI (for example, `s3://my-export-bucket`). If a fully qualified URI is provided, the prefix is stripped automatically so it does not get double-applied. |
| --- | --- |
| `strategy_id` | Required. The export strategy to use. Supported values are listed in the `build_exports.supported_strategies` field of the GET response (for example, `s3` or `gcs`). |



## Disable build export

Clears the build export configuration, stopping further build data exports.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/pipeline-settings/build-export"
```

Returns the full pipeline settings resource.

Required scope: `write_organization_settings`

Success response: `200 OK`

Error responses:



| `403 Forbidden` | The token does not have the `write_organization_settings` scope, the authenticated user is not an organization administrator, or your billing plan does not include build data export. |
| --- | --- |



## Response fields



| `url` | The canonical API URL for this resource. |
| --- | --- |
| `default_branch` | The default branch name for new pipelines in the organization. |
| `default_cluster_id` | The UUID of the default cluster for new pipelines, or `null` if no default cluster is set. |
| `default_timeout_in_minutes` | The default job timeout in minutes for new pipelines. |
| `maximum_timeout_in_minutes` | The maximum job timeout in minutes that can be set on any pipeline. |
| `scheduled_job_expiry_in_minutes` | The number of minutes after which unstarted scheduled jobs expire, or `null` if not set. |
| `hosted_agents_terminal_access` | SSH terminal access settings for hosted agents. Contains: `enabled` — whether SSH terminal access is currently enabled. `enabled_at` — ISO 8601 timestamp when it was enabled, or `null`. `enabled_by` — object with `id` and `name` of the user who enabled it, or `null`. |
| `public_pipeline_creation` | Public pipeline creation settings. Contains: `enabled` — whether members can create public pipelines. `enabled_at` — ISO 8601 timestamp when it was enabled, or `null`. `enabled_by` — object with `id` and `name` of the user who enabled it, or `null`. |
| `advanced_queue_metrics` | Advanced queue metrics settings. Contains: `enabled` — whether advanced queue metrics are enabled. `enabled_at` — ISO 8601 timestamp when it was enabled, or `null`. `enabled_by` — object with `id` and `name` of the user who enabled it, or `null`. `disable_supported` — always `false`; advanced queue metrics cannot be disabled via the API. |
| `build_exports` | Build data export settings. Contains: `available` — whether build data export is available on your billing plan. `enabled` — whether build data export is currently configured. `location` — the destination bucket name, or `null` if not configured. `strategy_id` — the active export strategy (for example, `s3` or `gcs`), or `null`. `supported_strategies` — list of strategy IDs accepted by the configure build export endpoint. |