Teams API

The teams API endpoint 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: read_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,
    "members_can_create_suites": true,
    "members_can_create_registries": true,
    "members_can_destroy_registries": false,
    "members_can_destroy_packages": false
  }'

{
  "name": "Barefoot Backenders",
  "description": "Backend engineers at Acme Inc",
  "privacy": "secret",
  "is_default_team": false,
  "default_member_role": "member",
  "members_can_create_pipelines": true,
  "members_can_create_suites": true,
  "members_can_create_registries": true,
  "members_can_destroy_registries": false,
  "members_can_destroy_packages": 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`)
`members_can_create_suites`	Whether or not team members can create new test suites (`true`, `false`)
`members_can_create_registries`	Whether or not team members can create new registries (`true`, `false`)
`members_can_destroy_registries`	Whether or not team members can destroy registries (`true`, `false`)
`members_can_destroy_packages`	Whether or not team members can destroy packages (`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 a 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,
    "members_can_create_suites": false,
    "members_can_create_registries": true,
    "members_can_destroy_registries": false,
    "members_can_destroy_packages": 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,
  "members_can_create_suites": false,
  "members_can_create_registries": true,
  "members_can_destroy_registries": false,
  "members_can_destroy_packages": 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`)
`members_can_create_suites`	Whether or not team members can create new test suites (`true`, `false`)
`members_can_create_registries`	Whether or not team members can create new registries (`true`, `false`)
`members_can_destroy_registries`	Whether or not team members can destroy registries (`true`, `false`)
`members_can_destroy_packages`	Whether or not team members can destroy packages (`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" }`

Enables team-based permissions for the organization. This endpoint performs the same action as the Enable Teams button in the Buildkite web interface. If the organization has no existing teams, enabling teams creates a default "Everyone" team containing all organization members.

This endpoint is idempotent. If teams are already enabled, it returns 204 No Content without making further changes.

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

Required scope: write_teams

Required permission: Organization administrator

Success response: 204 No Content

Error responses:

`403 Forbidden`	`{ "message": "Your plan doesn't include team permissions. Upgrade your plan to enable teams." }`