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 Online 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.13. 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.13. 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"
      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"
      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.13. 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.13/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.13. 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 Online.

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.13. 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.13/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!