Suites API

List all suites

Returns a paginated list of an organization's suites.

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

[
  {
    "id": "3e979a94-a479-4a6e-ab8d-8b6607ffb62c",
    "graphql_id": "U3VpdGUtLS0zZTk3OWE5NC1hNDc5LTRhNmUtYWI4ZC04YjY2MDdmZmI2MmM=",
    "organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "slug":"my_suite_slug",
    "name":"My suite name",
    "url":"https://api.buildkite.com/v2/analytics/organizations/my_great_org/suites/my_suite_slug",
    "web_url":"https://buildkite.com/organizations/my_great_org/analytics/suites/my_suite_slug",
    "default_branch":"main",
    "application_name": "Buildkite",
    "color": "#FFF700",
    "emoji": "🍋",
    "oidc_policy": null,
    "test_state_management": false,
    "allowed_test_states": []
  }
]

Optional query string parameters:

`show_api_token`	Return the suite's API token in the response. A 403 Forbidden error is returned if the user does not have permission to view the suite's API token. Default value: `false`. Example: `?show_api_token=true`

Required scope: read_suites

Success response: 200 OK

Returns a paginated list of the Buildkite Test Engine suites that have recorded at least one run attributed to a pipeline, ordered by creation time. Each suite is returned once, even if it has recorded several runs for the pipeline.

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

[
  {
    "id": "3e979a94-a479-4a6e-ab8d-8b6607ffb62c",
    "graphql_id": "U3VpdGUtLS0zZTk3OWE5NC1hNDc5LTRhNmUtYWI4ZC04YjY2MDdmZmI2MmM=",
    "organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "slug":"my_suite_slug",
    "name":"My suite name",
    "url":"https://api.buildkite.com/v2/analytics/organizations/my_great_org/suites/my_suite_slug",
    "web_url":"https://buildkite.com/organizations/my_great_org/analytics/suites/my_suite_slug",
    "default_branch":"main",
    "application_name": "Buildkite",
    "color": "#FFF700",
    "emoji": "🍋",
    "oidc_policy": null,
    "test_state_management": false,
    "allowed_test_states": []
  }
]

Required scope: read_suites

Success response: 200 OK

Get a suite

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

{
  "id": "3e979a94-a479-4a6e-ab8d-8b6607ffb62c",
  "graphql_id": "U3VpdGUtLS0zZTk3OWE5NC1hNDc5LTRhNmUtYWI4ZC04YjY2MDdmZmI2MmM=",
  "organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "slug":"my_suite_slug",
  "name":"My suite name",
  "url":"https://api.buildkite.com/v2/analytics/organizations/my_great_org/suites/my_suite_slug",
  "web_url":"https://buildkite.com/organizations/my_great_org/analytics/suites/my_suite_slug",
  "default_branch":"main",
  "application_name": "Buildkite",
  "color": "#FFF700",
  "emoji": "🍋",
  "oidc_policy": null,
  "test_state_management": false,
  "allowed_test_states": []
}

Optional query string parameters:

`show_api_token`	Return the suite's API token in the response. A 403 Forbidden error is returned if the user does not have permission to view the suite's API token. Default value: `false`. Example: `?show_api_token=true`

Required scope: read_suites

Success response: 200 OK

Create a suite

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/analytics/organizations/{org.slug}/suites" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jasmine",
    "default_branch": "main",
    "application_name": "Buildkite",
    "color": "#FFF700",
    "emoji": "🍋",
    "show_api_token": true,
    "team_ids": ["3f4aa5ee-671b-41b0-9b44-b94831db6cc8"]
  }'

{
  "id": "3e979a94-a479-4a6e-ab8d-8b6607ffb62c",
  "graphql_id": "U3VpdGUtLS0zZTk3OWE5NC1hNDc5LTRhNmUtYWI4ZC04YjY2MDdmZmI2MmM=",
  "organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "slug": "jasmine",
  "name": "Jasmine",
  "url": "https://api.buildkite.com/v2/analytics/organizations/my_great_org/suites/jasmine",
  "web_url": "https://buildkite.com/organizations/my_great_org/analytics/suites/jasmine",
  "default_branch": "main",
  "application_name": "Buildkite",
  "color": "#FFF700",
  "emoji": "🍋",
  "api_token": "AAAAAAAAAAAAAAAAAAAAAAAA",
  "oidc_policy": null,
  "test_state_management": false,
  "allowed_test_states": []
}

Required request body properties:

`name`	Name of the new suite. Example: `"Jasmine"`.
`default_branch`	Your test suite will default to showing trends for this default branch, but collect data for all test runs. Example: `"main"` or `"master"`.

Optional request body properties:

`show_api_token`	Return the suite's API token in the response. Default value: `false`.
`team_ids`	An array of team UUIDs to add this suite to. You can find your team's UUID either using the GraphQL API, or on the Settings page for a team. This property is only available if your organization has enabled Teams, in which case it is a required field. Example: `"team_ids": ["3f4aa5ee-671b-41b0-9b44-b94831db6cc8"]`
`application_name`	Application name for the suite. Example: `"Buildkite"`
`repo_url`	HTTPS URL of the repository for the suite. Example: `"https://example.com/acme/app"`.
`color`	Color for the suite navatar. Example: `"#FFF700"`
`emoji`	Emoji for the suite navatar. Check out our documentation for supported emoji. Example: `"🍋"`, `":lemon:"`
`oidc_policy`	The OIDC policy for the suite, as a YAML string or a JSON array of policy statements. Pass `null` to clear the policy. Example: `"- iss: \"https://agent.buildkite.com\"\n claims:\n organization_slug: my-org\n pipeline_slug: my-pipeline\n scopes:\n - read_suites\n - write_uploads\n"`
`flaky_detection`	Set to `false` if you don't want to create the `flaky` label and the default flaky test detection workflow. The default workflow is created only when your plan includes workflows. This option applies only when creating a suite. Default value: `true`.
`test_state_management`	Enable test state management for the suite. Requires a Pro or Enterprise plan. Default value: `false`.
`allowed_test_states`	An array of allowed quarantine states: `"muted"`, `"skipped"`, or both. Requires `test_state_management` to be enabled to use these states. Do not include `"enabled"`, which is always available. Default value: `[]`. Example: `["muted", "skipped"]`.

Required scope: write_suites

Success response: 201 Created

Update a suite

curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://api.buildkite.com/v2/analytics/organizations/{org.slug}/suites/{suite.slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jasmine",
    "default_branch": "main"
  }'

{
  "id": "3e979a94-a479-4a6e-ab8d-8b6607ffb62c",
  "graphql_id": "U3VpdGUtLS0zZTk3OWE5NC1hNDc5LTRhNmUtYWI4ZC04YjY2MDdmZmI2MmM=",
  "organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "slug": "jasmine",
  "name": "Jasmine",
  "url": "https://api.buildkite.com/v2/analytics/organizations/my_great_org/suites/jasmine",
  "web_url": "https://buildkite.com/organizations/my_great_org/analytics/suites/jasmine",
  "default_branch": "main",
  "application_name": "Buildkite",
  "color": "#FFF700",
  "emoji": "🍋",
  "oidc_policy": null,
  "test_state_management": false,
  "allowed_test_states": []
}

Optional request body properties:

`name`	Name of the suite. Changing the name regenerates the suite's `slug`. Use the returned `slug` or `url` for subsequent requests. Example: `"Jasmine"`.
`default_branch`	Your test suite will default to showing trends for this default branch, but collect data for all test runs. Example: `"main"` or `"master"`.
`application_name`	Application name for the suite. Example: `"Buildkite"`
`repo_url`	HTTPS URL of the repository for the suite. Example: `"https://example.com/acme/app"`.
`color`	Color for the suite navatar. Example: `"#ffb7c5"`
`emoji`	Emoji for the suite navatar. Check out our documentation for supported emoji. Example: `"🌸"`, `":cherry_blossom:"`
`show_api_token`	Return the suite's API token in the response. Default value: `false`.
`oidc_policy`	The OIDC policy for the suite, as a YAML string or a JSON array of policy statements. Pass `null` to clear the policy. Example: `"- iss: \"https://agent.buildkite.com\"\n claims:\n organization_slug: my-org\n pipeline_slug: my-pipeline\n scopes:\n - read_suites\n - write_uploads\n"`
`test_state_management`	Enable or disable test state management for the suite. Requires a Pro or Enterprise plan. Disabling permanently resets all muted and skipped tests to enabled. Re-enabling does not restore their previous states.
`allowed_test_states`	Replace the allowed quarantine states with an array containing `"muted"`, `"skipped"`, or both. Do not include `"enabled"`, which is always available. A state cannot be removed while tests use it or it is the automatic-quarantine default. Pass `[]` to allow only enabled tests. Example: `["muted", "skipped"]`.

Required scope: write_suites

Success response: 200 OK

Delete a suite

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

Required scope: write_suites

Success response: 204 No Content

Suites API

List all suites

List suites for a pipeline

Get a suite

Create a suite

Update a suite

Delete a suite