---
title: "Update team"
method: PATCH
path: "/teams/{id}"
tags: ["teams"]
---

# Update team

`PATCH /teams/{id}`

Updates the fields and/or members of an existing team.
Supports both field updates via `fields` and member management via `patch` operations.
Both can be combined in a single request.

## Updatable Fields

- `name`: The name of the team (1-255 characters)
- `handle`: Unique handle for @mentions (lowercase alphanumeric only)
- `description`: Optional description of the team (max 10,000 characters)

## Patch Operations on Members

Use `patch` array to manage team members with these operations:

- `addItems`: Add members to the team (idempotent, skips already-present members)
- `removeItems`: Remove members from the team (idempotent, skips already-absent members)
- `set`: Replace entire member list atomically
- `clear`: Remove all members from the team

Maximum 100 member references per operation.

## Response

Returns a reference to the updated team.
Use the GET endpoint to retrieve the full updated team details.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `data` union, required
    - object
      - `fields` TeamCreateOrUpdateFields, required — Fields for creating or updating a team. For creation, `name` and `handle` are required. For updates, the `fields` object is required but all individual field properties within it are optional. **Note:** `avatarUrl` is read-only and cannot be set via API. Avatar management is only available through the UI.
        - `name` string — The name of the team. # Validation - Required for creation - Must be between 1 and 255 characters - Must be unique per workspace # Filtering Supports exact match via `name` parameter and partial match via `query` parameter on GET /v2/teams.
        - `handle` string — Unique handle for @mentions. # Validation - Required for creation - Lowercase letters and numbers only (no uppercase, spaces, or special characters) - Must be unique per workspace
        - `description` string — Optional description of the team. # Validation - Optional field - Maximum length: 10000 characters
      - `patch` TeamPatchOperation[] — Array of patch operations for managing list-type fields (currently: `members`).
        - union — A patch operation for managing list-type fields on a team.
          - object — Operation with a value (addItems, removeItems, set)
            - `op` 'addItems' | 'removeItems' | 'set', required — The operation type.
            - `path` 'members', required — The field to operate on.
            - `value` union[], required — Member references for the operation. Each item must include either `id` (space membership UUID) or `email`.
              - …
          - object — Clear operation (no value needed)
            - `op` 'clear', required — Clear all items from the field.
            - `path` 'members', required — The field to clear.
    - object
      - `fields` TeamCreateOrUpdateFields — Fields for creating or updating a team. For creation, `name` and `handle` are required. For updates, the `fields` object is required but all individual field properties within it are optional. **Note:** `avatarUrl` is read-only and cannot be set via API. Avatar management is only available through the UI.
        - `name` string — The name of the team. # Validation - Required for creation - Must be between 1 and 255 characters - Must be unique per workspace # Filtering Supports exact match via `name` parameter and partial match via `query` parameter on GET /v2/teams.
        - `handle` string — Unique handle for @mentions. # Validation - Required for creation - Lowercase letters and numbers only (no uppercase, spaces, or special characters) - Must be unique per workspace
        - `description` string — Optional description of the team. # Validation - Optional field - Maximum length: 10000 characters
      - `patch` TeamPatchOperation[], required — Array of patch operations for managing list-type fields (currently: `members`).
        - union — A patch operation for managing list-type fields on a team.
          - object — Operation with a value (addItems, removeItems, set)
            - `op` 'addItems' | 'removeItems' | 'set', required — The operation type.
            - `path` 'members', required — The field to operate on.
            - `value` union[], required — Member references for the operation. Each item must include either `id` (space membership UUID) or `email`.
              - …
          - object — Clear operation (no value needed)
            - `op` 'clear', required — Clear all items from the field.
            - `path` 'members', required — The field to clear.

## Response `200`

Team updated successfully

- TeamReferenceResponse — Response wrapper containing a team reference.
  - `data` TeamReference, required — Minimal reference to a team resource containing only identifying information.
    - `id` string, uuid, required — Unique identifier of the team
    - `type` 'team', required — Resource type identifier
    - `links` TeamLinks, required — Links for navigating team resources.
      - `self` string, uri, required — URL of the team resource.
      - `members` string, uri, required — URL of the paginated team members sub-resource.
      - `html` string, uri, required — URL of the team page in the Productboard UI.

## Other responses

- `400` — Bad Request - Invalid input format or malformed request
- `401` — Unauthorized - Missing or invalid authentication credentials
- `403` — Forbidden - Insufficient permissions
- `404` — Not Found - The requested resource does not exist or is not accessible
- `408` — Request Timeout - The server did not receive a complete request within the allowed time
- `409` — Conflict - Action cannot be performed due to current state or constraint violation
- `422` — Unprocessable Entity - Validation failed (e.g., missing required fields, unknown fields)
- `429` — Too Many Requests - API rate limit exceeded, reduce request frequency and retry after the indicated time
- `500` — Internal Server Error - An unexpected error occurred on the server, please retry or contact support

---

[API](https://skmtc.dev/productboard/apis/notes.md) · [All operations](https://skmtc.dev/productboard/apis/notes/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/productboard/notes/revisions/b4004749b60f/schema)