Teams API

The teams API allows you to view and manage teams within an organization.

Team data model

id ID of the team
name Name of the team
slug URL slug of the team
description Description of the team
privacy Privacy setting of the team (visible, secret)
default Whether users join this team by default (true, false)
created_at Time of when the team was created
created_by User who created the team

List teams

Returns a paginated list of an organization's teams.

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

[
  {
    "id": "c5e09619-8648-4896-a936-9d0b8b7b3fe9",
    "graphql_id": "VGVhbS0tLWM1ZTA5NjE5LTg2NDgtNDg5Ni1hOTM2LTlkMGI4YjdiM2ZlOQ==",
    "name": "Fearless Frontenders",
    "slug": "fearless-frontenders",
    "description": "",
    "created_at": "2023-03-14T00:45:16.215Z",
    "privacy": "secret",
    "default": true,
    "created_by": {
      "id": "8s7ce846-f6c0-4360-8133-389b03c7c46a",
      "graphql_id": "VXNlci0tLTg3NWNlODQ2LWY2YzAtNDM2MC04MTMzLTM4OWIwM2M3YzQ2YQ==",
      "name": "Peter Pettigrew",
      "email": "pp@hogwarts.co.uk",
      "avatar_url": "https://www.gravatar.com/avatar/aa9e3513ea543edb9143cbcca425e56c",
      "created_at": "2022-01-18T02:51:30.983Z"
    }
  },
]

Optional query string parameters:

user_id Filters the results to teams that have the given user as a member.

Example: ?user_id=5acb99cf-d349-4189-b361-d1b9f36d70d7

Required scope: read_teams

Success response: 200 OK

Get a team

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

{
  "id": "c5e09619-8648-4896-a936-9d0b8b7b3fe9",
  "graphql_id": "VGVhbS0tLWM1ZTA5NjE5LTg2NDgtNDg5Ni1hOTM2LTlkMGI4YjdiM2ZlOQ==",
  "name": "Fearless Frontenders",
  "slug": "fearless-frontenders",
  "description": "",
  "created_at": "2023-03-14T00:45:16.215Z",
  "privacy": "secret",
  "default": true,
  "created_by": {
    "id": "8s7ce846-f6c0-4360-8133-389b03c7c46a",
    "graphql_id": "VXNlci0tLTg3NWNlODQ2LWY2YzAtNDM2MC04MTMzLTM4OWIwM2M3YzQ2YQ==",
    "name": "Peter Pettigrew",
    "email": "pp@hogwarts.co.uk",
    "avatar_url": "https://www.gravatar.com/avatar/aa9e3513ea543edb9143cbcca425e56c",
    "created_at": "2022-01-18T02:51:30.983Z"
  }
}

Required scope: view_teams

Success response: 200 OK

Create a team

Creates a team.

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/teams" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Barefoot Backenders",
    "description": "Backend engineers at Acme Inc",
    "privacy": "secret",
    "is_default_team": false,
    "default_member_role": "member",
    "members_can_create_pipelines": true
  }'

{
  "name": "Barefoot Backenders",
  "description": "Backend engineers at Acme Inc",
  "privacy": "secret",
  "is_default_team": false,
  "default_member_role": "member",
  "members_can_create_pipelines": true
}

Required request body properties:

name Name of the team
description Description of the team
privacy Privacy setting of the team (visible, secret)
is_default_team Whether new organization members are assigned to this team by default (true, false)
default_member_role The default role assigned to members of this team (member, maintainer)
members_can_create_pipelines Whether or not team members can create new pipelines (true, false)

Required scope: write_teams

Success response: 201 Created

Error responses:

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

Update a team

Updates an team.

curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/teams/{team.uuid}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New and Improved Backenders V2!",
    "description": "Updated backend engineers team at Acme Inc",
    "privacy": "visible",
    "is_default_team": true,
    "default_member_role": "maintainer",
    "members_can_create_pipelines": false
  }'

{
  "name": "New and Improved Backenders V2!",
  "description": "Updated backend engineers team at Acme Inc",
  "privacy": "visible",
  "is_default_team": true,
  "default_member_role": "maintainer",
  "members_can_create_pipelines": false
}

Required request body properties:

name Name of the team
description Description of the team
privacy Privacy setting of the team (visible, secret)
is_default_team Whether new organization members are assigned to this team by default (true, false)
default_member_role The default role assigned to members of this team (member, maintainer)
members_can_create_pipelines Whether or not team members can create new pipelines (true, false)

Required scope: write_teams

Success response: 200 OK

Error responses:

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

Delete a team

Remove a team.

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

Required scope: write_teams

Success response: 204 No Content

Error responses:

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