This page describes the Tableau Services Manager (TSM) API endpoints (or methods), organized by category.
For more information about how to make requests and for information about request parameters, see Get started.
Async jobs
Get information about asynchronous jobs.
List async jobs
Get a list of TSM jobs, and for each job display information about the status, progress, ID, job type, and more.
GET /asyncJobs
Request query parameters
status
Optional. Only return jobs that match the provided status. Valid statuses include Succeeded, Failed, Created, and Running.
Response status code
200 OK
Response body example
{
"asyncJobs": [{
"progress": 100,
"id": 4,
"status": "Succeeded",
"detailedProgress": {
"progressNotes": [{
"step": "DisableAllServices",
"messageData": [],
"message": "Disabling all services.",
"timestamp": 1497041247968,
"status": "Running"
}, {
"step": "DisableAllServices",
"messageData": [],
"message": "Disabling all services.",
"timestamp": 1497041248035,
"status": "Succeeded"
}, {
"step": "StopAllServices",
"messageData": [],
"message": "Waiting for the services to stop.",
"timestamp": 1497041248040,
"status": "Running"
}, {
"step": "StopAllServices",
"messageData": [],
"message": "Waiting for the services to stop.",
"timestamp": 1497041432154,
"status": "Succeeded"
}],
"doneSteps": 2,
"totalSteps": 2
},
"jobType": "StopServerJob",
"createdAt": 1497041247933,
"updatedAt": 1497041432165,
"statusMessageData": [],
"jobTimeout": 300,
"worker": "node1",
"completedAt": 1497041432165,
"statusMessage": "This job completed successfully."
}, {
"..."
}]
}
Get async job by job ID
Get the state of a previously started job.
GET /asyncJobs/<jobId>
Request path parameters
jobId
The ID of the asychronous job. To view a list of jobs and job IDs, see List async jobs.
Response status code
200 OK
Response body example
{
"asyncJob": {
"progress": 100,
"id": 4,
"status": "Succeeded",
"detailedProgress": {
"progressNotes": [
{
"step": "DisableAllServices",
"messageData": [],
"message": "Disabling all services.",
"timestamp": 1497041247968,
"status": "Running"
},
{
"step": "DisableAllServices",
"messageData": [],
"message": "Disabling all services.",
"timestamp": 1497041248035,
"status": "Succeeded"
},
{
"step": "StopAllServices",
"messageData": [],
"message": "Waiting for the services to stop.",
"timestamp": 1497041248040,
"status": "Running"
},
{
"step": "StopAllServices",
"messageData": [],
"message": "Waiting for the services to stop.",
"timestamp": 1497041432154,
"status": "Succeeded"
}
],
"doneSteps": 2,
"totalSteps": 2
},
"jobType": "StopServerJob",
"createdAt": 1497041247933,
"updatedAt": 1497041432165,
"statusMessageData": [],
"jobTimeout": 300,
"worker": "node1",
"completedAt": 1497041432165,
"statusMessage": "This job completed successfully."
}
}
Get latest async job
Get the status of the latest added asynchronous job, across all job types.
GET /asyncJobs/latest
Response status code
200 OK
Response body example
{
"asyncJob": {
"progress": 100,
"id": 23,
"status": "Succeeded",
"detailedProgress": {
"progressNotes": [
{
"step": "ConfigureServices",
"messageData": [],
"message": "Reconfiguring services.",
"timestamp": 1505842758105,
"status": "Running"
},
{
"step": "ConfigureServices",
"messageData": [],
"message": "Reconfiguring services.",
"timestamp": 1505842758126,
"status": "Succeeded"
},
{
"step": "WaitForConfigureAndStart",
"messageData": [],
"message": "Waiting for services to reconfigure and start.",
"timestamp": 1505842758137,
"status": "Running"
},
{
"step": "WaitForConfigureAndStart",
"messageData": [],
"message": "Waiting for services to reconfigure and start.",
"timestamp": 1505843134048,
"status": "Succeeded"
}
],
"doneSteps": 2,
"totalSteps": 2
},
"jobType": "ReconfigureJob",
"createdAt": 1505842758085,
"updatedAt": 1505843134060,
"statusMessageData": [],
"jobTimeout": 420,
"worker": "node1",
"completedAt": 1505843134060,
"statusMessage": "This job completed successfully."
}
}
Get latest async job by type
Get the state of the last async job that started that matches the specified job type. See
/asyncJobs/latest/<jobType>
Request path parameters
jobType
Required. The type of job. To view a list of available job types, see List async jobs.
Response status code
200 OK
Response body example
{
"asyncJob": {
"progress": 100,
"id": 19,
"status": "Succeeded",
"detailedProgress": {
"progressNotes": [
{
"step": "DisableAllServices",
"messageData": [],
"message": "Disabling all services.",
"timestamp": 1505245656514,
"status": "Running"
},
{
"step": "DisableAllServices",
"messageData": [],
"message": "Disabling all services.",
"timestamp": 1505245658760,
"status": "Succeeded"
},
{
"step": "StopAllServices",
"messageData": [],
"message": "Waiting for the services to stop.",
"timestamp": 1505245658764,
"status": "Running"
},
{
"step": "StopAllServices",
"messageData": [],
"message": "Waiting for the services to stop.",
"timestamp": 1505245691691,
"status": "Succeeded"
},
{
"step": "EnableAllServices",
"messageData": [],
"message": "Enabling all services.",
"timestamp": 1505245691698,
"status": "Running"
},
{
"step": "EnableAllServices",
"messageData": [],
"message": "Enabling all services.",
"timestamp": 1505245693213,
"status": "Succeeded"
},
{
"step": "StartAllServices",
"messageData": [],
"message": "Waiting for the services to start.",
"timestamp": 1505245693220,
"status": "Running"
},
{
"step": "StartAllServices",
"messageData": [],
"message": "Waiting for the services to start.",
"timestamp": 1505245853011,
"status": "Succeeded"
}
],
"doneSteps": 4,
"totalSteps": 4
},
"jobType": "RestartServerJob",
"createdAt": 1505245656450,
"updatedAt": 1505245853073,
"statusMessageData": [],
"jobTimeout": 1800,
"worker": "node1",
"completedAt": 1505245853073,
"statusMessage": "This job completed successfully."
}
}
Cancel an async job
Cancel an async job that is currently running.
PUT /asyncJob/<jobId>/cancel
Request path parameters
jobId
Required. ID of the async job to cancel. To view a list of available job IDs, see List async jobs.
Response status code
200 OK
Response body example
{
"asyncJob": {
"id": 2,
"args": "{\"withNetstatInfo\":false,\"withPostgresqlData\":false,\"withLatestDump\":false,\"minimumDate\":[2017,6,7],\"node\":\"node1\"}",
"progress": -1,
"status": "Cancelled",
"statusMessageData": [],
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 0
},
"jobType": "ZiplogsJob",
"createdAt": 1497029422819,
"updatedAt": 1497029433156,
"jobTimeout": 1800,
"completedAt": 1497029433156,
"statusMessage": "This job has been cancelled."
}
}
Backup
Create backup files.
Create a backup file
Create a backup and save it to a file in the data directory.
POST /backupFixedFile
Request query parameters
jobTimeoutSeconds
Optional. The timout length in seconds. Default is 1800 seconds.
skipVerification
Optional. Whether to verify the integrity of the database backup.
writepath
Required. The name for the backup file. Backup files are placed in the data directory. By default, you can find backup files in the following location:
/var/opt/tableau/tableau_server/data/tabsvc/files/backups
Response status code
200 OK
Response body example
{
"asyncJob": {
"args": "{\"node\":\"node1\",\"origin\":\"OTHER\",\"overrideDiskSpaceCheck\":false,\"writePath\":\"backupname\",\"skipVerification\":false}",
"progress": -1,
"id": 8,
"status": "Created",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 0
},
"jobType": "GenerateBackupJob",
"createdAt": 1497043142444,
"updatedAt": 1497043142444,
"statusMessageData": [],
"jobTimeout": 86400,
"statusMessage": "This job is queued."
}
}
Bootstrap
Get information about the controller so that you can connect to it.
Get bootstrap information
Get information about the controller, including the controller location and TSM certificate.
GET /bootstrap
Response status code
200 OK
Response body example
{
"initialBootstrapSettings": {
"port": 8850,
"certificate": "<certificate>",
"clusterId": "tabsvc-clusterid",
"nodeId": "<nodeId>",
"configurationName": "tabsvc",
"machineAddress": "<serverAddress>",
"cryptoEnabled": true,
"cryptoKeyStore": "<keyStore>"
}
}
Configuration
Get information about server configurations, compare configurations, request configuration changes, and apply configuration changes. Server configurations can be viewed and changed in one of two ways:
- Keys. Tableau Server uses key:value pairs to monitor and manage the server configuration. For a list of configuration keys (or “options”), see tsm configuration set Options.
- Entities. Entities provide a structured, strongly-typed way to monitor and update server configuration. For a list of entities, see Entity Definitions and Templates.
List configurations
Get information about the configuration versions available.
GET /configurations
Response status code
200 OK
Response body example
Note: In the following response body example, the values that follow "name" (for example, 1,
2) are used in other /configurations endpoints for the
{
"links": {
"items": [{
"name": "1",
"href": "/api/0.5/configurations/1"
}, {
"name": "2",
"href": "/api/0.5/configurations/2"
}, {
"name": "0",
"href": "/api/0.5/configurations/0"
}, {
"name": "requested",
"href": "/api/0.5/configurations/requested"
}, {
"name": "pending",
"href": "/api/0.5/configurations/pending"
}]
}
}
Get all keys for a configuration version
Get the complete server configuration, including all keys and values, for a specific configuration version.
GET /configurations/<config-version>/keys
Request path parameters
config-version
Required. The configuration version.
Response status code
200 OK
Response body example
The response body shows all keys for the configuration version. Because this response body is thousands of lines, it is not provided here.
Get a key and value for a configuration version
Get a key and the corresponding value for a specified configuration version.
GET /configurations/<config-version>/keys/<keyId>
Request path parameters
config-version
Required. The configuration version.
keyId
Required. The key to retrieve from the specified configuration version.
Response status code
200 OK
Response body example
{
"configKeys": {
"backgrounder.querylimit": 7200
}
}
Get all entities for a configuration version
Get the complete server configuration, represented as a set of entities, for a specific configuration version.
GET /configurations/<config-version>/entities
Request path parameters
config-version
Required. The configuration version.
Response status code
200 OK
Response body example
{
"links": {
"items": [
{
"name": "bootstrap",
"href": "/api/0.5/configurations/7/entities/bootstrap"
},
{
"name": "crashReporterSettings",
"href": "/api/0.5/configurations/7/entities/crashReporterSettings"
},
{
"name": "customization",
"href": "/api/0.5/configurations/7/entities/customization"
},
{
"name": "gatewaySettings",
"href": "/api/0.5/configurations/7/entities/gatewaySettings"
},
{
"name": "identityStore",
"href": "/api/0.5/configurations/7/entities/identityStore"
},
{
"name": "kerberosSettings",
"href": "/api/0.5/configurations/7/entities/kerberosSettings"
},
{
"name": "mutualSSLSettings",
"href": "/api/0.5/configurations/7/entities/mutualSSLSettings"
},
{
"name": "nonAdminUsernamePasswordSettings",
"href": "/api/0.5/configurations/7/entities/nonAdminUsernamePasswordSettings"
},
{
"name": "openIDSettings",
"href": "/api/0.5/configurations/7/entities/openIDSettings"
},
{
"name": "repositorySSL",
"href": "/api/0.5/configurations/7/entities/repositorySSL"
},
{
"name": "runAsUser",
"href": "/api/0.5/configurations/7/entities/runAsUser"
},
{
"name": "samlSettings",
"href": "/api/0.5/configurations/7/entities/samlSettings"
},
{
"name": "sapHanaSettings",
"href": "/api/0.5/configurations/7/entities/sapHanaSettings"
},
{
"name": "sspiSettings",
"href": "/api/0.5/configurations/7/entities/sspiSettings"
},
{
"name": "trustedAuthenticationSettings",
"href": "/api/0.5/configurations/7/entities/trustedAuthenticationSettings"
}
]
}
}
Get an entity for a configuration version
Get the details for a specific entity for a specific configuration version.
GET /configurations/<config-version>/entities/<entityId>
Request path parameters
config-version
Required. The configuration version.
entityId
Required. The unique string identifier (for example, gatewaySettings) for the entity.
Response status code
200 OK
Response body example
{
"configEntity": {
"_type": "gatewaySettingsType",
"port": 80,
"sslPort": 443,
"firewallOpeningEnabled": true,
"publicHost": "localhost",
"publicPort": 80,
"sslEnabled": false,
"sslRedirectEnabled": true,
"trustedIPs": [],
"trustedHosts": []
}
}
Get the difference between two configuration versions by keys
Gets the difference between one server configuration version and another, showing any keys and values that changed between those configuration versions.
GET /configurations/<from-config-version>/keys/diff/<to-config-version>
Request path parameters
from-config-version
Required. The first configuration that is used for comparison.
to-config-version
Required. The second configuration that is used for comparison.
Response status code
200 OK
Response body example
{
"configKeys": {
"config.timestamp": "2017-09-11T23:40:11.113",
"gateway.public.host": "localhost",
"gateway.trusted": "",
"gateway.trusted_hosts": ""
}
}
Get the difference between two configuration versions by entities
Gets the difference between one server configuration version and another, showing any entities that changed between those configuration versions.
GET /configurations/<from-config-version>/entities/diff/<to-config-version>
Request path parameters
from-config-version
Required. The first configuration that is used for comparison.
to-config-version
Required. The second configuration that is used for comparison.
Response status code
200 OK
Response body example
{
"configEntities": {
"gatewaySettings": {
"_type": "gatewaySettingsType",
"publicHost": "localhost",
"trustedIPs": [],
"trustedHosts": []
}
}
}
Get the most recent configuration version number
Gets the version number of the most recent server configuration.
GET /configurations/requested/version
Response status code
200 OK
Response body example
{
"version": "17"
}
Update configuration keys in the pending configuration
Updates the values associated with one or more configuration keys in the pending configuration.
To make the pending configuration take effect, you must call
POST /configurations/pending/promote.
PATCH /configurations/pending/keys
Request body example
{
"configKeys": {
"licensing.tries": 6
}
}
Response status code
204 No Content
Update an entity in the pending configuration
Update a configuration entity in the pending configuration. To make the pending configuration take
effect, you must call
POST /configurations/pending/promote.
PUT /configurations/pending/entities/<entityName>
Request path parameters
entityName
Required. The name of the entity that will be updated. For a list of entity names, call
GET /configurations/<config-version>/entities.
For example, you could use this parameter to update the gatewaySettings entity.
Request body example
The request body consists of the same JSON elements returned by
GET /configurations/<config-version>/entities/<entityName>
for the specified configuration entity.
{
"configEntity": {
"_type": "gatewaySettingsType",
"port": 80,
"firewallOpeningEnabled": true,
"publicHost": "localhost",
"publicPort": 80,
"sslEnabled": false,
"sslRedirectEnabled": true,
"trustedIPs": [],
"trustedHosts": [],
"sslPort": 443
}
}
Response status code
204 No Content
Update Tableau Server with the pending configuration
Updates Tableau Server with the pending configuration. The response body provides the latest configuration version number.
POST /configurations/pending/promote
Response status code
200 OK
Response body example
{
"version": "19"
}
Delete a configuration version
Deletes the specified configuration version. Subsequent configuration version numbers will remain
unchanged, resulting in gaps in the configuration version sequence. So if you delete configuration
version 9, configuration version 10 retains the same version number that it did previous to
using this endpoint. This command takes effect immediately and does not restart Tableau Server.
DELETE /configurations/<config-version>
Request path parameters
config-version
Required. The configuration version to delete.
Response status code
200 OK
Delete a key from the pending configuration
Deletes the specified key from the pending configuration. To make the pending configuration take
effect, call
POST /configurations/pending/promote.
DELETE /configurations/pending/keys/<keyId>
Request path parameters
keyId
Required. The name or ID of the key to be deleted.
Response status code
200 OK
Delete an entity from the pending configuration
Deletes the contents of the specified entity from the pending configuration. To make the pending
configuration take effect, call
POST /configurations/pending/promote.
DELETE /configurations/pending/entities/<entityId>
Request path parameters
entityId
Required. The name or ID of the entity that will have its contents deleted.
Response status code
200 OK
Coordination Service
These endpoints are used to manage the Tableau Coordination Service, which is built on the open-source Apache Zookeeper project. To learn more about the Coordination Service, see Deploy a Coordination Service Ensemble.
Cleanup Coordination Service
Deletes the previously-used coordination service ensemble. Tableau Server cannot be running when you use this command, so you must call POST /disable before running this command.
POST /cleanupzk
Response status code
200 OK
Response body example
{
"asyncJob": {
"progress": 0,
"id": 36,
"status": "Running",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 1
},
"jobType": "CleanupZooKeeperJob",
"createdAt": 1506727631431,
"updatedAt": 1506727631445,
"statusMessageData": [],
"jobTimeout": 1200,
"worker": "node1",
"statusMessage": "This job is currently running."
}
}
Switch Coordination Service ensembles
Switches Tableau Server to the new Coordination Service ensemble. Tableau Server cannot be running when you use this command, so you must call POST /disable before running this command.
POST /togglezk
Response status code
200 OK
Response body example
{
"asyncJob": {
"progress": -1,
"id": 28,
"status": "Created",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 0
},
"jobType": "CleanupZooKeeperJob",
"createdAt": 1506724940676,
"updatedAt": 1506724940676,
"statusMessageData": [],
"jobTimeout": 1200,
"statusMessage": "This job is queued."
}
}
Deploy Coordination Service ensemble to server cluster nodes
Deploys the Coordination Service ensemble to one or more cluster nodes. Tableau Server cannot be running when you use this command, so you must call POST /disable before running this command.
POST /reconfigzk
Request query parameters
nodes
Optional. A comma-separated list of node names that designates which nodes the Coordination Service ensemble should be deployed to.
For example, you might enter nodes=node2.
Response status code
200 OK
Enable
Enable Tableau Server services.
Enable services
Enable all Tableau Server services. (This starts Tableau Server.)
POST /enable
Response status code
200 OK
Response body example
{
"asyncJob": {
"progress": -1,
"id": 5,
"status": "Created",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 0
},
"jobType": "StartServerJob",
"createdAt": 1497041247933,
"updatedAt": 1497041247933,
"statusMessageData": [],
"jobTimeout": 480,
"statusMessage": "This job is queued."
}
}
Disable
Disable Tableau Server services.
Disable services
Disable all Tableau Server services. This stops Tableau Server until you call the Enable services endpoint.
POST /disable
Response status code
200 OK
Response body example
{
"asyncJob": {
"progress": -1,
"id": 4,
"status": "Created",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 0
},
"jobType": "StopServerJob",
"createdAt": 1497041247933,
"updatedAt": 1497041247933,
"statusMessageData": [],
"jobTimeout": 300,
"statusMessage": "This job is queued."
}
}
Restart
Restart Tableau Server services.
Restart services
Restart all Tableau Server services. This causes Tableau Server downtime while all services restart.
POST /restart
Response status code
200 OK
Response body example
{
"asyncJob": {
"progress": 0,
"id": 26,
"status": "Running",
"detailedProgress": {
"progressNotes": [
{
"step": "DisableAllServices",
"messageData": [],
"message": "Disabling all services.",
"timestamp": 1506724565632,
"status": "Running"
}
],
"doneSteps": 0,
"totalSteps": 4
},
"jobType": "RestartServerJob",
"createdAt": 1506724565614,
"updatedAt": 1506724565632,
"statusMessageData": [],
"jobTimeout": 600,
"worker": "node1",
"statusMessage": "This job is currently running."
}
}
Initialize
Initialize Tableau Server.
Initialize Tableau Server
Initializes Tableau Server after any pending changes to the configuration have been applied by
calling
POST /configurations/pending/promote.
POST /initialize
Request query parameters
configurationVersion
Optional. Specifies a specific version of the server configuration that should be used to initialize Tableau Server.
force
Optional. If set to true, override an error if Tableau Server has already been initialized.
jobTimeoutSeconds
Optional. Overrides the default timeout with the number of seconds provided.
startServer
Optional. If set to true, start Tableau Server after initializing.
Response status code
200 OK
Response body example
{
"asyncJob": {
"args": "{\"startServer\":true}",
"progress": 0,
"id": 42,
"status": "Running",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 25
},
"jobType": "InitializeServerJob",
"createdAt": 1506737181826,
"updatedAt": 1506737181845,
"statusMessageData": [],
"jobTimeout": 1620,
"worker": "node1",
"statusMessage": "This job is currently running."
}
}
File store
Make the file store writeable or write-only in preparation for node and process changes.
Decommission the file store
Set the file store to read-only.
POST /filestore/decommission
Request query parameters
nodes
Optional. A comma-separated list of node names that designates which nodes have file stores to decommission. If the nodes are not specified, TSM compares the staged topology to the live topology to determine which nodes are trying to remove the file store, and then adds those nodes to the decommission list.
For example, you might enter nodes=node1.
Response status code
200 OK
Response body example
{
"asyncJob": {
"args": "{\"hostnameList\":[\"node1\"],\"noFailureOnHAWarnings\":false}",
"progress": -1,
"id": 11,
"status": "Created",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 6
},
"jobType": "DecommissionFilestoreJob",
"createdAt": 1497058498658,
"updatedAt": 1497058498664,
"statusMessageData": [],
"jobTimeout": 300,
"statusMessage": "This job is queued."
}
}
Recommission the file store
Make the file store writeable.
/filestore/recommission
Request query parameters
nodes
Required. A comma-separated list of node names that designates which nodes have file stores to decommission.
For example, you might enter nodes=node1.
Response status code
204 No Content
Licensing
Activate product trial license
Activate a limited-time product trial license.
POST /licensing/activateTrial
Response status code
204 No Content
Activate product key
Activate a product key.
POST /licensing/productKeys/<serial>
Request path parameters
key
The product key to activate.
Response status code
201 Created
Response body example
{
"productKeys": {
"items": [
{
"valid": true,
"expiration": "2017-11-01T12:00:00.158Z",
"maintenance": "2017-11-01T12:00:00.157Z",
"guestAllowed": true,
"serial": "<serial>"
}
]
}
}
Refresh all product keys
Refreshes all product keys. To learn more about refreshing product keys, see Refresh Maintenance Date for the Product Key.
POST /licensing/resync
Response status code
204 No Content
Get licensing information
Get a list of API endpoints related to licensing that are relevant to the current Tableau Server installation.
GET /licensing
Response status code
200 OK
Response body example
{
"links": {
"items": [
{
"name": "collection",
"href": "/api/0.5/licensing/productKeys"
},
{
"name": "item",
"href": "/api/0.5/licensing/productKeys/{serial}"
},
{
"name": "related",
"href": "/api/0.5/licensing/resync"
},
{
"name": "related",
"href": "/api/0.5/licensing/activateTrial"
},
{
"name": "related",
"href": "/api/0.5/licensing/registration"
}
]
}
}
List product keys
List the product keys that have been activated.
GET /licensing/productKeys
Response status code
200 OK
Response body example
{
"productKeys": {
"items": [
{
"expiration": "2017-11-01T12:00:00.000Z",
"valid": true,
"numCores": 16,
"serial": "example-serial-number-here",
"maintenance": "2017-11-01T12:00:00.000Z",
"guestAllowed": true
}
]
}
}
Get product key details
Get information about a product key that has been activated.
GET /licensing/productKeys/<serial>
Request path parameters
serial
Required. The product key serial number.
Response status code
200 OK
Response body example
{
"productKeys": {
"items": [
{
"expiration": "2017-11-01T12:00:00.000Z",
"valid": true,
"numCores": 16,
"serial": "example-serial-number-here",
"maintenance": "2017-11-01T12:00:00.000Z",
"guestAllowed": true
}
]
}
}
Delete a product key
Delete the specified product keys.
DELETE /licensing/productKeys/<serial>
Request path parameters
serial
Required. The product key serial number.
Response status code
204 No Content
Get registration information
Get information on product registration.
GET /licensing/registration
Response status code
200 OK
Response body example
This method returns the following response body if registration has already occurred:
{
"registration": {
"fields": [],
"needToRegister": false
}
}
This method returns the following response body if registration is still required. This response body provides a template that you can complete and pass to POST /licensing/registration to complete registration.
{
"registration": {
"fields": [
{
"key": "first_name",
"value": ""
},
{
"key": "last_name",
"value": ""
},
{
"key": "email",
"value": ""
},
{
"key": "company",
"value": ""
},
{
"key": "title",
"value": ""
},
{
"key": "department",
"value": ""
},
{
"key": "industry",
"value": ""
},
{
"key": "phone",
"value": ""
},
{
"key": "city",
"value": ""
},
{
"key": "state",
"value": ""
},
{
"key": "zip",
"value": ""
},
{
"key": "country",
"value": ""
}
],
"type": "STANDARD",
"needToRegister": true
}
}
Register Tableau Server
Register Tableau Server, providing information that includes the name, company and contact information of the user who is registering the product.
POST /licensing/registration
Request body example
{
"registration": {
"fields": [
{
"key": "first_name",
"value": "Mary"
},
{
"key": "last_name",
"value": "Smith"
},
{
"key": "email",
"value": "marysmith@examplecompany.com"
},
{
"key": "company",
"value": "The Example Company"
},
{
"key": "title",
"value": "CEO"
},
{
"key": "department",
"value": "Executive"
},
{
"key": "industry",
"value": "Internet"
},
{
"key": "phone",
"value": "5555555555"
},
{
"key": "city",
"value": "Anytown"
},
{
"key": "state",
"value": "WA"
},
{
"key": "zip",
"value": "98033"
},
{
"key": "country",
"value": "USA"
}
],
"type": "STANDARD",
"needToRegister": true
}
}
Response status code
204 No Content
Get offline activation XML from product key
Get XML that you can use for offline activation. To learn more about offline activation, see Install Tableau Server in a Disconnected (Air-Gapped) Environment.
GET /licensing/offline/activationRequest/<productKey>
Response status code
204 No Content
Response body example
<?xml version="1.0" encoding="UTF-8" ?>
<Request xmlns="http://www.macrovision.com/fnp/2004/11/activation">
<RequestHeader>
<VersionNumber>3</VersionNumber>
<RequestType>ACTIVATION</RequestType>
</RequestHeader>
<RequestData>
<EntitlementData>
<EntitlementId>SOME-PRODU-CTKE-YHERE</EntitlementId>
<ActivationReason>0</ActivationReason>
<ProductId>Not Applicable</ProductId>
<PublisherId>4073728</PublisherId>
</EntitlementData>
<OriginData>
<ClientVersion>11.14.1</ClientVersion>
<ConfigData>
<IsServer>1</IsServer>
<TrustedHostInformation>
<TrustedId>1</TrustedId>
<Revision>1212466702754</Revision>
<RevisionType>SRV</RevisionType>
<MachineIdentifier>A05A4257F9F138A9FF9176A980F9DECE7AC86A68</MachineIdentifier>
<Status>OK</Status>
</TrustedHostInformation>
</ConfigData>
<Platform>
<PlatformTypeName>x64_lsb</PlatformTypeName>
<OperatingSystem>
<Info>none</Info>
</OperatingSystem>
</Platform>
<UniqueMachineNumbers>
<UniqueMachineNumber>
<Type>1</Type>
<Value></Value>
</UniqueMachineNumber>
<UniqueMachineNumber>
<Type>2</Type>
<Value>F0D038624F02B5B00D7436D390EBE11CEF84BB61</Value>
</UniqueMachineNumber>
<UniqueMachineNumber>
<Type>4</Type>
<Value></Value>
</UniqueMachineNumber>
</UniqueMachineNumbers>
<SequenceNumber>3</SequenceNumber>
</OriginData>
<PublisherDictionary>
<Entries>
<Entry>
<Key>flexFulfillmentVersion</Key>
<Value>1</Value>
</Entry>
<Entry>
<Key>pubExpiry</Key>
<Value>31-dec-2029</Value>
</Entry>
<Entry>
<Key>pubAct</Key>
<Value>0</Value>
</Entry>
<Entry>
<Key>pubActOd</Key>
<Value>0</Value>
</Entry>
<Entry>
<Key>pubConc</Key>
<Value>1</Value>
</Entry>
<Entry>
<Key>pubConcOd</Key>
<Value>0</Value>
</Entry>
<Entry>
<Key>pubHyb</Key>
<Value>0</Value>
</Entry>
<Entry>
<Key>pubHybOd</Key>
<Value>0</Value>
</Entry>
<Entry>
<Key>pubRepairCount</Key>
<Value>0</Value>
</Entry>
</Entries>
</PublisherDictionary>
<VendorDictionary>
<Entries>
<Entry>
<Key>OFFLINE</Key>
<Value>true</Value>
</Entry>
</Entries>
</VendorDictionary>
</RequestData>
<Hash>12345678910112</Hash>
<HashVersion>1</HashVersion>
</Request>
Activate offline
Activate Tableau Server in an offline (air-gapped) environment, passing the
contents of the activation.tlf file provided by the
Tableau Offline Activation
website as the request body.
To learn more about offline activation, see Install Tableau Server in a Disconnected (Air-Gapped) Environment.
POST /licensing/offline/activationRequest
Note: The POST request must use the multipart form-data type and must pass the activation.tlf
file as the value for the file key.
Request body example
<?xml version="1.0" encoding="UTF-8" ?><Request xmlns="http://www.macrovision.com/fnp/2004/11/activation"><RequestHeader><VersionNumber>3</VersionNumber><RequestType>ACTIVATION</RequestType></RequestHeader><RequestData><EntitlementData>
<EntitlementId>XXXX-XXXX-XXXX-XXXX-XXXX</EntitlementId>
<ActivationReason>0</ActivationReason>
<ProductId>Not Applicable</ProductId><PublisherId>4073728</PublisherId>
</EntitlementData><OriginData><ClientVersion>XX.XX.X</ClientVersion><ConfigData><IsServer>1</IsServer></ConfigData>
<Platform>
<PlatformTypeName>x64_lsb</PlatformTypeName>
<OperatingSystem><Info>none</Info></OperatingSystem>
</Platform>
<UniqueMachineNumbers>
<UniqueMachineNumber><Type>1</Type><Value>XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</Value></UniqueMachineNumber>
<UniqueMachineNumber><Type>2</Type><Value>XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</Value></UniqueMachineNumber>
<UniqueMachineNumber><Type>4</Type><Value></Value></UniqueMachineNumber>
</UniqueMachineNumbers>
<SequenceNumber>X</SequenceNumber></OriginData><PublisherDictionary>
<Entries>
<Entry>
<Key>flexFulfillmentVersion</Key>
<Value>1</Value>
</Entry>
<Entry>
<Key>pubExpiry</Key>
<Value>31-dec-2029</Value>
</Entry>
<Entry>
<Key>pubAct</Key>
<Value>0</Value>
</Entry>
<Entry>
<Key>pubActOd</Key>
<Value>0</Value>
</Entry>
<Entry>
<Key>pubConc</Key>
<Value>1</Value>
</Entry>
<Entry>
<Key>pubConcOd</Key>
<Value>0</Value>
</Entry>
<Entry>
<Key>pubHyb</Key>
<Value>0</Value>
</Entry>
<Entry>
<Key>pubHybOd</Key>
<Value>0</Value>
</Entry>
<Entry>
<Key>pubRepairCount</Key>
<Value>0</Value>
</Entry>
</Entries>
</PublisherDictionary><VendorDictionary>
<Entries>
<Entry>
<Key>OFFLINE</Key>
<Value>true</Value>
</Entry>
</Entries>
</VendorDictionary></RequestData><Hash>XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</Hash><HashVersion>1</HashVersion></Request>
Response status code
200 OK
Get offline deactivation file
Get a file (deactivate.tlq) that you can use to deactivate a Tableau Server product key on a server
that is not connected to the internet. To complete product deactivation, You must pass the
deactivate.tlq file to the Tableau Activation website
from a computer with an internet connection, download the return.tlr file, and then pass it to the
POST /licensing/offline/deactivationRequest method.
GET /licensing/offline/deactivationRequest/<product-key>
Request path parameters
product-key
The Tableau Server product key that you are deactivating.
Response status code
200 OK
Response body example
The response body is the contents of the deactivate.tlq file, formatted as XML.
Deactivate offline
Use the return.tlq file to complete offline deactivation of Tableau Server. The return.tlq file
is provided by the Tableau Activation website when you
provide a deactivation file (offline.tlq) generated using the
GET /licensing/offline/deactivationRequest/<product-key>
method.
POST /licensing/offline/deactivationRequest
Request body parameters
The request body must use the multipart form-data type.
file
Required. A return.tlf file.
Response status code
200 OK
Get offline licensing properties
Get properties that pertain to offline licensing of Tableau Server.
GET /licensing/offline/properties
Response status code
200 OK
Response body example
{
"offlineLicensingProperties": {
"trustedStorageInitialized": true,
"finalActivationFileCreated": false,
"initialActivationFileCreated": false,
"deactivationFileCreated": false
}
}
Login
Log in to TSM.
Log in
Log in to TSM and get an authentication cookie that can be used for additional requests.
POST /login
Request body parameters
user_name. The user name of a user that has access to TSM.password. The password of a user that has access to TSM.
Request body example
{
"authentication": {
"name": "<user_name>",
"password":"<password>"
}
}
Response status code
204 No Content
Logout
Log out of TSM.
Log out
Invalidate the authentication cookie for the current session.
POST /logout
Response status code
200
Log out all users
Invalidate the authentication cookies of all sessions.
POST /logout/all
Response status code
200
Nodes
Get information about nodes, add nodes, and remove nodes.
List nodes
List the nodes in the Tableau Server cluster.
GET /nodes
Response status code
200 OK
Response body example
{
"clusterNodes": {
"nodes": [
"node1"
]
}
}
Get node information by node ID
Get information about a node, including the node’s address, configuration
version, topology version, and more. The network addresses returned in the
addresses list are accessible from the initial node, but not necessarily from
other computers on your network, and are not returned in a predetermined order.
GET /nodes/<nodeId>
Request path parameters
nodeId
Required. The node ID. Note that node IDs are distinct from the computer address.
For example, the node ID might be node1.
Response status code
200 OK
Response body example
{
"nodeInfo": {
"address": "localhost",
"status": "NONE",
"roles": [],
"configurationVersion": "2",
"topologyVersion": "3",
"addresses": [
"tableau-server",
"10.10.10.6"
],
"processorCount": 8,
"availableMemory": 15887
}
}
Get topology defaults for a node
Get information about the topology defaults that are used when a new node is created. Topology defaults determine how many instances of each service exist on the nodes in a server topology, and are set according to the number of processors and the memory available on a given node. The response body example shown below shows the node topology defaults for a node with less than 32GB of memory available.
GET /nodes/<nodeId>/defaults/topology
Request path parameters
nodeId
Required. The node ID. Note that node IDs are distinct from the computer address.
For example, the node ID might be node1.
Response status code
200 OK
Response body example
{
"topologyDefaults": {
"serviceDefaults": [
{
"name": "clustercontroller",
"instanceCount": 1
},
{
"name": "backgrounder",
"instanceCount": 1
},
{
"name": "cacheserver",
"instanceCount": 1
},
{
"name": "dataserver",
"instanceCount": 1
},
{
"name": "vizqlserver",
"instanceCount": 2
},
{
"name": "gateway",
"instanceCount": 1
}
]
}
}
New node ID
Get a unique node ID for a new that you want to create. To actually create the node, you must pass the new node ID to to Create a node.
POST /nodes
Response status code
202 Accepted
Response body example
{
"nodeId": "node2"
}
Create a node
Create a node using an ID provided by New Node ID.
POST /nodes/<nodeId>
Request path parameters
nodeId
The node ID generated by Get new node ID.
Request body parameters
serverAddress
Required. The hostname or IP address of the new node.
Request body example
{
"nodeInfo": {
"configurationVersion": "1",
"topologyVersion": "1",
"address": "<serverAddress>",
"addresses": ["<serverAddress>"],
"roles": []
}
}
Response status code
200 OK
Response body example
{
"nodeInfo": {
"roles": [],
"addresses": [
"tableau-server2"
],
"status": "NONE",
"topologyVersion": "1",
"configurationVersion": "1",
"address": "tableau-server2"
}
}
Repository
Get information about the repository and configure fail over.
Get current master repository information
Get information about the node that hosts the master repository.
GET /repository/currentMaster
Response status code
200 OK
Response body example
{
"repositoryNodeInfo": {
"hostName": "localhost",
"port": 8060,
"nodeState": "AVAILABLE"
}
}
Check if a repository is safe to remove
Determine whether a repository can be safely removed.
GET /repository/isSafeToRemove
Request query parameters
host
Required. The hostname of the node with the repository.
For example, you might enter host=localhost.
Response status code
200 OK
Response body example
{
"isRepositorySafeToRemove": false
}
Fail over repository to another PostgreSQL node
Fail over to the specified, preferred, or next available PostgresSQL node. Although all request
query parameters are optional, you must specify a value for either the target parameter or the
preferred parameter.
GET /repository/failover
Request query parameters
jobTimeoutSeconds
Optional. The number of seconds provided before the job times out.
target
Optional. The hostname of the node to fail over to.
For example, you might enter target=localhost.
preferred
Optional. This boolean value can be set to true to fail over to the node specified by the
pgsql.preferred_host configuration key.
Response status code
200 OK
Response body example
{
"asyncJob": {
"args": "{\"target\":\"localhost\",\"isPreferredHostUsed\":false}",
"progress": 0,
"id": 40,
"status": "Running",
"detailedProgress": {
"progressNotes": [
{
"step": "SendFailoverCommand",
"messageData": [],
"message": "Initiating repository failover.",
"timestamp": 1506735366078,
"status": "Running"
}
],
"doneSteps": 0,
"totalSteps": 2
},
"jobType": "RepositoryFailover",
"createdAt": 1506735366056,
"updatedAt": 1506735366078,
"statusMessageData": [],
"jobTimeout": 600,
"worker": "node1",
"statusMessage": "This job is currently running."
}
}
Enable repository access by an external user
Enable access to the repository by an external user, including the built-in tableau user account.
Caution: Calling this endpoint causes an immediate restart of Tableau Server, resulting in downtime during that restart.
PUT /repository/externalUsers/<nickName>
Request path parameters
nickName
Required. The nickname of the external user account to enable.
For example, you could use tableau for this parameter.
Request query parameters
jobTimeoutSeconds
Optional. The number of seconds provided before the job times out.
Request body parameters
externalRepositoryPassword
Required. The password for the external user account.
For example, to set the password for the user to myexamplepassword, you would pass the following
request body:
{
"externalRepositoryPassword": {
"password": "myexamplepassword"
}
}
Response status code
200 OK
Response body example
{
"asyncJob": {
"args": "{\"usersAndPasswordsToUpdate\":{\"REMOTE\":\"mypassword\"}}",
"progress": -1,
"id": 3,
"status": "Created",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 0
},
"jobType": "UpdateRepositoryUsersJob",
"createdAt": 1507050583775,
"updatedAt": 1507050583775,
"statusMessageData": [],
"jobTimeout": 1320,
"statusMessage": "This job is queued."
}
}
Disable repository access for an external user
Disable access to the repository by an external user, including the built-in tableau user account.
Caution: Calling this endpoint causes an immediate restart of Tableau Server, resulting in downtime during that restart.
DELETE /repository/externalUsers/<nickName>
Request path parameters
nickName
Required. The nickname of the external user account to enable.
For example, you could use tableau for this parameter.
Request query parameters
jobTimeoutSeconds
Optional. The number of seconds provided before the job times out.
Response status code
200 OK
Response body example
{
"asyncJob": {
"args": "{\"usersToDisable\":[\"REMOTE\"]}",
"progress": -1,
"id": 5,
"status": "Created",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 0
},
"jobType": "UpdateRepositoryUsersJob",
"createdAt": 1507050638864,
"updatedAt": 1507050638864,
"statusMessageData": [],
"jobTimeout": 1320,
"statusMessage": "This job is queued."
}
}
Restore
Restores Tableau Server from a backup.
Restore
Restore Tableau Server from the specified backup file.
POST /restoreFixedFile
Request query parameters
fixedFile
Required. The name of the backup file in the data directory. By default, you can find backup files in the following location:
/var/opt/tableau/tableau_server/data/tabsvc/files/backups
jobTimeoutSeconds
Optional. The timout length in seconds. Default is 1800 seconds.
no-config
Optional. Restore the database but not the server configuration. Default is false.
restart
Optional. Restart Tableau Server after restoring. Default is false.
no-topology
Optional. Restore the database but not the server topology (the process configuration for nodes). Default is false.
Response status code
200 OK
Response body example
{
"asyncJob": {
"args": "{\"noConfig\":false,\"restart\":false,\"uploaded\":false,\"noTopology\":false,\"tsbakPath\":\"/var/opt/tableau/tableau_server/data/tabsvc/files/backups/backupname\"}",
"progress": -1,
"id": 12,
"status": "Created",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 22
},
"jobType": "RestoreJob",
"createdAt": 1497059398055,
"updatedAt": 1497059398070,
"statusMessageData": [],
"jobTimeout": 172800,
"statusMessage": "This job is queued."
}
}
Reindex search
Re-create the Tableau Server search index.
Reindex search
Re-create the Tableau Server search index.
POST /reindex-search
Request query parameters
jobTimeoutSeconds
Optional. The timout length in seconds. Default is 3600 seconds.
Response status code
200 OK
Response body example
{
"asyncJob": {
"args": "{\"startServer\":true}",
"progress": 0,
"id": 13,
"status": "Running",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 2
},
"jobType": "RebuildSearchIndex",
"createdAt": 1497060232637,
"updatedAt": 1497060232646,
"statusMessageData": [],
"jobTimeout": 900,
"worker": "node1",
"statusMessage": "This job is currently running."
}
}
Server information
Get information about Tableau Server.
Get server information
Get the version, initialization state, licensing state, and operating system of Tableau Server. This is the only TSM endpoint that does not require authentication.
GET /serverInfo
Response status code
200 OK
Response body example
{
"serverInfo": {
"serverVersion": "<version>",
"initializationState": "Initialized",
"operatingSystem": "Linux",
"licensingState": "Licensed"
}
}
Get support information
Get the operating system, server version, and locale of Tableau Server.
GET /supportInfo
Response status code
200 OK
Response body example
{
"supportInfo": {
"operatingSystem": "Linux",
"serverVersion": "<version>",
"locale": "en-us"
}
}
Settings
Export and import configuration and topology settings.
Export configuration and topology settings
Export the current configuration and topology settings, either as a response body, or as a file. The configuration settings are exported as configuration keys, rather than entities.
GET /export
Request query parameters
formatAsFile
Optional. A boolean value that determines whether to return the exported
configuration and topology settings as a file or as a response body. The default
value for this parameter is false.
includeBinaryVersion
Optional. A boolean value that determines whether to include a build number in
the configuration and topology settings. This build number is required by the
POST /import method if the
request body includes topologyVersion. The default value for this parameter
is false.
Response status code
200 OK
Response body example
{
"topologyVersion": {
"nodes": {
"node1": {
"services": {
"vizportal": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"backgrounder": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"licenseservice": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"tabadminagent": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"cacheserver": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"tabsvc": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"clustercontroller": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"gateway": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"pgsql": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"tabadmincontroller": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"samlservice": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"filestore": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"databasemaintenance": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"vizqlserver": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"searchserver": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"appzookeeper": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"dataserver": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"hyper": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"backuprestore": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
},
"siteimportexport": {
"instances": [
{
"instanceId": "0",
"binaryVersion": "10500.17.1217.1935"
}
]
}
}
}
}
},
"configKeys": {
"endpoints.health.enabled": true,
"config.version": 18,
"tableau_projects.language": "en",
"endpoints.enabled": false
}
}
Import configuration and topology settings
Import the current configuration and/or topology settings. The request body can
include either configuration keys (configKeys) or configuration entities
(configEntities). This method changes the pending configuration and/or
topology, so to apply changes, you need to call one or both of the following
methods:
POST /import
Request query parameters
configuration
Optional. Set this boolean value to false to ignore the configuration settings
in the request body. The default value is true.
topology
Optional. Set this boolean value to false to ignore the configuration settings
in the request body. The default value is true.
Request body example
The following is a request body that only includes a single configuration entity:
{
"configEntities": {
"gatewaySettings": {
"_type": "gatewaySettingsType",
"port": 80,
"sslRedirectEnabled": true,
"publicHost": "localhost",
"publicPort": 80
}
}
}
A request body can also include topology settings (in a topologyVersion field).
For an example of JSON that includes this field, see the response body for
GET /export.
Response code
200 OK
Status
Get the status of Tableau Server.
Get server status
Get the status of all nodes and services on Tableau Server.
GET /status
Response status code
200 OK
Response body example
{
"clusterStatus": {
"nodes": [{
"services": [{
"serviceName": "filestore",
"instances": [{
"code": "ACTIVE",
"processStatus": "Active",
"instanceId": "0",
"timestampUtc": 1497060680268,
"currentDeploymentState": "Enabled",
"binaryVersion": "<build>"
}],
"rollupStatus": "Running",
"rollupRequestedDeploymentState": "Enabled"
}, {
"..."
}],
"nodeId": "node1",
"rollupStatus": "Running",
"rollupRequestedDeploymentState": "Enabled"
}],
"href": "/api/0.5/status",
"rollupStatus": "Running",
"rollupRequestedDeploymentState": "Enabled"
}
}
Get node status
Get the status of all services on a specified node.
GET /status/nodes/<nodeId>
Request path parameters
nodeId
The node for which you want to get the status.
Response status code
200 OK
Response body example
{
"nodeStatus": {
"services": [{
"serviceName": "filestore",
"instances": [{
"code": "ACTIVE",
"processStatus": "Active",
"instanceId": "0",
"timestampUtc": 1497061100187,
"currentDeploymentState": "Enabled",
"binaryVersion": "<build>"
}],
"rollupStatus": "Running",
"rollupRequestedDeploymentState": "Enabled"
}, {
"..."
}],
"nodeId": "node1",
"rollupStatus": "Running",
"rollupRequestedDeploymentState": "Enabled"
}
}
Get service status
Get the status of all instances of a specified service.
GET /status/nodes/<nodeId>/services/<serviceName>
Request path parameters
nodeId
The node that hosts the service for which you want to get the status.
serviceName
The name of the service for which you want to get the status.
Response status code
200 OK
Response body example
{
"serviceStatus": {
"serviceName": "vizqlserver",
"instances": [{
"processStatus": "Active",
"instanceId": "0",
"timestampUtc": 1497061456668,
"currentDeploymentState": "Enabled",
"binaryVersion": "<build>"
}, {
"..."
}],
"rollupStatus": "Running",
"rollupRequestedDeploymentState": "Enabled"
}
}
Get service instance status
Get the status of the specified instance of a service.
GET /status/nodes/<nodeId>/services/<serviceName>/<instanceId>
Request path parameters
nodeId
The node that hosts the service for which you want to get the status.
serviceName
The name of the service for which you want to get the status.
instanceId
The instance for which you want to get the status.
Response status code
200 OK
Response body example
{
"instanceStatus": {
"processStatus": "Active",
"instanceId": "0",
"timestampUtc": 1497061516688,
"currentDeploymentState": "Enabled",
"binaryVersion": "<build>"
}
}
Sites
The TSM API sites methods are used to import and export sites, and to unlock sites. To export and re-import a site, do the following:
- Export the site using the
POST /sites/<siteId>/exportmethod. - Generate import mapping files using the
POST /sites/<siteId>/importmethod. - Verify that site settings are mapped correctly, and correct any errors. To learn more, see Verify that site settings are mapped correctly (Linux) or Verify that site settings are mapped correctly (Windows).
- Complete the import process using the
POST /sites/<siteId>/importverifiedmethod. - Unlock any sites that were locked due to errors that occurred when exporting or importing a site
using the
POST /sites/<siteId>/unlockmethod.
To learn more about exporting and importing a site, see Export or Import a Site (Linux) or Export or Import a Site (Windows).
Locating the siteId
The siteId is name of the site. You can get the siteId from the URL when you’re signed in to the site from a web browser. For example, if only one site exists on the server, that site is named Default. When you’re signed in to the Default site, the browser URL looks something like this:
https://server-name/#/projects
In the URL, the absence of the /site parameter indicates that it’s the Default site. The siteId for the Default site is Default.
On a multi-site Tableau Server deployment, the browser URL includes #/site/ followed by the siteId. The following URL would appear if you navigate to the Views page on a site whose siteId is finance:
https://localhost/#/site/finance/views
Export a site
Export a specified Tableau Server site to a .zip file. You can export a site to archive its contents,
or to complete the first step in a site migration process. If an error occurs when calling this
method, the site will be in a locked state until you call the
POST /sites/<siteId>/unlock method.
POST /sites/<siteId>/export
Request path parameters
siteId
Required. The siteId is name of the site. See Locating the siteId.
Request query parameters
bucketName
Optional, unless storageType is set to s3 (for Amazon S3 Storage). The name of the Amazon S3
storage bucket where the resulting site export file is placed.
continueOnIgnorableErrors
Optional. If set to true, site export will continue if ignorable errors are encountered.
exportFile
Required. Path to the resulting export file. For export files stored on the local server, the
default path must be under the directory defined by the basefilepath.site_export.exports
configuration setting.
On Linux, the default directory is the following:
/var/opt/tableau/tableau_server/data/tabsvc/files/siteexports
On Windows, the default directory is the following:
C:\ProgramData\Tableau\Tableau Server\data\tabsvc\files\siteexports
jobTimeoutSeconds
Optional. The timeout length in seconds. Default is 1800 seconds.
node
Optional. The node ID of the server node that is performing the site export.
overwrite
Optional. If set to true, this option will overwrite the site export file.
storageType
Optional. Determines where the resulting export file will be stored. If set to filesystem (the
default value), the export file is stored on the local server. If set to s3, the export file is
stored in Amazon S3 storage in the bucket defined by the bucketName parameter.
Request body parameters
remoteStorageEncryptionInfo
Required only if storageType is set to s3 because an Amazon S3 storage bucket is being used to
store the export file. The key in the request is a base-64 encoded 256-bit AES symmetric key to
used to encrypt the export file when uploading it to S3. The same key will be needed to decrypt the
file after downloading it and generating import mapping files using
POST /sites/<siteId>/import.
Request body example
The following request body is only required if storageType is set to s3 because an Amazon S3
storage bucket is being used to store the export file.
{
"remoteStorageEncryptionInfo": {
"key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
Response status code
200 OK.
Response body example
{
"asyncJob": {
"args": "{\"node\":\"node1\",\"siteUrl\":\"test\",\"exportName\":\"DefaultExport.zip\",\"productName\":\"Tableau Server\",\"overwriteExportFile\":false}",
"progress": -1,
"id": 10,
"status": "Created",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 4
},
"jobType": "SiteExportJob",
"createdAt": 1514502992219,
"updatedAt": 1514502992257,
"statusMessageData": [],
"jobTimeout": 43200,
"statusMessage": "This job is queued."
}
}
Generate import mapping files
Generates import mapping (.csv) files used to import a site from a site export (.zip) file.
POST /sites/<siteId>/import
Request path parameters
siteId
Required. The siteId is name of the site. See Locating the siteId.
Request query parameters
bucketName
Optional, unless storageType is set to s3 (for Amazon S3 Storage). The name of the Amazon S3
storage bucket where the site export file is located.
continueOnIgnorableErrors
Optional. If set to true, site import will continue if ignorable errors are encountered.
exportFile
Required. Path to the export file. For export files stored on the local server, the
default path must be under the directory defined by the basefilepath.site_import.imports
configuration setting, which defaults to
/var/opt/tableau/tableau_server/data/tabsvc/files/siteimports.
jobTimeoutSeconds
Optional. The timeout length in seconds. Default is 1800 seconds.
node
Optional. The node ID of the server node that is generating import mapping files.
scheduleMapperFile
Optional. The filename of the schedule mapper file (mapping-file.csv) that overrides normal schedule
mapping by name. The directory where this file is found is set by the
basefilepath.site_import.overrides configuration setting.
skipManualVerification
Optional, but must be set to true to use a remote storage option like Amazon S3. Skips
verification of mapping files if set to true.
storageType
Optional. Determines the storage type used to store the previously created export file. If set to
filesystem (the default value), the export file is stored on the local server. If set to s3, the
export file is stored in Amazon S3 storage in the bucket defined by the bucketName parameter.
Request body parameters
remoteStorageEncryptionInfo
Required only if storageType is set to s3 because an Amazon S3 storage bucket is being used to
store the export file. The key in the request is a the same base-64 encoded 256-bit AES symmetric
key used to encrypt the export file when it was uploaded to S3 using the
POST /sites/<siteId>/export method. The same key is used to decrypt the file and
generate mapping files.
Request body example
The following request body is only required if storageType is set to s3 because an Amazon S3
storage bucket is being used to store the export file.
{
"remoteStorageEncryptionInfo": {
"key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
Response status code
200 OK.
Response body example
{
"asyncJob": {
"id": 12,
"progress": -1,
"args": "{\"node\":"localhost",\"siteUrl\":\"ImportTest"\",\"exportName\":\"DefaultExport.zip"\",\"skipVerification\":true }",
"detailedProgress": {
"progressNotes": [],
"totalSteps": 0,
"doneSteps": 0
},
"jobType": "SiteImportJob",
"updatedAt": 1484263705085,
"jobTimeout": 1800,
"createdAt": 1484263705085,
"statusMessageData": []
}
}
Complete site import
Imports a site using import mapping (.csv) files generated using the
POST /sites/<siteId>/import method.
POST /sites/<siteId>/importverified
Request path parameters
siteId
Required. The siteId is name of the site. See Locating the siteId.
Request query parameters
jobTimeoutSeconds
Optional. The timeout length in seconds. Default is 1800 seconds.
node
Optional. The node ID of the server node that is performing the site export.
workingDirectory
Required. The path to a working directory that contains the import mapping files generated using the
POST /sites/<siteId>/import method. This directory is located
under the /working directory inside of the directory defined by the
basefilepath.site_import.imports configuration setting, which defaults to
/var/opt/tableau/tableau_server/data/tabsvc/files/siteimports. An example string for this
parameter is import 73943.
storageType
Optional. Determines where the resulting export file will be stored. If set to filesystem (the
default value), the export file is stored on the local server. If set to s3, the export file is
stored in Amazon S3 storage in the bucket defined by the bucketName parameter.
Response status code
200 OK.
Response body example
{
"asyncJob": {
"id": 12,
"progress": -1,
"args": "{\"node\":"localhost",\"siteUrl\":\"ImportTest"\",\"workingDirectory\":\"import73943"\" }",
"detailedProgress": {
"progressNotes": [],
"totalSteps": 0,
"doneSteps": 0
},
"jobType": "SiteImportVerifiedJob",
"updatedAt": 1484263705085,
"jobTimeout": 1800,
"createdAt": 1484263705085,
"statusMessageData": []
}
}
Unlock a site
Unlock a site that was locked as the result of errors when importing or exporting a site.
POST /sites/<siteId>/unlock
Request path parameters
siteId
Required. The ID of the site. See Locating the siteId.
Query request parameters
jobTimeoutSeconds
Optional. The timeout length in seconds. Default is 1800 seconds.
desiredState
Optional. The state to set the site to when it is unlocked (active or suspended). Defaults to
active.
Response status code
200 OK.
Response body example
{
"asyncJob": {
"id": 22,
"args": "{\"desiredState\":\"active\",\"siteUrl\":\"MySite\"}",
"progress": -1,
"status": "Created",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 2
},
"statusMessageData": [],
"updatedAt": 1504879269962,
"statusMessage": "This job is queued.",
"jobType": "SiteUnlockJob",
"jobTimeout": 300,
"createdAt": 1504879269951
}
}
Topology
The TSM API topology endpoints are used to examine the server topology, which is the set of services running across all nodes of your Tableau Server deployment, and the binary version of each of those services, and to make updates to the topology. Like configurations, topologies are tracked across multiple versions.
List topologies
Get a list of the topology versions available.
GET /topologies
Response status code
200 OK
Response body example
{
"links": {
"items": [{
"name": "0",
"href": "/api/0.5/topologies/0"
}, {
"name": "1",
"href": "/api/0.5/topologies/1"
}, {
"name": "2",
"href": "/api/0.5/topologies/2"
}, {
"name": "3",
"href": "/api/0.5/topologies/3"
}, {
"name": "requested",
"href": "/api/0.5/topologies/requested"
}, {
"name": "pending",
"href": "/api/0.5/topologies/pending"
}]
}
}
Get the current topology version
Gets the details of the current topology version.
GET /topologies/REQUESTED/version
Response status code
200 OK
Response body example
{
"version": "10"
}
Get a topology version
Gets the details of a specific topology version.
GET /topologies/<topology-version>
Request path parameters
topology-version
Required. The version of the server topology to get details on.
Response status code
200 OK
Response body example
{
"topologyVersion": {
"nodes": {
"node1": {
"services": {
"samlservice": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"searchserver": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"tabadmincontroller": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"tabsvc": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"pgsql": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"backuprestore": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"cacheserver": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"gateway": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"hyper": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"clustercontroller": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"vizportal": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"licenseservice": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"appzookeeper": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"vizqlserver": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"filestore": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"tabadminagent": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"siteimportexport": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"dataserver": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"databasemaintenance": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"backgrounder": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
}
},
"href": "/api/0.5/topologies/3/nodes/node1"
}
},
"href": "/api/0.5/topologies/3"
}
}
Validate a topology version against a configuration version
Validates that a specified topology version conforms to the specified configuration version, and reports any violations (cases where the specified topology version does not conform to the specified configuration version).
The response body returns the specified topology version, as well as a violatedTopologyConstraints
JSON element that describes which, if any, violations occurred.
GET /topologies/<topology-version>/violations
Request path parameters
topology-version
Required. The specified topology version number.
Request query parameters
configurationVersion
Required. The specified configuration version number, obtained by calling List configurations.
For example, you could use ?configurationVersion=9 for this query parameter.
Response status code
200 OK
Response body example
{
"topologyVersion": {
"nodes": {
"node1": {
"services": {
"tabadmincontroller": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"tabsvc": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"licenseservice": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"pgsql": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"appzookeeper": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"backuprestore": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"tabadminagent": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"siteimportexport": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"clustercontroller": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"databasemaintenance": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
}
},
"href": "/api/0.5/topologies/2/nodes/node1"
}
},
"href": "/api/0.5/topologies/2"
},
"violatedTopologyConstraints": {
"items": []
}
}
Get the topology of a single node
Get details of the current topology for a single node of a server cluster.
GET /topologies/<topology-version>/nodes/<nodeId>
Request path parameters
topology-version
Required. The specified topology version number.
nodeId
The node ID. Note that node IDs are distinct from the computer address.
For example, the node ID might be node1.
Response status code
200 OK
Response body example
{
"topologyVersion": {
"nodes": {
"node1": {
"services": {
"samlservice": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"searchserver": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"tabadmincontroller": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"tabsvc": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"pgsql": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"backuprestore": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"cacheserver": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"gateway": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"hyper": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"clustercontroller": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"vizportal": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"licenseservice": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"appzookeeper": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"vizqlserver": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"filestore": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"tabadminagent": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Enabled",
"binaryVersion": "<version-number>"
}
]
},
"siteimportexport": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"dataserver": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"databasemaintenance": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"backgrounder": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
}
},
"href": "/api/0.5/topologies/10/nodes/node1"
}
},
"href": "/api/0.5/topologies/10"
}
}
Get the difference between two topology versions
Gets the difference between one server topology version and another.
GET /topologies/<from-topology-version>/diff/<to-topology-version>
Request path parameters
from-topology-version
Required. The first topology version that is used for comparison.
to-topology-version
Required. The second topology version that is used for comparison.
Response status code
200 OK
Response body example
{
"topologyVersion": {
"nodes": {
"node1": {
"services": {
"filestore": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"searchserver": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"dataserver": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"cacheserver": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"vizqlserver": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"vizportal": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"backgrounder": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"hyper": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"gateway": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
},
"samlservice": {
"instances": [
{
"instanceId": "0",
"requestedDeploymentState": "Disabled",
"binaryVersion": "<version-number>"
}
]
}
}
}
},
"href": "/api/0.5/topologies/2/diff/9"
}
}
Delete a topology version
Deletes the specified topology version. Subsequent topology version numbers will remain unchanged, resulting in gaps in the topology version sequence. For example, if you delete topology version 9, version 10 retains the same version number that it did previous to using this endpoint. This command takes effect immediately and does not restart Tableau Server.
DELETE /topologies/<topology-version>
Request path parameters
topology-version
Required. The topology version to delete.
Response status code
200 OK
Update the pending topology
Updates the pending topology for the nodes and services provided in the request body. Includes the option to delete the pending topology for any nodes that are not included in the request body. If successful, this endpoint returns the new topology.
PUT /topologies/PENDING
Request query parameters
removeMissingNodes
Optional. If set to true, any nodes not included in the request body have their pending topology
deleted.
Response status code
200 OK
Update elements of the pending topology
Updates the the elements of the pending topology that correspond to the JSON elements specified in
the request body. The request body must contain the same elements and element structure as the
response body provided by
GET /topologies/<from-topology-version>/diff/<to-topology-version>.
PATCH /topologies/PENDING
Response status code
200 OK
Update Tableau Server with the pending topology
Updates Tableau Server with the pending topology. The response body provides the version number of the latest configuration version.
POST /topologies/PENDING/promote
Response status code
200 OK
Response body example
{
"version": "4"
}
Deployments
Update the server configuration and server topology simultaneously, and check to see if changes will require a restart of the nodes in the server cluster.
Update the configuration version and topology version
Update both the server configuration and the server topology to the specified version numbers
after validating that those versions exist. To check whether calling this endpoint will cause a
restart of the server cluster that hosts Tableau Server, first send the request body to the
POST /deployments/cluster-restart-needed
method.
Caution: Calling this endpoint will cause an immediate restart of Tableau Server, resulting in downtime during that restart.
POST /deployments
Request body parameters
requestedTopologyVersion
Required. The version of the server topology to deploy.
requestedConfigurationVersion
Required. The version of the server configuration to deploy.
Request body example
{
"deployment":{
"requestedTopologyVersion":"2",
"requestedConfigurationVersion":"2"
}
}
Response status code
200 OK
Response body example
{
"asyncJob": {
"args": "{\"requestedConfigurationVersion\":\"2\",\"requestedTopologyVersion\":\"2\"}",
"progress": 0,
"id": 11,
"status": "Running",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 20
},
"jobType": "DeploymentsJob",
"createdAt": 1507055185005,
"updatedAt": 1507055185017,
"statusMessageData": [],
"jobTimeout": 1200,
"worker": "node1",
"statusMessage": "This job is currently running."
}
}
Check whether an update to the configuration version and topology version will cause a cluster restart
Check whether calling the POST /deployments
method with a given request body will cause a restart of the server cluster that hosts Tableau
Server. The response body will contain true if a restart of the server cluster is needed, or
false if it is not needed.
POST /deployments/cluster-restart-needed
Request body parameters
requestedTopologyVersion
Required. The version of the server topology to deploy.
requestedConfigurationVersion
Required. The version of the server configuration to deploy.
Request body example
{
"deployment":{
"requestedTopologyVersion":"2",
"requestedConfigurationVersion":"2"
}
}
Response status code
200 OK
Response body example
{
"clusterRestartNeeded": {
"clusterRestartNeeded": true
}
}
Ports
Get and set ports assigned to Tableau Server services. These methods allow you to manage port assignments across all nodes, or scoped to specific nodes, services and service instances.
Get ports for all nodes
Get port assignments for all Tableau Server services.
GET /ports
Request query parameters
jobTimeoutSeconds
Optional. The timout length in seconds.
Response status code
200 OK
Response body example
{
"clusterPorts": {
"nodes": [
{
"services": [
{
"serviceName": "filestore",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8404,
"portType": "primary"
},
{
"port": 8308,
"portType": "status"
}
]
}
]
},
{
"serviceName": "siteimportexport",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8500,
"portType": "primary"
}
]
}
]
},
{
"serviceName": "databasemaintenance",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8077,
"portType": "primary"
}
]
}
]
},
{
"serviceName": "dataserver",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8572,
"portType": "primary"
},
{
"port": 8045,
"portType": "debug"
},
{
"port": 8781,
"portType": "jmx"
},
{
"port": 8501,
"portType": "jmx.rmi"
}
]
}
]
},
{
"serviceName": "cacheserver",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8614,
"portType": "primary"
}
]
}
]
},
{
"serviceName": "tabadmincontroller",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8850,
"portType": "primary"
}
]
}
]
},
{
"serviceName": "vizqlserver",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8549,
"portType": "primary"
},
{
"port": 8178,
"portType": "debug"
},
{
"port": 8249,
"portType": "jmx"
},
{
"port": 8668,
"portType": "jmx.rmi"
}
]
}
]
},
{
"serviceName": "backgrounder",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8940,
"portType": "primary"
},
{
"port": 8093,
"portType": "debug"
},
{
"port": 8537,
"portType": "jmx"
},
{
"port": 8851,
"portType": "jmx.rmi"
}
]
}
]
},
{
"serviceName": "appzookeeper",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8640,
"portType": "client"
},
{
"port": 8324,
"portType": "peer"
},
{
"port": 8706,
"portType": "leader"
}
]
}
]
},
{
"serviceName": "searchserver",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8217,
"portType": "primary"
},
{
"port": 8586,
"portType": "debug"
},
{
"port": 8624,
"portType": "jmx"
},
{
"port": 8316,
"portType": "jmx.rmi"
},
{
"port": 8206,
"portType": "startup"
}
]
}
]
},
{
"serviceName": "clustercontroller",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8277,
"portType": "status"
},
{
"port": 8977,
"portType": "storage"
}
]
}
]
},
{
"serviceName": "vizportal",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8269,
"portType": "primary"
},
{
"port": 8659,
"portType": "debug"
},
{
"port": 8485,
"portType": "jmx"
},
{
"port": 8797,
"portType": "jmx.rmi"
},
{
"port": 8146,
"portType": "authentication"
},
{
"port": 8414,
"portType": "authorization"
},
{
"port": 8301,
"portType": "maintenance"
}
]
}
]
},
{
"serviceName": "backuprestore",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8798,
"portType": "primary"
}
]
}
]
},
{
"serviceName": "gateway",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 80,
"portType": "primary"
}
]
}
]
},
{
"serviceName": "hyper",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8362,
"portType": "primary"
},
{
"port": 8859,
"portType": "connection"
}
]
}
]
},
{
"serviceName": "samlservice",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8866,
"portType": "primary"
}
]
}
]
},
{
"serviceName": "tabadminagent",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8388,
"portType": "filetransfer"
}
]
}
]
}
],
"nodeId": "node1"
}
]
}
}
Set ports for all nodes
Set port assignments for Tableau Server services. The request body must be a modified version of
the response body provided by GET /ports.
Caution: Calling this endpoint causes an immediate restart of Tableau Server, resulting in downtime during that restart.
PUT /ports
Request query parameters
jobTimeoutSeconds
Optional. The timout length in seconds.
Response status code
200 OK
Response body example
{
"asyncJob": {
"progress": 0,
"id": 12,
"status": "Running",
"detailedProgress": {
"progressNotes": [
{
"step": "ConfigureServices",
"messageData": [],
"timestamp": 1507057436496,
"message": "Reconfiguring services.",
"status": "Running"
}
],
"doneSteps": 0,
"totalSteps": 2
},
"jobType": "ReconfigureJob",
"createdAt": 1507057436474,
"updatedAt": 1507057436496,
"statusMessageData": [],
"jobTimeout": 420,
"worker": "node1",
"statusMessage": "This job is currently running."
}
}
Get ports for a node
Get port assignments for all Tableau Server services on a single server node.
GET /ports/nodes/<nodeId>
Request path parameters
nodeId
The node that you want to get port assignments from.
Response status code
200 OK
Response body example
{
"nodePorts": {
"services": [
{
"serviceName": "filestore",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8422,
"portType": "primary"
},
{
"port": 8668,
"portType": "status"
}
]
}
]
},
{
"serviceName": "siteimportexport",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8956,
"portType": "primary"
}
]
}
]
},
{
"serviceName": "databasemaintenance",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8907,
"portType": "primary"
}
]
}
]
},
{
"serviceName": "cacheserver",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8287,
"portType": "primary"
}
]
}
]
},
{
"serviceName": "dataserver",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8354,
"portType": "primary"
},
{
"port": 8750,
"portType": "debug"
},
{
"port": 8577,
"portType": "jmx"
},
{
"port": 8904,
"portType": "jmx.rmi"
}
]
}
]
},
{
"serviceName": "tabadmincontroller",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8850,
"portType": "primary"
}
]
}
]
},
{
"serviceName": "vizqlserver",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8731,
"portType": "primary"
},
{
"port": 8541,
"portType": "debug"
},
{
"port": 8691,
"portType": "jmx"
},
{
"port": 8172,
"portType": "jmx.rmi"
}
]
}
]
},
{
"serviceName": "backgrounder",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8624,
"portType": "primary"
},
{
"port": 8263,
"portType": "debug"
},
{
"port": 8900,
"portType": "jmx"
},
{
"port": 8088,
"portType": "jmx.rmi"
},
{
"port": 8827,
"portType": "recommendations.trainer"
}
]
}
]
},
{
"serviceName": "appzookeeper",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8332,
"portType": "client"
},
{
"port": 8797,
"portType": "leader"
},
{
"port": 8863,
"portType": "peer"
}
]
}
]
},
{
"serviceName": "searchserver",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8501,
"portType": "primary"
},
{
"port": 8244,
"portType": "debug"
},
{
"port": 8997,
"portType": "jmx"
},
{
"port": 8396,
"portType": "jmx.rmi"
},
{
"port": 8778,
"portType": "startup"
}
]
}
]
},
{
"serviceName": "clustercontroller",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8167,
"portType": "status"
},
{
"port": 8028,
"portType": "storage"
}
]
}
]
},
{
"serviceName": "vizportal",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8402,
"portType": "primary"
},
{
"port": 8141,
"portType": "debug"
},
{
"port": 8706,
"portType": "jmx"
},
{
"port": 8661,
"portType": "jmx.rmi"
},
{
"port": 8774,
"portType": "authentication"
},
{
"port": 8397,
"portType": "authorization"
},
{
"port": 8667,
"portType": "maintenance"
},
{
"port": 8639,
"portType": "publishing"
},
{
"port": 8465,
"portType": "recommendations"
}
]
}
]
},
{
"serviceName": "backuprestore",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8500,
"portType": "primary"
}
]
}
]
},
{
"serviceName": "gateway",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 80,
"portType": "primary"
}
]
}
]
},
{
"serviceName": "samlservice",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8166,
"portType": "primary"
}
]
}
]
},
{
"serviceName": "hyper",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8001,
"portType": "primary"
},
{
"port": 8210,
"portType": "connection"
}
]
}
]
},
{
"serviceName": "tabadminagent",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8949,
"portType": "filetransfer"
}
]
}
]
}
],
"nodeId": "node1"
}
}
Set ports for a node
Set port assignments for Tableau Server services on a node. The request body must be a modified
version of the response body provided by GET /ports/nodes/<nodeId>.
Caution: Calling this endpoint causes an immediate restart of Tableau Server, resulting in downtime during that restart.
PUT /ports/nodes/<nodeId>
Request path parameters
nodeId
The node that you want to set port assignments for.
Request query parameters
jobTimeoutSeconds
Optional. Specifies the number of seconds before the job times out.
Response status code
200 OK
Response body example
{
"asyncJob": {
"progress": -1,
"id": 11,
"status": "Created",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 2
},
"jobType": "ReconfigureJob",
"createdAt": 1514583948170,
"updatedAt": 1514583948178,
"statusMessageData": [],
"jobTimeout": 420,
"statusMessage": "This job is queued."
}
}
Get ports for a service on a node
Get port assignments for a Tableau Server service on a node.
GET /ports/nodes/<nodeId>/services/<serviceName>
Request path parameters
nodeId
The node that you want to get port assignments from.
serviceName
The name of the service that you want to get port assignments from.
Response status code
200 OK
Response body example
{
"servicePorts": {
"serviceName": "filestore",
"instances": [
{
"instanceId": 0,
"ports": [
{
"port": 8422,
"portType": "primary"
},
{
"port": 8668,
"portType": "status"
}
]
}
]
}
}
Set ports for a service on a node
Set port assignments for a Tableau Server service on a node. The request body must be a modified
version of the response body provided by
GET /ports/nodes/<nodeId>/services/<serviceName>.
Caution: Calling this endpoint causes an immediate restart of Tableau Server, resulting in downtime during that restart.
SET /ports/nodes/<nodeId>/services/<serviceName>
Request path parameters
nodeId
The node that you want to set port assignments form.
serviceName
The name of the service that you want to set port assignments for.
Response status code
200 OK
Response body example
{
"asyncJob": {
"progress": 0,
"id": 15,
"status": "Running",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 2
},
"jobType": "ReconfigureJob",
"createdAt": 1514587134936,
"updatedAt": 1514587134997,
"statusMessageData": [],
"jobTimeout": 420,
"worker": "node1",
"statusMessage": "This job is currently running."
}
}
Get ports for a service instance on a node
Get port assignments for a Tableau Server service instance on a node.
GET /ports/nodes/<nodeId>/services/<serviceName>/<instanceId>
Request path parameters
nodeId
The node that you want to get port assignments from.
serviceName
The name of the service that you want to get port assignments from.
instanceId
The ID number of the service instance.
Response status code
200 OK
Response body example
{
"instancePorts": {
"instanceId": 0,
"ports": [
{
"port": 8624,
"portType": "primary"
},
{
"port": 8263,
"portType": "debug"
},
{
"port": 8900,
"portType": "jmx"
},
{
"port": 8088,
"portType": "jmx.rmi"
},
{
"port": 8827,
"portType": "recommendations.trainer"
}
]
}
}
Set ports for a service instance on a node
Set port assignments for a Tableau Server service instance on a node. The request body must be a
modified version of the response body provided by
GET /ports/nodes/<nodeId>/services/<serviceName>/<instanceId>.
Caution: Calling this endpoint causes an immediate restart of Tableau Server, resulting in downtime during that restart.
GET /ports/nodes/<nodeId>/services/<serviceName>/<instanceId>
Request path parameters
nodeId
The node that you want to set port assignments from.
serviceName
The name of the service that you want to set port assignments from.
instanceId
The ID number of the service instance.
Response status code
200 OK
Response body example
{
"asyncJob": {
"progress": -1,
"id": 16,
"status": "Created",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 0
},
"jobType": "ReconfigureJob",
"createdAt": 1514587668481,
"updatedAt": 1514587668481,
"statusMessageData": [],
"jobTimeout": 420,
"statusMessage": "This job is queued."
}
}
Security
Configure Tableau Server security. These methods create or delete secure socket layer (SSL) configuration settings for external (gateway) SSL and recreate the security tokens that Tableau Server uses internally. To learn more about managing SSL in Tableau Server, see tsm security.
Configure and enable external SSL
Configure Tableau Server’s external (gateway) SSL configuration settings to encrypt traffic between external clients and Tableau Server.
POST /security/gateway-external-ssl
Request body parameters
The request body must use the multipart form-data type.
certFile
Required. A valid PEM-encoded x509 certificate with the .crt file extension.
keyFile
Required. A valid RSA or DSA private key file, with the .key file extension.
chainFile
Optional, but required to support deployments that use Tableau Mobile and Tableau Desktop on the
Mac. Some certificate providers issue two certificates for Apache web server. The second certificate
is a chain file, which is a concatenation of all the certificates that form the certificate chain
for the server certificate. All certificates in the chain file must be x509 PEM-encoded and the file
must have a .crt extension.
passphrase
Optional. Passphrase for the certificate file. The passphrase you enter will be encrypted while at rest.
protocols
Optional. List the Transport Layer Security (TLS) protocol versions you want to allow or disallow.
TLS is an improved version of SSL. Tableau Server uses TLS to authenticate and encrypt connections. Accepted values include protocol versions supported by Apache. To disallow a protocol, prepend the protocol version with a minus (-) character.
The default setting is "all, -SSLv2, -SSLv3"
This default explicitly does not allow clients to use SSL v2 or SSL v3 protocols to connect to Tableau Server. However, we recommend that you also disallow TLS v1 and TLS v1.1.
Before you deny a specific version of TLS, verify that the browsers from which your users connect to Tableau Server support TLS v1.2. You might need to preserve support for TLS v1.1 until your users update their browsers.
If you do not need to support TLS v1 or v1.1, set the following value for this parameter to allow TLS v1.2 (using the value all), and explicitly deny SSL v2, SSL v3, TLS v1, and TLS v1.1:
"all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1"
Response status code
204 No Content
TODO complete
Remove SSL configuration and disable external SSL
Remove Tableau Server’s existing external (gateway) SSL configuration settings and stop encrypting traffic between external clients and Tableau Server.
DELETE /security/gateway-external-ssl
Response status code
204 No Content
Recreate internal security tokens
Recreate the tokens used by Tableau Server to access the repository, and the certificates used to validate internal SSL connections between Tableau Server components and the repository.
Caution: Calling this endpoint causes an immediate restart of Tableau Server, resulting in downtime during that restart.
POST /security/regenerate-internal-tokens
Response status code
200 OK
Response body example
{
"asyncJob": {
"progress": 0,
"id": 13,
"status": "Running",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 24
},
"jobType": "RegenerateInternalTokens",
"createdAt": 1507058104158,
"updatedAt": 1507058104273,
"statusMessageData": [],
"jobTimeout": 1500,
"worker": "node1",
"statusMessage": "This job is currently running."
}
}
Log Files
Tableau Server creates archives that contain the complete set of current Tableau
Server log files. You can use the /ziplogs methods to create a .zip file
archive, which is stored on your server.
Create log file archive
Create a log file archive (logs.zip). The file is written to the directory defined in the
TSM basefilepath.log_archive variable. By default, this directory is
/var/opt/tableau/tableau_server/data/tabsvc/files/log-archives/.
For more information about file paths and how to change them, see tsm File Paths.
POST /ziplogs
Request query parameters
description
Optional. A description of the log file archive.
jobTimeoutSeconds
Optional. Specifies the number of seconds before the job times out.
minimumDate
Optional. Earliest date of files to be included. If not specified, a maximum of
two days of data are included. The expected date format is mm/dd/yyyy.
overwrite
Optional. Overwrites the an existing file with the same filename, if it exists.
withNetstatInfo
Optional. Include netstat information.
withPostgresqlData
Optional. Include the PostgreSQL data folder if Tableau Server is stopped or PostgreSQL dump files if Tableau Server is running.
withLatestDump
Optional. Include latest dumps.
writepath
Required. The name for the ziplogs file. Ziplogs files are placed in the data directory. By default, you can find ziplogs files in the following location:
/var/opt/tableau/tableau_server/data/tabsvc/files/log-archives
Response status code
200 OK
Response body example
{
"asyncJob": {
"args": "{\"withNetstatInfo\":false,\"withPostgresqlData\":false,\"withLatestDump\":false,\"minimumDate\":[2017,6,7],\"node\":\"node1\"}",
"progress": 0,
"id": 14,
"status": "Running",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 0
},
"jobType": "ZiplogsJob",
"createdAt": 1497062264656,
"updatedAt": 1497062264669,
"statusMessageData": [],
"jobTimeout": 1800,
"worker": "node1",
"statusMessage": "This job is currently running."
}
}
Create log file archive with a specified filename
Create a log file archive with a specified filename. The file is written to the
directory defined in the TSM basefilepath.log_archive variable. By default,
this directory is
/var/opt/tableau/tableau_server/data/tabsvc/files/log-archives/
For more information about file paths and how to change them, see tsm File Paths.
POST /ziplogsFixedFile
Request query parameters
description
Optional. A description of the log file archive.
jobTimeoutSeconds
Optional. Specifies the number of seconds before the job times out.
minimumDate
Optional. The earliest date of files to be included. If not specified, a maximum
of two days of data are included. The expected date format is mm/dd/yyyy.
withNetstatInfo
Optional. Include netstat information.
withPostgresqlData
Optional. Include the PostgreSQL data folder if Tableau Server is stopped or PostgreSQL dump files if Tableau Server is running.
withLatestDump
Optional. Include latest dumps.
writepath
Required. The name for the ziplogs file. Ziplogs files are placed in the data directory. By default, you can find ziplogs files in the following location:
/var/opt/tableau/tableau_server/data/tabsvc/files/log-archives
Response status code
200 OK
Response body example
{
"asyncJob": {
"args": "{\"withNetstatInfo\":false,\"withPostgresqlData\":false,\"withLatestDump\":false,\"minimumDate\":[2017,6,7],\"node\":\"node1\"}",
"progress": 0,
"id": 14,
"status": "Running",
"detailedProgress": {
"progressNotes": [],
"doneSteps": 0,
"totalSteps": 0
},
"jobType": "ZiplogsJob",
"createdAt": 1497062264656,
"updatedAt": 1497062264669,
"statusMessageData": [],
"jobTimeout": 1800,
"worker": "node1",
"statusMessage": "This job is currently running."
}
}
Get log file archive list
Get a list of log file archives (or “snapshots”), along with details including
when the log file was created (milliseconds since January 1st, 1970), the size
of the archive in bytes, and an ID number that is required for the
POST \sendlogs,
GET \snapshots\<id>, and
DELETE \snapshots\<id> methods.
GET /snapshots
Response status code
200 OK
Response body example
{
"logSnapshotInfo": {
"snapshots": [
{
"createdDate": 1513905215873,
"archiveSize": 5546728,
"ziplogsStatus": "Succeeded",
"sendlogsStatus": "Succeeded",
"id": 1,
"node": "node1",
"range": 72
},
{
"createdDate": 1513970549847,
"archiveSize": 20553477,
"ziplogsStatus": "Succeeded",
"id": 2,
"node": "node1",
"range": 72
},
{
"createdDate": 1513971159342,
"archiveSize": 21228741,
"ziplogsStatus": "Succeeded",
"id": 3,
"node": "node1",
"range": 72
}
]
}
}
Get log file archive
Get a log file archive, shown as text in the response body.
GET /snapshots/<snapshotId>
Request path parameters
snapshotId
The ID of the log file archive, provided in the id field when you call
GET /snapshots.
Response status code
200 OK
Response body example
The response body shows the contents of the log file archive, rendered as plan text. Because this response body is thousands of lines, it is not provided here.
Delete log file archive
Delete a log file archive.
DELETE /snapshots/<snapshotId>
Request path parameters
snapshotId
The ID of the log file archive, provided in the id field when you call
GET /snapshots.
Response status code
204 No Content
Send log file archive to Tableau
Upload the specified log file archive to Tableau and associate it with a support case and your email address.
POST \sendlogs
Request query parameters
caseNumber
Required. The case number provided by Tableau Support.
email
Required. The email address that Tableau Support will use as contact information to follow-up with you
jobTimeoutSeconds
Optional. Specifies the number of seconds before the job times out.
logPackagePath
Optional; but you must provide either logPackagePath or snapshotId in this
request. The full path, including the filename, of the log file archive.
snapshotId
Optional; but you must provide either logPackagePath or snapshotId in this
request. The ID of the log file archive, provided in the id field when you
call GET /snapshots.
Response status code
204 No Content