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

# Update Sharing

> Replace the visibility and the shared people and teams of a repository, report, playbook, blueprint or session.

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

Replaces the resource's whole sharing state, as the share dialog in the Wordsmith app does. Send the full lists you want, because anyone you omit loses access, the creator included. Repositories, reports, playbooks and blueprints must keep at least one person with `write` access. The request and response match [Update Task Sharing](/api-reference/tasks/update-sharing).

`access_level` is `read` or `write`. `user_id` takes a user id, email address or name, and `team_id` takes a team id or team name. A reference that matches more than one record is rejected with a `400` that lists the candidates, so pass the id to disambiguate. A person or team named twice gets the higher access level.

Nothing can be shared outside your organisation or made public.

Assistants change sharing through the MCP tool `share_resource`, one person or team at a time. This endpoint replaces the whole list in one call.

## Authentication

Requires an API key, or an OAuth token with the write scope of the resource type. The caller must also be an admin of the resource, as the share dialog requires. For a session that means its creator: `write` access to a session does not allow changing its sharing, and the creator keeps access without being listed.

| `resource_type` | Scope |
| - | - |
| `repositories` | `repositories:write` |
| `reports` | `reports:write` |
| `playbooks` | `playbooks:write` |
| `blueprints` | `blueprints:write` |
| `sessions` | `sessions:share`, which is not grantable yet: today only an API key can change a session's sharing |

## Path parameters

**resource\_type** `string` *required*

One of `repositories`, `reports`, `playbooks`, `blueprints` or `sessions`. Tasks keep their own [sharing route](/api-reference/tasks/get-sharing).

**resource\_id** `string` *required*

The resource id.

## Body parameters

**visibility** `enum` *required*

Who can see the resource by default: `private` or `customer`.

**users** `array`

The complete set of people with access. Anyone omitted loses access. Each entry is `{"user_id": "<user id, email or name>", "access_level": "read" | "write"}`.

**teams** `array`

The complete set of teams with access. Any team omitted loses access. Each entry is `{"team_id": "<team id or name>", "access_level": "read" | "write"}`. Needs teams to be enabled for your organisation.

## Response

Returns `200` with the new sharing state, in the same shape as [Get Sharing](/api-reference/sharing/get-sharing).

```bash cURL theme={null}
curl -X PUT "https://api.wordsmith.ai/api/v1/repositories/5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58/sharing" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "visibility": "private",
    "users": [
      { "user_id": "2d42958a-1e02-4ed5-8869-184209e7681a", "access_level": "write" }
    ],
    "teams": [
      { "team_id": "Legal", "access_level": "read" }
    ]
  }'
```

```json Response theme={null}
{
  "visibility": "private",
  "users": [
    {
      "id": "2d42958a-1e02-4ed5-8869-184209e7681a",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "role": "owner",
      "access_level": "write"
    }
  ],
  "teams": [
    {
      "id": "85998d74-1113-4b74-87d2-bec70ec508d2",
      "name": "Legal",
      "access_level": "read"
    }
  ]
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | `visibility` is missing or not `private` or `customer`, or an entry has the wrong shape. |
| 400 | `bad_request` | A `user_id` or `team_id` matches no one, or more than one record (the message lists the candidates). Also returned for `teams` when teams are not enabled. |
| 403 | `insufficient_scope` | The OAuth token does not hold the write scope of `resource_type`. |
| 403 | `not_available_to_connected_apps` | An OAuth token tried to change a session's sharing. That needs `sessions:share`, which no connected app can be granted yet, so reconnecting does not help. Use an API key. |
| 403 | `forbidden` | The caller can read the resource but is not one of its admins (for a session, not its creator). |
| 404 | `resource_not_found` | `resource_type` is not one of the five above, no resource has this id, or the caller cannot read it. |
| 422 | `at_least_1_admin_required` | No one in `users` has `write` access to the repository, report, playbook or blueprint. |


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