Tableau REST API Help

This topic illustrates the structure of REST API requests by showing the raw HTTP, including both headers and the body (as appropriate).

How to read the examples

In this topic, the first line of each example shows the verb (GET, POST, etc.) and the portion of the URI that describes the resource and the REST API version number. For example, for signing in the example URI shows this:

POST /api/2.2/auth/signin HTTP/1.1

This indicates that you should make a POST request, using version 2.2 of the REST API, and that the URI should be something like the following:

http://my-server/api/2.2/auth/signin

where my-server is the name or IP address of the computer where Tableau Server is installed.

The lines that follow the verb and endpoint show the headers that you must include.

If the examples shows a POST or PUT request, there's a blank line, followed by the XML information that's included in the body.

Sign in

The first REST API request in a session must be a sign-in request. This is a POST request that sends the user credentials in the body of the request. Because this is a POST request, the request must include the Content-Type header. You can send your the body of the request block as XML or JSON. For example, the following shows how you send an XML request block.

POST /api/2.2/auth/signin HTTP/1.1
HOST: my-server
Content-Type:text/xml

<tsRequest>
  <credentials name="administrator" password="passw0rd">
    <site contentUrl="" />
  </credentials>
</tsRequest>

 

You can also send the request using JSON by setting the Content-Type to application/json. You can receive the response in JSON or XML by setting the Accept header to application/json or application/xml.

POST /api/2.2/auth/signin HTTP/1.1
HOST: my-server
Content-Type:application/json
Accept:application/json

{
  "credentials": {
    "name": "administrator",
    "password": "passw0rd",
    "site": {
      "contentUrl": ""
    }
  }
}

Get a list of resources

To get a list of resources like users, you send a GET request. The request must include an X-Tableau-Auth header with the authentication token that was returned in the Sign In call. There is no request body.

The following examples shows a request that gets a list of users.

GET /api/2.2/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/users HTTP/1.1
HOST: my-server
X-Tableau-Auth: 12ab34cd56ef78ab90cd12ef34ab56cd

Create a new resource

To create a new resource, such as a new user, you send a POST request. The request must include:

• An X-Tableau-Auth header with the authentication token that was returned in the Sign In call

• A Content-Type header set to text/xml or application/xml if you are sending an XML block, or set to application/json for a JSON request block.

• A request body with an XML or a JSON block that includes the information for the new resource. The XML and JSON block is defined by an XML schema. The information in the request block depends on what type of resource you're creating.

The following example shows a request that creates a new user in an XML request. The response returns the ID of the resource you created.

POST /api/2.2/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users HTTP/1.1
HOST: my-server
X-Tableau-Auth: 12ab34cd56ef78ab90cd12ef34ab56cd
Content-Type: text/xml

<tsRequest>
  <user name="NewUser" siteRole="Publisher" />
</tsRequest>

This example shows the same request in JSON.

POST /api/2.2/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users HTTP/1.1
HOST: my-server
X-Tableau-Auth: 12ab34cd56ef78ab90cd12ef34ab56cd
Content-Type: application/json

{
  "user": {
    "name": "NewUser1",
    "siteRole":  "Publisher"
  }
}

Update a resource

To update an existing resource, you send a PUT request and include the ID of the resource that was returned in POST request. The request must include:

• An X-Tableau-Auth header with the authentication token that was returned in the Sign In call.

• A Content-Type header set to text/xml.

• A request body with an XML or JSON block that includes the changes for the existing resource. The XML or JSON block is defined by an XML schema. The information in the request block depends on the type of resource that you're updating.

The following example shows a request that updates an existing user. The URI includes the ID of the user that was returned from the POST request.

PUT /api/2.2/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d HTTP/1.1
HOST: my-server
X-Tableau-Auth: 12ab34cd56ef78ab90cd12ef34ab56cd
Content-Type: text/xml

<tsRequest>
  <user fullName="NewUser2" siteRole="ViewerWithPublish" />
</tsRequest>

This example shows the same request in JSON.

PUT /api/2.2/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d HTTP/1.1
HOST: my-server
X-Tableau-Auth: 12ab34cd56ef78ab90cd12ef34ab56cd
Content-Type: application/json

{
  "user": {
    "fullName": "NewUser2",
    "siteRole":  "ViewerWithPublish"
  }
}

Delete a resource

To remove resource, you send a DELETE request. The request must include an X-Tableau-Auth header with the authentication token that was returned in the Sign In call. There is no request body.

The following example shows a request that deletes an existing user.

DELETE /api/2.2/sites/d0356794-bb9d-4c5c-b43d-ec384a2baf5a/users/2798bf2f-964d-4cf6-994a-0744c4555f84 HTTP/1.1
HOST: my-server
X-Tableau-Auth: 12ab34cd56ef78ab90cd12ef34ab56cd

Publish a resource

To publish a resource such as a data source or a workbook, you have two options. You can publish the resource using a single call. In that case, you create a POST request with the content type of multipart/mixed, and you include the resource in the body of the request.

Another option is to publish the resource in pieces. For that scenario, you initiate a file upload as a POST request, and then send a series of POST requests that each append another piece of the resource. When the resource has been completely uploaded, you make a final POST request to finish the upload.

For details about how to publish, see Publishing Resources.