Create Team

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

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

POST

api

teams

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

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

string

required

The team name.

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.

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

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

Preview

Agents, playbooks and blueprints

Sessions

Playbook authoring

Drafts

Files

Document actions

Operations

Research

Reports

Reviews

Organisation

Sharing

Usage and value

Repositories and search

Authentication

Body parameters

Response

Errors

​Authentication

​Body parameters

​Response

​Errors

Authentication

Body parameters

Response

Errors