> ## Documentation Index
> Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Team

> Rename a team, move it in the team tree, or hide it.

> [!NOTE]
>
> **Preview.** This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive `403 mcp_not_enabled`. See the [preview overview](/preview).

Changes a [team](/proposed/objects#organisation)'s name, parent or visibility. Send only the fields you want to change.

Moving a team changes who can reach what. Anything shared with the new parent, and with every team above it, now reaches this team's members. Anything shared with the old parent no longer does, unless it was also shared another way.

Hiding a team also hides every team beneath it. Its members and the people who can manage it still see it, so they can unhide it later.

## Authentication

Requires an API key, or an OAuth token with `directory:admin`. The caller must also be an organisation admin, or hold a role with the matching permission. `directory:admin` is never granted by default. It only narrows what the person who approved it can already do, so a team admin's token can edit their own teams and nothing else. Admin changes are not available through the MCP server.

An admin of the team can also update it. To move the team under a new parent, the caller must be able to manage that parent too.

## Path parameters

**team\_id** `string` *required*

The team id.

## Body parameters

**name** `string`

The new team name. It cannot be empty.

**parent\_team\_id** `string | null`

The team to nest this one under. `null` moves it to the top level. The parent cannot be this team, a team beneath it, or a team synced from a Slack channel.

**hidden** `boolean`

`true` hides the team and every team beneath it. `false` unhides it, which fails while a team above it is still hidden. When you also send `parent_team_id`, Wordsmith moves the team first, so you can move a team out from under a hidden parent and unhide it in one call.

## Response

Returns `200` with the updated [team](/proposed/objects#organisation).

```bash cURL theme={null}
curl -X PATCH "https://api.wordsmith.ai/api/v1/teams/88840f5f-fbe8-4602-a8b5-e4c48123c591" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Disputes",
    "parent_team_id": null
  }'
```

```json Response theme={null}
{
  "id": "88840f5f-fbe8-4602-a8b5-e4c48123c591",
  "name": "Disputes",
  "parent_team_id": null,
  "member_count": 1,
  "direct_member_count": 1,
  "member_ids": ["4c98ef69-d5ef-4471-a2b8-89ded5b7b121"],
  "hidden": false,
  "membership_source": "manual",
  "members": [
    { "user_id": "4c98ef69-d5ef-4471-a2b8-89ded5b7b121", "role": "admin" }
  ]
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | The body is empty, `name` is empty, or a field has the wrong type. |
| 400 | `team_parent_is_self` | `parent_team_id` is this team. |
| 400 | `team_parent_is_descendant` | `parent_team_id` is a team beneath this one, which would make a loop. |
| 400 | `team_hierarchy_too_deep` | The move would nest teams deeper than Wordsmith allows. |
| 400 | `team_hierarchy_too_many_members` | The move would put more people under one team than Wordsmith allows. |
| 400 | `team_parent_is_slack_sourced` | `parent_team_id` is a team synced from a Slack channel. Such a team cannot have sub-teams. |
| 403 | `insufficient_scope` | The OAuth token does not hold `directory:admin`. |
| 403 | `forbidden` | The caller can see the team but cannot manage it. |
| 404 | `resource_not_found` | No team in your organisation has this id or the caller cannot see it, or the caller cannot manage `parent_team_id`. |
| 400 | `team_ancestor_is_hidden` | `hidden` is `false`, but a team above this one is still hidden. Unhide that team first. |
| 404 | `resource_not_found` | Teams are not enabled for your organisation. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.