> ## 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.

# Create Team

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

> [!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).

Creates a [team](/proposed/objects#organisation) with manual membership. The caller becomes the team's first member, with the team role `admin`. Add more people with [Add Team Member](/api-reference/organisation/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](/proposed/objects#organisation).

```bash cURL theme={null}
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"
  }'
```

```json Response theme={null}
{
  "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. |


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