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=",
    "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"
  }
]

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=",
  "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"
}

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=",
  "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"
}

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. This is the only way to view the suite's API token via the REST API.
Default value: false.
teams_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"
color Color for the suite navatar.
Example: "#FFF700"
emoji Emoji for the suite navatar. Check out our documentation for supported emoji.
Example: "🍋", ":lemon:"

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=",
  "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"
}

Optional request body properties:

name Name of the 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".
application_name Application name for the suite.
Example: "Buildkite"
color Color for the suite navatar.
Example: "#ffb7c5"
emoji Emoji for the suite navatar. Check out our documentation for supported emoji.
Example: "🌸", ":cherry_blossom:"

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