---
title: "Update team"
method: PATCH
path: "/api/v2/teams/{teamKey}"
tags: ["Teams"]
---

# Update team

`PATCH /api/v2/teams/{teamKey}`

Perform a partial update to a team. Updating a team uses the semantic patch format.

To make a semantic patch request, you must append `domain-model=launchdarkly.semanticpatch` to your `Content-Type` header. To learn more, read [Updates using semantic patch](https://launchdarkly.com/docs/api#updates-using-semantic-patch).

### Instructions

Semantic patch requests support the following `kind` instructions for updating teams. Several of the instructions require one or more member IDs as parameters. The member ID is returned as part of the [List account members](https://launchdarkly.com/docs/api/account-members/get-members) response. It is the `_id` field of each element in the `items` array.


<details>
<summary>Click to expand instructions for <strong>updating teams</strong></summary>

#### addCustomRoles

Adds custom roles to the team. Team members will have these custom roles granted to them.

##### Parameters

- `values`: List of custom role keys.

Here's an example:

```json
{
  "instructions": [{
    "kind": "addCustomRoles",
    "values": [ "example-custom-role" ]
  }]
}
```

#### addMembers

Adds members to the team.

##### Parameters

- `values`: List of member IDs to add.

Here's an example:

```json
{
  "instructions": [{
    "kind": "addMembers",
    "values": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
  }]
}
```

#### addPermissionGrants

Adds permission grants to members for the team. For example, a permission grant could allow a member to act as a team maintainer. A permission grant may have either an `actionSet` or a list of `actions` but not both at the same time. The members do not have to be team members to have a permission grant for the team.

##### Parameters

- `actionSet`: Name of the action set.
- `actions`: List of actions.
- `memberIDs`: List of member IDs.

Here's an example:

```json
{
  "instructions": [{
    "kind": "addPermissionGrants",
    "actions": [ "updateTeamName", "updateTeamDescription" ],
    "memberIDs": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
  }]
}
```

#### addRoleAttribute

Adds a role attribute to a team. Team members will have these role attribute values scoped for all custom roles granted to them.

##### Parameters

- `key`: The role attribute key to add.
- `values`: List of role attribute values for that key.

Here's an example:

```json
{
  "instructions": [
    {
      "kind": "addRoleAttribute",
      "key": "testAttribute",
      "values": ["someNewValue", "someOtherNewValue"]
    }
  ]
}
```

#### removeCustomRoles

Removes custom roles from the team. The app will no longer grant these custom roles to the team members.

##### Parameters

- `values`: List of custom role keys.

Here's an example:

```json
{
  "instructions": [{
    "kind": "removeCustomRoles",
    "values": [ "example-custom-role" ]
  }]
}
```

#### removeMembers

Removes members from the team.

##### Parameters

- `values`: List of member IDs to remove.

Here's an example:

```json
{
  "instructions": [{
    "kind": "removeMembers",
    "values": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
  }]
}
```

#### removePermissionGrants

Removes permission grants from members for the team. A permission grant may have either an `actionSet` or a list of `actions` but not both at the same time. The `actionSet` and `actions` must match an existing permission grant.

##### Parameters

- `actionSet`: Name of the action set.
- `actions`: List of actions.
- `memberIDs`: List of member IDs.

Here's an example:

```json
{
  "instructions": [{
    "kind": "removePermissionGrants",
    "actions": [ "updateTeamName", "updateTeamDescription" ],
    "memberIDs": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
  }]
}
```

#### removeRoleAttribute

Removes a role attribute from the team.

##### Parameters

- `key`: The role attribute key to remove.

Here's an example:
```json
{
  "instructions": [
    {
      "kind": "removeRoleAttribute",
      "key": "testAttribute"
    }
  ]
}
```

#### replaceMembers

Replaces the existing members of the team with the new members.

##### Parameters

- `values`: List of member IDs of the new members.

Here's an example:

```json
{
  "instructions": [{
    "kind": "replaceMembers",
    "values": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
  }]
}
```

#### replaceRoleAttributes

Replaces the existing role attributes for the team with new role attributes.

##### Parameters

- `value`: A map of role attribute keys to lists of role attribute values

Here's an example:

```json
{
  "instructions": [{
    "kind": "replaceRoleAttributes",
    "value": {
      "testAttribute": [ "someNewValue", "someOtherNewValue" ],
      "projectRoleAttribute": [ "project1", "project2"]
    }
  }]
}
```

#### updateDescription

Updates the description of the team.

##### Parameters

- `value`: The new description.

Here's an example:

```json
{
  "instructions": [{
    "kind": "updateDescription",
    "value": "Updated team description"
  }]
}
```

#### updateName

Updates the name of the team.

##### Parameters

- `value`: The new name.

Here's an example:

```json
{
  "instructions": [{
    "kind": "updateName",
    "value": "Updated team name"
  }]
}
```

#### updateRoleAttribute

Updates a role attribute on the team. Any existing values for the given key will be replaced with the new values. Team members will have these role attribute values scoped for all custom roles granted to them.

##### Parameters

- `key`: The role attribute key to update.
- `values`: List of role attribute values for that key.

Here's an example:
```json
{
  "instructions": [
    {
      "kind": "updateRoleAttribute",
      "key": "testAttribute",
      "values": ["someNewValue", "someOtherNewValue"]
    }
  ]
}
```

</details>

### Expanding the teams response
LaunchDarkly supports four fields for expanding the "Update team" response. By default, these fields are **not** included in the response.

To expand the response, append the `expand` query parameter and add a comma-separated list with any of the following fields:

* `members` includes the total count of members that belong to the team.
* `roles` includes a paginated list of the custom roles that you have assigned to the team.
* `projects` includes a paginated list of the projects that the team has any write access to.
* `maintainers` includes a paginated list of the maintainers that you have assigned to the team.

For example, `expand=members,roles` includes the `members` and `roles` fields in the response.

## Path parameters

- `teamKey` string, string, required — The team key

## Query parameters

- `expand` string, string — A comma-separated list of properties that can reveal additional information in the response. Supported fields are explained above.

## Request body

- TeamPatchInput
  - `comment` string — Optional comment describing the update
  - `instructions` Instruction[], required

## Response `200`

Teams response

- Team
  - `description` string — A description of the team
  - `key` string — The team key
  - `name` string — A human-friendly name for the team
  - `_access` Access
    - `denied` AccessDenied[], required
      - `action` string, required
      - `reason` AccessDeniedReason, required
        - `resources` string[] — Resource specifier strings
        - `notResources` string[] — Targeted resources are the resources NOT in this list. The <code>resources</code> and <code>notActions</code> fields must be empty to use this field.
        - `actions` ActionSpecifier[] — Actions to perform on a resource
        - `notActions` ActionSpecifier[] — Targeted actions are the actions NOT in this list. The <code>actions</code> and <code>notResources</code> fields must be empty to use this field.
        - `effect` 'allow' | 'deny', required — Whether this statement should allow or deny actions on the resources.
        - `role_name` string
    - `allowed` AccessAllowedRep[], required
      - `action` string, required
      - `reason` AccessAllowedReason, required
        - `resources` string[] — Resource specifier strings
        - `notResources` string[] — Targeted resources are the resources NOT in this list. The <code>resources</code> and <code>notActions</code> fields must be empty to use this field.
        - `actions` ActionSpecifier[] — Actions to perform on a resource
        - `notActions` ActionSpecifier[] — Targeted actions are the actions NOT in this list. The <code>actions</code> and <code>notResources</code> fields must be empty to use this field.
        - `effect` 'allow' | 'deny', required — Whether this statement should allow or deny actions on the resources.
        - `role_name` string
  - `_creationDate` integer
  - `_links` object — The location and content type of related resources
  - `_lastModified` integer
  - `_version` integer — The team version
  - `_idpSynced` boolean — Whether the team has been synced with an external identity provider (IdP). Team sync is available to customers on an Enterprise plan.
  - `roleAttributes` RoleAttributeMap
  - `roles` TeamCustomRoles
    - `totalCount` integer — The number of custom roles assigned to this team
    - `items` TeamCustomRole[] — An array of the custom roles that have been assigned to this team
      - `key` string — The key of the custom role
      - `name` string — The name of the custom role
      - `projects` TeamProjects
        - `totalCount` integer
        - `items` ProjectSummary[] — Details on each project where team members have write privileges on at least one resource type (e.g. flags)
          - `_id` string, required — The ID of this project
          - `_links` object, required — The location and content type of related resources
          - `key` string, required — The project key
          - `name` string, required — The project name
      - `appliedOn` integer
    - `_links` object — The location and content type of related resources
  - `members` TeamMembers
    - `totalCount` integer — The total count of members that belong to the team
  - `projects` TeamProjects
    - `totalCount` integer
    - `items` ProjectSummary[] — Details on each project where team members have write privileges on at least one resource type (e.g. flags)
      - `_id` string, required — The ID of this project
      - `_links` object, required — The location and content type of related resources
      - `key` string, required — The project key
      - `name` string, required — The project name
  - `maintainers` TeamMaintainers
    - `totalCount` integer — The number of maintainers of the team
    - `items` MemberSummary[] — Details on the members that have been assigned as maintainers of the team
      - `_links` object, required — The location and content type of related resources
      - `_id` string, required — The member's ID
      - `firstName` string — The member's first name
      - `lastName` string — The member's last name
      - `role` string, required — The member's base role. If the member has no additional roles, this role will be in effect.
      - `email` string, required — The member's email address
    - `_links` object — The location and content type of related resources

## Other responses

- `400` — Invalid request
- `401` — Invalid access token
- `404` — Invalid resource identifier
- `405` — Method not allowed
- `409` — Status conflict
- `429` — Rate limited

---

[API](https://skmtc.dev/launchdarkly/apis/launchdarkly-rest-api.md) · [All operations](https://skmtc.dev/launchdarkly/apis/launchdarkly-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/launchdarkly/launchdarkly-rest-api/revisions/69c5c9aafe78/schema)