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

# Add Team Member

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

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

Adds a member of your organisation to a [team](/proposed/objects#organisation). 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](/api-reference/directory/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.

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

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


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