Sign in

v1

latestOpenAPI 3.0.32026-08-061874701.5 MB
sharing

List asset shares

Retrieves a list of all users and groups to whom the specified asset is shared, and their access level. This operation supports query string parameters for pagination of results.

Note: For pagination guidance, refer to Token-based pagination.

get/shares

Query parameters

assetType'sheet' | 'report' | 'sight' | 'workspace' | 'collection' | 'file' required
Example:sheet

The type of the asset. Used in combination with assetId to determine the asset.

assetIdstring required
Example:1234567890

The ID of the asset being accessed. It's used in combination with assetType to determine the asset.

Depending on the asset, this may be a numeric or string value.

maxItemsinteger
Example:100

Request query parameter used in endpoints that support token based pagination.

The maximum amount of items to return in the response. The default and minimum are 100.

lastKeystring
Example:abcDefGhIjKlMnOpQrStUvWxYz

The lastKey token returned from the previous page of results. If not specified, the first page of results is returned.

sharingInclude'ITEM' | 'WORKSPACE'

When applicable for the specific object this parameter defines the scope of the share. Possible values are ITEM or WORKSPACE. ITEM is an item-level share (that is, the specific object to which the share applies is shared with the user or group). WORKSPACE is a workspace-level share (that is, the workspace that contains the object to which the share applies is shared with the user or group).

Response

Object containing an array of Share response objects. By default, this operation returns only item-level shares (scope=ITEM). Use the sharingInclude parameter to request that workspace level shares also be returned.

The response result will always exist, but the list may be empty if there are no shares for the specified asset.

lastKeystring

A token that is used to retrieve the next page of results when passed as the lastKey query parameter. This value will be absent when there are no further pages.

Example response

{
  "lastKey": "abcDefGhIjKlMnOpQrStUvWxYz",
  "items": [
    {
      "id": "AAAMCmYGFOeE",
      "email": "test.email@smartsheet.com",
      "userId": 9876543210,
      "groupId": 1234567890,
      "name": "Example Name",
      "type": "USER"
    }
  ]
}