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

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

{
  "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.

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

{
  "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.

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.

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.

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.

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.

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.

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 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.

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.