Get Sharing

Read who a repository, report, playbook, blueprint or session is shared with.

GET /api/v1/{resource_type}/{resource_id}/sharing

cURL

curl "https://api.wordsmith.ai/api/v1/repositories/5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58/sharing" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

Response

{
  "visibility": "private",
  "users": [
    {
      "id": "2d42958a-1e02-4ed5-8869-184209e7681a",
      "name": "Jane Doe",
      "email": "[e-mail]",
      "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.

Returns the resource’s visibility and the people and teams it is shared with. The shape is the same as Get Task Sharing, so one client can read sharing for every kind of resource.

visibility is private (only the people and teams listed) or customer (anyone in your organisation). A session someone published from the Wordsmith app reads public; the API never sets that. In users, role is owner for the person who created the resource and shared for everyone else. access_level is write for the resource’s admins and read for its viewers.

Sessions differ. A session’s creator always has access, so they are not listed. write on a session lets someone continue and edit it, not change its sharing: only the creator can do that.

A review has no sharing of its own: it is shared through the session it belongs to.

Assistants read the same information through the MCP tool get_resource with include: ["sharing"], for playbooks, blueprints and tasks.

Authentication

Requires an API key, or an OAuth token with the read scope of the resource type:

resource_type	Scope
repositories	repositories:read
reports	reports:read
playbooks	playbooks:read
blueprints	blueprints:read
sessions	sessions:read

As in the Wordsmith app, only an admin of a repository, playbook or blueprint can see who it is shared with. Anyone who can read a report or a session can see its sharing.

Path parameters

resource_type · string · required

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

resource_id · string · required

The resource id.

Response

Returns 200 with visibility, users and teams.

cURL

curl "https://api.wordsmith.ai/api/v1/repositories/5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58/sharing" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

Response

{
  "visibility": "private",
  "users": [
    {
      "id": "2d42958a-1e02-4ed5-8869-184209e7681a",
      "name": "Jane Doe",
      "email": "[e-mail]",
      "role": "owner",
      "access_level": "write"
    }
  ],
  "teams": [
    {
      "id": "85998d74-1113-4b74-87d2-bec70ec508d2",
      "name": "Legal",
      "access_level": "read"
    }
  ]
}

Errors

Status	error_code	When
403	insufficient_scope	The OAuth token does not hold the read scope of resource_type.
403	forbidden	The caller can read the repository, playbook or blueprint but is not one of its admins.
404	resource_not_found	resource_type is not one of the five above, no resource has this id, or the caller cannot read it.