Update Team

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

PATCH /api/v1/teams/{team_id}

cURL

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
  }'

Response

{
  "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" }
  ]
}

Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.

Changes a team’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.

cURL

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
  }'

Response

{
  "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.