---
title: "Update a team"
method: PATCH
path: "/v1/teams/{teamId}"
tags: ["Teams"]
---

# Update a team

`PATCH /v1/teams/{teamId}`

## Request

- Base URL: `https://api.telgea.com`
- URL: `https://api.telgea.com/v1/teams/{teamId}`
- Auth: API key in header `x-api-key`

Updates an existing team's information. All fields are optional - only provide the fields you want to update.

You can update basic information like name, emoji, and cost center code. Providing `userIds` replaces the team's full membership: users in the list are added, and users not in the list move to the default team, Unassigned.

The default team (`isDefault: true` in GET /v1/teams) cannot be updated.

## Path parameters

- `teamId` string, uuid, required: UUID of the team.

## Headers

- `idempotency-key` string: A value unique to this request, of 1 to 255 printable ASCII characters — a UUID is the usual choice. Retry with the same key within 24 hours and you get the original response back, even if it was a failure, and nothing is done twice. Send a new key whenever you change the request. Keys are private to your API key and organisation.

## Request body

- UpdateTeamBody
  - `name` string: Team name
  - `emoji` string: Emoji representing the team
  - `costCode` string: Cost center code applied to all users in this team
  - `userIds` string[]: Full desired member list. When provided, replaces the team's membership: users not in the list are removed, new user IDs are added.

## Response `204`

Team updated successfully. No content returned.

## Other responses

- `400`: Request failed schema validation, or was refused by a business rule
- `401`: Missing or invalid API key in the X-API-Key header
- `403`: Insufficient permissions to update teams
- `404`: Team not found, or a user id in `userIds` is not in your organization
- `409`: This is your organization's default team, Unassigned, so it cannot be changed.
- `429`: The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.
- `500`: Internal server error. Contact support if this persists.

---

[API](https://skmtc.dev/telgea/apis/telgea-api.md) - [All operations](https://skmtc.dev/telgea/apis/telgea-api/llms.txt) - [OpenAPI document](https://skmtc.dev/telgea/apis/telgea-api/revisions/4e8f8c04fe9e?raw)