Site Methods

Using the site methods of the Tableau Server REST API you can:

  • List sites on a server or get details of a specific site
  • Create, update, or delete a site
  • List views in a site

This functionality relates to the UI elements and concepts described at: Sites Overview(Link opens in a new window).

Create Site

Creates a site on Tableau Server. To make changes to an existing site, call Update Site. This method is not available for Tableau Online.

For more information, see Work with Sites(Link opens in a new window) and Add or Edit Sites(Link opens in a new window) 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"
	storageQuota="limit-in-megabytes"
	disableSubscriptions="disable-subscriptions"
    editingFlowsEnabled="editing-flows-enabled-flag"
    schedulingFlowsEnabled="scheduling-flows-enabled-flag"
	allowSubscriptionAttachments="allow-subcription-attachments-flag"
	guestAccessEnabled="guest-access-enabled-flag"
	cacheWarmupEnabled="cache-warmup-enabled-flag"
	commentingEnabled="commenting-enabled-flag"
	revisionHistoryEnabled="enable-revision-history-flag"
	revisionLimit="num-revision-limit"
	subscribeOthersEnabled="subscribe-others-enabled-flag"
	extractEncryptionMode="extractEncryptionMode"
	requestAccessEnabled="request-access-enabled-flag"
	runNowEnabled="run-now-enabled-flag"
	userQuota="all-license-limit-total"
	tierCreatorCapacity="creator-license-limit"
	tierExplorerCapacity="explorer-license-limit"
	tierViewerCapacity="viewer-license-limit"
	dataAlertsEnabled="data-alerts-enabled-flag"
	commentingMentionsEnabled="commenting-mentions-enabled-flag"
	catalogObfuscationEnabled="catalog-obfuscation-enabled-flag"
	flowAutoSaveEnabled="flow-auto-save-enabled-flag"
	webExtractionEnabled="web-extraction-enabled-flag"
	runNowEnabled="run-now-enabled-flag"
	metricsContentTypeEnabled="metrics-content-type-enabled-flag"
	notifySiteAdminsOnThrottle="notify-site-admins-on-throttle-flag"
	authoringEnabled="authoring-enabled-flag"
	customSubscriptionEmailEnabled="custom-subscription-email-enabled-flag"
	customSubscriptionEmail="custom-subscription-email"
	customSubscriptionFooterEnabled="custom-subscription-footer-enabled-flag"
	customSubscriptionFooter="custom-subscription-footer"
	askDataMode="ask-data-mode"
	namedSharingEnabled="named-sharing-enabled-flag"
	catalogingEnabled="cataloging-enabled-flag"
	derivedPermissionsEnabled="derived-permissions-enabled-flag"
	userVisibilityMode="user-visibility-mode"
	useDefaultTimeZone="default-time-zone-flag"
 	timeZone="time-zone"
    autoSuspendRefreshEnabled="auto-suspend-refresh-enabled-flag"
    autoSuspendRefreshInactivityWindow="auto-suspend-refresh-inactivity-window" />
</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 userQuota. The default value is ContentAndUsers.

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.

editing-flows-enabled-flag

(Optional) Specify true to enable and false to disable editing flows for a site. For more information on flows, see Enable and Configure Tableau Prep Conductor(Link opens in a new window).

The default is set to true which means editing flows is enabled by default. For more information, see Implication of disabling Tableau Prep Conductor.

scheduling-flows-enabled-flag

(Optional) Specify true to enable and false to disable scheduling flows for a site. For more information on flows, see Enable and Configure Tableau Prep Conductor(Link opens in a new window).

The default is set to true which means scheduling flows is enabled by default. For more information, see Implication of disabling Tableau Prep Conductor.

flows-enabled-flag

The flowsEnabled attribute is deprecated as of API version 3.10.

allow-subscription-attachments-flag

(Optional) If true, and subscription to attachments is enabled on the server, then users can create subscriptions that send an email with images of a workbook or view in a PDF attachment. The default value is true. If subscription to attachments is disabled in the server settings, then making this value true will have no effect. Default is true.

guest-access-enabled-flag

(Optional) Specify true to enable and false to disable the ability for guests, users without specific site access permission, to access the site. Default is false.

cache-warmup-enabled-flag

(Optional) Set this value to true to enable cache warm up to improve workbook load time. Set the value to false to disable cache warmup. Default is true.

commenting-enabled-flag

(Optional) Specify true to enable and false to disable the ability for user comments on views in the site. Default is true.

revision-history-enabled (Optional) true if the site maintains revisions for changes to workbooks and data sources; otherwise, false. The default is false.
num-revision-limit (Optional) An integer between 2 and 10000 to indicate a limited number of revisions for content.

Setting this value to -1 removes any value that was set previously, and effectively removes any limit to the number of revisions that are maintained.

subscribe-others-enabled-flag

(Optional) Specify true to enable and false to disable the ability for view owners to subscribe other users to a view. Default is true.

extractEncryptionMode

(Optional) Specify enforced, enabled, or disabled. Default is disabled. For more information, see Extract and Encryption Methods.

requestAccessEnabled (Optional) Specify true to allow users send access request emails to content or project owners. Specify false if you do not want users to be able to request access. The default is false.
runNowEnabled

(Optional) Specify true to allow users to run flows, extract refreshes, and schedules manually. Specify false if you do not want users to be able to run flows, extract refreshes, and subscriptions manually. The default is true. If this attribute is set to false, the following methods will fail and will return an error message.

Run Flow Now

Run Flow Task(Link opens in a new window)

Update Data Source Now(Link opens in a new window)

Run Extract Refresh Task(Link opens in a new window)

Licensing attributes

For user-based license types, the maximum possible 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.

The REST API enables administrators to set licensing limits below the purchased maximum with two types of license-related attributes:
- User Quota - The total maximum number of licenses currently configured for a site.
- Tiered Capacities - If set, the configured maximum license count for each license type (role).

Online administrators can get these attributes. An on premise server administrator can both get and set them but if license maximums are set using one attribute kind then the value(s) of the other kind must be null. Setting values for both kinds of attributes will result in an error.

For more information, see Licensing Overview(Link opens in a new window).

User quota

all-license-limit-total

(Optional) The maximum total number of users with Creator, Explorer, or Viewer licenses currently allowed on a site.

On premise server administrators can set userQuota with the following rules: The number can't exceed the number of licenses activated for the site; and if tiered capacity attributes are set, then userQuota will equal the sum of the tiered capacity values, and attempting to set userQuota will cause an error.

An administrator can revert the license limit to number of activated licenses on the site, or shift control of license limits to tiered capacities values, by omitting userQuota from a Create Site or Update Site request, or making its value -1.

Tiered capacity attributes

creator-license-limit
explorer-license-limit
viewer-license-limit

(Optional) The maximum number of licenses for users with the Creator, Explorer, or Viewer role, respectively, allowed on a site.

On premise server administrators can set tiered capacity attributes with the following rules: the number can't exceed the number of licenses of a given type that are activated for the site; a value must be supplied for every tiered capacity license type every time any one or more of them is set.

A value of -1 removes the administrator applied limit for a license type, and reverts the limit to the number of activated licenses configured for the role. Setting the value of a tiered capacity to -1 will not automatically increase the limit if more licenses are purchased and activated for the role in the future.

To use role-specific license limits, the userQuota must be set to null by omitting the attribute from Create Site or Update Site request, or setting its value to -1. Attempting to set values for both tiered capacities and userQuota will result in an error.

data-alerts-enabled-flag

(Optional, boolean) If true, data alerts are enabled on the site. Default value is true.

commenting-mentions-enabled-flag

(Optional, boolean) If true, mentions for commenting are enabled. Default value is true.

catalog-obfuscation-enabled-flag

(Optional, boolean) If true, catalog obfuscation is enabled on the site. Default value is true.

flow-auto-save-enabled-flag

(Optional, boolean) If true, flow auto save is enabled on the site. Default value is true.

web-extraction-enabled-flag

(Optional, boolean) If true, web extraction is enabled on the site. Default value is true.

run-now-enabled-flag

(Optional, boolean) If true, run now for schedules is enabled which allows non-administrators to run schedules manually. Default value is true.

metrics-content-type-enabled-flag

(Optional, boolean) If true, the metrics content type is enabled on the server. Default value is true.

notify-site-admins-on-throttle-flag

(Optional, boolean) If true, site admins will be notified if their background jobs are being throttled. Default value is false.

authoring-enabled-flag

(Optional, boolean) If true, web authoring is enabled. Default value is true.

custom-subscription-email-enabled-flag

(Optional, boolean) If true, sending custom subscription email is enabled. If set to false after being set true, the current custom subscription email is voided. Default value is false.

custom-subscription-email

A valid custom email that will be sent if customSubscriptionEmailEnabled is set to true. Default value is false.

custom-subscription-footer-enabled-flag

(Optional, boolean) If true, a custom footer will be included on subscription and data alert emails. If set to false after being set true, the current custom subscription footer is voided. Default value is false.

custom-subscription-footer

A custom subscription footer that will be added to subscription and data alerts if customSubscriptionFooterEnabled is set to true. Default value is false.

ask-data-mode

The mode of the ask data feature on the site. Can be set to one of three values:
  • EnabledByDefault - datasouces will have ask data mode set to enabled unless manually disabled
  • DisabledByDefault - datasources will have ask data mode set to disabled unless manually enabled
  • DisabledAlways - datasources will have ask data mode set to disabled in all cases
Default value is EnabledByDefault.

named-sharing-enabled-flag

(Optional, boolean) If true, named sharing is enabled. Default value is true.

cataloging-enabled-flag

(Optional, boolean) If true, data catalog is enabled for the site. Default value is true.

derived-permissions-enabled-flag

(Optional, boolean) If true, derived permissions are enabled for the site. Default value is false.

user-visibility-mode

(Optional, string) When the value is FULL users can see the user of other site users. If the value is LIMITED User information on the site is not visibel to other users. Default value is FULL. For more information, see User Visibility(Link opens in a new window).
use-default-time-zone Optional, boolean) Set this to true, if you want the time-zone attribute use the Server time Zone at run time. This attribute is set to official IANA name.  If this is set to false, the time-zone value must be specified.
time-zone (Optional, string) Use this attribute to specify a time zone other than the Server time zone at run time. Only canonical names in the official IANA database are supported. You can find the list of the canonical time zone names on wikipedia.
autoSuspendRefreshEnabled (Optional) Tableau can automatically suspend extract refresh tasks for inactive workbooks to save resources. Specify true to enable or false to disable. Default is true.
autoSuspendRefreshInactivityWindow (Optional) An integer between 7 and 100 to indicate the number of days to wait before automatically suspending extract refresh tasks for inactive workbooks. The default is 30.

Permissions

This method can only be called by server administrators.

Response Code

201

Response Body

<tsResponse>
  <site id="site-id"
 	name="site-name"
	contentUrl="content-url"
 	adminMode="admin-mode"
	disableSubscriptions="disable-subscriptions-flag"
	state="active-or-suspended"
	revisionHistoryEnabled="history-enabled-flag"
	revisionLimit="max-num-revisions"
	allowSubscriptionAttachments="allow-subcription-attachments-flag"
	subscribeOthersEnabled="enable-subscription-of-others-flag"
	guestAccessEnabled="guest-access-enabled-flag"
	cacheWarmupEnabled="cache-warmup-enabled-flag"
	commentingEnabled="commenting-enabled-flag"
    editingFlowsEnabled="editing-flows-enabled-flag"
    schedulingFlowsEnabled="scheduling-flows-enabled-flag"
	extractEncryptionMode="encryption-mode"
	catalogingEnabled="cataloging-enabled-flag"
	derivedPermissionsEnabled="derived-permissions-enabled-flag"
	requestAccessEnabled="request-access-enabled-flag"
	webExtractionEnabled="create-extracts-on-the-web-flag"
	runNowEnabled="run-now-enabled-flag"
	userQuota="all-license-limit-total"
	tierCreatorCapacity="creator-license-limit"
	tierExplorerCapacity="explorer-license-limit"
	tierViewerCapacity="viewer-license-limit" />
	askDataMode="ask-data-mode"
	useDefaultTimeZone="default-time-zone-flag"
	timeZone="time-zone"
    autoSuspendRefreshEnabled="auto-suspend-refresh-enabled-flag"
    autoSuspendRefreshInactivityWindow="auto-suspend-refresh-inactivity-window" />
  </site>
</tsResponse>
        

Response Body Details:

  • userQuota, storageQuota, and tiered capacity (tierCreatorCapacity, tierExplorerCapacity, tierViewerCapacity) attributes are only present in the response body if those quotas have been set for the site being queried.

Response Headers

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing, 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 User quota and tiered capacity conflict The request cannot set both tiered capacity attributes and userQuota. One or the other must be null.
409 409004 License limit exceeded The request cannot set tiered capacity attributes or userQuota values that are larger than the number of active licenses configured for the site.
409 409004 Administrator mode or user quota conflict The request cannot set adminMode to ContentOnly and also specify a userQuota value.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.12/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"
		tierCreatorCapacity="2"
		tierExplorerCapacity="1"
		tierViewerCapacity="1"
		useDefaultTimeZone="false"
		timeZone="America/Los_Angeles"/>
</tsRequest>
        

Response body:

<tsResponse>
	<site id="43e01bb6-d7f9-42ef-bc9f-0422c07520e5"
		name="Marketing-Site"
		contentUrl="marketingsite"
		adminMode="ContentAndUsers"
		disableSubscriptions="true"
		state="Active"
		revisionHistoryEnabled="true"
		revisionLimit="25"
		subscribeOthersEnabled="false"
		allowSubscriptionAttachments="true"
		guestAccessEnabled="true"
		cacheWarmupEnabled="true"
		commentingEnabled="true"
        editingFlowsEnabled="false"
        schedulingFlowsEnabled="false"
		extractEncryptionMode="enabled"
		catalogingEnabled="true"
		derivedPermissionsEnabled="false"
		requestAccessEnabled="false"
		runNowEnabled="true"
		userQuota="4"
		tierCreatorCapacity="2"
		tierExplorerCapacity="1"
		tierViewerCapacity="1"
		useDefaultTimeZone="false"
		timeZone="America/Los_Angeles" />
</tsResponse>
        

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.12. For more information, see REST API and Resource 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 and Resource 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.12/sites/9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

curl "http://MY-SERVER/api/3.12/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.

Get Data Acceleration Report for a Site

Returns a report about data acceleration for the site. It lets you compare page load times for before and after data acceleration is enabled.

URI

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

Parameter Values

api-version The version of the API to use, such as 3.12. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the task.

Request Body

None

Permissions

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

Response Code

200

Response Body

<tsResponse>
  <dataAccelerationReport>
    <comparisonRecord site="Default" sheetURI="sheetURI" unacceleratedSessionCount="unacceleratedSessionCount" averageUnAcceleratedPLT="averageUnAcceleratedPLT" acceleratedSessionCount="acceleratedSessionCount" averageAcceleratedPLT="averageAcceleratedPLT" />
</tsResponse>
					
        

Attribute Values

sheetURI The URI of the sheet in the workbook.
unacceleratedSessionCount The number of sessions that were created to load the workbook sheet before it was accelerated. For example, if you loaded it 7 times in a row, the session is reused so the count will still be 1. Generally, the more data you compare, the better the comparison is. Note: If sheets were loaded but never accelerated, they are not shown.
averageUnAcceleratedPLT The average page load time for the sheet before it was accelerated.
acceleratedSessionCount The number of sessions that were created to load the workbook sheet after it was accelerated.
averageAcceleratedPLT The average page load time for the sheet after it was accelerated.

Version

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

Errors

404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 40500 Invalid requests method Request type was not GET

For more information, see Handling Errors.

Example

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

Example response:


<tsResponse version-and-namespace-settings>
  <dataAccelerationReport>
    <comparisonRecord site="Default" sheetURI="Live/Sheet1" unacceleratedSessionCount="0" averageUnAcceleratedPLT="0.0" acceleratedSessionCount="1" averageAcceleratedPLT="0.166" />
  ...
  </dataAccelerationReport>
</tsResponse>
          

Get Recently Viewed for Site

Gets the details of the views and workbooks on a site that have been most recently created, updated, or accessed by the signed in user. The 24 most recently viewed items are returned, though it may take some minutes after being viewed for an item to appear in the results.

URI

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

Parameter Values

api-version The version of the API to use, such as 3.12. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the views and workbooks.

Request Body

None

Permissions

For Tableau Server users who are not server administrators or site administrators, the method returns only the views and workbooks that the user owns or has Read permissions for (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse >
<recents>
  <recent>
	<view
	  id="view-id"
	  name="view-name"
	  contentUrl="view-content-url"
	  createdAt="created-at-time"
	  updatedAt="updated-at-time"
	  viewUrlName="view-url-name">
		<workbook id=""workbook-of-view" "/>
		<owner id="owner-id" />
		<project id="project-id" />
		<tags/>
	</view>
  </recent>
  <recent>
    <workbook
 	  id="workbook-id"
	  name="workbook-name"
	  description="workbook-description"
	  contentUrl="workbook-content-url"
	  webpageUrl="workbook-webpage-url"
	  showTabs="show-tags-flag"
	  size="size-in-mb"
	  createdAt="created-at-time"
	  updatedAt="updated-at-time"
	  encryptExtracts="encrypt-extracts-flag"
	  defaultViewId="default-view-id" >
        <project id="project-id"/>
        <owner id="ownwer-id"
		name="project-name" />
        <tags/>
	</workbook>
  </recent>
  <!--  more recently viewed views and workbooks  -->
</tsResponse>
        

The value of view-url-name is the name of the view in its URL. For example, if a view named View 1 shows the URL https://MY_SERVER/#/site/MY_SITE/views/VIEW_1 in your browser address bar, then the the view-url-name would be VIEW_1. Modifying the name (display name) of a view will not impact the view-url-name (path element of the view's URL).

Version

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

Errors

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 -X GET "https://qa-windows/api/3.5/sites/cd24a433-b66c-46cd-a4af-6cde73db9ee1/content/recent" -H "X-Tableau-Auth: pI8NzKb-S5-Jqiatds8jrQ|GKUYlgHjuHSPSVfS38plFpH31UkHGtNl"

Example response:

<tsResponse >
  <recents>
    <recent>
      <view
	    id="8a922e79-3041-4916-942e-1a18162ef8a9"
	    name="MySQL PostgresSQL"
	    contentUrl="my_site1"
	    createdAt="2019-01-28T20:33:35Z"
	    updatedAt="2019-01-28T20:44:05Z"
		viewUrlName="MySQL_PostgresSQL">
		  <workbook id="1eb0d238-c9d2-49ec-a0ce-762ddc6f9827"/>
		  <owner id="2dbbee8a-202c-4a74-82d6-8e3544f55ceb"/>
		  <project id="50b87b02-74b6-11e8-a4b0-df15be81c0c4"/>
		  <tags/>
      </view>
    </recent>
    <recent>
	  <workbook
	    id="5589cf2b-8601-43f9-9151-0f6c2db760cc"
	    name="Connections-AmazonAurora (1)"
	    description=""
	    contentUrl="my_site2"
	    webpageUrl="https://my_server/#/workbooks/222"
	    showTabs="false"
	    size="7"
	    createdAt="2019-02-13T20:52:37Z"
	    updatedAt="2019-02-13T20:52:38Z"
	    encryptExtracts="false"
	    defaultViewId="d4bed763-1cb1-4924-b455-6a6c298d860d">
	      <project id="add6c395-11b8-4d57-a66b-733220a33aa0" name="project2"/>
	      <owner id="3f90c20d-069f-46dd-b5a0-6e7092140790" name="my_name"/>
	      <tags/>
	  </workbook>
    </recent>
    <!--  more recently viewed views and workbooks  --%gt;
  </recent>
</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

GET /api/api-version/sites/site-id?includeUsage=include-usage-flag

Parameter Values

api-version The version of the API to use, such as 3.12. For more information, see REST API and Resource 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.
include-usage-flag The boolean flag to include site usage metrics in the response body. If true, then the site element of the response will contain a usage node with the attributes numUsers (number of users) and storage (storage in megabytes).

To set the flag to include usage in the response, append includeUsage=true as a querystring element any valid query site URI.

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"
	disableSubscriptions="new-disable-subscriptions"
	state="active-or-suspended
	revisionHistoryEnabled="revision-history-enabled-flag"
	revisionLimit="revision-limit"
	subscribeOthersEnabled="subscribe-others-enabled-flag"
	allowSubscriptionAttachments="allow-subcription-attachments-flag"
	userQuota="num-users"
	guestAccessEnabled="guest-access-enabled-flag"
	cacheWarmupEnabled="cache-warmup-enabled-flag"
	commentingEnabled="commenting-enabled-flag"
	storageQuota="limit-in-megabytes"
    editingFlowsEnabled="editing-flows-enabled-flag"
    schedulingFlowsEnabled="scheduling-flows-enabled-flag"
	extractEncryptionMode="encryption-mode"
	catalogingEnabled="cataloging-enabled-flag"
	derivedPermissionsEnabled="derived-permissions-enabled-flag"
	requestAccessEnabled="request-access-enabled-flag"
	runNowEnabled="run-now-enabled-flag"
	usage numUsers="number-of-users"
	storage="storage-in-megabytes"
	userQuota="all-license-limit-total"
	tierCreatorCapacity="creator-license-limit"
	tierExplorerCapacity="explorer-license-limit"
	tierViewerCapacity="viewer-license-limit"
	isDataAlertsEnabled="data-alerts-enabled-flag"
    	askkDataMode="ask-data-enablement"
	useDefaultTimeZone="default-time-zone-flag"
	timeZone="time-zone"
    autoSuspendRefreshEnabled="auto-suspend-refresh-enabled-flag"
    autoSuspendRefreshInactivityWindow="auto-suspend-refresh-inactivity-window"/>
  </site>
</tsResponse>
        

Response Body Details:

  • userQuota, storageQuota, and tiered capacity (tierCreatorCapacity, tierExplorerCapacity, tierViewerCapacity) attributes are only present in the response body if those quotas have been set for the site being queried.

Version

Version 1.0 and later. For more information, see REST API and Resource 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.12/sites/1234abcd-12ab-12ab-12ab-1234abcd1234?includeUsage=true" -X GET \
-H "X-Tableau-Auth:ABCD1234abcdABCD|ABCD1234abcdABCDABCD1234abcd-1"

Example response:

<tsResponse>
  <site id="1234abcd-12ab-12ab-12ab-1234abcd1234"
    	name="new_site_name"
    	contentUrl="new_site_url"
    	adminMode="ContentAndUsers"
    	storageQuota="100"
    	disableSubscriptions="true"
    	state="Active"
    	revisionHistoryEnabled="true"
    	revisionLimit="25"
    	subscribeOthersEnabled="false"
    	allowSubscriptionAttachments="true"
    	guestAccessEnabled="false"
    	cacheWarmupEnabled="true"
    	commentingEnabled="true"
        editingFlowsEnabled="false"
        schedulingFlowsEnabled="false"
	extractEncryptionMode="enabled"
	catalogingEnabled="true"
    	derivedPermissionsEnabled="false"
    	requestAccessEnabled ="false"
    	runNowEnabled="true"
    	usage numUsers="0" storage="0"
	userQuota="4"
	tierCreatorCapacity="2"
	tierExplorerCapacity="1"
	tierViewerCapacity="1"
    	isDataAlertsEnabled="true"
    	askDataMode="EnabledByDefault"
	useDefaultTimeZone="false"
	timeZone="America/Los_Angeles"/>
  </site>
</tsResponse>
          

Command:

curl "http://MY-SERVER/api/3.12/sites/Default?key=name" -X GET \
-H "X-Tableau-Auth:ABCD1234abcdABCD|ABCD1234abcdABCDABCD1234abcd-1"

Example response:

<tsResponse>
  <site id="1234abcd-12ab-12ab-12ab-1234abcd1234"
	name="new_site_name"
	contentUrl=""
	adminMode="ContentAndUsers"
	storageQuota="100"
	disableSubscriptions="true"
	state="Active"
	revisionHistoryEnabled="true"
	revisionLimit="25"
	subscribeOthersEnabled="false"
    allowSubscriptionAttachments="true"
	guestAccessEnabled="false"
	cacheWarmupEnabled="true"
	commentingEnabled="true"
    editingFlowsEnabled="false"
    schedulingFlowsEnabled="false"
	extractEncryptionMode="enabled"
	catalogingEnabled="true"
	derivedPermissionsEnabled="false"
	requestAccessEnabled ="false"
 	runNowEnabled="true"/>
	userQuota="4"
	tierCreatorCapacity="2"
	tierExplorerCapacity="1"
	tierViewerCapacity="1"
    	askDataMode="EnabledByDefault"
	useDefaultTimeZone="false"
	timeZone="America/Los_Angeles" />
  </site>
</tsResponse>
          

Query Sites

Returns a list of the sites on the server that the caller of this method has access to. This method is not available for Tableau Online.

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.12. For more information, see REST API and Resource 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="site-name"
	  contentUrl="content-url"
	  adminMode="admin-mode"
	  disableSubscriptions="disable-subscriptions-flag"
	  userQuota="num-users"
	  storageQuota="limit-in-megabytes"
	  state="active-or-suspended"
	  statusReason="reason-for-state"
	  revisionHistoryEnabled="revision-history-flag"
	  revisionLimit="num-revisions"
	  subscribeOthersEnabled="subscribe-others-flag"
      allowSubscriptionAttachments="allow-subcription-attachments-flag"
	  guestAccessEnabled="guest-access-enabled-flag"
	  cacheWarmupEnabled="enable-cache-warm-up-flag"
	  commentingEnabled="enable-commenting-flag"
      editingFlowsEnabled="editing-flows-enabled-flag"
      schedulingFlowsEnabled="scheduling-flows-enabled-flag"
	  extractEncryptionMode="extract-encryption-mode"
	  catalogingEnabled="enable-cataloging-flag"
	  derivedPermissionsEnabled="derived-permissions-enabled-flag
	  requestAccessEnabled ="false"
	  runNowEnabled="true"
	  isDataAlertsEnabled="data-alerts-enabled-flag"
	  askDataMode="ask-data-enablement"
	useDefaultTimeZone="default-time-zone-flag"
	  timeZone="time-zone" />
	<!--   ... additional sites ... -->
  </sites>
</tsResponse>
        

The response for users without administrative permissions contains only the site id, name, and content-url attributes.

Version

Version 1.0 and later. For more information, see REST API and Resource 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.12/sites?pageSize=1&pageNumber=1" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse>
  <pagination pageNumber="1"
    pageSize="1"
    totalAvailable="2"/>
  <sites>
    <site id="abcd1234-ab12-ab12-ab12-abcd1234abcd"
    name="Default"
    contentUrl=""
	adminMode="ContentAndUsers"
	disableSubscriptions="true"
	state="Active"
    revisionHistoryEnabled="true"
	revisionLimit="25"
	subscribeOthersEnabled="false"
	allowSubscriptionAttachments="true"
	guestAccessEnabled="true"
	cacheWarmupEnabled="true"
	commentingEnabled="true"
    editingFlowsEnabled="false"
    schedulingFlowsEnabled="false"
	extractEncryptionMode="enabled"
	catalogingEnabled="true"
	derivedPermissionsEnabled="false"
	requestAccessEnabled ="false"
    runNowEnabled="true"
	isDataAlertsEnabled="true"
	askkDataMode="EnabledByDefault"
	useDefaultTimeZone="false"
	timeZone="America/Los_Angeles" />
  </sites>
</tsResponse>
        

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/site-id/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 and Resource 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 and Resource 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.12/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>

Update Site

Modifies settings for the specified site, including the content URL, administration mode, user quota, state (active or suspended), storage quota, whether flows are enabled, whether subscriptions are enabled, and whether revisions are enabled. If you're working with Tableau Online, this method can also be used to upload a new logo image for the site.

Note: You must be signed in to a site in order to update it.

URI

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

Parameter Values

api-version The version of the API to use, such as 3.12. For more information, see REST API and Resource Versions.
site-id The ID of the site to update.

Request Body

Updating individual settings

<tsRequest>
  <site name="new-site-name"
	contentUrl="new-content-url"
	adminMode="new-admin-mode"
	storageQuota="limit-in-megabytes"
	disableSubscriptions="new-disable-subscriptions"
	state="new-state"
	revisionHistoryEnabled="revision-history-enabled"
	revisionLimit="revision-limit"
	allowSubscriptionAttachments="allow-subcription-attachments-flag"
	subscribeOthersEnabled="subscribe-others-enabled-flag"
	guestAccessEnabled="guest-access-enabled-flag"
	cacheWarmupEnabled="cache-warmup-enabled-flag"
	commentingEnabled="commenting-enabled-flag"
    editingFlowsEnabled="editing-flows-enabled-flag"
    schedulingFlowsEnabled="scheduling-flows-enabled-flag"
	extractEncryptionMode="extractEncryptionMode"
	dataAccelerationMode="dataAccelerationMode"
	requestAccessEnabled="request-access-enabled-flag"
	runNowEnabled="run-now-enabled-flag"
	userQuota="all-license-limit-total"
	tierCreatorCapacity="creator-license-limit"
	tierExplorerCapacity="explorer-license-limit"
	tierViewerCapacity="viewer-license-limit"
	dataAlertsEnabled="data-alerts-enabled-flag"
	commentingMentionsEnabled="commenting-mentions-enabled-flag"
	catalogObfuscationEnabled="catalog-obfuscation-enabled-flag"
	flowAutoSaveEnabled="flow-auto-save-enabled-flag"
	webExtractionEnabled="web-extraction-enabled-flag"
	runNowEnabled="run-now-enabled-flag"
	metricsContentTypeEnabled="metrics-content-type-enabled-flag"
	notifySiteAdminsOnThrottle="notify-site-admins-on-throttle-flag"
	authoringEnabled="authoring-enabled-flag"
	customSubscriptionEmailEnabled="custom-subscription-email-enabled-flag"
	customSubscriptionEmail="custom-subscription-email"
	customSubscriptionFooterEnabled="custom-subscription-footer-enabled-flag"
	customSubscriptionFooter="custom-subscription-footer"
	askDataMode="ask-data-mode"
	namedSharingEnabled="named-sharing-enabled-flag"
	catalogingEnabled="cataloging-enabled-flag"
	derivedPermissionsEnabled="derived-permissions-enabled-flag"
	userVisibilityMode="user-visibility-mode"
	useDefaultTimeZone="default-time-zone-flag"
	timeZone="time-zone"
    autoSuspendRefreshEnabled="auto-suspend-refresh-enabled-flag"
    autoSuspendRefreshInactivityWindow="auto-suspend-refresh-inactivity-window" />
</tsRequest>
          

Updating the site logo

If you are working with Tableau Online, you can specify a new site logo. The optimum image size for the logo is 150 pixels wide by 30 pixels tall. For more information, see "Image File Tips" in the topic Upload a Custom Logo for your Site(Link opens in a new window).

To set a new site logo, you pass a multi-part payload to the site. In addition to setting the X-Tableau-Auth header to the sign-in token, you must set the Content-Type header to multipart/mixed and include a boundary string. For example, the header might look like the following example:

Content-Type: multipart/mixed; boundary=az1by2cx34dw

The request body starts with the string you specify as the boundary. This is followed by two headers. You set Content-Disposition header to form-data, and then a name value set to site_logo and a filename value. You must also include a Content-Type header set to application/octet-stream. After the headers, you include a blank line then the binary data (not encoded). The binary data is followed by a line that includes the boundary string and the two required termination hyphens (--).

The following example shows the request body using the boundary string that was specified in the example header earlier.

--az1by2cx34dw Content-Disposition: form-data; name="site_logo"; filename="new-site-logo.png" Content-Type: application/octet-stream  <binary data here> --az1by2cx34dw--

Restoring the default site logo

To restore the default site logo, you pass a multi-part payload to the site, as you do to set the logo. However, instead of passing binary data for the image, you pass an empty image. And instead of setting the Content-Type header in the body to application/octet-stream, you set the content type to text/plain.

The following example shows the request body using the boundary string that was specified in the example header earlier.

--az1by2cx34dw Content-Disposition: form-data; name="site_logo"; filename="empty.txt" Content-Type: text/plain   --az1by2cx34dw--

Attribute Values

new-site-name (Optional) The new name of the site.
new-content-url (Optional) The new site URL. This value can contain only characters that are valid in a URL.
new-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 a userQuota value. The default value is ContentAndUsers.

new-state (Optional) Active to set the site to active mode, or Suspended to suspend the site. Default is Active.
new-storage-quota (Optional) The new 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.
new-disable-subscriptions (Optional) true to prevent users from being able to subscribe to workbooks on the specified site. Default is false.
revision-history-enabled (Optional) true if the site maintains revisions for changes to workbooks and data sources; otherwise, false. The default is false.
revision-limit (Optional) An integer between 2 and 10000 to indicate a limited number of revisions for content.

Setting this value to -1 removes any value that was set previously, and effectively removes any limit to the number of revisions that are maintained.

allow-subscription-attachments-flag

(Optional) If true, and subscription to attachments is enabled on the server, then users can create subscriptions that send an email with images of a workbook or view in a PDF attachment. The default value is true. If subscription to attachments is disabled in the server settings, then making this value true will have no effect. Default is true.

subscribe-others-enabled-flag

(Optional) Specify true to enable and false to disable the ability for view owners to subscribe other users to a view. Default is true.

editing-flows-enabled-flag

(Optional) Specify true to enable and false to disable editing flows for a site. For more information on flows, see Enable and Configure Tableau Prep Conductor(Link opens in a new window).

The default is set to true which means editing flows is enabled by default. For more information, see Implication of disabling Tableau Prep Conductor.

scheduling-flows-enabled-flag

(Optional) Specify true to enable and false to disable scheduling flows for a site. For more information on flows, see Enable and Configure Tableau Prep Conductor(Link opens in a new window).

The default is set to true which means scheduling flows is enabled by default. For more information, see Implication of disabling Tableau Prep Conductor.

flows-enabled-flag

The flowsEnabled attribute is deprecated as of API version 3.10.

guest-access-enabled-flag

(Optional) Specify true to enable and false to disable the ability for guests, users without specific site access permission, to access the site. Default is false.

cache-warmup-enabled-flag

(Optional) Set this value to true to enable cache warm up to improve workbook load times. Set the value to false to disable cache warmup. Default is true.

commenting-enabled-flag

(Optional) Specify true to enable and false to disable the ability for user comments on views in the site. Default is true.

extractEncryptionMode

(Optional) Specify enforced, enabled, or disabled. Default is disabled. For more information, see Extract and Encryption Methods.

dataAccelerationMode

(Optional) Specify enable_selective or disabled. The default is enable_selective which lets you update particular workbooks to turn on data acceleration using the accelerationEnabled attribute. For more information, see Data Acceleration.

requestAccessEnabled (Optional) Specify true to allow users send access request emails to content or project owners. Specify false if you do not want users to be able to request access. The default is false.
runNowEnabled

(Optional) Specify true to allow users to run flows, extract refreshes, and schedules manually. Specify false if you do not want users to be able to run flows, extract refreshes, and subscriptions manually. The default is true. If this attribute is set to false, the following methods will fail and will return an error message.

Run Flow Now

Run Flow Task(Link opens in a new window)

Update Data Source Now(Link opens in a new window)

Run Extract Refresh Task(Link opens in a new window)

Licensing attributes

For user-based license types, the maximum possible 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.

The REST API enables administrators to set licensing limits below the purchased maximum with two types of license-related attributes:
- User Quota - The total maximum number of licenses currently configured for a site.
- Tiered Capacities - If set, the configured maximum license count for each license type (role).

Online administrators can get these attributes. An on premise server administrator can both get and set them but if license maximums are set using one attribute kind then the value(s) of the other kind must be null. Setting values for both kinds of attributes will result in an error.

For more information, see Licensing Overview(Link opens in a new window).

User quota

all-license-limit-total

(Optional) The maximum total number of users with Creator, Explorer, or Viewer licenses currently allowed on a site.

On premise server administrators can set userQuota with the following rules: The number can't exceed the number of licenses activated for the site; and if tiered capacity attributes are set, then userQuota will equal the sum of the tiered capacity values, and attempting to set userQuota will cause an error.

An administrator can revert the license limit to number of activated licenses on the site, or shift control of license limits to tiered capacities values, by omitting userQuota from a Create Site or Update Site request, or making its value -1.

Tiered capacity attributes

creator-license-limit
explorer-license-limit
viewer-license-limit

(Optional) The maximum number of licenses for users with the Creator, Explorer, or Viewer role, respectively, allowed on a site.

On premise server administrators can set tiered capacity attributes with the following rules: the number can't exceed the number of licenses of a given type that are activated for the site; a value must be supplied for every tiered capacity license type every time any one or more of them is set.

A value of -1 removes the administrator applied limit for a license type, and reverts the limit to the number of activated licenses configured for the role. Setting the value of a tiered capacity to -1 will not automatically increase the limit if more licenses are purchased and activated for the role in the future.

To use role-specific license limits, the userQuota must be set to null by omitting the attribute from Create Site or Update Site request, or setting its value to -1. Attempting to set values for both tiered capacities and userQuota will result in an error.

data-alerts-enabled-flag

(Optional, boolean) If true, data alerts are enabled on the site. Default value is true.

commenting-mentions-enabled-flag

(Optional, boolean) If true, mentions for commenting are enabled. Default value is true.

catalog-obfuscation-enabled-flag

(Optional, boolean) If true, catalog obfuscation is enabled on the site. Default value is true.

flow-auto-save-enabled-flag

(Optional, boolean) If true, flow auto save is enabled on the site. Default value is true.

web-extraction-enabled-flag

(Optional, boolean) If true, web extraction is enabled on the site. Default value is true.

run-now-enabled-flag

(Optional, boolean) If true, run now for schedules is enabled which allows non-administrators to run schedules manually. Default value is true.

metrics-content-type-enabled-flag

(Optional, boolean) If true, the metrics content type is enabled on the server. Default value is false.

notify-site-admins-on-throttle-flag

(Optional, boolean) If true, site admins will be notified if their background jobs are being throttled. Default value is false.

authoring-enabled-flag

(Optional, boolean) If true, web authoring is enabled. Default value is false.

custom-subscription-email-enabled-flag

(Optional, boolean) If true, sending custom subscription email is enabled. If set to false after being set true, the current custom subscription email is voided. Default value is false.

custom-subscription-email

A valid custom email that will be sent if customSubscriptionEmailEnabled is set to true. Default value is false.

custom-subscription-footer-enabled-flag

(Optional, boolean) If true, a custom footer will be included on subscription and data alert emails. If set to false after being set true, the current custom subscription footer is voided. Default value is false.

custom-subscription-footer

A custom subscription footer that will be added to subscription and data alerts if customSubscriptionFooterEnabled is set to true. Default value is false.

ask-data-mode

The mode of the ask data feature on the site. Can be set to one of three values:
  • EnabledByDefault - datasouces will have ask data mode set to enabled unless manually disabled
  • DisabledByDefault - datasources will have ask data mode set to disabled unless manually enabled
  • DisabledAlways - datasources will have ask data mode set to disabled in all cases
Default value is EnabledByDefault.

named-sharing-enabled-flag

(Optional, boolean) If true, named sharing is enabled. Default value is true.

cataloging-enabled-flag

(Optional, boolean) If true, data catalog is enabled for the site. Default value is true.

derived-permissions-enabled-flag

(Optional, boolean) If true, derived permissions are enabled for the site. Default value is false.

user-visibility-mode

(Optional, string) When the value is FULL users can see the user of other site users. If the value is LIMITED User information on the site is not visible to other users. Default value is FULL. For more information, see User Visibility(Link opens in a new window).
use-default-time-zone (Optional, boolean) Set this to true, if you want the time-zone attribute use the Server time Zone at run time. This attribute is set to official IANA name.  If this is set to false, the time-zone value must be specified.
time-zone (Optional, string) Use this attribute to specify a time zone other than the Server time zone at run time. Only canonical names in the official IANA database are supported. You can find the list of the canonical time zone names on wikipedia.
autoSuspendRefreshEnabled (Optional) Tableau can automatically suspend extract refresh tasks for inactive workbooks to save resources. Specify true to enable or false to disable. Default is true.
autoSuspendRefreshInactivityWindow (Optional) An integer between 7 and 100 to indicate the number of days to wait before automatically suspending extract refresh tasks for inactive workbooks. The default is 30.

Any combination of the attributes inside the <site> element is valid. Only the attributes that are included are updated for the site. If no attributes are present, no update occurs. To update only the logo, include an empty <site> element (<site />) and the logo in the multipart message.

Starting in version 2.3 of the REST API, you can call Update Site to upload a custom logo image for the site. (For information about custom logos, see Custom the Name or Logo(Link opens in a new window) in the Tableau Server Help.)

To upload a logo image, you include the image in a multipart message; this is similar to how you publish a workbook or data source. You must include the following headers in the request:

  • MIME-Version: 1.0

  • Content-Type: multipart/mixed; boundary=boundary-string

  • X-Tableau-auth: authentication-token

The following example shows the request body for a Update Site request that updates the site with a new logo. For this example, the boundary string has been set in the header to 6691a87289ac461bab2c945741f136e6. The <site> element can be empty if you are calling Update Site only to update the logo image.

--6691a87289ac461bab2c945741f136e6 Content-Disposition: name="request_payload" Content-Type: text/xml  <tsRequest>   <site site attributes >   </site> </tsRequest> --6691a87289ac461bab2c945741f136e6 Content-Disposition: name="site_logo"; filename="MySiteLogo.png" Content-Type: application/octet-stream logo stream here --6691a87289ac461bab2c945741f136e6--
        

To clear a custom logo image and revert to using the default logo for the site, call Update Site with a multipart message, but leave the portion of the request body blank where you would normally include the logo stream.

For more information about creating multipart messages, see Publishing Resources.

Permissions

Tableau Server: This method can only be called by server administrators.

Tableau Online: This method can only be called by site administrators.

Response Code

200

Response Body

<tsResponse>
  <site id="site-id"
	name="site-name"
	contentUrl="content-url"
	adminMode="admin-mode"
	storageQuota="limit-in-megabytes"
	disableSubscriptions="true-or-false"
	state="active-or-suspended"
	revisionHistoryEnabled="true-or-false"
	revisionLimit="revision-limit"
	allowSubscriptionAttachments="allow-subcription-attachments-flag"
	cacheWarmupEnabled="cache-warmup-enabled-flag"
	commentingEnabled="commenting-enabled-flag"
    editingFlowsEnabled="editing-flows-enabled-flag"
    schedulingFlowsEnabled="scheduling-flows-enabled-flag"
	catalogingEnabled="cataloging-enabled-flag"
	derivedPermissionsEnabled="derived-permissions-enabled-flag"
	requestAccessEnabled= "request-access-enabled-flag"
	runNowEnabled="run-now-enabled-flag"
	userQuota="all-license-limit-total"
	tierCreatorCapacity="creator-license-limit"
	tierExplorerCapacity="explorer-license-limit"
	tierViewerCapacity="viewer-license-limit"
	askDataMode="ask-data-enablement"
	useDefaultTimeZone="default-time-zone-flag"
	timeZone="time-zone"
    autoSuspendRefreshEnabled="auto-suspend-refresh-enabled-flag"
    autoSuspendRefreshInactivityWindow="auto-suspend-refresh-inactivity-window" />
  </site>
</tsResponse>
        

Response Body Details:

  • userQuota, storageQuota, and tiered capacity (tierCreatorCapacity, tierExplorerCapacity, tierViewerCapacity) attributes are only present in the response body if those quotas have been set for the site being queried.

Version

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

Errors

HTTP status error Code Condition Details
400 400008 Invalid revision history limit The value for the revision history limit is not an integer.
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400004 Invalid administrator mode An administrator mode parameter was provided in the request with an invalid value. The valid values are ContentOnly and ContentAndUsers.
400 400004 Invalid state A state parameter was provided in the request with an invalid value
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 PUT.
409 409001 Site name conflict The new site name in the request already belongs to an existing site.
409 409002 Site URL conflict The new content URL in the request already belongs to an existing site.
409 409004 User quota and tiered capacity conflict The request cannot set both tiered capacity attributes and userQuota. One or the other must be null.
409 409004 License limit exceeded The request cannot set tiered capacity attributes or userQuota values that are larger than the number of active licenses configured for the site.
409 409004 Administrator mode or user quota conflict The request cannot set adminMode to ContentOnly and also specify a userQuota value.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.12/sites/9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @update-site.xml

Content of update-site.xml:

<tsRequest>
  <site
	adminMode="ContentOnly"
	storageQuota="1000"
	tierCreatorCapacity="2"
	tierExplorerCapacity="1"
	tierViewerCapacity="1"
	useDefaultTimeZone="false"
	timeZone="America/Los_Angeles" />
</tsRequest>
      

Example response:

<tsResponse<
  <site id="9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
	name="Default"
	contentUrl="svc_licensingtest"
	adminMode="ContentAndUsers"
	disableSubscriptions="false"
	state="Active"
	revisionHistoryEnabled="true"
	revisionLimit="25"
	subscribeOthersEnabled="true"
	allowSubscriptionAttachments="true"
	guestAccessEnabled="false"
	cacheWarmupEnabled="true"
	commentingEnabled="true"
    editingFlowsEnabled="false"
    schedulingFlowsEnabled="false"
	extractEncryptionMode="disabled"
	catalogingEnabled="true"
	derivedPermissionsEnabled="true"
	askDataMode="EnabledByDefault"
	useDefaultTimeZone="false"
	timeZone="America/Los_Angeles"
</tsResponse>
      


Thanks for your feedback!