Server Methods

Using the server method of the Tableau Server REST API you can:

Get the current version of Tableau Server and REST API.
Get the details of the current Tableau Server session.
Delete a specified server session.
List the Active Directory domains in use by a server.
Change the domain name and nickname of a specified Active Directory domain in use by a server.

Delete Server Session

Deletes a specified session. This method is not available for Tableau Cloud and is typically used in programmatic management of the life cycles of embedded Tableau sessions.

URI

DELETE api/api-version/sessions/session-id

Parameter Values

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

session-id

The unique ID of the session to be deleted. A session's ID and other metadata can be queried from the Tableau Server Postgres repository.

Reading the Postgres repository excessively can impact performance and that writing directly to the repository is not supported in any form. For more information, see Collect Data with the Tableau Server Repository and Tableau Server Postgres Data Dictionary.

Request Body

None.

Permissions

This method can only be called by server administrators.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400105	Session delete error	An unknown error occurred and the session could not be deleted.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404029	Content not found	The requested asset could not be found.

Get Current Server Session

Returns details of the current session of Tableau Server.

URI

GET /api/api-version/sessions/current

Parameter Values

api-version

The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.

Request Body

None

Permissions

This method can be called by all authenticated users.

Response Code

200

Response Body

<tsResponse">
  <session>
	<site id="a946d998-2ead-4894-bb50-1054a91dcab3"
  	  name="site-name"
	  contentUrl=""
      adminMode="admin-mode"
      disableSubscriptions="disable-subscription-flag"
      state="state"
      revisionHistoryEnabled="revision-history-enabled-flag"
	  subscribeOthersEnabled="subscribe-others-enabled-flag"
	  guestAccessEnabled="guest-access-enabled-flag"
	  cacheWarmupEnabled="cache-warmup-enabled-flag [REMOVED IN API 3.19]"
	  editingFlowsEnabled="editing-flows-enabled-flag"
      schedulingFlowsEnabled="scheduling-flows-enabled-flag"
	  extractEncryptionMode="extract-encryption-mode"
	  mobileBiometricsEnabled="mobile-biometrics-enabled-flag"
	  sheetImageEnabled="sheetimage-enabled-flag"
	  catalogingEnabled="catalog-enabled-flag"
	  derivedPermissionsEnabled="true"/>
    <user authSetting="ServerDefault"
	  externalAuthUserId=""
	  id="cdfe8548-84c8-418e-9b33-2c0728b2398a"
	  lastLogin="2020-04-29T04:59:08Z"
	  name="workgroupuser"
	  siteRole="ServerAdministrator"/>
 </session>
</tsResponse>

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

Version

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

Errors

HTTP status	`error` Code	Condition	Details
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example Response

<tsResponse">
  <session>
    <site id="a946d998-2ead-4894-bb50-1054a91dcab3"
	  name="Default"
	  contentUrl="" adminMode="ContentAndUsers"
	  disableSubscriptions="false"
	  state="Active"
	  revisionHistoryEnabled="true"
	  subscribeOthersEnabled="true"
	  guestAccessEnabled="false"
	  cacheWarmupEnabled="true" [REMOVED IN API 3.19]
      editingFlowsEnabled="false"
      schedulingFlowsEnabled="false"
	  extractEncryptionMode="enabled"
	  mobileBiometricsEnabled="false"
	  sheetImageEnabled="true"
	  catalogingEnabled="true"
	  derivedPermissionsEnabled="true"/>
    <user authSetting="ServerDefault"
	  externalAuthUserId=""
	  id="cdfe8548-84c8-418e-9b33-2c0728b2398a"
	  lastLogin="2020-04-29T04:59:08Z"
	  name="workgroupuser"
	  siteRole="ServerAdministrator"/>
  </session>
</tsResponse>

List Server Active Directory Domains

Returns the details of the Active Directory domains that are in use on the server, including their full domain names, nicknames and IDs. If the server is configured to use local authentication, the command returns only the domain name local.

URI

GET /api/api-version/domains/

Parameter Values

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

Request Body

None

Permissions

This method can only be called by server administrators.

Response Code

200

Response Body

<tsRequest>
  <domainList>
    <domain id="domain-id-int"
  	  name="domain-name"
	  shortName="domain-nickname" />
  </domainList>
</tsRequest>

Version

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

Errors

HTTP status	`error` Code	Condition	Details
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example

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

Example response body:

<tsRequest>
  <domainList>
    <domain id="1045" name="domain.com" shortName="myDomainNickName" />
    < . . . more domains . . . />
  </domainList>
</tsRequest>

Server Info

Returns the version of Tableau Server and the supported version of the REST API.

URI

GET /api/api-version/serverinfo

Parameter Values

api-version

The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.

Request Body

None

Permissions

This method can be called by all users and does not require authentication.

Response Code

200

Response Body

<tsResponse>
    <serverInfo>
        <productVersion build="build-number">product-version</productVersion>
        <restApiVersion>api-version</restApiVersion>
    </serverInfo>
</tsResponse>

The response contains the following information:

build-number. The build number of your installation of Tableau Server.
product-version. The product version of your installation of Tableau Server.
api-version. The REST API version that is compatible with your version of Tableau Server.

Version

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

Errors

HTTP status	`error` Code	Condition	Details
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Update Server Active Directory Domain

Changes the nickname or full domain name of an Active Directory domain on the server. This method is not available on Tableau Cloud.

A domain nickname, also called short name, is the Windows NetBIOS domain name. You can modify the nickname for any domain the server is using.

In general, you can modify the full domain name for any domain except the one that you used to sign in. However, if the user name that you are currently signed in with exists in both the current domain and the new domain, you can modify the full name for the current domain. For information about how to enable access for users from multiple domains, see Support for multiple domains(Link opens in a new window).

If the domain is local, it's names cannot be changed.

URI

PUT /api/api-version/domains/domain-id

Parameter Values

api-version	The version of the API to use, such as `3.22`. For more information, see REST API and Resource Versions.
domain-id	The integer ID of the of the Active Directory domain being updated. Find a domain's ID using List Server Active Directory Domains.

Request Body

<tsRequest>
  <domain name="new-domain-name"
  shortName="new-domain-nickname" />
</tsRequest>

Attribute Values

Any combination of attributes is valid. If no attributes or nested elements are included, no update is made.

new-domain-name	A new full domain name you are using to replace the existing one.
new-domain-nickname	A new domain nickname you are using to replace the existing one.

Permissions

This method can only be called by server administrators.

Response Code

200

Response Body

Example response:

<tsRequest>
  <domain id="domain-id-int"
    name="domain-name"
    shortName="domain-nickname" />
</tsRequest>

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404032	Resource not found	The requested domain ID in the URI doesn't correspond to an existing domain.

For more information, see Handling Errors.

Example

For an Active Directory with the ID of 1045, name of myOldDomainName, and a nickname of myOldDomainNickname:

curl "http://MY-SERVER/api/3.22/domains/f34ab56cd12ab34cd56ef78ab90cd12ef" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @update-domain.xml

Content of update-domain.xml:

<tsRequest>
  <domain name="myNewDomainName.com"
  shortName="myNewDomainNickName" />
</tsRequest>

Example response body:

<tsRequest>
  <domain id="1045" name="myNewDomainName.com" shortName="myDomainNickName" />
</tsRequest>

Thanks for your feedback!

Your feedback has been successfully submitted. Thank you!

Tableau REST API Help

Server Methods

Delete Server Session

URI

Parameter Values

Request Body

Permissions

Response Code

Response Body

Version

Errors

Get Current Server Session

URI

Parameter Values

Request Body

Permissions

Response Code

Response Body

Version

Errors

Example Response

List Server Active Directory Domains

URI

Parameter Values

Request Body

Permissions

Response Code

Response Body

Version

Errors

Example

Server Info

URI

Parameter Values

Request Body

Permissions

Response Code

Response Body

Version

Errors

Update Server Active Directory Domain

URI

Parameter Values

Request Body

Attribute Values

Permissions

Response Code

Response Body

Version

Errors

Example