Getting Started Guide
Tableau REST API
Manage provisioning, permissions, and publishing on Tableau Server or Tableau Cloud via HTTP
Supported By: Tableau Server: at least 9 & Tableau Cloud
Overview
Get started with the Tableau REST API to perform many Tableau site and server management actions from within scripts, programs and apps that you create. The REST API methods cover a large number of the actions available in Tableau settings and dialogs, and a few actions that can only be done through REST requests. Explore the dozens of methods available in the REST API reference.
Typically, using the REST API to perform a given task will involve several requests, using the information returned from one to provide info for the next. A few common uses for the REST API, among the huge array of possibilities, include:
- Authenticating a user, which provides sign in credentials used by other Tableau Developer Platform functionality like extensions, metadata, and embedding APIs.
- Managing permissions for users and groups to access Tableau Resources.
- Managing scheduling of data source and extract refreshes.
In order for Tableau to know you are a valid user and which content you have permissions to, each request needs to contain a credentials token that provides that info. To get the token you make a REST request containing your sign in credentials. The credentials token string in the response is a short-lived cryptographic key that needs to be periodically refreshed with a new sign in.
In the commonly used command line tool cURL, the REST request to sign in looks like:
curl
"https://MY-SERVER/api/3.12/auth/signin"
-X POST -d
"@signin.xml"
This REST request contains a URI that points to the address of a Tableau user sign in resource: 3.12/auth/signin
.
The resource location includes an API version (3.12
). When you make a request to a specific API version, you know you will get that version of Tableau behavior, even if that behavior evolves in a future version. For the full story on versioning, see REST API and Resource Versions.
In this case, the request also includes a request body that provides the details of the request. The cURL request above points to an XML file (-d "@signin.xml")
that contains the user credentials and the site content URL.
Note: This request body uses credentials in the form of a personal access token for authenticating the user, but you can also use username and password.
Now that the resource is defined in the URI, and the details Tableau needs are described in the request body, you need to choose an HTTP verb. This tells Tableau what action that resource should use to take. The verb in this request is POST
, which tells Tableau to create and return a credentials token.
Common verbs include:
- POST (create) - Create a resource.
- GET (read) - Retrieve a list of a specified kind of resource or the details of a specified resource.
- PUT (update) - Update the properties of a resource, or a list of resources.
- DELETE (delete) - Delete a resource.
There are many ways to make a REST request. You can open a terminal window and type in the cURL command to run the examples provided here. Postman, another common tool for making individual requests, has many features including the ability to make a collection of reusable requests. Each language typically has REST libraries or intrinsic functions that you can use to integrate requests to Tableau.
For Python scripting, you can also access the REST API using the Tableau Server Client (TSC) library. TSC is an open source Python wrapper that allows you to use Tableau REST API methods without dealing with REST call details. Tableau Developer Platform teams often contribute, and new REST methods are typically available in the library in the TSC version that follows their release in the Tableau product. Use the REST API TSC if your code is in Python. and you aren’t calling the very latest methods to be released. Use the REST API directly if you are calling from other languages, or need a very recently released method
When you succeed at making the sign in request, the Tableau response looks like:
<tsResponse . . .> <credentials token="W6cRFuYwRKyd50fQuMxebQ|GxSzZnSWOCCHlBW86W3ILBlaukFgmFza" estimatedTimeToExpiration="361:20:45" > <site id="a905dbfd-6550-4546-908b-3e055fcc026d" contentUrl="my_site_name" /> <user id="d5e162f1-6821-422c-a34b-3198eac500e5" /> </credentials> </tsResponse>
Here is an cURL example, of how to use the credentials token and site ID to make a validated request to Tableau. This request creates a new project. The credentials token and site id values are abbreviated for simplicity.
curl "https://
MY_SERVER
/api/3.12/sites/{{site_id}}
/projects
" -X POST -H "X-Tableau-Auth:{{credentials_token}}" -d "@create-project.xml"
The credentials token is added to the request header (-H "X-Tableau-Auth:6{{credentials_token}}"
), a part of the request that contains metadata related to the characteristics of the request.
create-project.xml
contains the request body with the name and description of the new project:
<tsRequest> <project name="my-new-project-name" description="The new project I created to get started!" /> </tsRequest>
The successful response will look like:
<tsResponse . . .> <project id="91560c1b-a407-4453-bbf6-8368bf2367df" name="my-new-project-name" description="he new project I created to get started!" createdAt="2021-05-07T22:31:58Z" updatedAt="2021-05-07T22:31:58Z" contentPermissions="ManagedByOwner"> <owner id="1b526a10-048b-4d1d-96e7-e12ec7f46388"/> </project> </tsResponse>
The next step depends on the task you want to perform. You might want to add a workbook owned by a specific user to the project using the Update Workbook method. That method requires the LUID of the workbook, so you might first call the Query Workbooks for User method, and parse the workbooks listed in the response to find the right one. To make that request you might need to find the user’s LUID, meaning you would first call Get Users on Site and find the LUID in that response.
Pro-tip
One way you could further verify that your project exists and is in the site you expect is to use the Query projects method, again using the site ID and credentials token plus an added filter expression in the query string of the URI:
curl "http://MY-SERVER/ /3.12/sites/{site_id}/projects?filter=name:eq:my-new-project-name" -X GET -H "X-Tableau-Auth:credential_token"
Or you could use the LUID in the `id` attribute of the response:
curl "http://MY-SERVER/api/3.12/sites/{site_id}/projects/91560c1b-a407-4453-bbf6-8368bf2367df" -X GET -H "X-Tableau-Auth:{{credential_token}}"
For a more in-depth tutorial on signing in and REST API usage, see the Getting Started tutorial in the REST API reference.
Last updated: September 13, 2021