Update Sharing

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

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

PUT

api

{resource_type}

{resource_id}

sharing

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

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

Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.

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

string

required

One of repositories, reports, playbooks, blueprints or sessions. Tasks keep their own sharing route.

string

required

The resource id.

Body parameters

enum

required

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

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

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.

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

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

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

Path parameters

Body parameters

Response

Errors

​Authentication

​Path parameters

​Body parameters

​Response

​Errors

Authentication

Path parameters

Body parameters

Response

Errors