Create Team

Create a team, at the top level or nested under another team.

POST /api/v1/teams

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/teams" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Litigation",
    "parent_team_id": "26fb01d1-34cc-4ec6-9823-53fdeb24c86e"
  }'

Response

{
  "id": "88840f5f-fbe8-4602-a8b5-e4c48123c591",
  "name": "Litigation",
  "parent_team_id": "26fb01d1-34cc-4ec6-9823-53fdeb24c86e",
  "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.

Creates a team with manual membership. The caller becomes the team’s first member, with the team role admin. Add more people with Add Team Member.

Nesting widens access. Anything shared with the parent, now or later, also reaches this team’s members. Set parent_team_id only when that is what you want.

Teams that mirror a Slack channel are set up in the Wordsmith app, not through this endpoint.

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.

To nest the team, the caller must also be able to manage the parent team.

Body parameters

name · string · required

The team name.

parent_team_id · string

The team to nest this one under. Leave it out to create a top-level team. The parent cannot be a team synced from a Slack channel.

hidden · boolean · default: "false"

true hides the team from listings and pickers for anyone who is not on it and cannot manage it. This stops people sharing with it by mistake.

Response

Returns 201 with the new team.

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/teams" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Litigation",
    "parent_team_id": "26fb01d1-34cc-4ec6-9823-53fdeb24c86e"
  }'

Response

{
  "id": "88840f5f-fbe8-4602-a8b5-e4c48123c591",
  "name": "Litigation",
  "parent_team_id": "26fb01d1-34cc-4ec6-9823-53fdeb24c86e",
  "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	name is missing or empty, or a field has the wrong type.
400	team_hierarchy_too_deep	Nesting under parent_team_id would go deeper than Wordsmith allows.
400	team_hierarchy_too_many_members	Nesting 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 is not an organisation admin and holds no role that can create teams.
404	resource_not_found	parent_team_id is not a team in your organisation, or the caller cannot manage it. Also returned when teams are not enabled for your organisation.