# Sharing

The Sharing API lets platform users distribute content to external recipients — people
without a platform account — in a controlled, auditable way. Shares are scoped to
specific documents or collections and can be time-limited, password-protected,
or restricted to specific recipient email addresses.

- `create` — create a new share, specifying documents, recipients, expiry, and access level
- `update` — modify share settings (expiry date, recipient list, permissions)
- `retrieve / list` — inspect share details and enumerate active shares in the organization
- `update-access` — adjust what a specific recipient can do (view-only, download, etc.)
- `revoke` — immediately invalidate a share; recipients lose access on their next request

External recipients authenticate into a share using [Share Authentication](#tag/Share-Authentication)
and then access content via [Shared Content](#tag/Shared-Content).


## Create a share

 - [POST /api/v1/share/create](https://api.tenovos.com/openapi/content-intelligence/sharing/tenovos.sharing.shareservice.create.md): Creates a new share granting one or more external users access to a set of documents until an expiry time.

Request:
users            - List of User entries specifying each recipient's email and access level
(VIEW or VIEW_DOWNLOAD).
documentIds     - List of document IDs to include in the share.
expiryTime      - Timestamp at which the share will automatically expire.
siteId          - ID of the site through which recipients will access the share.

Response:
shareItem   - The created ShareItem including its assigned id, users, documentIds,
expiryTime, siteId, createdAt, and initial status (ACTIVE).

## Update a share

 - [POST /api/v1/share/update](https://api.tenovos.com/openapi/content-intelligence/sharing/tenovos.sharing.shareservice.update.md): Updates the document list and/or expiry time of an existing share.

Request:
id               - ID of the share to update.
documentIds     - Replacement list of document IDs for the share.
expiryTime      - New expiry timestamp for the share.

Response:
shareItem   - The updated ShareItem reflecting the applied changes.

## Get a share

 - [POST /api/v1/share/retrieve](https://api.tenovos.com/openapi/content-intelligence/sharing/tenovos.sharing.shareservice.retrieve.md): Retrieves a share by its ID.

Request:
id   - ID of the share to retrieve.

Response:
shareItem   - The ShareItem including users, documentIds, expiryTime, status, and timestamps.

## Search shares

 - [POST /api/v1/share/list](https://api.tenovos.com/openapi/content-intelligence/sharing/tenovos.sharing.shareservice.list.md): Lists shares created by the authenticated user, with optional inclusion of revoked shares and pagination.

Request:
includeRevoked    - When true, includes shares with REVOKED status in the results.
pagination         - Optional Pagination cursor and page size.

Response:
shareItems        - List of ShareItem objects matching the filter.
nextPageCursor   - Opaque cursor for the next page. Absent when there are no further results.

## Update share access

 - [POST /api/v1/share/update-access](https://api.tenovos.com/openapi/content-intelligence/sharing/tenovos.sharing.shareservice.updateaccess.md): Updates the access level for one or more recipients of an existing share.

Request:
id             - ID of the share to update access for.
emails         - List of recipient email addresses whose access level is being changed.
accessLevel   - The new access level to assign (VIEW or VIEW_DOWNLOAD).

Response:
id      - ID of the updated share.
users   - Updated list of User entries reflecting the new access levels.

## Revoke a share

 - [POST /api/v1/share/revoke](https://api.tenovos.com/openapi/content-intelligence/sharing/tenovos.sharing.shareservice.revoke.md): Revokes a share, immediately preventing all recipients from accessing it.

Request:
id   - ID of the share to revoke. The share status is set to REVOKED.

Response:
id   - ID of the share that was revoked.