Getting Started Guide

Tableau REST API

Manage provisioning, permissions, and publishing on Tableau Server or Tableau Cloud via HTTP

Difficulty Level
Beginner

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.
REST API: Authenticate

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.

REST API: Specify

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.

REST API: Choose

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.
REST API: Make

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
 

REST API: Process

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.

 

Test in your own Sandbox

Last updated: September 13, 2021