Team members API

The team members API allows users to review, create, update, and delete members associated with a team in your organization.

Team member data model

user_name The name of the user
user_id The UUID of the user
created_at When the team and user association was created
role The role the member has within the team - member or maintainer

List team members

Returns a list of a team's associated members.

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

[
  {
    "role": "member",
    "created_at": "2023-03-14T00:49:55.534Z",
    "user_id": "978ce846-f6c0-4360-8133-389b03cus7a",
    "user_name": "Severus Snape"
  },
  {
    "role": "member",
    "created_at": "2023-03-14T00:49:55.534Z",
    "user_id": "3878ce86-f6c0-4360-8133-389b0372",
    "user_name": "Draco Malfoy"
  },
]

Required scope: view_teams

Success response: 200 OK

Get a team member

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

{
  "role": "member",
  "created_at": "2023-12-15T00:23:23.823Z",
  "user_id": "018c6030-b459-45b2-a844-951f0fc8a4e7",
  "user_name": "Dolores Umbridge"
}

Required scope: view_teams

Success response: 200 OK

Create a team member

Creates an association between a team and a user.

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/teams/{team.uuid}/members/" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "6030-b459-45b2-a844-951f0fs727",
    "role": "maintainer"
  }'

{
  "role": "maintainer",
  "created_at": "2023-12-14T00:43:04.675Z",
  "user_id": "875ce846-f6c0-4360-8133-389b03c7c46a",
  "user_name": "Professor Quirrel"
}

Required request body properties:

user_id The UUID of the user.
role The role the member has within the team - member or maintainer

Required scope: write_teams

Success response: 201 Created

Error responses:

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

Update a team member

Updates an association between a team and a user.

curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/teams/{team.uuid}/members/{user.uuid}" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "member"
  }'

{
  "role": "member",
  "created_at": "2023-12-15T00:23:23.823Z",
  "user_id": "027c6030-b459-45b2-a844-951f0fc8a4e7",
  "user_name": "Ron Weasley"
}

Required request body properties:

role The role the member has within the team - member or maintainer

Required scope: write_teams

Success response: 200 OK

Error responses:

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

Delete a team member

Remove the association between a team and a user.

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

Required scope: write_teams

Success response: 204 No Content

Error responses:

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