Add Team Member

Add a member to a team as a team admin or member.

POST /api/v1/teams/{team_id}/members

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/teams/26fb01d1-34cc-4ec6-9823-53fdeb24c86e/members" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "828b17cf-5f09-4edd-bcba-9d1de130a2e6",
    "role": "admin"
  }'

Response

{
  "user_id": "828b17cf-5f09-4edd-bcba-9d1de130a2e6",
  "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.

Adds a member of your organisation to a team. They gain access to everything shared with the team and with every team above it.

role is the person’s role in this team, not in the organisation. A team admin can rename the team and manage its members. A team member cannot.

If the person is already a direct member, the call sets their role instead. If they belong only through a sub-team, they become a direct member as well.

You cannot add people to a team synced from a Slack channel. Wordsmith takes its members from the channel.

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 add members.

Path parameters

team_id · string · required

The team id.

Body parameters

user_id · string · required

The member to add, from List Users. They must be active: suspended members cannot be added.

role · enum · default: "member"

member or admin.

Response

Returns 201 with the person’s team membership.

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/teams/26fb01d1-34cc-4ec6-9823-53fdeb24c86e/members" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "828b17cf-5f09-4edd-bcba-9d1de130a2e6",
    "role": "admin"
  }'

Response

{
  "user_id": "828b17cf-5f09-4edd-bcba-9d1de130a2e6",
  "role": "admin"
}

Errors

Status	error_code	When
400	invalid_request_body	user_id is missing, or role is not member or admin. Also returned when the team’s membership_source is slack_channel: its members come from the channel.
400	team_hierarchy_too_many_members	The team, or a team above it, would hold more people than Wordsmith allows.
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 user_id is not an active member of your organisation.
404	resource_not_found	Teams are not enabled for your organisation.