Tableau REST API Help

Two Version Types

Classic REST endpoints: The more than 150 REST endpoints that let you programmatically take many of the actions available in the user interface of Tableau Cloud, on-premise Tableau Server, Tableau Prep and more. This powerful set of APIs started life in Tableau Server 2.5 and has been evolving organically as our server products grew and matured. The existing REST APIs are in heavy usage throughout the Tableau community and will continue to be maintained and grow.

Endpoints of the classic Tableau REST API have request URIs that begin with {server}/api/{api-version-number}/site/{site-luid}. The API version defines a set of resource versions that ship with a given release of Tableau Server (such as 2019.4). Versions of the REST API are identified using major and minor version numbers in the format <major>.<minor>, as in 3.6. For more information, see REST API Versioning.

Per resource versioned RESTful endpoints: Alongside the classic APIs, starting with Tableau Server 2020.2 we will be releasing a growing body of a new kind of endpoint. Because the new APIs are based a modern standard and designed for the mature Tableau environment, our teams will be able to produce more consistent endpoints at a faster pace. The new endpoints will call the same code that clicking the corresponding UI element calls, not always the case for classic APIs. URIs for this new generation of endpoints begin with {server}/api/-, where the version number is replaced with a hyphen. These resources are versioned independently of the REST API version number. For more information, see Per Resource Versioning.

Site LUID in the URI path: Note that in both cases, the site containing the resources addressed for a Tableau REST session is specified in the contentUrl value of the sign in request for a REST API session. The site LUID is returned in a sign in the credentials token element of the response. For classic endpoints, that LUID must be included in the URI path. For per resource requests, the site LUID is inferred from the sign in context.

REST API Versioning

When you make a request using the REST API, you include the API version number as part of the request, as in the following example:

https://MY-SERVER/api/3.24/auth/signin

When a new version of the REST API becomes available, if you try to call a method that was introduced in the new version but the URI includes a previous version, the method call will fail. In the API reference documentation, each method includes a Version section that tells you the version of the REST API in which that method was introduced.

REST API Update releases

Small changes to the REST API might be made during update releases, which are identified using the format <major>.<minor>.<update-release>. For example, version 2.0.1 is an update release for version 2.0 of the REST API. Update releases might include bug fixes, and might include a new element or attribute in the XML body for a method.

When you specify the API version in the URI of a request, do not include the update release value. For example, when you specify the version number in the URI for update release 2.0.1, use version 2.0 in request URIs.

REST API Schema versions

Although an update release does not change the version of the REST API, an update release can include changes to the XML for requests and responses. If so, these updates are reflected in the REST API schema (.xsd file). Unlike the version numbers for the REST API as a whole, the version number of the schema file does reflect update releases.

If you rely on the schema (for example, if you generate code from it), you should make sure that you have the latest version of the .xsd file. You should also examine the changes in the schema and determine whether they affect you.

You can determine the version of the schema file by looking at the xsi:schemaLocation attribute in the opening <tsResponse> tag of the response body. The following example shows what the tag looks like for the 3.24 version of the schema.

<tsResponse
    xmlns="http://tableau.com/api"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.24.xsd">

Tableau Server versions and REST API versions

Versions of the REST API are made available with releases of Tableau Server. The following table lists versions of Tableau Server and of the corresponding REST API and REST API schema versions.

Tableau Server version	REST API version	Schema version
8.3, 9.0	2.0	2.0
9.0.1 and later versions of 9.0	2.0	2.0.1
9.1	2.0	2.0.1
9.2	2.1	2.1
9.3	2.2	2.2
10.0	2.3	2.3
10.1	2.4	2.4
10.2	2.5	2.5
10.3	2.6	2.6
10.4	2.7	2.7
10.5	2.8	2.8
2018.1	3.0	3.0
2018.2	3.1	3.1
2018.3	3.2	3.2
2019.1	3.3	3.3
2019.2	3.4	3.4
2019.3	3.5	3.5
2019.4	3.6	3.6
2020.1	3.7	3.7
2020.2	3.8	3.8
2020.3	3.9	3.9
2020.4	3.10	3.10
2021.1	3.11	3.11
2021.2	3.12	3.12
2021.3	3.13	3.13
2021.4	3.14	3.14
2022.1	3.15	3.15
2022.2 (Tableau Cloud only)	3.16	3.16
2022.3	3.17	3.17
2022.4 (Tableau Cloud only)	3.18	3.18
2023.1	3.19	3.19
2023.2 (Tableau Cloud only)	3.20	3.20
2023.3	3.21	3.21
2024.1 (Tableau Cloud only)	3.22	3.22
2024.2	3.23	3.23s
2024.3 (Tableau Cloud only)	3.24	3.24

Per Resource Versioning

Endpoints with URIs that begin with /api/-  are of a new kind, where versions of each resource are independent of the Tableau REST API version. When you make a request using one of these new endpoints, the URI contains only the path to the target resource:

{server}api/-/settings/site/extensions/dashboard

Dashboard extensions settings methods are an example of the new, per resource version scheme, which is as follows:

• For Tableau Cloud: Features and fixes will be added to the current version of endpoint as long as they are additive and backward compatible. A request to one of these new resources returns the behavior of its latest version.
• For on-premise Tableau Server: These new resources will have the version that was latest at the time of the Server version’s release.
• Resource versions: The version of a resource will only increment when there is a breaking change introduced for the resource. You can request the behavior of the earlier version of a resource by specifying that version in your request.
• Client generation: For both Tableau Cloud and on-premise Server, you can use the OpenAPI definition of the the API surface for these new endpoints to generate client integration code in the language of your choice.

• Manual mediatype formation: Most often we expect users to make calls via a generated client library, but to manually form a request to one of these new endpoints, the request header must include Content-Type (if the request type has a body) and Accept keys whose values are a mediatype containing the version string of the resource being called. The form of mediatype to use in your header values is as follows:

  • application/vnd.{resource_string}+json

  • An example would look something like:

  • application/vnd.com.tableau.workbooks.v1.Workbook+json.

  The exception to this rule is that when you omit the Accept value or make its value application/*. In this case, Tableau response will be the expected behavior of the latest version of the resource. This is provided to facilitate experimentation, and for automation scenarios where the requesting script or program parses and forks behavior based on the version of the response.

Generate Client Integration Code

The OpenAPI spec for these new endpoints on the Tableau Cloud or Server instance you use can be downloaded from {server}/services/specifications/openapi. There are many tools available that enable you to generate clients for many languages from an OpenAPI spec.

The following commandline example uses openapi generator(Link opens in a new window) and the java cli(Link opens in a new window) to create a Python client library.

java -jar openapi-generator-cli-4.2.3.jar generate
	-i {OpenAPI spec location}
	-o {output dir}
	--generator-name python
	--additional-properties=packageName=rest_client_python,projectName=rest_client_python