TSM API Reference


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:

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 request path parameter.

{
    "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

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."
  }
}

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:

  1. Export the site using the POST /sites/<siteId>/export method.
  2. Generate import mapping files using the POST /sites/<siteId>/import method.
  3. 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).
  4. Complete the import process using the POST /sites/<siteId>/importverified method.
  5. Unlock any sites that were locked due to errors that occurred when exporting or importing a site using the POST /sites/<siteId>/unlock method.

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