Tableau REST API Help

Collections REST API endpoints enable you to retrieve and manipulate Tableau collections programmatically. You can use a Tableau collection to make and share a list of resources. The list items don't need to be in the same project. Users that access a shared collection will only be able to see the items that they have permissions to. With collections REST methods, you can: - List all collections that the signed in user has access to. - Create a collection or delete a specified collection the signed in user has access to. - Get the details of a specified collection the signed in user has access to. - Create or delete specified items in a collection the signed in user has access to. - Update the properties of a batch of collections the signed in user has access to. - List all items of a collection that the signed in user has permissions to. - Transfer ownership of specified collections from one user to another.

Using Filters & Sort Options

When using GET methods for collections endpoints, you can use filter and sort parameters to: - Filter which collections or items are returned - Control the order in which items appear in the results

Valid filter options are:

type - The resource type of items in a collection, called contentType in responses. The value can be one or more comma separated types. - ownerLuid - The LUID of the owner. - visibility - The value can be public or private. If no value is provided, then both private and public collections visible to the user will be returned. A private collection is one that has not been shared and can only be seen by its owner, or a user with server or site administrator permissions. A public collection is one that has been shared and is visible to whoever it is shared with. - createdTime - The creation time in ISO 8601 format. - updatedTime - The last updated time in ISO 8601 format. - modifiedTime - The last updated time in ISO 8601 format. - siteId - The integer ID value of the site that the collection belongs to. - favorite - The boolean value of whether the item is marked as a favorite for the currently signed in user. - luid The LUID of the collection. - title - The title of the collection item. Use quotes for entry (i.e. filter=name:eq:Superstore Workbook).

Valid sort options are:

• type - The resource type of items in a collection, called contentType in responses.
• visibility - The value can be public or private. If no value is provided, then both private and public collections visible to the user will be returned. A private collection is one that has not been shared and can only be seen by its owner, or a user with server or site administrator permissions. A public collection is one that has been shared and is visible to whoever it is shared with.
• createdTime - The creation time.
• updatedTime - The last updated time.
• modifiedTime - The last updated time.
• title - The title of the collection item.
• name - The title of the collection.
• ownerName - The name of the owner.
• position - The custom order of the content in the collection.

Add Collection Permissions

Adds permissions to the specified collection for a user or group. You can specify multiple sets of permissions using one call.

If a specified permission has already been granted or denied for a given user or group, the system ignores it.

URI

PUT /api/api-version/sites/site-id/collections/collection-id/permissions

Parameter Values

api-version	The version of the API to use, such as 3.28. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the collection.
collection-id	The ID of the collection to set permissions for.

Request Body

<tsRequest>
  <permissions>
    <granteeCapabilities>
      <user id="user-id" />
        <capabilities>
          <capability name="capability-name" mode="capability-mode" />
          <!-- ... additional capabilities ... -->
        </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
        <capabilities>
          <capability name="capability-name" mode="capability-mode" />
          <!-- ... additional capabilities ... -->
        </capabilities>
    </granteeCapabilities>
    <!-- ... additional granteeCapability sets ... -->
  </permissions>
</tsRequest>

Attribute Values

user-id	The ID of the user to add permissions for.
group-id	The ID of the group to add permissions for.
capability-name	The capability to assign. The only valid capability for a collection is Read. For more information, see Permissions.
capability-mode	Allow to allow the capability, or Deny to deny it.

Permissions

This method can be called by server administrators, site administrators, and collection owners.

Required scope for JWT authorization

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

Authorize use of this method by including this scope in the JSON Web Token (JWT). For more information, see Access scopes for UATs(Link opens in a new window) (Cloud), or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:permissions:update

Response Code

200

Response Body

<tsResponse>
  <permissions>
    <collection id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d" name="My Collection">
      <owner id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd"/>
    </collection>
    <granteeCapabilities>
      <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"/>
      <capabilities>
        <capability name="Read" mode="Allow"/>
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <user id="#9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
      <capabilities>
        <capability name="Read" mode="Allow"/>
      </capabilities>
    </granteeCapabilities>
  </permissions>
</tsResponse>

Version

Version 3.12 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
403	403004	No permissions to set permissions.	A user attempted to add permissions to a collection, but the caller doesn't have permission to set permissions on the collection.
404	404000	Resource not found	The site ID in the URI wasn't found.
404	404002	User not found	The user in the request body wasn't found.
404	404012	Group not found	The group in the request body wasn't found.
404	404013	Resource not found	The capability to remove the permission for. The only valid capability name for a collection is Read. The only valid capability mode is Allow or Deny.

For more information, see Handling Errors.

Delete Collection Permission

Removes the specified collection permission for the specified group or user.

URI

DELETE /api/api-version/sites/site-id/collections/collection-id/permissions/groups/group-id/capability-name/capability-mode

DELETE /api/api-version/sites/site-id/collections/collection-id/permissions/users/user-id/capability-name/capability-mode

Parameter Values

api-version	The version of the API to use, such as 3.28. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the collection.
collection-id	The ID of the collection to remove the permission for.
group-id	The ID of the group to remove the permission for.
user-id	The ID of the user to remove the permission for.
capability-name	The capability to remove the permission for. The only valid capability for a collection is Read. The only valid capability mode is Allow or Deny. For more information, see Permissions.
capability-mode	Allow to delete an allow permission, or Deny to delete a deny permission. This value is case sensitive.

Request Body

None

Permissions

This method can be called by server administrators, site administrators, and collection owners.

Required scope for JWT authorization

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

Authorize use of this method by including this scope in the JSON Web Token (JWT). For more information, see Access scopes for UATs(Link opens in a new window) (Cloud), or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:permissions:delete

Response Code

204

Response Body

None

Version

Version 3.12 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	error Code	Condition	Details
400	400009	Invalid capability	The capability in the URI is invalid for a collection. The only valid capability for a collection is Read.
403	403004	Permissions setting forbidden	A non-administrator user called this method but doesn't have permission to set permissions on the collection.
404	404000	Resource not found	The site ID in the URI wasn't found.
404	404002	Resource not found	The user ID in the URI wasn't found.
404	404012	Resource not found	The group ID in the URI wasn't found.
404	404013	Resource not found	The capability in the URI isn't recognized.
404	404014	Resource not found	The user or group permission wasn't found on the collection. Check the permissions on the collection that you're trying to remove and try again.
404	404038	Resource not found	The collection ID in the URI wasn't found.
405	405000	Invalid request method	Request type was not DELETE.

For more information, see Handling Errors.

List Collection Permissions

Returns a list of permissions for a specific collection.

URI

GET /api/api-version/sites/site-id/collections/collection-luid/permissions

Parameter Values

api-version	The version of the API to use, such as 3.28. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the collection.
collection-id	The ID of the collection to get permissions for.

Request Body

None

Permissions

This method can be called by server administrators, site administrators, and collection owners.

Required scope for JWT authorization

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

Authorize use of this method by including this scope in the JSON Web Token (JWT). For more information, see Access scopes for UATs(Link opens in a new window) (Cloud), or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:permissions:read

Response Code

200

Response Body

<tsResponse>
  <permissions>
    <collection id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd" name="Bob's Collection">
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
    </collection>
    <granteeCapabilities>
      <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"/>
      <capabilities>
        <capability name="Read" mode="Allow"/>
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <user id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6"/>
      <capabilities>
        <capability name="Read" mode="Allow"/>
      </capabilities>
    </granteeCapabilities>

  </permissions>
</tsResponse>

Version

Version 3.12 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	error Code	Condition	Details
404	404038	Resource not found	The collection ID in the URI wasn't found.
404	404000	Resource not found	The site ID in the URI wasn't found.

For more information, see Handling Errors.

Add items to a collection

Adds items to a collection.

POST {server}/api/-/collections/{luid}/items/batchCreate

view details

Batch update collections

Batch updates collections.

POST {server}/api/-/collections/batchUpdate

view details

Create a collection

Creates a new collection.

POST {server}/api/-/collections

view details

Delete collections

Deletes collections.

DELETE {server}/api/-/collections

view details

Delete collections

Deletes collections.

DELETE {server}/api/-/collections/{luid}

view details

Get details of a collection

Gets the details of a collection.

GET {server}/api/-/collections/{luid}

view details

List collections

Lists collections.

GET {server}/api/-/collections

view details

List items in a collection

Lists items in a collection.

GET {server}/api/-/collections/{luid}/items

view details

Remove items from a collection

Removes items from a collection.

POST {server}/api/-/collections/{luid}/items/batchDelete

view details

Reorder items in a collection

Reorders items in a collection.

PATCH {server}/api/-/collections/{luid}/orderItems

view details