Was this page helpful?
Yes No
Have a comment? Please leave it here.Thanks for your feedback!

Home > 

API Reference

Using the Tableau Server REST API, you can manage and change Tableau Server resources programmatically, via HTTP. The API gives you simple access to the functionality behind the data sources, projects, workbooks, site users, and sites on a Tableau server. You can use this access to create your own custom applications or to script interactions with Tableau Server resources.

Note: Tableau does not provide support for programs that customers create that use the Tableau REST API. For help with your code, submit questions and ask for help on the Tableau developer community forums. Tableau does provide support for potential bugs in the Tableau REST API code itself, and for unmodified sample code that isn't working.

Schema version

The API reference reflects version 3.1 of the REST API schema, which is available with Tableau Server 2018.2. For more information, see REST API XML Schema and REST API Versions.

If you are working with an earlier version of Tableau Server, see the following REST API reference pages:

About the REST API Request and Response Examples

The examples in this reference section show requests and responses in XML. However, the REST API supports JSON and XML. You can set Content-Type and Accept headers to application/json or application/xml to control how you want send requests or receive responses. For more information, see Fundamentals of the Tableau Server REST API and REST API Example Requests.

Note: The structure of the response body returned from the server is the same whether you specify application/json or application/xml. That is, the hierarchy or nesting of the objects and elements within the response body is the same. The principal difference is that the XML response has a root element called <tsResponse>, while the JSON response does not. The JSON response body is contained in opening and closing braces { }. If you plan to make programmatic use of the response body, it is a good idea to test the endpoint using available utilities and examine the response payload. See Testing and Troubleshooting REST API Calls.

API Listing

The following table lists the Tableau Server REST API methods by category. The table also indicates which methods can be used with Tableau Online.

Area

Name

Tableau Online?

Authentication

Sign In

Yes

 

Sign Out

Yes

 

Switch Site

No

Sites

Create Site

No

 

Query Site

Yes

 

Query Sites

No

 

Query Views for Site

Yes

 

Update Site

No

 

Delete Site

No

Projects

Create Project

Yes

 

Query Projects

Yes

 

Update Project

Yes

 

Delete Project

Yes

Workbooks and Views

Publish Workbook

Yes

 

Add Tags to View

Yes

 

Add Tags to Workbook

Yes

 

Query Views for Site

Yes

 

Query Views for Workbook

Yes

 

Query View Data

Yes

 

Query View Image

Yes

 

Query View PDF

Yes

 

Query View Preview Image

Yes

 

Query Workbook

Yes

 

Query Workbook Connections

Yes

 

Get Workbook Revisions

Yes

 

Query Workbook Preview Image

Yes

 

Query Workbooks for Site

Yes

 

Query Workbooks for User

Yes

 

Download Workbook

Yes

 

Download Workbook Revision

Yes

 

Update Workbook

Yes

 

Update Workbook Connection

Yes

 

Update Workbook Now

Yes

 

Delete Workbook

Yes

 

Remove Workbook Revision

Yes

 

Delete Tag from View

Yes

 

Delete Tag from Workbook

Yes

Data sources

Publish Data Source

Yes

 

Add Tags to Data Source

Yes

 

Delete Tag from Data Source

Yes

 

Query Data Source

Yes

 

Query Data Sources

Yes

 

Query Data Source Connections

Yes

 

Get Data Source Revisions

Yes

 

Download Data Source

Yes

 

Download Data Source Revision

Yes

 

Update Data Source

Yes

 

Update Data Source Connection

Yes

 

Update Data Source Now

Yes

 

Delete Data Source

Yes

 

Remove Data Source Revision

Yes

Users and Groups

Create Group

Yes

 

Add User to Group

Yes

 

Add User to Site

Yes

 

Get Users in Group

Yes

 

Get Users on Site

Yes

 

Query Groups

Yes

 

Query User On Site

Yes

 

Update Group

Yes

 

Update User

Yes

 

Remove User from Group

Yes

 

Remove User from Site

Yes

 

Delete Group

No

Revisions

Get Data Source Revisions

Yes

 

Get Workbook Revisions

Yes

 

Download Data Source Revision

Yes

 

Download Workbook Revision

Yes

 

Remove Data Source Revision

Yes

 

Remove Workbook Revision

Yes

Permissions

Add Data Source Permissions

Yes

 

Add Project Permissions

Yes

 

Add Default Permissions

Yes

 

Add Workbook Permissions

Yes

 

Add Workbook to Schedule

Yes

 

Query Data Source Permissions

Yes

 

Query Project Permissions

Yes

 

Query Default Permissions

Yes

 

Query Workbook Permissions

Yes

 

Delete Data Source Permission

Yes

 

Delete Project Permission

Yes

 

Delete Default Permission

Yes

 

Delete Workbook Permission

Yes

Jobs, Tasks, and Schedules Add Data Source to Schedule

Yes

  Add Workbook to Schedule

Yes

  Cancel Job

Yes

  Query Job

Yes

  Query Jobs

Yes

 

Get Extract Refresh Task

Yes

 

Get Extract Refresh Tasks

Yes

  Create Schedule

No

  Query Extract Refresh Tasks

No

  Query Schedules

No

 

Run Extract Refresh Task

Yes

  Update Schedule

No

  Delete Schedule

No

Subscriptions

Create Subscription

Yes

 

Query Subscription

Yes

 

Query Subscriptions

Yes

 

Update Subscription

Yes

 

Delete Subscription

Yes

Favorites

Add Data Source to Favorites

Yes

 

Add Project to Favorites

Yes

 

Add View to Favorites

Yes

 

Add Workbook to Favorites

Yes

 

Delete Data Source from Favorites

Yes

 

Delete Project from Favorites

Yes

 

Delete View from Favorites

Yes

 

Delete Workbook from Favorites

Yes

 

Get Favorites for User

Yes

Publishing

Initiate File Upload

Yes

 

Append to File Upload

Yes

 

Publish Data Source

Yes

 

Publish Workbook

Yes

 

Update Site

Yes

Server

Server Info

Yes

Add Data Source Permissions

Adds permissions to the specified data source for a Tableau Server 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.

If the request body includes a child workbook or <project> element, the request is invalid.


URI

PUT /api/api-version/sites/site-id/datasources/datasource-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to set permissions for.

Request Body

<tsRequest>
  <permissions>
    <datasource id="datasource-id" />
    <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 grantee capability sets ...
  </permissions>
</tsRequest>

Attribute Values

datasource-id The <datasource> element is not required, but can be included for compatibility with earlier versions of the REST API. If the <datasource> element is included, the datasource-id value must match the data source ID in the URI. Any other attributes in the <datasource> element are ignored.
user-id The ID (not name) of the user to add permissions for.
group-id The ID (not name) of the group to add permissions for.
capability-name The capability to assign. For valid capabilities for a data source project are ChangePermissions, Connect, Delete, ExportXml, Read (view), and Write.

For more information, see Permissions.

capability-mode Allow to allow the capability, or Deny to deny it. This value is case sensitive.

Permissions

Tableau Server users who are not server administrators or site administrators can add permissions only to a data source for which they have ChangePermissions permission (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse version-and-namespace-settings>
  <permissions>
    <datasource id="datasource-id" />
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    ... additional grantee capability sets ...
  </permissions>
</tsResponse>

Version

Version 2.0 and later. For more information, see REST API 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.
400 400009 Invalid capability The specified capability is invalid for a data source. Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read, and Write.
403 403004 No permissions to set permissions. A user attempted to add permissions to a data source, but the caller doesn't have permission to set permissions on the data source.
404 404000 Site not found The specified site doesn't correspond to an existing site.
404 404002 User not found The user specified in the request body doesn't correspond to an existing user.
404 404004 Data source not found The specified data source doesn't correspond to an existing data source.
404 404012 Group not found The group specified in the request body doesn't correspond to an existing group.
404 404013 Capability not found A capability specified in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Add Data Source to Favorites

Adds the specified data source to the user's favorites.

If the user already has the data source listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.


URI

PUT /api/api-version/sites/site-id/favorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the data source.
user-id The ID of the user to add the favorite for.

Request Body

<tsRequest> 
  <favorite label="favorite-label"> 
    <datasource id="datasource-id" /> 
  </favorite> 
</tsRequest>

Attribute Values

favorite-label A label to assign to the favorite. This value is displayed when you search for favorites on the server.
datasource-id The ID of the data source to add as a favorite.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have Read (view) permissions on the data source (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <favorites>
    <favorite label="favorite-label">
     <datasource id="datasource-id" />
    </favorite>
    <favorite label="favorite-label">
     <datasource id="datasource-id" />
    </favorite>
    ... additional favorites ...
  </favorites>
</tsResponse>

Version

Version 2.3 and later. For more information, see REST API 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.
400 400005 Invalid label The favorite label is empty or consists of only white space characters.
403 403004 Forbidden favorites access A non-administrator user called this method but doesn't have permission to add a data source to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
404 404011 Data source not found The data source ID in the request body doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not PUT.
409 409007 Label conflict There is already a favorite with the same label for a different data source in the specified user's favorites.

For more information, see Handling Errors.

Add Data Source to Schedule

Adds a task to refresh a data source to an existing schedule.


URI

PUT /api/api-version/sites/site-id/schedules/schedule-id/datasources

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the view.
schedule-id The ID of the schedule that you are associating with the data source.

Request Body

<tsRequest>
  <task>
    <extractRefresh>
      <datasource id="datasource-id" />
    </extractRefresh>            
  </task>
</tsRequest>

Attribute Values

datasource-id The ID of the data source to add to the schedule.

Permissions

Tableau Server users who are not server administrators or site administrators can only add a data source to a schedule if they own the data source, or are the project leader for the project that contains the data source.

Response Code

20

Response Body

<tsResponse>
  <task>
    <extractRefresh>
      <schedule id="schedule-id" />
      <datasource id="datasource-id" />
    </extractRefresh>
  </task>
</tsResponse>

Version

Version 2.8 and later. For more information, see REST API 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.
401 401002 Unauthorized Access The authentication token provided in the request header was invalid or has expired.
403 403032 Update Forbidden A non-administrator user called this method, but the caller doesn't have sufficient permissions.
404 404000 Site not found The site ID in the URI is unknown.
404 404004 Resource not found The data source ID in the request body is unknown.
405 405000 Invalid request method Request type was not PUT.
500 500000 Internal Server Error The schedule ID in the URI is unknown..

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/schedules/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/datasources" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @add-to-schedule.xml"

Content of add-to-schedule.xml:

<tsRequest>
  <task>
    <extractRefresh>
      <datasource id="89a82d78-664f-45a1-8256-d4d2961a070b" />
    </extractRefresh>            
  </task>
</tsRequest>
						

Example response:

<tsResponse>
  <task>
    <extractRefresh id="9bf8aea0-e3ca-422e-b7ef-d9c4ba6cca45" priority="50" consecutiveFailedCount="0" type="RefreshExtractTask">
      <schedule id="9a4ebbab-9ec8-487a-9b48-47fa81d6077a" name="Weekday early mornings" state="Active" />
      <datasource id="89a82d78-664f-45a1-8256-d4d2961a070b" />
    </extractRefresh>
  </task>
</tsResponse>
							

Add Default Permissions

Adds permissions to the specified project that will be applied by default to new workbooks and data sources as they are added to the project. You make separate requests to set default permissions for workbooks and for data sources.

Content owners can override default permissions for their content, but only if project permissions have not been locked. Project permissions can be locked for a new project when you call Create Project or for an existing project by calling Update Project. For more information, see Lock Content Permissions to the Project.


URI

PUT /api/api-version/sites/site-id/projects/project-id/default-permissions/workbooks

PUT /api/api-version/sites/site-id/projects/project-id/default-permissions/datasources

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the project.
project-id The ID of the project to set default 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 grantee capability sets ...
  </permissions>
</tsRequest>

Attribute Values

user-id The ID (not name) of the user to add default permissions for.
group-id The ID (not name) of the group to add permissions for.
capability-name The capability to assign. Valid capabilities for a workbook are

AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write.

Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read (view), and Write.

For more information, see Permissions.

capability-mode Allow to allow the capability, or Deny to deny it. This value is case sensitive.

Permissions

Tableau Server users who are not server administrators can add permissions defaults for a project only if they have the ProjectLeader permission for that project (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <permissions>
    <project id="project-id" name="project-name" />
      <owner id="project-owner-id" />
    </project>
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    ... additional grantee capability sets ...
  </permissions>
</tsResponse>

Version

Version 2.1 and later. For more information, see REST API 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.
400 400009 Invalid capability The capability in the URI is invalid for a data source.

Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write.

Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read (view), and Write.

400 400042 Malformed permissions qualifier The request body includes a <workbook> or <datasource> element.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to add permissions on the project.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found A user ID in the request body as the grantee doesn't correspond to an existing user.
404 404005 Project not found The project ID in the URI doesn't correspond to an existing project.
404 404009 Project ID mismatch A project ID specified in the URI does not match the project ID specified in the request body. (You do not have to specify a project ID in the request body.)
404 404012 Group not found A group ID in the request body doesn't correspond to an existing group.
404 404013 Capability not found The capability in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Add Project Permissions

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

If the request body includes a child datasource or <project> element, the request is invalid.


URI

PUT /api/api-version/sites/site-id/projects/project-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the project.
project-id The ID of the project 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 grantee capability sets ...
  </permissions>
</tsRequest>

Attribute Values

user-id The ID (not name) of the user to add permissions for.
group-id The ID (not name) of the group to add permissions for.
capability-name The capability to assign permissions to. In Tableau Server 10.0, the valid capabilities for a project are ProjectLeader, Read (view), and Write.

For more information, see Permissions.

capability-mode Allow to allow the capability, or Deny to deny it. This value is case sensitive.

Permissions

Tableau Server users who are not server administrators or site administrators can add permissions for a project only if they have ChangePermissions (version 2.0) or ProjectLeader (version 2.1) permission for that project (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <permissions>
    <project id="project-id" name="project-name" />
      <owner id="project-owner-id" />
    </project>
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    ... additional grantee capability sets ...
  </permissions>
</tsResponse>

Version

Version 2.0 and later. For more information, see REST API 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.
400 400009 Invalid capability The capability in the URI is invalid for a project. For a list of valid capabilities, see the capability-name attribute earlier.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to add permissions on the project.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found A user ID in the request body as the grantee doesn't correspond to an existing user.
404 404005 Project not found The project ID in the URI doesn't correspond to an existing project.
404 404009 Project ID mismatch A project ID specified in the URI does not match the project ID specified in the request body. (You do not have to specify a project ID in the request body.)
404 404012 Group not found A group ID in the request body doesn't correspond to an existing group.
404 404013 Capability not found The capability in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Add Project to Favorites

Adds the specified project to a user's favorites.

If the user already has the project listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.


URI

PUT /api/api-version/sites/site-id/favorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the project.
user-id The ID of the user to add the favorite for.

Request Body

<tsRequest>
  <favorite label="favorite-label">
    <project id="project-id"/>
  <favorite>
</tsRequest>

Attribute Values

favorite-label A label to assign to the favorite. This value is displayed when you search for favorites on the server.
project-id The ID (not name) of the project to add as a favorite.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have permission to add a project to a favorite list (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <favorites>
    <favorite label="favorite1-label">
     <project id="project-id" />
    </favorite>
    <favorite label="favorite2-label">
     <project id="project-id" />
    </favorite>
  </favorites>
</tsResponse>

Version

Version 3.1 and later. For more information, see REST API 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.
400 400005 Invalid label The favorite label is empty or consists of only white space characters.
403 403004 Access to favorites denied A non-administrator user called this method but doesn't have permission to add a project to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/favorites/2474164d-8d37-4a4c-abc7-c2070fd25fd5" -X PUT -d @add-project-to-favorites.xml -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Content of add-project-to-favorites.xml:

<tsRequest>
  <favorite label="Economic Indicators">
    <project id="1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c" />
  </favorite>
</tsRequest>

Example response::

<tsResponse version-and-namespace-settings>
  <favorites>
    <favorite label="Economic Indicators">
      <project id="1f1e1d1c2-b2a2-f2e3-d3c3-b3a4f4e4d4c"/>
    </favorite>
  </favorites>
</tsResponse>

Add Tags to Data Source

Adds one or more tags to the specified data source.


URI

PUT /api/api-version/sites/site-id/datasources/datasource-id/tags

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to add tags to.

Request Body

<tsRequest>
  <tags>
    <tag label="tag" />
    ... additional tags ...
  </tags>
</tsRequest>

Attribute Values

datasource-id The data source to add the tag to. If the data source is already tagged with a tag that's included in the request body, those tags are ignored and the data source retains them. If the <tags> element is empty, no new tags are added to the data source.
tag The text of the tag.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have Read permissions for the data source (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <tags>
    <tag label="tag"/>
        ... additional new tags ...
        ... existing tags ...
  </tags>
</tsResponse>

Version

Version 1.0 and later. For more information, see REST API 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.
400 400075 Error adding tags There was a problem adding tags to the specified data source.
403 403004 Adding tags forbidden

A non-administrator user called this method but doesn't have permission to add tags. This error is raised even if the <tags> element is empty.

404 404000 Site not found

The site ID in the URI is not for an existing site.

404 404004 Data source not found The data source ID in URI doesn't correspond to an existing data source.
404 404009 Data source ID mismatch The request body contains a data source ID (which is optional) and it doesn't match the ID in the URI.
404 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/tags" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-tags-to-datasource.xml

Content of add-tags-to-workbook.xml:

<tsRequest>
    <tags>
      <tag label="GDP" />
      <tag label="Health" />
    </tags>
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <tags>
    <tag label="GDP"/>
    <tag label="Health"/>
    <tag label="Spending"/>
  </tags>
</tsResponse>

Add Tags to View

Adds one or more tags to the specified view.


URI

PUT /api/api-version/sites/site-id/views/view-id/tags

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the workbook.
view-id The ID of the views to add tags to.

Request Body

<tsRequest>
  <tags>
    <tag label="tag" />
    ... additional tags ...
  </tags>
</tsRequest>

Attribute Values

view-id The view to add the tag to. If the view is already tagged with a tag that's included in the request body, those tags are ignored and the view retains them. If the <tags> element is empty, no new tags are added to the view.
tag The text of the tag.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have Read permissions for the view (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <tags>
    <tag label="tag"/>
        ... additional new tags ...
        ... existing tags ...
  </tags>
</tsResponse>

Version

Version 1.0 and later. For more information, see REST API 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.
400 400076 Error adding tags There was a problem adding tags to the specified view.
403 403004 Adding tags forbidden

A non-administrator user called this method but doesn't have permission to add tags. This error is raised even if the <tags> element is empty.

404 404000 Site not found

The site ID in the URI is not for an existing site.

404 404011 View not found The view ID in URI doesn't correspond to an existing view.
404 404009 Workbook ID mismatch The request body contains a view ID (which is optional) and it doesn't match the ID in the URI.
404 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views/1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c/tags" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-tags-to-view.xml

Content of add-tags-to-workbook.xml:

<tsRequest>
    <tags>
      <tag label="GDP" />
      <tag label="Health" />
    </tags>
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <tags>
    <tag label="GDP"/>
    <tag label="Health"/>
    <tag label="Spending"/>
  </tags>
</tsResponse>

Add Tags to Workbook

Adds one or more tags to the specified workbook.


URI

PUT /api/api-version/sites/site-id/workbooks/workbook-id/tags

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to add tags to.

Request Body

<tsRequest>
  <tags>
    <tag label="tag" />
    ... additional tags ...
  </tags>
</tsRequest>

Attribute Values

workbook-id The workbook to add the tag to. If the workbook is already tagged with a tag that's included in the request body, those tags are ignored and the workbook retains them. If the <tags> element is empty, no new tags are added to the workbook.
tag The text of the tag.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have Read permissions for the workbook (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <tags>
    <tag label="tag"/>
        ... additional new tags ...
        ... existing tags ...
  </tags>
</tsResponse>

Version

Version 1.0 and later. For more information, see REST API 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.
400 400049 Error adding tags There was a problem adding tags to the specified workbook.
403 403004 Adding tags forbidden

A non-administrator user called this method but doesn't have permission to add tags. This error is raised even if the <tags> element is empty.

404 404000 Site not found

The site ID in the URI is not for an existing site.

404 404006 Workbook not found The workbook ID in URI doesn't correspond to an existing workbook.
404 404009 Workbook ID mismatch The request body contains a workbook ID (which is optional) and it doesn't match the ID in the URI.
404 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/tags" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-tags-to-workbook.xml

Content of add-tags-to-workbook.xml:

<tsRequest>
    <tags>
      <tag label="GDP" />
      <tag label="Health" />
    </tags>
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <tags>
    <tag label="GDP"/>
    <tag label="Health"/>
    <tag label="Spending"/>
  </tags>
</tsResponse>

Add User to Group

Adds a user to the specified group.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

POST /api/api-version/sites/site-id/groups/group-id/users

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the group.
group-id The ID of the group to add the user to.

Request Body

<tsRequest>
  <user id="user-id" />
</tsRequest>

Attribute Values

user-id The ID (not name) of the user to add. You can get the user ID by calling Get Users on Site .

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <user id="user-id"
    name="user-name"
    siteRole="site-role" />
</tsResponse>

The siteRole value is returned as one of the following values: Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, or Viewer.

Version

Version 2.0 and later. For more information, see REST API 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.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404012 Group not found The group name in the request body doesn't correspond to an existing group.
405 405000 Invalid request method Request type was not POST.
409 409011 User conflict The specified user is already a member of the group.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/users" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-group.xml

Content of add-user-to-group.xml:

<tsrequest>
  <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
</tsrequest>

Example response:

<?xml version="1.0" encoding="UTF-8" ?>
<tsResponse version-and-namespace-settings>
  <user id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" name="Adam"
        siteRole="Explorer" />
</tsresponse>

Add User to Site

Adds a user to Tableau Server and assigns the user to the specified site.

If Tableau Server is configured to use local authentication, the information you specify is used to create a new user in Tableau Server.

Note: After creating the user, you must set a full name, password, and email address for the user with the call to Update User. If you are using SAML with local authentication, the user information that you add is not synchronized with the SAML IdP, as it would be if you were using Active Directory. Even if it is not used by SAML, the user information must be present.

If Tableau Server is configured to use Active Directory for authentication, the user you specify is imported from Active Directory into Tableau Server.

When you add user to Tableau Online, the name of the user must be the email address that is used to sign in to Tableau Online. After you add a user, Tableau Online sends the user an email invitation. The user can click the link in the invitation to sign in and update their full name and password.

If you try to add a user using a specific site role but you have already reached the limit on the number of licenses for your users, the user is added as an unlicensed user. In that case, the response code is 201 (which indicates success), but the siteRole value in the response body is set to Unlicensed.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

POST /api/api-version/sites/site-id/users

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site to add users to.

Request Body

<tsRequest>
  <user name="user-name"
        siteRole="site-role" 
        authSetting="auth-setting" />
</tsRequest>

Attribute Values

user-name The name of the user. If the server uses local authentication, this can be any name. If you are using Active Directory authentication, or if you are using Tableau Online, there are specific requirements for the name.

Tableau Server If Tableau Server uses Active Directory authentication, this must be the name of an existing user in Active Directory. If the user name is not unique across domains, you must include the domain as part of the user name (for example, example\Adam or adam@example.com).

Note: Active Directory specifies a user name using two attributes: sAMAccountName and userPrincipalName (UPN) prefix. For most Active Directory users, these attributes are the same. By default, if you are adding a user from Active Directory, the name that you provide in the user-name is matched against the Active Directory sAMAccountName attribute, which becomes the name that the user signs in to Tableau Server with. There are two exceptions: if the name that you provide is longer than 20 characters, or if the name that you provides includes an @ character, Tableau imports the user using the Active Directory UPN. For more information, see User Naming Attributes on the MSDN site.

Tableau Online The user-name is the email address that the user will use to sign in to Tableau Online. When you add a user to the site, Tableau Online sends an email invitation. The user can click the link in the invitation to sign in and update their full name and password.

site-role

The site role to assign to the user. You can assign the following roles: Creator, Explorer, ExplorerCanPublish, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, or Viewer.

Note: You cannot use the REST API to set a user to be a server administrator (ServerAdministrator site role).

auth-setting (Optional) The new authentication type for the user. You can assign the following values for this attribute: SAML (the user signs in using SAML) or ServerDefault (the user signs in using the authentication method that's set for the server). These values appear in the Authentication tab on the Settings page in Tableau Online�the SAML attribute value corresponds to Single sign-on, and the ServerDefault value corresponds to TableauID.

Note: The authSetting attribute is only available if you are using Tableau Online or Tableau Server with site-specific SAML enabled.

Permissions

This method can only be called by server administrators and site administrators.

Response Code

201

Response Body

<tsResponse>
  <user id="user-id"
   name="user-name"
   siteRole="site-role" 
   authSetting="auth-setting" />
</tsResponse>

Note: The authSetting attribute is only returned if you are using Tableau Online or Tableau Server with site-specific SAML enabled.

Response Headers

Location: /api/3.1/sites/site-id/users/new-user-id

Version

Version 1.0 and later. For more information, see REST API 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.
400 400013 Invalid site role

The value of the siteRole attribute must be Explorer, ExplorerCanPublish, SiteAdministratorCreator, SiteAdministratorExplorer, Unlicensed, or Viewer.

404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The server is configured to use Active Directory for authentication, and the username specified in the request body doesn't match an existing user in Active Directory.
405 405000 Invalid request method Request type was not POST.
409 409000 User conflict The specified user already exists on the site.
409 409005 Guest user conflict The Tableau Server API doesn't allow adding a user with the guest role to a site.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-site.xml

  • MY-SERVER is the name or IP address of your server.
  • 9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d is the ID of the site to add the user to, as returned by a previous call to Sign In.
  • 12ab34cd56ef78ab90cd12ef34ab56cd is the authentication returned by a previous call to Sign In.

Content of add-user-to-site.xml:

<tsRequest>
  <user name="Adam"
        siteRole="Explorer" />
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
    <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" name="Adam"
          siteRole="Explorer" />
</tsResponse>

Add View to Favorites

Adds the specified view to a user's favorites.

If the user already has the view listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.


URI

PUT /api/api-version/sites/site-id/favorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the view.
user-id The ID of the user to add the favorite for.

Request Body

<tsRequest>
  <favorite label="favorite-label">
    <view id="view-id" />
  </favorite>
</tsRequest>

Attribute Values

favorite-label A label to assign to the favorite. This value is displayed when you search for favorites on the server.
view-id The ID (not name) of the view to add as a favorite.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have permission to add a view to a favorite list (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <favorites>
    <favorite label="favorite1">
     <view id="view-id" />
    </favorite>
    <favorite label="favorite-label">
     <view id="view-id" />
    </favorite>
    ... additional favorites ...
  </favorites>
</tsResponse>

Version

Version 1.0 and later. For more information, see REST API 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.
400 400005 Invalid label The favorite label is empty or consists of only white space characters.
403 403004 Forbidden Favorites access A non-administrator user called this method but doesn't have permission to add a view to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
404 404011 View not found The view ID in the request body doesn't correspond to an existing view.
405 405000 Invalid request method Request type was not PUT.
409 409007 Label conflict There is already a favorite with the same label for a different view of the same workbook in the specified user's favorites.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/favorites/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X PUT -d @add-view-to-favorites.xml -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Content of add-view-to-favorite.xml:

<tsRequest>
  <favorite label="Economic Indicators">
    <view id="1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c" />
  </favorite>
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <favorites>
    <favorite label="DC Crimespotting">
      <view id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6"/>
    </favorite>
    <favorite label="Economic Indicators">
      <view id="1f1e1d1c2-b2a2-f2e3-d3c3-b3a4f4e4d4c"/>
    </favorite>
  </favorites>
</tsResponse>

Add Workbook Permissions

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


URI

PUT /api/api-version/sites/site-id/workbooks/workbook-id/permissions

Parameter Values

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

Request Body

<tsRequest>
  <permissions>
    <workbook id="workbook-id" />
    <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 grantee capability sets ...
  </permissions>
</tsRequest>

Attribute Values

workbook-id The <workbook> element is not required, but can be included for compatibility with earlier versions of the REST API. If the <workbook> element is included, the workbook-id value must match the workbook ID in the URI. Any other attributes in the <workbook> element are ignored.
user-id The ID (not name) of the user to add permissions for.
group-id The ID (not name) of the group to add permissions for.
capability-name

The capability to assign. If any capability has already been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write.

For more information, see Permissions.

capability-mode Allow to allow the capability, or Deny to deny it. This value is case sensitive.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if the have permission to set permissions on the workbook (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <permissions>
    <workbook id="workbook-id" />
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    ... additional grantee capability sets ...
  </permissions>
</tsResponse>

Version

Version 2.0 and later. For more information, see REST API 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.
400 400009 Invalid capability The capability in the URI is invalid for a workbook resource. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to set permissions on the workbook.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found A user ID in the request body doesn't correspond to an existing user.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
404 404012 Group not found A group ID in the request body doesn't correspond to an existing group.
404 404013 Capability not found The specified capability doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allow or Deny for any mode value.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Add Workbook to Favorites

Adds the specified workbook to a user's favorites.

If the user already has the workbook listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.


URI

PUT /api/api-version/sites/site-id/favorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the workbook.
user-id The ID of the user to add the favorite for.

Request Body

<tsRequest>
  <favorite label="favorite-label">
    <workbook id="workbook-id" />
  </favorite>
</tsRequest>

Attribute Values

favorite-label A label to assign to the favorite. This value is displayed when you search for favorites on the server. If the label is already in use for another workbook, an error is returned.
workbook-id The ID (not name) of the workbook to add as a favorite.

Permissions

Tableau Server users who are not administrators or site administrators can call this method only if they have permission to add a workbook to a favorites list.

Response Code

200

Response Body

<tsResponse>
  <favorites>
      <favorite label="favorite-label">
        <workbook id="workbook-id" />
      </favorite>
      <favorite label="favorite">
        <view id="view-id" />
      </favorite>
      ... additional favorites ...
  </favorites>
</tsResponse>

Version

Version 1.0 and later. For more information, see REST API 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.
400 400005 Invalid label

The favorite label is empty or consists of only white space characters.

403 403004 Access to Favorites forbidden

A non-administrator user called this method but doesn't have permission to add a workbook to the specified user's favorites. This will always be the case when the user references in the URI identifies a user other than the user who is calling the method.

404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
404 404006 Workbook not found The workbook ID in the request body doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not PUT.
409 409007 Label conflict There is already a favorite with the same label for a different workbook in the specified user's favorites.

For more information, see Handling Errors.

Add Workbook to Schedule

Adds a task to refresh a workbook to an existing schedule.


URI

PUT /api/api-version/sites/site-id/schedules/schedule-id/workbooks

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the view.
schedule-id The ID of the schedule that you are associating with the workbook.

Request Body

<tsRequest>
  <task>
    <extractRefresh>
      <workbook id="workbook-id" />
    </extractRefresh>            
  </task>
</tsRequest>

Attribute Values

workbook-id The ID of the workbook to add to the schedule.

Permissions

Tableau Server users who are not server administrators or site administrators can only add a workbook to a schedule if they own the workbook, or are the project leader for the project that contains the workbook.

Response Code

20

Response Body

<tsResponse>
  <task>
    <extractRefresh>
      <schedule id="schedule-id" />
      <workbook id="workbook-id" />
    </extractRefresh>
  </task>
</tsResponse>

Version

Version 2.8 and later. For more information, see REST API 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.
401 401002 Unauthorized Access The authentication token provided in the request header was invalid or has expired.
403 403032 Update Forbidden A non-administrator user called this method, but the caller doesn't have sufficient permissions.
404 404000 Site not found The site ID in the URI is unknown.
404 404006 Resource not found The workbook ID in the request body is unknown.
405 405000 Invalid request method Request type was not PUT.
500 500000 Internal Server Error The schedule ID in the URI is unknown..

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1sites/ 1edc53ac-e247-4870-9fd3-6fad0ce5f84d/schedules/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/workbooks" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @add-to-schedule.xml"

Content of add-to-schedule.xml:

<tsRequest>
  <task>
    <extractRefresh>
      <workbook id="5de9cc53-b17d-45af-804d-49144b39f29f" />
    </extractRefresh>            
  </task>
</tsRequest>

Example response:

<tsResponse>
  <task>
    <extractRefresh id="9bf8aea0-e3ca-422e-b7ef-d9c4ba6cca45" priority="50" consecutiveFailedCount="0" type="RefreshExtractTask">
      <schedule id="9a4ebbab-9ec8-487a-9b48-47fa81d6077a" name="Weekday early mornings" state="Active" />
      <workbook id="5de9cc53-b17d-45af-804d-49144b39f29f" />
    </extractRefresh>
  </task>
</tsResponse>

Append to File Upload

Uploads a block of data and appends it to the data that is already uploaded. This method is called after an upload has been initiated using Initiate File Upload.

You call Append to File Upload as many times as needed in order to upload the complete contents of a file. When the final block of data has been uploaded, you call Publish Data Source or Publish Workbook to commit the file.

For more information, see Publishing Resources.


URI

PUT /api/api-version/sites/site-id/fileUploads/upload-session-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site to upload the file to.
upload-session-id The ID of the upload session. You get this value when you start an upload session using Initiate File Upload.

Request Body

The content of the file to be uploaded is included in a MIME multipart message. For more information, see Publishing Resources.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have publishing rights on the site.

Response Code

200

Response Body

<tsResponse>
  <fileUpload uploadSessionId=upload-session-id
              fileSize=size-of-file-in-megabytes-after-append />
</tsResponse>

Version

Version 2.0 and later. For more information, see REST API 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.
400 400016 File size too large The attached file exceeds the configured maximum attachment size for a single append call. The maximum allowable size will be reported in the error response.
400 400019 Malformed request body The XML content in the MIME multipart request is not empty.
400 400020 Missing file data There is no attachment in the request with the file data to be appended to the upload.
403 403007 Not a publisher A non-administrator user attempted to initiate a file upload, but the caller doesn't have publishing rights on the site.
403 403016 Upload failure The file could not be uploaded for some other reason than those specified earlier.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404015 File upload not found The file upload ID in the URI doesn't correspond to an existing file upload.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Cancel Job

Cancels a job specified by job ID. To get a list of job IDs for jobs that are currently queued or in-progress, use the Query Jobs method.


URI

PUT /api/api-version/sites/site-id/jobs/job-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site where the job is running.
job-id The ID of the job to cancel.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403032 Update forbidden A non-administrator user tried to cancel a job.
403 403091 Can not cancel job, because it's already complete. The job ID provided is for a job that has already succeeded or failed.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/jobs/2474164d-8d37-4a4c-abc7-c2070fd25fd5" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Create Group

Creates a group in Tableau Server. If the server is configured to use Active Directory for authentication, this method can create a group in Tableau Server and then import users from an Active Directory group.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

To add users to a group, call Add User To Group. To make changes to an existing group, call Update Group.

If you use the method to import users from an Active Directory, the import process can be performed immediately (synchronously) or as a background job (asynchronously).

Note: If Active Directory contains a large number of users, you should import them asynchronously; otherwise, the process can time out.

The Create Group response returns information in two ways: in the response header and in the response body. The ID of the new group is always returned as the value of the Location header. If you create a local group or import an Active Directory group immediately, the response body contains the name and ID of the new group. If you import an Active Directory group using a background process, the response body contains a <job> element that includes a job ID. You can use the job ID to check the status of the operation by calling Query Job.


URI

POST /api/api-version/sites/site-id/groups

POST /api/api-version/sites/site-id/groups?asJob=asJob-value

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site to create the group in.
asJob-value A Boolean value that is used if you are importing from Active Directory. If you set this to false (the default), the import process runs as a synchronous process. If the Active Directory group contains many users, the process might time out before it finishes.

If you set this to true, the process runs asynchronously. In that case, Tableau Server starts a job to perform the import and returns the job ID in the Location header. You can check the status of the import job by calling Query Job.

Note: This parameter has no effect if the server is configured to use local authentication.

Request Body

Creating a group in Tableau Server (no Active Directory):

<tsRequest>
  <group name="new-tableau-server-group-name" />
</tsRequest>

Importing a group from Active Directory:

<tsRequest>
  <group name="active-directory-group-name" >
    <import source="ActiveDirectory"
            domainName="active-directory-domain-name"
            siteRole="default-site-role" />
  </group>
</tsRequest>

When the request body contains an <import> element, a Tableau Server configured to authenticate via Active Directory will create the group in Tableau Server and modify the set of users in the group to be the same as those in Active Directory. The source attribute of the <import> element must be set to ActiveDirectory.

Note: When a group is created by importing from Active Directory, Tableau Server uses the value of the Active Directory sAMAccountName attribute as the user name.

Attribute Values

new-tableau-server-group-name The name for the new group.
active-directory-group-name

The name of the Active Directory group to import.

active-directory-domain-name

The domain of the Active Directory group to import.

default-site-role

The site role to assign to users who are imported from Active Directory. You can assign the following roles: Creator, Explorer, ExplorerCanPublish, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, or Viewer.

Note: You cannot use the REST API to set a user to be a server administrator (ServerAdministrator site role).

If you import a user from Active Directory whose name matches an existing user, the existing user might have a different site role than the one specified in the <import> element in the request body. The site role that you pass with Update Group can modify the existing user's site role, either by directly upgrading the user's site role or by combining the site role you pass with the user's exiting site role. The ordering of site roles for purposes of upgrading a role is as follows, from the role with the least capabilities to the role with the most capabilities:

  1. Unlicensed
  2. Viewer
  3. Explorer
  4. ExplorerCanPublish
  5. SiteAdministratorExplorer
  6. SiteAdministratorCreator

Permissions

This method can only be called by server administrators and site administrators.

Response Code

201, for creating a local group and for importing immediately.

202, for importing using a background process.

Response Headers

Location: /api/3.1/sites/site-id/groups/new-group-id

Response Body

Creating a group in Tableau Server (no Active Directory) and importing from Active Directory immediately:

<tsResponse>
  <group id="new-group-id"
    name="group-name" />
</tsResponse>

Importing as a background process:

<tsResponse>
    <job id="job-id" mode="Asynchronous" type="GroupImport"
      progress="0" createdAt="time-job-created" />
</tsResponse>

Version

Version 2.0 and later. For more information, see REST API 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.
400 400013 Invalid site role

The value of the siteRole attribute must be Explorer, ExplorerCanPublish, SiteAdministratorCreator, SiteAdministratorExplorer, Unlicensed, or Viewer.

400 400019 Malformed import element When the <import> element is present in the request body, there must be a source, domainName, and siteRole attribute present. If any of these is missing, the element is malformed. The source attribute must also have a value of ActiveDirectory; otherwise the element is likewise malformed.
403 403011 ActiveDirectory is not configured The <import> element is present, but Tableau Server is configured for local authentication.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404016 Domain not found The request body includes an <import> element, but the specified domain name doesn't exist in Active Directory.
404 404017 Active Directory group not found The request body includes an <import> element, but no group exists in Active Directory that matches the specified group name.
405 405000 Invalid request method Request type was not POST.
409 409009 Group name conflict The group name in the request already belongs to the specified site. For the purpose of uniqueness checks, group names are case-insensitive.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-group.xml

Content of create-group.xml:

<tsRequest>
  <group name="marketing-group" />
</tsRequest>

Response header:

Location: /api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d5-e6f7-a8b9-c0d1-e2f3a4b5c6d

Response body:

<tsResponse version-and-namespace-settings>
  <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
        name="marketing-group" />
</tsResponse>

Create Project

Creates a project on the specified site. You can also create project hierarchies by creating a project under the specified parent project on the site. To make changes to an existing project, call Update Project.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

POST /api/api-version/sites/site-id/projects

POST /api/api-version/sites/site-id/projects?publishSamples=publish-value

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site to create the project in.
publish-value (Optional) A Boolean value that specifies whether to publish the sample workbooks provided by Tableau to the project. When the publish-value is not specified in the request, or the publishSamples parameter is missing, no samples will be published. To publish the sample workbooks, set publishSamples parameter to true. This option is equivalent to the tabcmd command-line utility option, publishsamples. For more information, see tabcmd.

Request Body

<tsRequest>
  <project parentProjectId="parent-project-id"
   name="project-name"
   description="project-description"
   contentPermissions="content-permissions" />
</tsRequest>

Attribute Values

parent-project-id (Optional) The identifier of the parent project. Use this option to create project hierarchies. For information about how permissions are evaluated in project hierarchies, see Project Permissions States and Defaults.
project-name The name to assign to the project.
project-description (Optional) A description for the project.
content-permissions (Optional) Specify LockedToProject to lock permissions so that users cannot overwrite the default permissions set for the project, or specify ManagedByOwner to allow users to manage permissions for content that they own. For more information, see Lock Content Permissions to the Project. The default is ManagedByOwner.

Permissions

This method can only be called by server administrators and site administrators.

Response Code

201

Response Body

<tsResponse>
  <project id="new-project-id"
    parentProjectId="parent-project-id"							
    name="project-name"
    description="project-description"
    contentPermissions="content-permissions" />
</tsResponse>

Response Headers

Location: /api/3.1/sites/site-id/projects/new-project-id

Version

Version 1.0 and later. For more information, see REST API 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 403008 Insufficient storage on site The samples could not be published because there is not enough storage space remaining on the server to accommodate the samples.
404 404000 Site not found

The site ID in the URI doesn't correspond to an existing site.

405 405000 Invalid request method Request type was not POST.
409 409006 Project name conflict The project name in the request already belongs to the specified site. For the purpose of uniqueness checks, project names are case-insensitive.

For more information, see Handling Errors.

Example 1

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-project.xml

Content of create-project.xml:

<tsRequest>
  <project name="New-Project"
   description="This is a new project"
   contentPermissions="LockedToProject" />
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="New-Project"
     description="This is a new project"
     contentPermissions="LockedToProject" />
</tsResponse>

Example 2

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-nested-project.xml

Content of create-nested-project.xml:

<tsRequest>
  <project name="New-Nested-Project"
    parentProjectId="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e"
    description="This is a new nested project"
    contentPermissions="LockedToProject" />
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <project id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6"  
   parentProjectId="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e"  
   name="New-Nested-Project"
   description="This is a new nested project"
   contentPermissions="LockedToProject" />
</tsResponse>

Create Schedule

Creates a new schedule on Tableau Server.

Schedules are not specific to sites. For more information, see Extracts and Refresh Schedules and Create or Modify a Schedule in the Tableau Server documentation.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

POST /api/api-version/schedules

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.

Request Body

<tsRequest>
  <schedule name="schedule-name"
    priority="schedule-priority" 
    type="schedule-type"
    frequency="schedule-frequency" 
    executionOrder="schedule-execution-order">
    <frequencyDetails start="start-time" end="end-time">
     <intervals>
        <interval interval-expression />
      </intervals>
    </frequencyDetails>
  </schedule>
</tsRequest>

Attribute Values

schedule-name The name to give to the schedule. This name identifies the schedule in the server environment when users select a schedule and manage schedule information.
schedule-priority An integer value between 1 and 100 that determines the default priority of the schedule if multiple tasks are pending in the queue. Higher numbers have higher priority.
schedule-type Extract to create an extract refresh schedule, or Subscription to create a subscription schedule.
schedule-execution-order Parallel to allow jobs associated with this schedule to run at the same time, or Serial to require the jobs to run one after the other.
schedule-frequency The granularity of the schedule. Valid values are:
  • Hourly. Jobs can be scheduled to run one or more times per day at intervals specified in minutes or hours.
  • Daily. Jobs can be scheduled to run once per day at a specific time.
  • Weekly. Jobs can be scheduled to run one or more times per week.
  • Monthly. Jobs can be scheduled to run once per month on a specific day.

The value you provide for schedule-frequency determines whether you must include an end-time value, and what is required in the contents of the <intervals> element.

start-time The time of day on which scheduled jobs should run (or if the frequency is hourly, on which they should start being run), in the format HH:MM:SS (for example, 18:30:00). This value is required for all schedule frequencies.
end-time If the schedule frequency is Hourly, the time of day on which scheduled jobs should stop being run, in the format HH:MM:SS (for example, 23:30:00). Hourly jobs will occur at the specified intervals between the start time and the end time. For other schedule frequencies, this value is not required; if the attribute is included, it is ignored.
interval-expression A value that specifies the interval between jobs associated with the schedule. The value you specify here depends on the value specified in schedule-frequency.

Hourly

The interval expression is only one of the following:

  • hours="interval" where interval is 1, 2, 4, 6, 8, or 12, representing how many hours between jobs.
  • minutes="interval" where interval is 15 or 30, representing how many minutes between jobs.

You can specify an interval in hours or minutes, but not both.

Daily

If the schedule frequency is Daily, no interval is specified. Any information specified in the <intervals> element is ignored.

Weekly

The interval expression is weekDay="weekday", where weekday is Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.

You can specify multiple <interval> elements to indicate that scheduled jobs should run on multiple days during the week.

Monthly

The interval expression is monthDay="day", where day is either the day of the month (1, 2, etc.) or LastDay.

Permissions

This method can only be called by server administrators.

Response Code

200

Response Body

<tsResponse>
  <schedule id="schedule-id" 
        name="schedule-name" 
        state="Active-or-Suspended" 
        priority="schedule-priority" 
        createdAt="datetime-created" 
        updatedAt="datetime-updated" 
        type="Extract-or-Subscription" 
        frequency="schedule-frequency" 
        nextRunAt="datetime-next-run" 
        executionOrder="Parallel-or-Serial">
        <frequencyDetails frequency-expression >
            <intervals>
               <interval interval-expression />
             </intervals>
        </frequencyDetails>
  </schedule>
</tsResponse>

Version

Version 2.3 and later. For more information, see REST API 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.
400 400064 Error creating schedule An unspecified error occurred while trying to create the schedule.
400 409004 Bad request The content of the request body is missing or incomplete. For hourly, daily, or monthly schedules, this often means that the content of the <intervals> element does not match the expected format. The <detail> element of the error provides detail about the expected format.
405 405000 Invalid request method Request type was not POST.
409 409021 Schedule name conflict The schedule name in the request already belongs to an existing schedule.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/schedules/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-schedule.xml


Content of create-schedule.xml for an hourly schedule

For an hourly schedule, frequencyDetails is set to Hourly. Both start and end values are required. The intervals element is required, and must include 1 interval subelement that contains either an hours or a minutes attribute. Valid values for minutes are 15 or 30. Valid values for hours are 1, 2, 4, 6, 8, or 12.

<tsRequest>
  <schedule name="hourly-schedule-1" 
        priority="50" 
        type="Extract" 
        frequency="Hourly" 
        executionOrder="Parallel">
      <frequencyDetails start="18:30:00" end="23:00:00">
        <intervals>
          <interval hours="2" />
        </intervals>
      </frequencyDetails>
   </schedule>
</tsRequest>

Response body

<tsResponse <span class="api-placeholder">version-and-namespace-settings</span>>
  <schedule id="4d652179-36bf-47e4-a9dc-e069227c72d0" 
       name="hourly-schedule-1" 
       state="Active" 
       priority="50" 
       createdAt="2016-05-07T01:51:19Z" 
       updatedAt="2016-05-07T01:51:19Z" 
       type="Extract" 
       frequency="Hourly" 
       nextRunAt="2016-05-07T03:30:00Z" 
       executionOrder="Parallel">
    <frequencyDetails start="18:30:00" end="23:00:00">
      <intervals>
          <interval hours="2" />
      </intervals>
   </frequencyDetails>
  </schedule>
</tsResponse>


Content of create-schedule.xml for a daily schedule

For a daily schedule, frequencyDetails is set to Daily. The start attribute is required. No intervals element is required.

<tsRequest>
  <schedule name="daily-schedule-1" 
      priority="50" 
      type="Subscription" 
      frequency="Daily" 
      executionOrder="Parallel">
    <frequencyDetails start="02:15:00">
    </frequencyDetails>
  </schedule>
</tsRequest>

Response body

<tsResponse <span class="api-placeholder">version-and-namespace-settings</span>>
    <schedule id="4d652179-36bf-47e4-a9dc-e069227c72d0" 
        name="daily-schedule-1" 
        state="Active" 
        priority="50" 
        createdAt="2016-05-07T01:43:33Z" 
        updatedAt="2016-05-07T01:43:33Z" 
        type="Subscription" 
        frequency="Daily" 
       nextRunAt="2016-05-07T09:15:00Z" 
        executionOrder="Parallel">
      <frequencyDetails start="02:15:00" />
    </schedule>
</tsResponse>


Content of create-schedule.xml for a weekly schedule

For a weekly schedule, frequencyDetails is set to Weekly. A start attribute is required. The intervals element is required, and must include between 1 and 7 interval subelements that contain a weekDay attribute. Valid values for the weekDay attribute are Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.

<tsRequest>
    <schedule name="weekly-schedule-1" 
      priority="50" 
      type="Subscription" 
      frequency="Weekly" 
      executionOrder="Serial">
      <frequencyDetails start="18:30:00">
        <intervals>
          <interval weekDay="Sunday" />
          <interval weekDay="Wednesday" />
        </intervals>
      </frequencyDetails>
     </schedule>
</tsRequest>

Response body

<tsResponse <span class="api-placeholder">version-and-namespace-settings</span>>
  <schedule id="4d652179-36bf-47e4-a9dc-e069227c72d0" 
      name="weekly-schedule-1" 
      state="Active" 
      priority="50" 
      createdAt="2016-05-07T02:01:30Z" 
      updatedAt="2016-05-07T02:01:30Z" 
      type="Subscription" 
      frequency="Weekly" 
      nextRunAt="2016-05-09T01:30:00Z" 
      executionOrder="Serial">
    <frequencyDetails start="18:30:00">
      <intervals>
         <interval weekDay="Sunday" />
         <interval weekDay="Wednesday" />
      </intervals>
    </frequencyDetails>
  </schedule>
</tsResponse>


Content of create-schedule.xml for a monthly schedule

For a monthly schedule, frequencyDetails is set to Monthly. A start attribute is required. The intervals element is required, and must include 1 interval subelement that contains a monthDay attribute. Valid values for the monthDay attribute are integers between 1 and 31 and the string LastDay.

<tsRequest>
  <schedule name="monthly-schedule-1" 
      priority="50" 
      type="Subscription" 
      frequency="Monthly" 
      executionOrder="Parallel">
    <frequencyDetails start="06:00:00">
      <intervals>
        <interval monthDay="15" />
      </intervals>
    </frequencyDetails>
  </schedule>
</tsRequest>

Response body

<tsResponse <span class="api-placeholder">version-and-namespace-settings</span>>
  <schedule id="4d652179-36bf-47e4-a9dc-e069227c72d0" 
        name="monthly-schedule-1" 
        state="Active" 
        priority="50" 
        createdAt="2016-05-07T02:08:25Z" 
        updatedAt="2016-05-07T02:08:25Z" 
        type="Subscription" 
        frequency="Monthly" 
        nextRunAt="2016-06-03T13:00:00Z" 
        executionOrder="Parallel">
    <frequencyDetails start="06:00:00">
      <intervals>
         <interval monthDay="15" />
      </intervals>
    </frequencyDetails>
  </schedule>
</tsResponse>

Create Site

Creates a site on Tableau Server. To make changes to an existing site, call Update Site.

For more information, see Work with Sites and Add or Edit Sites in the Tableau Server documentation.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

POST /api/api-version/sites

Request Body

<tsRequest>
  <site name="site-name"
    contentUrl="content-url"
    adminMode="admin-mode"
    tierCreatorCapacity="num-users"
    tierExplorerCapacity="num-users"
    tierViewerCapacity="num-users"
    storageQuota="limit-in-megabytes"
    disableSubscriptions="disable-subscriptions" />
</tsRequest>

Attribute Values

site-name The name of the site.
content-url The site URL. This value can contain only characters that are valid in a URL.
admin-mode (Optional) Specify ContentAndUsers to allow site administrators to use the server interface and tabcmd commands to add and remove users. (Specifying this option does not give site administrators permissions to manage users using the REST API.) Specify ContentOnly to prevent site administrators from adding or removing users. (Server administrators can always add or remove users.)

Note: You cannot set adminMode to ContentOnly and also set tierCreatorCapacity, tierExplorerCapacity or tierViewerCapacity..

num-users (Optional) The maximum number of users for the site in each of the user-based license types (Creator, Explorer and Viewer). If you do not specify this value, the limit depends on the type of licensing configured for the server. For user-based license types, the maximum number of users is set by the licenses activated on that server. For core-based licensing, there is no limit to the number of users; if you specify a maximum value, only licensed users are counted and server administrators are excluded.
storage-quota (Optional) The maximum amount of space for the new site, in megabytes. If you set a quota and the site exceeds it, publishers will be prevented from uploading new content until the site is under the limit again.
disable-subscriptions (Optional) Specify true to prevent users from being able to subscribe to workbooks on the specified site. The default is false.

Permissions

This method can only be called by server administrators.

Response Code

201

Response Body

<tsResponse>
  <site id="new-site-id"
    name="site-name"
    contentUrl="content-url"
    adminMode="admin-mode"
    tierCreatorCapacity="num-users"
    tierExplorerCapacity="num-users"
    tierViewerCapacity="num-users"
    storageQuota="limit-in-megabytes"
    disableSubscriptions="false" />
</tsResponse>

Response Headers

Location: /api/3.1/sites/new-site-id

Version

Version 1.0 and later. For more information, see REST API 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.
400 400000 Invalid storage quota The storage quota value was not a positive number.
400 400000 Invalid user quota The user quota value was not a positive number.
400 400013 Invalid administrator mode The user provided an administrator mode that is not ContentOnly or ContentAndUsers.

Note: An empty string or all whitespace is invalid.

405 405000 Invalid request method Request type was not POST.
409 409001 Site name conflict The site name in the request already belongs to an existing site.
409 409002 Site URL conflict The content URI in the request already belongs to an existing site.
409 409004 Administrator mode or user quota conflict The request cannot set adminMode to ContentOnly and specify a tierCreatorCapacity, tierExplorerCapacity, or tierViewerCapacity value.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-site.xml

Content of create-site.xml:

<tsRequest>
  <site name="Marketing-Site"
    contentUrl="marketingsite"
    adminMode="ContentAndUsers" />
</tsRequest>

Response body:

<tsResponse version-and-namespace-settings>
  <site id="9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d" name="Marketing-Site"
      contentUrl="marketingsite" adminMode="ContentAndUsers"
      disableSubscriptions="false"
      state="Active">
  </site>
</tsResponse>

Create Subscription

Creates a new subscription to a view or workbook for a specific user. When a user is subscribed to the content, Tableau Server sends the content to the user in email on the schedule that's defined in Tableau Server and specified in this call.

For more information, see Subscribe to Views in the Tableau Server documentation.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

POST /api/api-version/sites/site-id/subscriptions

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site to create the subscription in.

Request Body

<tsRequest>
  <subscription subject="subscription-subject">
    <content type="content-type" id="content-id"  />
    <schedule id="schedule-id" />
    <user id="user-id" />
  </subscription>
</tsRequest>

Attribute Values

subscription-subject A description for the subscription. This description is displayed when users list subscriptions for a site in the server environment. A description is required.
content-type Workbook to create a subscription for a workbook, or View to create a subscription for a view.
content-id The ID of the workbook or view to subscribe to.
schedule-id The ID of a schedule to associate the subscription with. To determine what schedules are available, call Query Schedules.
user-id The ID of the user to create the subscription for.

Note: The user must have an email address defined in Tableau Server.

Permissions

The following list summarizes the permissions required to subscribe a user to specific content:

  • Tableau Server users who are server administrators can subscribe any user to any content.
  • Site administrators can subscribe any user on the site to any content on that site.
  • Project leaders can subscribe users to any content that they are project leaders for.
  • Content owners can subscribe users to any content they own.
  • Non-owners can subscribe themselves to any content that they have Read (view) permissions for.

Response Code

201

Response Body

<tsResponse>
  <subscription id="subscription-id"  subject="subscription-subject">
    <content id="content-id" type="content-type" />
    <schedule id="schedule-id" name="schedule-name" />
    <user id="user-id" name="user-name" />
  </subscription>
</tsResponse>

Response Headers

Location: /api/3.1/sites/site-id/subscriptions/new-subscription-id

Version

Version 2.3 and later. For more information, see REST API 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.
400 400067 Invalid subscription subject The subscription subject is null or empty.
400 400068 Invalid subscription target The content type specified in the request body is not a workbook or view.
400 400069 Invalid subscription type The subscription type is not Workbook or View.
403 403060 No permissions to create subscription. The user does not have permission to create a subscription for the specified content.
403 403063 No user permissions for content. The user specified in the request body does not have Read (view) permissions for the specified content.
403 403064 No user email address. The user does not have an email address.
404 404000 Site not found The specified site doesn't correspond to an existing site.
404 404002 User not found The user specified in the request body doesn't correspond to an existing user.
404 404006 Workbook not found The workbook ID in the request body doesn't correspond to an existing workbook.
404 404011 View not found The view ID in the request body doesn't correspond to an existing view.
404 404023 Schedule not found The schedule ID in the request body doesn't correspond to an existing schedule.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Delete Data Source

Deletes the specified data source from a site. When a data source is deleted, its associated data connection is also deleted. Workbooks that use the data source are not deleted, but they will no longer work properly.


URI

DELETE /api/api-version/sites/site-id/datasources/datasource-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to delete.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete a data source for which they have Read (view) and Delete permissions (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Deletion forbidden A non-administrator user called this method but doesn't have Read (view) and Delete permission for the data source.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source in the site.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Data Source from Favorites

Deletes the specified data source from the user's favorites. If the specified data source is not a favorite, the operation has no effect.


URI

DELETE /api/api-version/sites/site-id/favorites/user-id/datasources/datasource-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the data source.
user-id The ID of the user to remove the favorite from.
datasource-id The ID of the data source to remove from the user's favorites.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have Read (view) permissions on the data source (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Forbidden favorites access A non-administrator user attempted to delete a data source from a different user's favorites.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user
404 404010 Data source not a favorite The data source ID in the URI exists but is not a favorite of the specified user.
404 404011 Data source not found The data source ID in the URI doesn't correspond to an existing data source
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Data Source Permission

Removes the specified data source permission for the specified group or user.


URI

DELETE /api/api-version/sites/site-id/datasources/datasource-id/permissions/groups/group-id/capability-name/capability-mode

DELETE /api/api-version/sites/site-id/datasources/datasource-id/permissions/users/user-id/capability-name/capability-mode

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source 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. Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read (view), and Write.

For more information, see Permissions.

capability-mode Allow to remove the allow permission, or Deny to remove the deny permission. This value is case sensitive.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have permission to delete permissions from the data source (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400009 Invalid capability The capability in the URI is invalid for a data source. Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read, and Write.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to set permissions on the data source.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
404 404012 Group not found The group ID in the URI doesn't correspond to an existing group.
404 404013 Capability not found The capability in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny at the end of the URI.
404 404013 Capability not assigned The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny).
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Default Permission

Removes default permissions from a project. After the default permission has been removed, workbooks or data sources that are added to the project do not get the specified permission by default. You make separate requests to remove default permissions for workbooks and for data sources, and you make separate requests to remove default permissions for a specific group or user.


URI

DELETE /api/api-version/sites/site-id/projects/project-id/default-permissions/workbooks/groups/group-id/capability-name/capability-mode

DELETE /api/api-version/sites/site-id/projects/project-id/default-permissions/workbooks/users/user-id/capability-name/capability-mode

DELETE /api/api-version/sites/site-id/projects/project-id/default-permissions/datasources/groups/group-id/capability-name/capability-mode

DELETE /api/api-version/sites/site-id/projects/project-id/default-permissions/datasources/users/user-id/capability-name/capability-mode

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the project.
project-id The ID of the project to remove the default permission for.
group-id The ID of the group to remove the default permission for.
user-id The ID of the user to remove default permission for.
capability-name

The capability to remove the permissions for.

Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write.

Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read (view), and Write.

For more information, see Permissions.

capability-mode Allow to remove the allow permission, or Deny to remove the deny permission. This value is case sensitive.

Request Body

None

Permissions

Tableau Server users who are not server administrators can remove permissions for a project only if they have ProjectLeader permissions for that project (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400009 Invalid capability The capability in the URI is invalid.

Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read, ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write.

Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read, and Write.

403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permissions to remove permissions for the project.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found A user ID in the URI doesn't correspond to an existing user.
404 404005 Project not found The project ID in the URI doesn't correspond to an existing project.
404 404012 Group not found A group ID in the URI doesn't correspond to an existing group.
404 404013 Capability not assigned The capability in the URI isn't assigned to the specified user or group.
404 404013 Capability not found The capability in the URI doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allow or Deny for any mode value.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Group

Deletes the group on a specific site. Deleting a group does not delete the users in group, but users are no longer members of the group. Any permissions that were previously assigned to the group no longer apply.

Note: You cannot delete the All Users group.


URI

DELETE /api/api-version/sites/site-id/groups/group-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the project.
group-id The ID of the group to delete.

Request Body

None

Permissions

This method can be called by site administrators.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404012 Group not found The group ID in the URI doesn't correspond to an existing group or the group is not part of the specified site.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response contains no body (data) for a successful delete operation. The HTTP response code is 204 if the delete operation succeeded.

Delete Project

Deletes the specified project on a specific site. When a project is deleted, all of its assets are also deleted: associated workbooks, data sources, project view options, and rights. Use this method with caution.


URI

DELETE /api/api-version/sites/site-id/projects/project-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the project.
project-id The ID of the project to delete.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403003 Deletion forbidden Attempt to delete the default project, which cannot be deleted.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404005 Project not found The project ID in the URI doesn't correspond to an existing project or the project is not found on this site.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects/1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response contains no body (data) for a successful delete operation. The HTTP response code is 204 if the delete operation succeeded.

Delete Project from Favorites

Deletes the specified project from the user's favorites. If the specified project is not a favorite, the operation has no effect.


URI

DELETE /api/api-version/sites/site-id/favorites/user-id/projects/project-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the project.
user-id The ID of the user to remove the favorite from.
project-id The ID of the project to remove from the user's favorites.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete a project only from their own favorites.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Forbidden favorites access A non-administrator user attempted to delete a project from a different user's favorites.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
404 404005 Project not found The project ID in the URI doesn't correspond to an existing project.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/favorites/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/projects/89a82d78-664f-45a1-8256-d4d2961a070b" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Delete Project Permission

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


URI

DELETE /api/api-version/sites/site-id/projects/project-id/permissions/groups/group-id/capability-name/capability-mode

DELETE /api/api-version/sites/site-id/projects/project-id/permissions/users/user-id/capability-name/capability-mode

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the project.
project-id The ID of the project 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 project the permission for.
capability-name The capability to remove the permission for. In Tableau Server 10.0, valid capabilities for a project are ProjectLeader, Read (view), and Write.

For more information, see Permissions.

capability-mode Allow to remove the allow permission, or Deny to remove the deny permission. This value is case sensitive.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can remove permissions for a project only if they have ChangePermissions (version 2.0) or ProjectLeader (version 2.1) permissions for that project (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400009 Invalid capability The capability in the URI is invalid for a project. For a list of valid capabilities, see the capability-name attribute earlier.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permissions to remove default permissions for the project.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found A user ID in the URI doesn't correspond to an existing user.
404 404005 Project not found The project ID in the URI doesn't correspond to an existing project.
404 404012 Group not found A group ID in the URI doesn't correspond to an existing group.
404 404013 Capability not assigned The capability in the URI isn't assigned to the specified user or group.
404 404013 Capability not found The capability in the URI doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allow or Deny for any mode value.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Schedule

Deletes the specified schedule.


URI

DELETE /api/api-version/schedules/schedule-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
schedule-id The ID of the schedule to delete. To determine what schedules are available, call Query Schedules.

Request Body

None

Permissions

This method can only be called by server administrators.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400059 Error deleting the schedule. An unspecified error occured during the deletion operation.
404 404023 Schedule not found The specified schedule doesn't correspond to an existing schedule on the site.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Site

Deletes the specified site.

You can specify the site to delete by using the site ID, the site name, or the content URL. You use the key query string parameter to indicate how you are specifying the site, as shown in the URIs.

Note: You must have previously called Sign In and signed in to a site in order to delete the site. (When you call this method, you must include the authentication token that you got back when you signed into the site.)


URI

DELETE /api/api-version/sites/site-id

DELETE /api/api-version/sites/site-name?key=name

DELETE /api/api-version/sites/content-url?key=contentUrl

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site to delete.
site-name The name of the site to delete. If you specify a site name, you must also include the parameter key=name.
content-url The URL of the site to delete. If you specify a content URL, you must also include the parameter key=contentUrl.

Request Body

None

Permissions

This method can only be called by server administrators.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403002 Deletion not allowed. An attempt was made to delete the default Tableau Server site.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

curl "http://MY-SERVER/api/3.1/sites/marketing-site?key=contentUrl" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response contains no body (data) for a successful delete operation. The HTTP response code is 204 if the delete operation succeeded.

Delete Subscription

Deletes the specified subscription.


URI

DELETE /api/api-version/sites/site-id/subscriptions/subscription-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the subscription.
subscription-id The ID of the subscription to delete. To determine what subscriptions are available, call Query Subscriptions.

Request Body

None

Permissions

Tableau Server users can call this method to delete any subscription that they had permission to create. For details, see Create Subscription.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400062 Error deleting the subscription. An unspecified error occured during the deletion operation.
401 401002 User not authenticated. The user making the request has not been authenticated for this site.
403 403059 Delete forbidden. A non-administrator user called this method but doesn't have permission to delete the subscription.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Tag from Data Source

Deletes a tag from the specified data source.


URI

DELETE /api/api-version/sites/site-id/datasources/datasource-id/tags/tag-name

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to remove the tag from.
tag-name The name of the tag to remove from the data source.

Request Body

None

Permissions

Tableau Server users who are not server administrators, site administrators, or workbook owners can delete a tag from a data source only if they are project leaders or if they originally added the tag.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400077 Error deleting tag There was a problem deleting the tag from the specified data source.
403 403004 Deleting tags forbidden A non-administrator user called this method but doesn't have permission to delete a tag from the specified workbook.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
404 404007 Tag not found The tag in the URI doesn't exist for the specified workbook.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Tag from View

Deletes a tag from the specified view.


URI

DELETE /api/api-version/sites/site-id/views/view-id/tags/tag-name

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the workbook.
view-id The ID of the view to remove the tag from.
tag-name The name of the tag to remove from the view.

Request Body

None

Permissions

Tableau Server users who are not server administrators, site administrators, or workbook owners can delete a tag from a workbook only if they are project leaders or if they originally added the tag.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400078 Error deleting tag There was a problem deleting the tag from the specified view.
403 403004 Deleting tags forbidden A non-administrator user called this method but doesn't have permission to delete a tag from the specified workbook.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
404 404007 Tag not found The tag in the URI doesn't exist for the specified workbook.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Tag from Workbook

Deletes a tag from the specified workbook.


URI

DELETE /api/api-version/sites/site-id/workbooks/workbook-id/tags/tag-name

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to remove the tag from.
tag-name The name of the tag to remove from the workbook.

Request Body

None

Permissions

Tableau Server users who are not server administrators, site administrators, or workbook owners can delete a tag from a workbook only if they are project leaders or if they originally added the tag.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400051 Error deleting tag There was a problem deleting the tag from the specified workbook.
403 403004 Deleting tags forbidden A non-administrator user called this method but doesn't have permission to delete a tag from the specified workbook.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
404 404007 Tag not found The tag in the URI doesn't exist for the specified workbook.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete View from Favorites

Deletes the specified view from user's favorites. If the specified view is not a favorite, the operation has no effect.


URI

DELETE /api/api-version/sites/site-id/favorites/user-id/views/view-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the view.
user-id The ID of the user to remove the favorite from.
view-id The ID of the view to remove from the user's favorites.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete a view only from their own favorites.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Forbidden Favorites access A non-administrator user attempted to delete a view from a different user's favorites.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user
404 404010 View not a favorite The view ID in the URI exists but is not a favorite of the specified user.
404 404011 View not found The view ID in the URI doesn't correspond to an existing view
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Workbook

Deletes a workbook. When a workbook is deleted, all of its assets are also deleted, including associated views, data connections, and so on.


URI

DELETE /api/api-version/sites/site-id/workbooks/workbook-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to remove.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete a workbook for which they have Read (view) and Delete permissions (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Workbook from Favorites

Deletes a workbook from a user's favorites. If the specified workbook is not a favorite of the specified user, this call has no effect.


URI

DELETE /api/api-version/sites/site-id/favorites/user-id/workbooks/workbook-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the user.
user-id The ID of the user to remove the favorite from.
workbook-id The ID of the workbook to remove from the user's favorites.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can remove a workbook only from their own favorites.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Access to Favorites forbidden A non-administrator user attempted to delete a workbook from a different user's favorites.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
404 404010 Workbook not a favorite The workbook ID in the URI exists but belongs to a different user.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Workbook Permission

Deletes the specified permission from the specified workbook for a group or user.


URI

DELETE /api/api-version/sites/site-id/workbooks/workbook-id/permissions/groups/group-id/capability-name/capability-mode

DELETE /api/api-version/sites/site-id/workbooks/workbook-id/permissions/users/user-id/capability-name/capability-mode

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook 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. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write.

For more information, see Permissions.

capability-mode Allow to remove the allow permission, or Deny to remove the deny permission. This value is case sensitive.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete permissions from a workbook only if they have ChangePermissions permission for workbook (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400009 Invalid capability The capability in the URI is invalid for a workbook resource. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read, Share_view, ViewComments, ViewUnderlyingData, WebAuthoring, and Write.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to delete permissions from the workbook.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
404 404012 Group not found The group ID in the URI doesn't correspond to an existing group.
404 404013 Capability not found The capability in the URI doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allow or Deny at the end of the URI.
404 404013 Capability not assigned The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny).
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Download Data Source

Downloads a data source in .tdsx format.


URI

GET /api/api-version/sites/site-id/datasources/datasource-id/content

GET /api/api-version/sites/site-id/datasources/datasource-id/content?includeExtract=extract-value

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to download.
extract-value (Optional) The extract-value is a Boolean value (False or True). When the data source specified for download has an extract, if you add the parameter ?includeExtract=False, the extract is not included when you download the data source. You can use this parameter to improve performance if you are downloading workbooks or data sources that have large extracts.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can download a data source only if they have ExportXml permission for the data source (either explicitly or implicitly).

Response Code

200

Response Body

The data source content in .tdsx format (Content-Type: application/octet-stream).

The response will have the following content disposition header:

Content-Disposition: name="tableau_datasource"; filename="datasource-filename"

Version

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

Errors

HTTP status error Code Condition Details
403 403028 Read forbidden A non-administrator user attempted to download a data source, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/content" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" > my-datasource.tdsx

The response is a file that contains the data source.

Download Data Source Revision

Downloads a specific version of a data source in .tdsx format.

Note: This method is available only if version history is enabled for the specified site. For more information, see Maintain a History of Revisions in the Tableau Server Help.


URI

GET /api/api-version/sites/site-id/datasources/datasource-id/revisions/revision-number/content

GET /api/api-version/sites/site-id/datasources/datasource-id/revisions/revision-number/content?includeExtract=extract-value

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to download.
revision-number The revision number of the data source to download. To determine what versions are available, call Get Data Source Revisions.
extract-value (Optional) The extract-value is a Boolean value (False or True). When the data source specified for download has an extract, if you add the parameter ?includeExtract=False, the extract is not included when you download the data source. You can use this parameter to improve performance if you are downloading workbooks or data sources that have large extracts.

Request Body

None

Permissions

Tableau Server users who are site administrators can download data source revisions on the site that they are administrators for. Users who are not server administrators or site administrators can get data source revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified data source.
  • Save (write) permissions for the project that contains the data source.

Response Code

200

Response Body

The data source content in .tdsx format (Content-Type: application/octet-stream).

The response will have the following content disposition header:

Content-Disposition: name="tableau_datasource"; filename="datasource-filename"

Version

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

Errors

HTTP status error Code Condition Details
403 403028 Read forbidden A non-administrator user attempted to download a data source, but the caller doesn't have required permissions.
403 403053 Version history not enabled version history is not enabled for the specified site.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
404 404024 Data source revision not found The revision number in the URI doesn't correspond to an existing data source revision.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Download Workbook

Downloads a workbook in .twb or .twbx format.


URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/content

GET /api/api-version/sites/site-id/workbooks/workbook-id/content?includeExtract=extract-value

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to download.
extract-value (Optional) The extract-value is a Boolean value (False or True). When the workbook specified for download has an extract, if you add the parameter ?includeExtract=False, the extract is not included when you download the workbook. You can use this option to improve performance if you are downloading workbooks or data sources that have large extracts.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can download a workbook only if they have ExportXml permission for the workbook (either explicitly or implicitly).

Response Code

200

Response Body

One of the following, depending on the format of the workbook:

  • The workbook's content in .twb format (Content-Type: application/xml)
  • The workbook's content in .twbx format (Content-Type: application/octet-stream)

In both cases, the response will have the following content disposition header:

Content-Disposition: name="tableau_workbook"; filename="workbook-filename"

Version

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

Errors

HTTP status error Code Condition Details
403 403019 Read forbidden A non-administrator user attempted to download a workbook, but the caller doesn't have ExportXml permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/content" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" > c:\files\my-workbook.twbx

The response is a file that contains the workbook.

Download Workbook Revision

Downloads a specific version of a workbook in .twb or .twbx format.

Note: This method is available only if version history is enabled for the specified site. For more information, see Maintain a History of Revisions in the Tableau Server Help.


URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions/revision-number/content

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions/revision-number/content?includeExtract=extract-value

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to download.
revision-number The revision number of the workbook to download. To determine what versions are available, call Get Workbook Revisions. Note that the current revision of a workbook cannot be accessed by this call; use Download Workbook instead.
extract-value (Optional) The extract-value is a Boolean value (False or True). When the workbook specified for download has an extract, if you add the parameter ?includeExtract=False, the extract is not included when you download the workbook. You can use this option to improve performance if you are downloading workbooks or data sources that have large extracts.

Request Body

None

Permissions

Tableau Server users who are site administrators can download workbook revisions on the site that they are administrators for. Users who are not server administrators or site administrators can download workbook revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified workbook.
  • Save (write) permissions for the project that contains the workbook.

Response Code

200

Response Body

One of the following, depending on the format of the workbook:

  • The workbook's content in .twb format (Content-Type: application/xml)
  • The workbook's content in .twbx format (Content-Type: application/octet-stream)

In both cases, the response will have the following content disposition header:

Content-Disposition: name="tableau_workbook"; filename="workbook-filename"

Version

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

Errors

HTTP status error Code Condition Details
403 403053 Version history not enabled version history is not enabled for the specified site.
403 403019 Read forbidden A non-administrator user attempted to download a workbook, but the caller doesn't have required permissions.
404 404024 Workbook revision not found The revision number in the URI doesn't correspond to an existing data source revision.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Get Data Source Revisions

Returns a list of revision information (history) for the specified data source.

Note: This method is available only if version history is enabled for the specified site. For more information, see Maintain a History of Revisions in the Tableau Server Help.

To get a specific version of the data source from revision history, use the Download Data Source Revision method.


URI

GET /api/api-version/sites/site-id/datasources/datasource-id/revisions

GET /api/api-version/sites/site-id/datasources/datasource-id/revisions?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the data source to get revisions for.
datasource-id The ID of the data source to get revisions for.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

Tableau Server users who are site administrators can get data source revisions on the site that they are administrators for. Users who are not server administrators or site administrators can get data source revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified data source.
  • Save (write) permissions for the project that contains the data source.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber" pageSize="page-size"
       totalAvailable="total-available" />
  <revisions>
    <revision createdAt="date" revisionNumber="1" isDeleted="false">
      <user id="user-id" name="user-name"/>
    </revision>
    <revision createdAt="date" revisionNumber="2" isDeleted="false">
    </revision>
    <revision createdAt="date" revisionNumber="3" isCurrent="true">
        <user id="user-id" name="user-name"/>
    </revision>
  </revisions>
</tsResponse>

If the revision element includes the attribute isDeleted="true", the data source has been deleted and cannot be downloaded using the Download Data Source Revision method.

If a user has been deleted from the site, no <user> element is included in the <revision> element.

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
403 403053 Version history not enabled version history is not enabled for the specified site.
403 403054 A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Get Extract Refresh Task

Returns information about the specified extract refresh task.

This method shows you information about the scheduled task for the data source extract or a published workbook that connects to the data extract.


URI

GET /api/api-version/sites/site-id/tasks/extractRefreshes/task-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that the user is a member of.
task-id The ID of the extract refresh that you want information about.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can only access the list of extract refresh tasks that they own.

Response Code

200

Response Body

<tsResponse>
<task>
 <extractRefresh id="refresh_task_id" 
  priority="nn" 
  consecutiveFailedCount="n" 
  type="REFRESH_EXTRACT">
  <schedule id="schedule_id" 
    name="schedule_name" 
    state="state" 
    priority="nn" 
    createdAt="DATE_TIME" 
    updatedAt="DATE_TIME" 
    type="Extract" 
    frequency="frequency" 
    nextRunAt="DATE_TIME" />
   <datasource id="datasource_id" />
 </extractRefresh>	
</task>
</tsResponse>

Version

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

Errors

403 403004 Operation unauthorized The user is not authorized to get the task.
404 404026 Task not found The task ID in the URI doesn't correspond to an existing task.
405 40500 Invalid requests method Request type was not GET

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/extractRefreshes/9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:


<tsResponse version-and-namespace-settings>
 <task>
  <extractRefresh id="9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c" 
   priority="50" 
   consecutiveFailedCount="0" 
   type="REFRESH_EXTRACT">
   <schedule id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b" 
	 name="Weekday early mornings" 
	 state="Active" 
	 priority="50" 
	 createdAt="2016-07-13T20:55:52Z" 
	 updatedAt="2017-04-27T11:00:40Z" 
	 type="Extract" 
	 frequency="Weekly" 
	 nextRunAt="2017-04-28T11:00:00Z" />
   <datasource id="1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b" />
  </extractRefresh>
 </task>
</tsResponse>

Get Extract Refresh Tasks

Returns a list of extract refresh tasks for the site.

This method shows you information about the scheduled tasks on the specified site for data source extracts or a published workbooks that connect to data extracts.


URI

GET /api/api-version/sites/site-id/tasks/extractRefreshes

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that the user is a member of.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can only access the list of extract refresh tasks that they own.

Response Code

200

Response Body

<tsResponse>
<tasks>
 <task>
  <extractRefresh id="refresh_task_id" 
  priority="nn" 
  consecutiveFailedCount="n" 
  type="REFRESH_EXTRACT">
  <schedule id="schedule_id" 
    name="schedule_name" 
    state="state" 
    priority="nn" 
    createdAt="DATE_TIME" 
    updatedAt="DATE_TIME" 
    type="Extract" 
    frequency="frequency" 
    nextRunAt="DATE_TIME" />
   <datasource id="datasource_id" />
  </extractRefresh>	
 </task>
 <task>
 ... additional tasks ...
 </task>
</tasks>								
</tsResponse>

Version

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

Errors

405 40500 Invalid requests method Request type was not GET

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/extractRefreshes" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:


<tsResponse version-and-namespace-settings>
  <task>
   <extractRefresh id="9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c" 
   priority="50" 
   consecutiveFailedCount="0" 
   type="REFRESH_EXTRACT">
	<schedule id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b" 
	 name="Weekday early mornings" 
	 state="Active" 
	 priority="50" 
	 createdAt="2016-07-13T20:55:52Z" 
	 updatedAt="2017-04-27T11:00:40Z" 
	 type="Extract" 
	 frequency="Weekly" 
	 nextRunAt="2017-04-28T11:00:00Z" />
	<datasource id="1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b" />
   </extractRefresh>
  </task>
</tsResponse>

Get Favorites for User

Returns a list of favorite projects, data sources, views and workbooks for a user.


URI

GET /api/api-version/sites/site-id/favorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that the user is a member of.
user-id The ID of the user for which you want to get a list favorites.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they are the user for which they want to get a list of favorites.

Response Code

200

Response Body

<tsResponse>
  <favorites>
    <favorite label="favorite-label">
      <project id="project-id" />
    </favorite>
    <favorite label="favorite-label">
     <workbook id="workbook-id" />
    </favorite>
    <favorite label="favorite-label">
     <view id="view-id" />
    </favorite>
    <favorite label="favorite-label">
     <datasource id="datasource-id" />
    </favorite>
    ... additional favorites ...
  </favorites>
</tsResponse>

Version

Version 2.5 and later. Support for favorite projects added in version 3.1. For more information, see REST API Versions.

Errors

403 403004 Forbidden Favorites access A non-administrator user called this method but doesn't have permission to view the specified user's favorites.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/favorites/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <favorites>
    <favorite label="Global Economic Indicators">
      <project id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6"/>
    </favorite>
    <favorite label="US Economic Indicators">
      <view id="1f1e1d1c2-b2a2-f2e3-d3c3-b3a4f4e4d4c"/>
    </favorite>
  </favorites>
</tsResponse>

Get Users in Group

Gets a list of users in the specified group.

URI

GET /api/api-version/sites/site-id/groups/group-id/users

GET /api/api-version/sites/site-id/groups/group-id/users?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the group.
group-id The ID of the group to get the users for.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber"
           pageSize="page-size"
           totalAvailable="total-available" />
    <users>
      <user id="user-id"
    name="user-name"
    siteRole="site-role"
    lastLogin="last-login-date-time"
    externalAuthUserId="authentication-id-from-external-provider" />
    ... additional user information ...
   </users>
</tsResponse>

The siteRole value is returned as one of the following values: Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, or Viewer.

The externalAuthUserId value is returned for Tableau Online; it represents ID stored in Tableau's single sign-on (SSO) system. For other server configurations, this field contains null, and the value of lastLogin is an empty string.

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404012 Group not found The group ID in the URI doesn't correspond to an existing group.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/users" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="2"/>
  <users>
    <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" name="Adam" siteRole="Explorer" />
    <user id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" name="Bob" siteRole="ExplorerCanPublish" />
  </users>
</tsResponse>

Get Users on Site

Returns the users associated with the specified site.


URI

GET /api/api-version/sites/site-id/users

GET /api/api-version/sites/site-id/users?filter=filter-expression

GET /api/api-version/sites/site-id/users?sort=sort-expression

GET /api/api-version/sites/site-id/users?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/users?fields=field-expression

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the users.
filter-expression (Optional) An expression that lets you specify a subset of users to return. You can filter on predefined fields such as name and lastLogin. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which user information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
field-expression (Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as _all_ or _default_, and you can specify individual fields for the views or other supported resources. You can include multiple field expressions in a request. For more information, see Using Fields in the REST API.

Note: The filter and sort parameters can be combined with each other and with paging parameters and fields parameters using an ampersand &.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
   <pagination pageNumber="page-number"
     pageSize="page-size"
     totalAvailable="total-available" />
   <users>
    <user id="user-id"
      name="user-name"
      siteRole="site-role"
      lastLogin="date-time"
      externalAuthUserId="authentication-id-from-external-provider"
      authSetting="auth-setting" />
    <user id="user-id"
      name="user-name"
      siteRole="site-role"
      lastLogin="date-time"
      externalAuthUserId="authentication-id-from-external-provider"
      authSetting="auth-setting" />
  ... additional users ...
  </users>
</tsResponse>

The siteRole value is returned as one of the following values: Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, or Viewer.

The externalAuthUserId value is returned for Tableau Online; it represents ID stored in Tableau's single sign-on (SSO) system. For other server configurations, this field contains null, and the value of lastLogin is an empty string.

The authSetting attribute is returned only if you are using Tableau Online or Tableau Server with site-specific SAML enabled.

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number is not an integer, is less than one, or is greater than the final page number for users at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="161"/>
  <users>
    <user id="9f9e9d9c8-b8a8-f8e7-d7c7-b7a6f6d6e6d" name="Ashley"
        siteRole="Viewer" />
    <user id="12ab34cd5-6ef7-8ab9-0cd1-2ef34ab56cd" name="Laura"
        siteRole="Unlicensed" />
    <user id="9a8a7b6b5-c4c3-d2d1-e0e9-a8a7b6b5b4b" name="Michelle"
        siteRole="ExplorerCanPublish" />
    <user id="9f8e7d6c5-b4a3-f2e1-d0c9-b8a7f6e5d4c" name="Susan"
        siteRole="Explorer" />
    ... another 95 users listed here ...
  </users>
</tsResponse>

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users?filter=siteRole:eq:Unlicensed&sort=name:asc" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

This example includes a filter to return the users whose site role is Unlicensed and specifies that the results should be sorted by the name value.

Get Workbook Revisions

Returns a list of revision information (history) for the specified workbook.

Note: This method is available only if version history is enabled for the specified site.

To get a specific version of the workbook from revision history, use the Download Workbook Revision method. For more information, see Maintain a History of Revisions in the Tableau Server Help.


URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the workbook to get revisions for.
workbook-id The ID of the workbook to get revisions for.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

Tableau Server users who are site administrators can get workbook revisions on the site that they are administrators for. Users who are not server administrators or site administrators can get workbook revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified workbook.
  • Save (write) permissions for the project that contains the workbook.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber" pageSize="page-size"
       totalAvailable="total-available" />
  <revisions>
    <revision createdAt="date" revisionNumber="1" isDeleted="false">
      <user id="user-id" name="user-name"/>
    </revision>
    <revision createdAt="date" revisionNumber="2" isDeleted="false">
    </revision>
    <revision createdAt="date" revisionNumber="3" isCurrent="true">
        <user id="user-id" name="user-name"/>
    </revision>
  </revisions>
</tsResponse>

If the revision element includes the attribute isDeleted="true", the workbook has been deleted and cannot be downloaded using the Download Workbook Revision method.

If a user has been deleted from the site, no <user> element is included in the <revision> element.

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
403 403053 Version history not enabled version history is not enabled for the specified site.
403 403056 A non-administrator user attempted to get workbook revision information, but the caller doesn't have sufficient permissions.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Initiate File Upload

Initiates the upload process for a file. After the upload has been initiated, you call Append to File Upload to send individual blocks of the file to the server. When the complete file has been sent to the server, you call Publish Data Source or Publish Workbook to commit the upload.

Initiate File Upload returns an upload session ID that you pass to Append to File Upload or one of the publishing methods in order to identify the upload session.

The file size that is returned in the response is initialized to zero (0) megabytes, because no data has yet been loaded. Subsequent calls to Append to File Upload or the publishing APIs update this value.

For more information, see Publishing Resources.


URI

POST /api/api-version/sites/site-id/fileUploads

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site to upload the file to.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can initiate a file upload only if they have publishing rights on the site.

Response Code

201

Response Body

<tsResponse>
  <fileUpload uploadSessionId=new-upload-session-id
     fileSize=0 />
</tsResponse>

Version

Version 2.0 and later. For more information, see REST API 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 403015 Access to Favorites forbidden A non-administrator user attempted to initiate a file upload, but the caller doesn't have publishing rights on the site.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Publish Data Source

Publishes a data source on the specified site, or appends data to an existing data source. To make other changes to a published data source, call Update Data Source or Update Data Source Connection.

This method is used in two ways. You can call it to publish a workbook in a single request. To do that, you include the content of the workbook file in the body of the request. The maximum size of a file that can be published in a single request is 64 MB. If you want to avoid having the publishing process time out, you can use the asJob parameter to make workbook publication asynchronous.

Alternatively, you can publish a data source in multiple parts. To do that, you initiate a file upload by calling Initiate File Upload, send portions of the file to the server using Append to File Upload, and then commit the upload by calling Publish Data Source. In this case, Publish Data Source doesn't contain the file to publish.

Note: When you publish a data source from your local computer to the server, you must make sure that the server has all the components that are required in order for other users to see and interact with the data source. For example, if the data source is based on an Excel spreadsheet, you typically publish a packaged data source (.tdsx file) that contains all the components for that data source.

For more information, see Publishing Resources.


URI

POST /api/api-version/sites/site-id/datasources

POST /api/api-version/sites/site-id/datasources?overwrite=overwrite-flag&asJob=asJob-value

POST /api/api-version/sites/site-id/datasources?append=append-flag

POST /api/api-version/sites/site-id/datasources?uploadSessionId=upload-session-id&datasourceType=datasource-file-type&overwrite=overwrite-flag&append=append-flag

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site to publish to.
overwrite-flag (Optional) true to overwrite a data source that has the same name, or false to fail if the specified data source already exists. The default is false. If overwrite-flag is set to true but the data source doesn't already exist, the operation succeeds.

You can include both the overwrite and append parameters in a request, but they cannot both be true.

asJob-value (Optional) A Boolean value that is used to publish data sources asynchronously. If you set this value to false (the default), the publishing process runs as a synchronous process. If a workbook is very large, the process might time out before it finishes. If you set this value to true, the process runs asynchronously, and a job will start to perform the publishing process and return the job ID. You can check the status of the import job by calling Query Job.
append-flag (Optional) true to append the data being published to an existing data source that has the same name. The default is false. If append-flag is set to true but the data source doesn't already exist, the operation fails.

In order to append data to an existing data source, both the data source on the server and the data source you are publishing must be extracts (.tde and .hyper files). The schemas of the two extracts must match.

You can include both the overwrite and append parameters in a request, but they cannot both be true.

upload-session-id If you are calling this method to commit a file that was uploaded in parts, this value contains the upload session ID that was generated by a call to Initiate File Upload. If this value is not included, the server assumes that the body of the request contains the file to be published.
datasource-file-type hyper, tds, tdsx, or tde the kind of file that you are uploading. This value is required if you are calling Publish Data Source in order to commit a file that was previously uploaded using Append to File Upload. The value is not used if you upload a file in the body of the request.

Request Body

Publishing a file in the request body

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml

<tsRequest>
    <datasource name="datasource-name" >
        <connectionCredentials name="connection-username" password="connection-password"
            embed="embed-flag" />
        <project id="project-id" />
  </datasource>
</tsRequest>
--boundary-string
Content-Disposition: name="tableau_datasource"; filename="datasource-file-name"
Content-Type: application/octet-stream

content-of-datasource-file
--boundary-string--

Committing a file previously uploaded

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml

<tsRequest>
    <datasource name="datasource-name" >
        <connectionCredentials name="connection-username" password="connection-password"
            embed="embed-flag" oAuth="oauth-flag" />
        <project id="project-id" />
  </datasource>
</tsRequest>
--boundary-string--

Attribute Values

boundary-string A string of characters that is guaranteed to be unique within the body of the request, and that is used to delimit sections of the request body. This value must be declared as a header that has this format:

Content-type: multipart/mixed; boundary=boundary-string

datasource-name The name to assign to the data source when it is saved on the server.
connection-username (Optional) If the data source connection requires credentials, the <connectionCredentials> element is included and this attribute specifies the connection username. If the element is included but is not required, the server ignores the element and its attributes.
connection-password (Optional) If the data source connection requires credentials, the <connectionCredentials> element is included and this attribute specifies the connection password. If the element is included but is not required, the server ignores the element and its attributes.
embed-flag (Optional) If the data source connection requires credentials, the <connectionCredentials> element is included. Setting this attribute to True instructs the server to save the credentials for when the data source is used.
oauth-flag (Optional) If the data source connection is configured to use OAuth, set this to True to specify that the value of the name attribute in the <connectionCredentials> element is an OAuth username. In that case, no password is required and the value of the embed attribute specifies whether to embed the OAuth credential with the data source. For more information, see OAuth Connections in the Tableau Server documentation.
project-id The ID of the project to assign the data source to.
datasource-file-name The file name (including extension) of the data source file to upload. This attribute is used in the request body only if the request also includes the content of the data source file; it is not used if you are committing a file uploaded using previous requests.
content-of-datasource-file The content of the data source file, if the request includes the file. The maximum size of a file that can be uploaded in one call is 64 MB.

Permissions

Tableau Server users who are not server administrators or site administrators can view data sources only if they have Connect permission for the data source (either explicitly or implicitly).

Response Code

201

Response Body

<tsResponse>
  <datasource id="datasource-id"
     name="datasource-name"
     type="datasource-type" 
     createdAt="datetime-created" 
     updatedAt="datetime-updated">
    <project id="project-id" name="project-name" />
    <tags>
      <tag label="tag"/>
      <tag label="tag"/>
      ... additional tags ...
    </tags>
  </datasource>
</tsResponse>

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Response Headers

Location: /api/3.1/sites/site-id/datasources/id-from-server
 

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The request message is missing or incomplete, or contains malformed XML. Make sure that the Content-Length value is set.
400 400000 Missing data source There is no attachment in the request for the data source.
400 400008 Invalid overwrite value The overwrite parameter must be set to true or false.
400 400008 Invalid append value The append parameter must be set to true or false.
400 400008 Invalid embed value The request body contains a <connectionCredentials> element and it has an embed attribute whose value is not true or false.
400 400010 Invalid data source filename The name of the data source file did not end with the suffix .hyper, .tds, .tdsx, or .tde.
400 400010 Missing or invalid file type The request included an uploadSessionId parameter but no file type, or the file type was something other than hyper, tds, tdsx, or tde.
400 400010 Unexpected attachments The message had both a uploadSessionId parameter and an attachment, or the message contained more than one attachment.
400 400011 Publishing error The data source could not be published for some other reason than those specified earlier.
400 400019 Malformed request body The request message is missing or incomplete, or contains malformed XML. Make sure that the Content-Length value is set.
400 400055 Incompatible overwrite and append values The overwrite and append parameter cannot both be set to true.
403 403007 Insufficient publishing permission A non-administrator user attempted to publish a data source, but the caller doesn't have sufficient project permissions.
403 403007 Unlicensed publishing forbidden A non-administrator user who is unlicensed attempted to publish a data source. This is disallowed for all projects (including the default project).
403 403007 Overwrite forbidden A data source with the specified name already exists and the overwrite parameter was not set to true.
403 403007 Problem connecting to data source There was a problem connecting to a data source used by the workbook. This can be due to missing or invalid connection credentials or because the referenced data source is not available on the server.
403 403008 Insufficient storage quota The data source could not be published because there is not enough storage remaining on the server to accommodate its size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404004 Data source not found The append parameter is true but the data source name specified in the request body does not correspond to an existing data source.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project on the site.
404 404015 File upload not found The file upload session ID in the request body doesn't correspond to an existing file upload on the site.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Publish Workbook

Publishes a workbook on the specified site. To make changes to a published workbook, call Update Workbook or Update Workbook Connection.

This method is used in two ways. You can call it to publish a workbook in a single request. To do that, you include the content of the workbook file in the body of the request. The maximum size of a file that can be published in a single request is 64 MB. If you want to avoid having the publishing process time out, you can use the asJob parameter to make workbook publication asynchronous.

Alternatively, you can publish a workbook in multiple parts. To do that, you initiate a file upload by calling Initiate File Upload, send portions of the file to the server using Append to File Upload, and then commit the upload by calling Publish Workbook. In this case, Publish Workbook doesn't contain the file to publish.

Note: When you publish a workbook from your local computer to the server, the publish process will fail if the workbook relies on resources (such as an Excel file or other data file) that are on your local computer but are not available on the server. (Unlike the publish process that is used in Tableau Desktop, the REST API publish process cannot automatically include extracts or other resources that the workbook uses.) If you are publishing a workbook that gets its data from a source on your computer, save the workbook as a packaged workbook (.twbx file) and publish the package so that workbook has all the resources it needs on the server.

For more information, see Publishing Resources.

URI

POST /api/api-version/sites/site-id/workbooks

POST /api/api-version/sites/site-id/workbooks?overwrite=overwrite-flag

POST /api/api-version/sites/site-id/workbooks?uploadSessionId=upload-session-id&workbookType=workbook-file-type&overwrite=bool&asJob=asJob-value

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site to publish to.
overwrite-flag (Optional) true to overwrite a workbook that has the same name, or false to fail if the specified workbook already exists. The default is false. If overwrite-flag is set to true but the workbook doesn't already exist, the operation succeeds.
asJob-value (Optional) A Boolean value that is used to publish workbooks asynchronously. If you set this value to false (the default), the workbook publishing process runs as a synchronous process. If a workbook is very large, the process might time out before it finishes. If you set this value to true, the process runs asynchronously, and a job will start to perform the publishing process and return the job ID. You can check the status of the import job by calling Query Job.
upload-session-id If you are calling this method to commit a file that was uploaded in parts, this value contains the upload session ID that was generated by a call to Initiate File Upload. If this value is not included, the server assumes that the body of the request contains the file to be published.
workbook-file-type twb or twbx to indicate whether you have uploaded a workbook file (twb) or a packaged workbook file (twbx). This value is required if you are calling Publish Workbook in order to commit a file that was previously uploaded using Append to File Upload. The value is not used if you upload a file in the body of the request.

Request Body

Publishing a file in the request body

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml

<tsRequest>
  <workbook name="workbook-name" showTabs="show-tabs-flag" >
    <connections>
    <connection serverAddress="server-address" serverPort="port-number">
    <connectionCredentials name="connection-username" password="connection-password"
          embed="embed-flag" />
    </connection>
    </connections>
    <project id="project-id"/>
  </workbook>
</tsRequest>
--boundary-string
Content-Disposition: name="tableau_workbook"; filename="workbook-file-name"
Content-Type: application/octet-stream

content-of-workbook-file
--boundary-string--

Committing a file previously uploaded

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml

<tsRequest>
  <workbook name="workbook-name" showTabs="show-tabs-flag">
    <connections>
    <connection serverAddress="server-address" serverPort="port-number">
    <connectionCredentials name="connection-username" password="connection-password"
          embed="embed-flag" oAuth="oauth-flag" />
    </connection>
    </connections>
    <project id="project-id"/>
  </workbook>
</tsRequest>
--boundary-string--

Attribute Values

boundary-string A string of characters that is guaranteed to be unique within the body of the request, and that is used to delimit sections of the request body. This value must be declared as a header that has this format:

Content-type: multipart/mixed; boundary=boundary-string

workbook-name The name to assign to the workbook when it is saved on the server.
show-tabs-flag (Optional) Specify true to have the published workbook show views in tabs; otherwise, false. The default is false.
server-address (Optional) Specify the server address for a data source connection if that data source does not use OAuth.
port-number (Optional) Specify the port number for a data source connection if that data source does not use OAuth.
connection-username

(Optional) If the workbook's data source connections require credentials, the <connectionCredentials> elements are included and this attribute specifies the connection username. If the element is included but is not required (for example, if the data source uses OAuth), the server ignores the element and its attributes.

Note: Even if credentials are embedded in a workbook, you must still provide credentials when connecting to a data source that requires credentials, unless that data source uses OAuth.

connection-password

(Optional) If the workbook's data source connections require credentials, the <connectionCredentials> elements are included and this attribute specifies the connection password. If the element is included but is not required (for example, if the data source uses OAuth), the server ignores the element and its attributes.

Note: Even if credentials are embedded in a workbook, you must still provide credentials when connecting to a data source that requires credentials, unless that data source uses OAuth.

embed-flag (Optional) If the workbook's data source connection requires credentials, the <connectionCredentials> element is included. Setting this attribute to True instructs the server to save the credentials for when the data source is used.
oauth-flag (Optional) If the workbook's data source connection is configured to use OAuth, set this to True to specify that the value of the name attribute in the <connectionCredentials> element is an OAuth username. In that case, no password is required and the value of the embed attribute specifies whether to embed the OAuth credential with the workbook, and the server address and port number are not required. For more information, see OAuth Connections in the Tableau Server documentation.
project-id The ID of the project to assign the workbook to.
workbook-file-name The file name (including extension) of the workbook file to upload. This attribute is used in the request body only if the request also includes the content of the workbook file; it is not used if you are committing a file uploaded using previous requests.
content-of-workbook-file The content of the workbook file, if the request includes the file. The maximum size of a file that can be uploaded in one call is 64 MB.

Permissions

Tableau Server users who are not server administrators or site administrators can publish a workbook only if the workbook belongs to a project that they have permissions to publish to.

Response Code

201

Response Body

<tsResponse>
  <workbook name="workbook-name"
     id="workbook-id"
     contentUrl="content-url"  
     showTabs="show-tabs-flag"
     size="size-in-megabytes"
     createdAt="datetime-created"
     updatedAt="datetime-updated"  >
    <project id="project-id" />
    <owner id="owner-id" />
    <views>
      <view id="view-id"
        name="view-name"
        title="view-title"
        caption="view-caption"
        type="view-or-dashboard" />
      ... additional views ...
    </views>
  </workbook>
</tsResponse>>

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Response Headers

Location: /api/3.1/sites/site-id/workbooks/workbook-id

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Malformed request body The XML content in the MIME multipart request is not empty.
400 400000 Missing workbook There is no attachment in the request and no uploadSessionID parameter.
400 400000 Unexpected attachments The message had both an uploadSessionId parameter and an attachment, or the request body contained more than one attachment.
400 400008 Invalid embed value The request body contains a <connectionCredentials> element and it has an embed attribute whose value is not true or false.
400 400008 Invalid overwrite value The overwrite parameter must be true or false.
400 400011 Publishing error The workbook could not be published for some other reason than those specified earlier.
400 400020 Invalid workbook file name The name of the workbook doesn't end in .twb or .twbx.
400 400035 Missing or invalid file type The request included an uploadSessionId parameter but no file type, or the file type was something other than .twb or .twbx.
403 403007 Insufficient publishing permission A non-administrator user attempted to publish a workbook, but the caller doesn't have sufficient project permissions.
403 403007 Unlicensed publishing forbidden A non-administrator user attempted to publish a workbook. This is disallowed for all projects (including the default project).
403 403007 Overwrite forbidden A workbook with the specified name already exists and the overwrite parameter was not set to true.
403 403007 Problem connecting to data source There was a problem connecting to a data source used by the workbook. This can be due to missing or invalid connection credentials or because the referenced data source is not available on the server.
403 403008 Insufficient storage quota The workbook could not be published because there is not enough storage remaining on the server to accommodate its size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project on the site.
404 404006 Workbook not found The user specified overwrite as true but no workbook with the specified name exists on the site.
404 404015 File upload not found The file upload session ID in the uploadSessionId parameter doesn't correspond to an existing file upload on the site.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Query Data Source

Returns information about the specified data source.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

GET /api/api-version/sites/site-id/datasources/datasource-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The site that contains the data source.
datasource-id The ID of the data source to get.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can view a data source only if they have Connect permission for the data source (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <datasource id="datasource-id"
    name="datasource-name"
    type="datasource-type" 
    contentUrl="datasource-content-url"
    createdAt="datetime-created"
    updatedAt="datetime-updated" >
    <project id="project-id" name="project-name" />
    <owner id="datasource-owner-id"  />
    <tags>
      <tag label="tag"/>
      ... additional tags ...
    </tags>
  </datasource>
</tsResponse>

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Read forbidden A non-administrator user attempted to query a data source, but the caller doesn't have Connect permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <datasource id="1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b" name="Activity rates and healthy living" 
      contentUrl="activity-dates-and-healthy-living" type="excel-direct"
      createdAt="2011-03-30T22:32:35Z" updatedAt="2016-01-13T01:00:02Z">
    <project id="1f2f3e4e5-d6d7-c8c9-b0b1-a2a3f4f5e6e" name="default"/>
    <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
    <tags>
    </tags>
  </datasource>
</tsResponse>

Query Data Source Connections

Returns a list of data connections for the specified data source.


URI

GET /api/api-version/sites/site-id/datasources/datasource-id/connections

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to return connection information about.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query a data source only if they have Read (view) permission for the data source (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <connections>
    <connection id="connection-id" type="connection-type"
      serverAddress="server-address" serverPort="port"
      userName="connection-user-name" />
    ... additional connections ...
  </connections>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
403 403021 Read forbidden A user who is not a server administrator user attempted to query the data source connections, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404011 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <connections>
    <connection id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd" type="dataengine" />
    <connection id="374371c0-ffe9-4e16-b48e-6b868e3026ca" type="dataengine" />
    <connection id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" type="dataengine" />
  </connections>
</tsResponse>

Query Data Source Permissions

Returns a list of permissions for a specific data source.


URI

GET /api/api-version/sites/site-id/datasources/datasource-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to get permissions for.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can view a data source only if they have Read (view) permission for the data source (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <permissions>
   <parent type="Project" id="project-id"
   <datasource id="datasource-id"
     owner="owner-user-id" />
   <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" mode="capability-mode" />
        ... additional capabilities ...
       </capabilities>
     </granteeCapabilities>
     ... additional grantee capability sets ...
  </permissions>
</tsResponse>

Note: The parent element is included in the response only if the workbook's permissions are determined by project-level default permissions and project permissions are locked. Project permissions can be locked for a new project when you call Create Project or for an existing project by calling Update Project. For more information, see Lock Content Permissions to the Project.

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <parent type="Project" id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" />
  <permissions>
    <datasource id="1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b" name="USPS-rates">
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
    </datasource>
    <granteeCapabilities>
      <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" />
      <capabilities>
        <capability name="Connect" mode="Allow"/>
        <capability name="Read" mode="Allow"/>
      </capabilities>
    </granteeCapabilities>
  </permissions>
</tsResponse>

Query Data Sources

Returns a list of data sources on the specified site, with optional parameters for specifying the paging of large results.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

GET /api/api-version/sites/site-id/datasources

GET /api/api-version/sites/site-id/datasources?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/datasources?filter=filter-expression

GET /api/api-version/sites/site-id/datasources?sort=sort-expression

GET /api/api-version/sites/site-id/users?fields=field-expression

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the data sources.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
filter-expression (Optional) An expression that lets you specify a subset of data sources to return. You can filter on predefined fields such as name and updatedAt. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which user information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.
field-expression (Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as _all_ or _default_, and you can specify individual fields for the workbooks or other supported resources. You can include multiple field expressions in a request. For more information, see Using Fields in the Rest API.

Note: The filter and sort parameters can be combined with each other and with paging parameters and fields parameters using an ampersand (&).

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can view a data source only if they have Connect permission for the data source (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber" pageSize="page-size"
    totalAvailable="total-available" />
  <datasources>
    <datasource id="datasource1-id"
      name="datasource-name"
      contentUrl="datasource-content-url"
      type="datasource-type" 
      createdAt="datetime-created"
      updatedAt="datetime-updated">
      <project id="project-id" name="project-name" />
      <owner id="datasource-owner-id" />
      <tags>
       <tag label="tag"/>
       ... additional tags ...
      </tags>
    </datasource>
    ... additional data sources ...
  </datasources>
</tsResponse>

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="2"/>
  <datasources>
    <datasource id="1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b"
         name="Sample - Coffee Chain (Access)" contentUrl="coffee-chain"  type="msaccess" 
         createdAt="2011-03-30T22:32:35Z" updatedAt="2016-01-13T01:00:02Z">
      <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="Default"/>
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
      <tags>
      </tags>
    </datasource>
    <datasource id="9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c"
          name="Activity rates and healthy living" contentUrl="activity-rates-and-healthy-living" type="excel-direct"
          createdAt="2011-03-30T22:32:35Z" updatedAt="2016-01-13T01:00:02Z">
      <project id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd" name="Default"/>
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
      <tags>
      </tags>
    </datasource>
  </datasources>
</tsResponse>

Query Default Permissions

Returns information about the default permissions for a project that is, the permissions that will be set by default for workbooks and data sources that are added to the project. You make separate requests to query the default permissions for workbooks and for data sources.


URI

GET /api/api-version/sites/site-id/projects/project-id/default-permissions/datasources

GET /api/api-version/sites/site-id/projects/project-id/default-permissions/workbooks

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the project.
project-id The project to get default permissions for.

Request Body

None

Permissions

Tableau Server users who are not server administrators can query default permissions for a project only if they have the ProjectLeader permission for that project (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <permissions>
    <project id="project-id" name="project-name" />
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability" mode="capability-mode" />
        <capability name="capability" mode="capability-mode" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    ... additional grantee capabilities ...
  </permissions>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
403 403035 Querying data source permissions forbidden The caller doesn't have permissions to query the project's default permissions for data sources.
403 403036 Querying workbook permissions forbidden The caller doesn't have permissions to query the project's default permissions for workbooks.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404005 Project not found The project ID in the URI doesn't correspond to an existing project.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Query Extract Refresh Tasks

Returns a list of the extract refresh tasks for a specified schedule on the specified site.

To get the ID of a schedule, call the Query Schedules method. Note that the Query Schedules method is global to the server; schedules are not specific to a site. Therefore, the URI for the Query Schedules method does not include /sites/ or a site ID. However, individual scheduled tasks are specific to a site, and the URI for Query Extract Refresh Tasks must include the site information.

For more information about refresh tasks, see Manage Refresh Tasks.

URI

GET /api/api-version/sites/site-id/schedules/schedule-id/extracts

GET /api/api-version/sites/site-id/schedules/schedule-id/extracts?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 2.2. For more information, see REST API Versions.
site-id The ID of the site that contains the refresh tasks.
schedule-id The ID of the schedule to get extract information for.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators. When a site administrator calls this method, the payload contains only the tasks that are associated with the site that the user is signed in to.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber"
     pageSize="page-size"
     totalAvailable="total-available" />
  <extracts> 
    <extract id="task-id" 
      priority="task-priority"
      type="incremental-or-full" >
        <workbook id="workbook-id" />
    </extract>
    <extract id="task-id" 
      priority="task-priority"
      type="incremental-or-full" >
        <datasource id="datasource-id" />
    </extract>
    ... additional extract refresh tasks ... 
  </extracts> 
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
400 400047 Invalid schedule type The schedule type does not represent an extract refresh task. (For example, it might be a subscription task.)
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404 Schedule not found The schedule ID in the URI doesn't correspond to an existing schedule.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/schedules/59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba/extracts" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
<pagination pageNumber="1" pageSize="100" totalAvailable="2" />
  <extracts>
    <extract id="639c7e80-0d11-44b2-9b5b-018ffc5eddb4" priority="60" type="FullRefresh">
      <datasource />
    </extract>
    <extract id="303f6c45-fb48-47aa-88d3-0dd87f5f5c74" priority="50" type="FullRefresh">
      <workbook />
    </extract>
  </extracts>
</tsResponse>

Query Groups

Returns a list of groups on the specified site, with optional parameters for specifying the paging of large results.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

GET /api/api-version/sites/site-id/groups

GET /api/api-version/sites/site-id/groups?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/groups?filter=filter-expression

GET /api/api-version/sites/site-id/groups?sort=sort-expression

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the groups.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
filter-expression (Optional) An expression that lets you specify a subset of groups to return. You can filter on predefined fields such as name. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which user information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber"
    pageSize="page-size"
    totalAvailable="total-available" />
  <groups>
    <group id="group-id"
      name="group-name">
      <domain name="domain-for-group" />
    </group>
    <group id="group-id"
      name="group-name">
      <domain name="domain-for-group" />
    </group>
    ... additional groups ...
  </groups>
</tsResponse>

If the group was imported from Active Directory, the name attribute of the <domain> element contains the group's Active Directory domain. If the server is configured to use local authentication, the name attribute of the <domain> contains local.

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/" -X GET -H "X-Tableau-Auth:e35Z608JMPHgZfVyJncnedlUeXSX8bmb"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="3"/>
  <groups>
    <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" name="All Users">
      <domain name="local"/>
    </group>
    <group id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b" name="marketing-users">
      <domain name="local"/>
    </group>
    <group id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6" name="finance-users">
      <domain name="local"/>
    </group>
  </groups>
</tsResponse>

Query Job

Returns status information about an asynchronous process that is tracked using a job. This method can be used to query jobs that are used to do the following:


URI

GET /api/api-version/sites/site-id/jobs/job-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site where the job is running.
job-id The ID of the job to get status information for.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <job id="job-id" mode="job-mode" type="job-type"
    progress="percent-completed"
    createdAt="time-job-created"
    updatedAt="time-job-last-updated"
    completedAt="time-job-completed"
    finishCode="status-code">
    <extractRefreshJob>
      <notes>
      ... view, workbook, or datasource id and name ...
      </notes>
    </extractRefreshJob>    
    <statusNotes>
      <statusNote type="classifier"
        value="value"
        text="note" />
      ... additional job notes ...
    </statusNotes>
  </job>
</tsResponse>

The createdAt, updatedAt, and CompletedAt values are dates and times in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Note: When using this method to query the progress of asynchronous workbook publishing, progress will switch from 0 when the job is in-progress to 100 when it is complete, finishCode will switch from 1 when the job is in-progress to 0 when it is complete, and no <statusNotes> elements are provided.

The finishCode indicates the status of the job: 0 for success, 1 for error, or 2 for cancelled.

The <statusNotes> element contains one or more notes that provide details about the status of a job in a format that can be used for logging, auditing, and error recovery. Each status note contains three attributes:

  • type. An enumerated value (a string) that indicates the classification of the note.
  • value. A value that indicates the number of records reported by the current status, such as the count of records processed.
  • text. A description of the status that can be displayed to users. If you are working with a localized (translated) version of Tableau Server, this text is also localized. You should not rely on this text for any application logic. If you need to take action based on a specific status, test the value of the type attribute.

The following table lists job status types. Some values are returned only when the job is synchronizing groups (Update Group).

Type Value Text
CountOfUsersAddedToGroup Integer Description of how many users were added to the group during the import.
CountOfUsersAddedToSite Integer Description of how many users were added to the site during the import.
CountOfUsersWithInsufficientLicenses Integer Description of how many users could not have their site role updated due to server lacking sufficient licenses for them.
CountOfUsersInActiveDirectoryGroup Integer Description of the total number of users in the Active Directory group being imported or synchronized
CountOfUsersProcessed Integer Description of the total number of users processed during the import or synchronization process.
CountOfUsersSkipped Integer Description of the total number of users skipped during the import or synchronization process
CountOfUsersInformationUpdated Integer Description of the total number of users who's information was updated during the import or synchronization process.
CountOfUsersSiteRoleUpdated Integer Description of the total number of users whose site role was updated during the import or synchronization process.
CountOfUsersRemovedFromGroup Integer (Synchronization process only) Description of the number of users removed from the group during the synchronization process.
CountOfUsersUnlicensed Integer (Synchronization process only) Description of the number of users who were unlicensed during the synchronization process.

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404018 Job not found The job ID in the URI doesn't correspond to an existing job.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Query Jobs

Returns a list of active jobs on the specified site. To get details on a specific job, pass a job ID returned by this method to the Query Job method. To cancel an active job, pass a job ID returned by this method to the Cancel Job method.

Calls to this method can be filtered, as shown in the URI examples shown below. To learn more about filtering, see Filtering and Sorting in the REST API.


URI

GET /api/api-version/sites/site-id/jobs

GET /api/api-version/sites/site-id/jobs?filter=progress:lte:0

GET /api/api-version/sites/site-id/jobs?filter=jobType:eq:refresh_extracts

GET /api/api-version/sites/site-id/jobs?filter=createdAt:gt:2018-04-18

GET /api/api-version/sites/site-id/jobs?filter=title:has:Superstore

GET /api/api-version/sites/site-id/jobs?filter=notes:has:nightly

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site where the job is running.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="page-number" pageSize="page-size"/>
    <backgroundJobs>
      <backgroundJob id="job-id" status="status-value" createdAt="date-time" startedAt="date-time" endedAt="date-time" priority="priority-value" jobType="type-value"/>
      ...
    </backgroundJobs>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/jobs" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse>
  <pagination pageNumber="1" pageSize="100" totalAvailable="48999"/>
    <backgroundJobs>
      <backgroundJob id="919055e5-25db-4a2b-9611-1408dd06632d" status="Failed" createdAt="2018-04-17T23:00:15Z" startedAt="2018-04-17T23:00:15Z" endedAt="2018-04-17T23:00:15Z" priority="50" jobType="increment_extracts"/>
      <backgroundJob id="b5cadda9-2b32-447a-acb6-1c1b8c06caf9" status="Failed" createdAt="2018-04-17T23:00:15Z" startedAt="2018-04-17T23:00:15Z" endedAt="2018-04-17T23:00:15Z" priority="50" jobType="increment_extracts"/>
      <backgroundJob id="d281297b-9834-44a1-b71a-a2cab6060df6" status="Failed" createdAt="2018-04-17T23:00:15Z" startedAt="2018-04-17T23:00:24Z" endedAt="2018-04-17T23:00:32Z" priority="50" jobType="refresh_extracts"/>
    </backgroundJobs>
</tsResponse>

Query Project Permissions

Returns information about the set of permissions allowed or denied for groups and users in a project.


URI

GET /api/api-version/sites/site-id/projects/project-id/permissions

Parameter Values

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

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <permissions>
    <project id="project-id" name="project-name" />
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability" mode="capability-mode" />
        <capability name="capability" mode="capability-mode" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
        <capability name="capability" mode="capability-mode" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    ... additional grantee capabilities ...
  </permissions>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404005 Project not found The project ID in the URI doesn't correspond to an existing project.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects/1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <permissions>
    <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="default">
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
    </project>
    <granteeCapabilities>
      <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"/>
      <capabilities>
        <capability name="Read" mode="Allow"/>
        <capability name="Write" mode="Allow"/>
      </capabilities>
    </granteeCapabilities>
  </permissions>
</tsResponse>

Query Projects

Returns a list of projects on the specified site, with optional parameters for specifying the paging of large results.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

GET /api/api-version/sites/site-id/projects

GET /api/api-version/sites/site-id/projects?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/projects?filter=filter-expression

GET /api/api-version/sites/site-id/projects?sort=sort-expression

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the projects.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
filter-expression (Optional) An expression that lets you specify a subset of data sources to return. You can filter on predefined fields such as name, ownerName, and parentProjectId. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which user information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have Read (view) permission for the project (either implicitly or explicitly).

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber"
    pageSize="page-size"
    totalAvailable="total-available" />
  <projects>
    <project id="project1-id"
      name="project1-name"
      description="project1-description"
      contentPermissions="content-permissions" />
    <project id="project2-id"
      name="project2-name"
      description="project2-description"
      contentPermissions="content-permissions" />
    ... additional projects ...
  </projects>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects?filter=parentProjectId:eq:711d4c5d-60b7-4f77-a9a6-bbf05021b6ec" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
	<pagination pageNumber="1" pageSize="100" totalAvailable="1"/>
    <projects>
        <project id="fae56e51-fbee-4eab-a9af-d8283cc0ed77" name="TestNestProject" description="" parentProjectId="711d4c5d-60b7-4f77-a9a6-bbf05021b6ec">
            <owner id="4d8308f7-ec47-4eb1-a383-429374a8d9cb"/>
        </project>
    </projects>
</tsResponse>

Query Schedules

Returns a list of extract and subscription schedules. For each schedule, the API returns the name, frequency, priority, and other information.

For more information about schedules, see Create or Modify a Schedule.

URI

GET /api/api-version/schedules

GET /api/api-version/schedules?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 2.2. For more information, see REST API Versions.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber"
    pageSize="page-size"
    totalAvailable="total-available" />
  <schedules> 
    <schedule id="schedule-id" 
      name="schedule-name" 
      state="Active-or-Suspended" 
      priority="schedule-priority" 
      createdAt="datetime-created" 
      updatedAt="datetime-last-updated" 
      type="extract-or-subscription" 
      frequency="schedule-frequency" 
      nextRunAt ="datetime-next-run-time" 
      endScheduleAt ="datetime-expiration" /> 
    ... additional schedules ... 
    </schedules> 
</tsResponse>

The datetime-created, datetime-last-updated, datetime-next-run-time, and datetime-expiration attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/schedules -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings >
<pagination pageNumber="1" pageSize="100" totalAvailable="3" />
  <schedules>
    <schedule id="ca3ce4f5-666c-4bb8-a763-5df24783881f" 
        name="Hourly" 
        state="Active" 
        priority="50" 
        createdAt="2011-03-30T22:32:35Z" 
        updatedAt="2016-01-13T01:00:02Z" 
        type="Extract" 
        frequency="Hourly" 
        nextRunAt="2016-01-13T23:00:00Z" />
    <schedule id="13abd238-0b22-4789-bcc4-614d31908310" 
        name="Saturday night" 
        state="Active" 
        priority="50" 
        createdAt="2010-10-28T21:11:33Z" 
        updatedAt="2016-01-10T07:00:00Z" 
        type="Extract" 
        frequency="Weekly" 
        nextRunAt="2016-01-17T07:00:00Z" />
    <schedule id="b6a6d11a-9e20-49f1-9b74-693f196b9aca" 
        name="End of the month" 
        state="Suspended" 
        priority="50" 
        createdAt="2010-10-28T21:11:33Z" 
        updatedAt="2016-01-01T07:00:03Z" 
        type="Extract" 
        frequency="Monthly" 
        nextRunAt="2016-02-01T07:00:00Z" />
   </schedules>
 </tsResponse>

Query Site

Returns information about the specified site, with the option to return information about the storage space and user count for the site.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

You can specify the site to delete by using the site ID, the site name, or the content URL. You use the key query string parameter to indicate how you are specifying the site, as shown in the URIs.

Note: You can only get site information for the site that you have signed in to.


URI

GET /api/api-version/sites/site-id

GET /api/api-version/sites/site-name?key=name

GET /api/api-version/sites/content-url?key=contentUrl

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site to get information for.
site-name The name of the site to get information for. If you specify a site name, you must also include the parameter key=name.
content-url The URL of the site to get information for. If you specify a content URL, you must also include the parameter key=contentUrl.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
 <site id="site-id"
  name="site-name"
  contentUrl="content-url"
  adminMode="admin-mode"
  tierCreatorCapacity="num-users"
  tierExplorerCapacity="num-users"
  tierViewerCapacity="num-users"
  storageQuota="limit-in-megabytes"
  disableSubscriptions="new-disable-subscriptions" 
  revisionHistoryEnabled="revision-history-enabled"
  revisionLimit="revision-limit"   
  state="active-or-suspended">
    <usage numUsers="number-of-users"
        storage="storage-in-megabytes">
    </usage>
 </site>
</tsResponse>

The <usage> element is returned only if you have specified includeStorage=true in the URI.

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

Command:

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d?includeUsage=true" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <site id="9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d" name="Default" adminMode="ContentAndUsers"
        disableSubscriptions="false" state="Active">
    <usage numUsers="98" storage="7373"/>
  </site>
</tsResponse>

Command:

curl "http://MY-SERVER/api/3.1/sites/Default?key=name" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <site id="9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d" name="Default" adminMode="ContentAndUsers"
        disableSubscriptions="false" state="Active">
  </site>
</tsResponse>

Query Sites

Returns a list of the sites on the server that the caller of this method has access to.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

GET /api/api-version/sites

GET /api/api-version/sites?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

This method can be called by all users. The method only returns the sites that the user has access to.

Response Code

200

Response Body

<tsResponse>
 <pagination pageNumber="pageNumber"
  pageSize="page-size"
  totalAvailable="total-available" />
 <sites>
  <site id="site-id"
   name="site1-name"
   contentUrl="content-url"
   adminMode="admin-mode"
   tierCreatorCapacity="num-users"
   tierExplorerCapacity="num-users"
   tierViewerCapacity="num-users"
   storageQuota="limit-in-megabytes"
   state="active-or-suspended"
   statusReason="reason-for-state" />
  </site>
  ... additional sites ...
 </sites>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for the sites at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="2"/>
  <sites>
    <site id="9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d" name="Default"
          adminMode="ContentAndUsers" state="Active">
    </site>
    <site id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6" name="Marketing-Site"
           contentUrl="marketingsite" adminMode="ContentAndUsers"
           state="Active">
    </site>
  </sites>
</tsResponse>

Query Subscription

Returns information about the specified subscription.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

GET /api/api-version/sites/site-id/subscriptions/subscription-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the subscriptions.
subscription-id The ID of the subscription to get information for.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can get subscription information as follows:

  • Project Leaders can get subscription information for projects that they are project leaders for and for their own subscriptions.
  • Content owners can get subscription information for content that they own and for their own subscriptions.
  • Other users can get subscription information for their own subscriptions.

Response Code

200

Response Body

<tsResponse>
   <subscription id="subscription-id" subject="subscription-subject">
     <content id="content-id" type="content-type" />
     <schedule id="schedule-id" name="schedule-name" />
     <user id="user-id" name="user-name" />
   </subscription>
 </tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
403 403058 Unauthorized The user attempted to get information for a subscription that they don't have permission to access.
404 404000 Site not found The specified site doesn't correspond to an existing site.
404 404025 Subscription not found The specified subscription doesn't correspond to an existing subscription.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/subscriptions/59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <subscription id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" subject="Daily Statistics">
    <content id="08b50973-a526-4f65-b898-829e6292c949" type="View" />
    <schedule id="67e341a3-7c58-4605-9897-7db1e565e827" name="Mondays" />
    <user id="c6f87a48-f603-41dc-af0c-8098c763df97" name="joe@example.com" />
  </subscription>
</tsResponse>

Query Subscriptions

Returns a list of all the subscriptions on the specified site.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

GET /api/api-version/sites/site-id/subscriptions

GET /api/api-version/sites/site-id/subscriptions?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the subscriptions.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can get subscription information as follows:

  • Project Leaders can get subscription information for projects that they are project leaders for.
  • Content owners can get subscription information for content that they own and for their own subscriptions.
  • Other users can get subscription information for their own subscriptions.

Response Code

200

Response Body

<tsResponse>
   <pagination pageNumber="pageNumber"
    pageSize="page-size"
    totalAvailable="total-available" />
   <subscriptions>
     <subscription id="subscription-id" 
         subject="subscription-subject">
       <content id="content-id" type="content-type" />
       <schedule id="schedule-id" name="schedule-name" />
       <user id="user-id" name="user-name" />
     </subscription>
     ... additional subscriptions ...
   </subscriptions>
 </tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for the sites at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/subscriptions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="2"/>
  <subscriptions>
    <subscription id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" subject="Daily Statistics">
      <content id="08b50973-a526-4f65-b898-829e6292c949" type="View" />
      <schedule id="67e341a3-7c58-4605-9897-7db1e565e827" name="Mondays" />
      <user id="c6f87a48-f603-41dc-af0c-8098c763df97" name="joe@example.com" />
    </subscription>
    <subscription id="672930ac-b7d2-4ed9-beb7-d931241f8209" subject="Sales Update">
      <content id="8fcd394e-27f4-4071-9c5a-2dfed2ad1230" type="View" />
      <schedule id="67e341a3-7c58-4605-9897-7db1e565e827" name="Weekly Updates" />
      <user id="e54cde3c-0c44-4024-a34e-8cab98f58ea2" name="Michelle@example.com" />
    </subscription>
  </subscriptions>  
</tsResponse>

Query User On Site

Returns information about the specified user.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

URI

GET /api/api-version/sites/site-id/users/user-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the user.
user-id The ID of the user to get information for.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <user id="user-id"
        name="user-name"
        siteRole="site-role"
        lastLogin="last-login-date"
        externalAuthUserId="authentication-id-from-external-provider"
        fullName="user-full-name"
        authSetting="auth-setting" />
  <domain name="user-domain" />
</tsResponse>

The lastLogin attribute value is returned as a date in UTC format (YYYY-MM-DDTHH:MM:SSZ).

The siteRole value is returned as one of the following values: Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, or Viewer.

The externalAuthUserId value represents an ID for the user for single sign-on (SSO) with an external identity provider. If the user is not configured to use external authentication, this value is an empty string.

The authSetting attribute is returned only if you are using Tableau Online or Tableau Server with site-specific SAML enabled.

(Tableau Server version 9.0.1/schema version 2.0.1 and later). If the user was imported from Active Directory, the name attribute of the <domain> element contains the user's Active Directory domain. If the server is configured to use local authentication, the name attribute of the <domain> contains local.

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" name="Alan"
      siteRole="ExplorerCanPublish"
      fullName="Alan Wang"
      lastLogin="2015-01-05T03:24:36Z" />
</tsResponse>

Query View Data

Returns a specified view rendered as data in comma-separated-value (CSV) format.

CSV data is provided in the response body, rather than as a download. If you make multiple requests for CSV data, subsequent calls return a cached version of the data. This means that the returned data file might not include the latest changes to the view

This method includes the ability to filter a view using fields in the underlying workbook data. To learn more about filtering query views, see Filtering and Sorting in the REST API.


URI

GET /api/api-version/sites/site-id/views/view-id/data

GET /api/api-version/sites/site-id/views/view-id/data?vf_<fieldname>=filter-value

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the view.
view-id The ID of the view to render as data.
filter-value The value of the field that you want to use to filter the workbook view. For example, a workbook with the filter /data?vf_year=2017 would only display data from the year 2017. To learn more, see Filter query views.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query workbook views only if they have Read (view) permission for the views (either explicitly or implicitly).

Response Code

200

Response Body

The response body contains data in CSV format.

Version

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

Errors

HTTP status error Code Condition Details
400 400080 Bad Request The view ID in the URI doesn't correspond to a view available on the specified site.
401 401002 Unauthorized The authentication token provided in the request header was invalid or has expired.
403 403032 Read forbidden A non-administrator user attempted to query workbook views, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/views/2474164d-8d37-4a4c-abc7-c2070fd25fd5/data" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

Month of Date,Year of Date,Above Median?,Avg. Median
January,1893,below median,-1.0
January,1864,below median,-0.9
January,1861,below median,-0.9
December,1862,below median,-0.9
March,1917,below median,-0.8
December,1892,below median,-0.8
February,1862,below median,-0.8
February,1911,below median,-0.8
February,1917,below median,-0.8
May,1861,below median,-0.8
November,1862,below median,-0.8
March,1898,below median,-0.8
December,1860,below median,-0.8
January,1862,below median,-0.7
March,1850,below median,-0.7
February,1893,below median,-0.7
December,1870,below median,-0.7

Query View Image

Returns an image of the specified view.

If you make multiple requests for an image, subsequent calls return a cached version of the image. This means that the returned image might not include the latest changes to the view. To decrease the amount of time that an image is cached, use TSM to reduce the value of the vizportal.rest_api.view_image.max_age setting. For more information, see tsm configuration set Options in the Tableau Server help.

This method includes the ability to filter a view using fields in the underlying workbook data. To learn more about filtering query views, see Filtering and Sorting in the REST API.

Note: If you want to disable this endpoint, use TSM to set the sheet_image.enabled setting to false. For more information, see tsm configuration set options in the Tableau Server help.


URI

GET /api/api-version/sites/site-id/views/view-id/image

GET /api/api-version/sites/site-id/views/view-id/image?resolution=image-resolution

GET /api/api-version/sites/site-id/views/view-id/image?vf_<fieldname>=filter-value

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the view.
view-id The ID of the view to return an image for.
image-resolution (Optional) The resolution of the image. By default, the width of the returned image is 784 pixels. If you set this parameter value to high, the width of the returned image is 1568 pixels. For both resolutions, the height varies to preserve the aspect ratio of the view.
filter-value The value of the field that you want to use to filter the workbook view. For example, a workbook with the filter /data?vf_year=2017 would only display data from the year 2017. To learn more, see Filter query views.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query workbook views only if they have Read (view) permission for the views (either explicitly or implicitly).

Response Code

200

Response Body

The view's image in PNG format (MIME media type image/png).

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Read forbidden A non-administrator user attempted to query a view preview image, but the caller doesn't have Read permission.
403 403068 Forbidden The endpoint has been disabled on the server. To enable the endpoint, a server administrator must use tsm to configure the sheet_image.enabled setting. For more information, see tsm configuration set Options in the Tableau Server help.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
404 404011 View not found The view ID in the URI doesn't correspond to an existing view in the specified workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d/image?resolution=high" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Query View PDF

Returns a specified view rendered as a .pdf file.

If you make multiple requests for a .pdf file, subsequent calls return a cached version of the .pdf file. This means that the returned .pdf file might not include the latest changes to the view.

This method includes the ability to filter a view using fields in the underlying workbook data. To learn more about filtering query views, see Filtering and Sorting in the REST API.


URI

GET /api/api-version/sites/site-id/views/view-id/pdf

GET /api/api-version/sites/site-id/views/view-id/pdf?vf_<fieldname>=filter-value

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the view.
view-id The ID of the view to render as a .pdf file.
filter-value The value of the field that you want to use to filter the workbook view. For example, a workbook with the filter /data?vf_year=2017 would only display data from the year 2017. To learn more, see Filter query views.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query workbook views only if they have Read (view) permission for the views (either explicitly or implicitly).

Response Code

200

Response Body

None.

Version

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

Errors

HTTP status error Code Condition Details
400 400080 Bad Request The view ID in the URI doesn't correspond to a view available on the specified site.
401 401002 Unauthorized The authentication token provided in the request header was invalid or has expired.
403 403032 Read forbidden A non-administrator user attempted to query workbook views, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/views/2474164d-8d37-4a4c-abc7-c2070fd25fd5/pdf" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Query View Preview Image

Returns the thumbnail image for the specified view.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/views/view-id/previewImage

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the view.
workbook-id The ID of the workbook that contains the view to return a thumbnail image for.
view-id The ID of the view to return a thumbnail image for.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query workbook views only if they have Read (view) permission for the views (either explicitly or implicitly).

Response Code

200

Response Body

The view's preview image in PNG format (MIME media type image/png).

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Read forbidden A non-administrator user attempted to query a view preview image, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
404 404011 View not found The view ID in the URI doesn't correspond to an existing view in the specified workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Query Views for Site

Returns all the views for the specified site, optionally including usage statistics.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

GET /api/api-version/sites/site-id/views

GET /api/api-version/sites/views?includeUsageStatistics=get-usage-information

GET /api/api-version/sites/site-id/views?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/views?includeUsageStatistics=get-usage-information&pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/views?filter=filter-expression

GET /api/api-version/sites/site-id/views?sort=sort-expression

GET /api/api-version/sites/site-id/views?fields=field-expression

Parameter Values

api-version The version of the API to use, such as 2.2. For more information, see REST API Versions.
site-id The ID of the site that contains the views.
get-usage-information (Optional) true to return usage statistics. The default is false.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
field-expression (Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as _all_ or _default_, and you can specify individual fields for the workbooks or other supported resources. You can include multiple field expressions in a request. For more information, see Using Fields in the REST API.

Note: The filter and sort parameters can be combined with each other and with paging parameters and fields parameters using an ampersand (&).

Request Body

None

Permissions

For Tableau Server users who are not server administrators or site administrators, the method returns only the views that the user owns or has Read permissions for (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <views>
    <view id="view-id" 
        name="view-name" 
        contentUrl="content-url" >
      <workbook id="workbook-id" />
      <owner id="owner-id" />
      <usage totalViewCount="total-count" />
    </view>
     ... additional views ...
  </views>
</tsResponse>

The <usage> element is included in the response only if the method has includeUsageStatistics=true in the URI.

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
400 400008 Invalid parameter value The includeUsageStatistics was provided with a value other than true or false.
403 403004 Read forbidden A non-administrator user attempted to query workbook views, but the caller doesn't have Read permission.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views" -X GET -H "X-Tableau-Auth:1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="2" />
  <views>
    <view id="1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c" name="Economic Indicators" 
         contentUrl="Finance/sheets/EconomicIndicators">
      <workbook id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d" />
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
    </view>
    <view id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b" name="Investing in the Dow" 
          contentUrl="Finance/sheets/InvestingintheDow">
      <workbook id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" />
      <owner id="9f8e7d6c5-b4a3-f2e1-d0c9-b8a7f6e5d4c" />
  </view>
</tsResponse>

Query Views for Workbook

Returns all the views for the specified workbook, optionally including usage statistics.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/views

GET /api/api-version/sites/site-id/workbooks/workbook-id/views?includeUsageStatistics=get-usage-information

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to get the views for.
(Optional) get-usage-information true to return usage statistics. The default is false.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query workbook views only if they have Read (view) permission for the views (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <views>
    <view id="view-id" name="view-name"
        contentUrl="content-url" >
      <usage totalViewCount="total-count" />
    </view>
     ... additional views ...
  </views>
</tsResponse>

The <usage> element is included in the response only if the method has includeUsageStatistics=true in the URI.

Version

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

Errors

HTTP status error Code Condition Details
400 400008 Invalid parameter value The includeUsageStatistics was provided with a value other than true or false.
403 403004 Read forbidden A non-administrator user attempted to query workbook views, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/views" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <views>
    <view id="1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c" name="Tale of 100 Start-ups"
          contentUrl="Finance/sheets/Taleof100Start-ups"/>
    <view id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b" name="Economic Indicators"
          contentUrl="Finance/sheets/EconomicIndicators"/>
    <view id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6" name="Investing in the Dow"
          contentUrl="Finance/sheets/InvestingintheDow"/>
  </views>
</tsResponse>

Query Workbook

Returns information about the specified workbook, including information about views and tags.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

GET /api/api-version/sites/site-id/workbooks/workbook-id

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to return information about.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query a workbook only if they have Read (view) permission for the workbook (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <workbook id="workbook-id" name="workbook-name" 
      contentUrl="workbook-url" 
      showTabs="show-tabs-flag" 
      size="size-in-megabytes" 
      createdAt="datetime-created" 
      updatedAt="datetime-updated" >
    <project id="project-id" />
    <owner id="owner-id" />
    <tags>
      <tag label="tag" />
      ... additional tags ...
    </tags>
    <views>
      <view id="view-id" name="view-name" contentUrl="view-content-url" />
      ... additional views ...
    </views>
  </workbook>
</tsResponse>

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

Errors

HTTP status error Code Condition Details
403 403018 Read forbidden A non-administrator user attempted to query the workbook, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <workbook id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d" name="Finance"
        contentUrl="Finance" showTabs="true" 
        createdAt="2011-03-30T22:32:35Z" updatedAt="2016-01-13T01:00:02Z">
    <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="Tableau Samples"/>
    <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
    <tags>
    </tags>
    <views>
      <view id="1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c"
            contentUrl="Finance/sheets/Taleof100Start-ups"/>
      <view id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b"
            contentUrl="Finance/sheets/EconomicIndicators"/>
      <view id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6"
            contentUrl="Finance/sheets/InvestingintheDow"/>
    </views>
  </workbook>
</tsResponse>

Query Workbook Connections

Returns a list of data connections for the specific workbook.


URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/connections

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to return connection information about.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query a workbook only if they have Read (view) permission for the workbook (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <connections>
    <connection id="connection-id" type="connection-type"
      serverAddress="server-address" serverPort="port"
      userName="connection-user-name" />
    ... additional connections ...
  </connections>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
403 403021 Read forbidden A user who is not a server administrator user attempted to query the workbook connections, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <connections>
    <connection id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd" type="dataengine" />
    <connection id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b" type="dataengine" />
    <connection id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6" type="dataengine" />
    <connection id="374371c0-ffe9-4e16-b48e-6b868e3026ca" type="dataengine" />
    <connection id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" type="dataengine" />
  </connections>
</tsResponse>

Query Workbook Permissions

Returns a list of permissions for the specific workbook.


URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/permissions

Parameter Values

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

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <parent type="Project" id="project-id" />
  <permissions>
    <workbook id="workbook-id" name="workbook-name >
      <owner="owner-user-id" />
    </workbook>
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability" mode="capability-mode" />
         ... additional capabilities for users ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
        <capability name="capability" mode="capability-mode" />
         ... additional capabilities for groups ...
      </capabilities>
    </granteeCapabilities>
    ... additional grantee capability sets ...
  </permissions>
</tsResponse>

Note: The parent element is included in the response only if the workbook's permissions are determined by project-level default permissions and project permissions are locked. Project permissions can be locked for a new project when you call Create Project or for an existing project by calling Update Project. For more information, see Lock Content Permissions to the Project.

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <parent type="Project" id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" />
  <permissions>
    <workbook id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d" name="Finance">
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
    </workbook>
    <granteeCapabilities>
      <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"/>
      <capabilities>
        <capability name="Read" mode="Allow"/>
        <capability name="Filter" mode="Allow"/>
        <capability name="ViewUnderlyingData" mode="Allow"/>
        <capability name="ExportImage" mode="Allow"/>
        <capability name="ExportData" mode="Allow"/>
        <capability name="AddComment" mode="Allow"/>
        <capability name="ViewComments" mode="Allow"/>
        <capability name="ShareView" mode="Allow"/>
      </capabilities>
    </granteeCapabilities>
  </permissions>
</tsResponse>

Query Workbook Preview Image

Returns the thumbnail image as a PNG file for the specified workbook. Usually the image that is returned is for the first sheet in the workbook.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/previewImage

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to return the thumbnail image for.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query a workbook preview image only if they have Read (view) permission for the workbook (either explicitly or implicitly) and also have Read (view) permission for the view that is used as the preview image. If the user doesn't have Read permissions to that view, the preview image for another view might be used. If the user doesn't have Read permissions to any views in the workbook, the user is not allowed to query a workbook query image.

Response Code

200

Response Body

The workbook's preview image in PNG format (MIME media type image/png).

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Read forbidden A non-administrator user attempted to query the workbook preview image, but the caller doesn't have Read permission for the workbook.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/previewImage" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" > workbook-preview.png

The response is a graphics file in PNG format.

Query Workbooks for Site

Returns the workbooks on a site.

If the user is not an administrator, the method returns just the workbooks that the user has permissions to view.


URI

GET /api/api-version/sites/site-id/workbooks

GET /api/api-version/sites/site-id/workbooks?filter=filter-expression

GET /api/api-version/sites/site-id/workbooks?sort=sort-expression

GET /api/api-version/sites/site-id/workbooks?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/workbooks?fields=field-expression

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the workbooks.
filter-expression (Optional) An expression that lets you specify a subset of workbooks to return. You can filter on predefined fields such as name, tags, and createdAt. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which workbook information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
field-expression (Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as _all_ or _default_, and you can specify individual fields for the workbooks or other supported resources. You can include multiple field expressions in a request. For more information, see Using Fields in the REST API.

Note: The filter and sort parameters can be combined with each other and with paging parameters and fields parameters using an ampersand (&).

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can get workbooks that they have Read (view) permissions for (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="page-number"
     pageSize="page-size"
     totalAvailable="total-available" />
  <workbooks>
    <workbook id="workbook-id" name="name"
          contentUrl="content-url"  
          showTabs="show-tabs-flag"
          size="size-in-megabytes"
          createdAt="datetime-created"
          updatedAt="datetime-updated"  >
      <project id="project-id" name="project-name" />
      <owner id="user-id" />
      <tags>
        <tag label="tag"/>
        ... additional tags ...
     </tags>
   </workbook>
   ... additional workbooks ...
  </workbooks>
</tsResponse>

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number is not an integer, is less than one, or is greater than the final page number for users at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size exceeds upper limit The page size parameter exceeds the system-wide upper limit of 1000.
403 403018 Read forbidden A non-administrator user attempted to query workbooks for the site, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="27"/>
  <workbooks>
    <workbook id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d" name="Finance" 
        contentUrl="Finance" showTabs="true" size="2" 
        createdAt="2013-03-30T22:32:35Z" updatedAt="2016-01-13T01:00:02Z">
      <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="Tableau Samples"/>
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
      <tags></tags>
    </workbook>
    <workbook id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" name="World Indicators"
         contentUrl="WorldIndicators" showTabs="true" size="1" 
         createdAt="2014-02-19T10:19:23Z" updatedAt="2015-12-29T013:23:45Z">
      <project id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" name="default"/>
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
      <tags>
          <tag label="training" >
      </tags>
    </workbook>
  </workbooks>
  ... another 25 workbooks listed here ...
  </tsResponse>

curl "http://MY-SERVER/api/3.1/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks?filter=updatedAt:gte:2016-05-01T06:00:00Z&sort=name:asc" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

This example includes a filter to return the workbooks that were updated on 1 May 2016 at 6:00 AM or later and specifies that the results should be sorted by the workbook name.

Query Workbooks for User

Returns the workbooks that the specified user owns in addition to those that the user has Read (view) permissions for.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.


URI

GET /api/api-version/sites/site-id/users/user-id/workbooks

GET /api/api-version/sites/site-id/users/user-id/workbooks?ownedBy=isOwner&pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.1. For more information, see REST API Versions.
site-id The ID of the site that contains the user.
user-id The ID of the user to get workbooks for.
isOwner (Optional) true to return only workbooks that the specified user owns, or false to return all workbooks that the specified user has at least read access to. The default is false.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

All users can call this method, but the results of the call depend on the user's permissions. Server and site administrators see all workbooks for the specified user. If the isOwner parameter is true, users who are not server or site administrators see the workbooks that they own on the site. If isOwner parameter is false, users who are not server administrators see the workbooks that they have Read (view) permissions for.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber" pageSize="page-size"
         totalAvailable="total-available" />
  <workbooks>
    <workbook id="workbook-id" name="name"
      contentUrl="content-url"  
      showTabs="show-tabs-flag"
      size="size-in-megabytes"
      createdAt="datetime-created"
      updatedAt="datetime-updated"  >
      <project id="project-id" name="project-name" />
      <owner id="user-id" />
      <tags>
        <tag label="tag"/>
        ... additional tags ...
      </tags>
   </workbook>
   ... additional workbooks ...
</tsResponse>

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than o